Parameter/Command Hooks

hardware_control.base.hooks module

Functions that can be used in hooks for instrument parameters and commands.

A hook function takes a single argument, the value, and returns the modified value or None. If None is returned no further hooks (if they exist) will be executed.

To create a hook function that depends on other variables, you can create a function that returns another function (similar to decorators), e.g.:

Example

>>> def create_hook(arg):
...     def hook(value):
...         return value + arg
...     return hook
class hardware_control.base.hooks.Ramp(app, instrument: str, set_parameter: str, ramp_speed: int, read_parameter: str = '', timer_step: int = 500, min_value: float = 0, epsilon: float = 0.0001)

Bases: QObject

Ramp a setting up and down via a timer.

This can be useful for, e.g., high voltage power supplies that do not support ramping.

The class can be used as a hook. If there are several hooks, this should be the first one, so that the ramp units are all in the same units as on the UI, e.g. before any scaling happens.

Parameters:

  • app – The main app.

  • instrument – The instrument name

  • set_parameter – The instrument parameter for setting the voltage

  • ramp_speed – The change in the parameter (in UI units) per second.

  • read_parameter – The instrument parameter to reading the current voltage (if empty, then set_parameter will be used)

  • timer_step – The time between steps, in ms. (default 500 ms)

  • min_value – Only scan when we are above this value

  • epsilon – Stop when we are within epsilon of target value

do_step()

Execute one ramping step.

Calculated the next value in the ramping cycle and set it via the app.

hardware_control.base.hooks.add_offset(offset)

Convert value to float and add offset to it.

hardware_control.base.hooks.call_hooks(hooks_list: list[Callable], value: str) → str | None

Call a list of functions.

If any of the functions returns None, the final value will be ignored and no further hooks will be called.

Every hook function must take a single parameter: the value of the parameter to be set (set to None for commands)

If a hook needs several parameters, one should pass these in when defining the hook using lambda functions, e.g.:

app.add_hook(instrument, parameter, ‘pre_set_hooks’, lambda x: change_ui(app, x, widget))

where app and widget are defined in the environment where add_hook is called.

Parameters:

  • hooks_list – A list of functions or callable objects

  • values – The value to be manipulated

hardware_control.base.hooks.create_converter(lookuptable: dict) → Callable

Replaces the parameter value with one stored in a dictionary.

The dictionary consists of “old value”:”new value” pairs.

hardware_control.base.hooks.expected_input_validator(types: list, default_val=None)

Ensures value is in a specified list, returns a default if this is not the case.

hardware_control.base.hooks.format_bool(value)

Convert True/False string to 1/0.

hardware_control.base.hooks.format_float(format_type='.17', as_string=True)

Convert value to float and format using any f-string format.

hardware_control.base.hooks.format_int(value)

Convert value to int.

hardware_control.base.hooks.last_n_values_converter(num_of_values: int) → Callable

Assume value is a list and only return the last num_of_values entries.

hardware_control.base.hooks.list_hook_names(hooks_list: list[Callable]) → list[str]

List the function names of all hooks in a given list of hooks.

hardware_control.base.hooks.make_negative(value)

Convert to float and multiple by -1.

hardware_control.base.hooks.max_len_converter(max_length: int) → Callable

Ensure that a string is not longer than max_length.

hardware_control.base.hooks.range_validator(min_val: float, max_val: float)

Ensure value is in a specified numerical range.

If the value is outside of the range, the value gets replaces by the min/max value.

hardware_control.base.hooks.scaling_converter(scale_val)

Convert value to float and scale by scale_val.

hardware_control.base.hooks.splitter(idx_lst: list, delimiter: str = ',')

Split a string into parts and only return n of those parts.

idx_lstList

Indices of elements in split string to return

delimiterstr

delimiter to use in split function

hardware_control.base.hooks.substring_hook(min_char: int = None, max_char: int = None)

Return a substring value[min_char:max_char].

hardware_control.base.hooks.uppercase(value)

Convert to uppercase.