Writing properties
In PyMeasure, Python properties are the preferred method for dealing with variables that are read or set.
The property factories
PyMeasure comes with three central convenience factory functions for making properties for classes: CommonBase.control, CommonBase.measurement, and CommonBase.setting.
You can call them, however, as Instrument.control, Instrument.measurement, and Instrument.setting.
The Instrument.measurement function returns a property that can only read values from an instrument.
For example, if our “Extreme 5000” has the *IDN? command, we can write the following property to be added after the def __init__ line in our above example class, or added to the class after the fact as in the code here:
Extreme5000.cell_temp = Instrument.measurement(
":TEMP?",
"""Measure the temperature of the reaction cell.""",
)
You will notice that a documentation string is required, see Docstrings for details.
When we use this property we will get the temperature of the reaction cell.
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.cell_temp # Sends ":TEMP?" to the device
127.2
The Instrument.control function extends this behavior by creating a property that you can read and set. For example, if our “Extreme 5000” has the :VOLT? and :VOLT <float> commands that are in Volts, we can write the following property.
Extreme5000.voltage = Instrument.control(
":VOLT?", ":VOLT %g",
"""Control the voltage in Volts (float)."""
)
You will notice that we use the Python string format %g to format passed-through values as floating point.
We can use this property to set the voltage to 100 mV, which will send the appropriate command, and then to request the current voltage:
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.voltage = 0.1 # Sends ":VOLT 0.1" to set the voltage to 100 mV
>>> extreme.voltage # Sends ":VOLT?" to query for the current value
0.1
Finally, the Instrument.setting function can only set, but not read values.
Using the Instrument.control, Instrument.measurement, and Instrument.control functions, you can create a number of properties for basic measurements and controls.
The next sections detail additional features of the property factories. These allow you to write properties that cover specific ranges, or that have to map between a real value to one used in the command. Furthermore it is shown how to perform more complex processing of return values from your device.
Restricting values with validators
Many GPIB/SCPI commands are more restrictive than our basic examples above. The Instrument.control function has the ability to encode these restrictions using validators. A validator is a function that takes a value and a set of values, and returns a valid value or raises an exception. There are a number of pre-defined validators in pymeasure.instruments.validators that should cover most situations. We will cover the four basic types here.
In the examples below we assume you have imported the validators.
In many situations you will also need to process the return string in order to extract the wanted quantity or process a value before sending it to the device. The Instrument.control, Instrument.measurement and Instrument.setting function also provide means to achieve this.
In a restricted range
If you have a property with a restricted range, you can use the strict_range and truncated_range functions.
For example, if our “Extreme 5000” can only support voltages from -1 V to 1 V, we can modify our previous example to use a strict validator over this range.
Extreme5000.voltage = Instrument.control(
":VOLT?", ":VOLT %g",
"""Control the voltage in Volts (float strictly from -1 to 1).""",
validator=strict_range,
values=[-1, 1]
)
Now our voltage will raise a ValueError if the value is out of the range.
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.voltage = 100
Traceback (most recent call last):
...
ValueError: Value of 100 is not in range [-1,1]
This is useful if you want to alert the programmer that they are using an invalid value. However, sometimes it can be nicer to truncate the value to be within the range.
Extreme5000.voltage = Instrument.control(
":VOLT?", ":VOLT %g",
"""Control the voltage in Volts (float from -1 to 1).
Invalid voltages are truncated.
""",
validator=truncated_range,
values=[-1, 1]
)
Now our voltage will not raise an error, and will truncate the value to the range bounds.
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.voltage = 100 # Executes ":VOLT 1"
>>> extreme.voltage
1.0
In a discrete set
Often a control property should only take a few discrete values. You can use the strict_discrete_set and truncated_discrete_set functions to handle these situations. The strict version raises an error if the value is not in the set, as in the range examples above.
For example, if our “Extreme 5000” has a :RANG <float> command that sets the voltage range that can take values of 10 mV, 100 mV, and 1 V in Volts, then we can write a control as follows.
Extreme5000.voltage = Instrument.control(
":RANG?", ":RANG %g",
"""Control the voltage range in Volts (float in 10e-3, 100e-3, 1).""",
validator=truncated_discrete_set,
values=[10e-3, 100e-3, 1]
)
Now we can set the voltage range, which will automatically truncate to an appropriate value.
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.voltage = 0.08
>>> extreme.voltage
0.1
Mapping values
Now that you are familiar with the validators, you can additionally use maps to satisfy instruments which require non-physical values. The map_values argument of Instrument.control enables this feature.
If your set of values is a list, then the command will use the index of the list. For example, if our “Extreme 5000” instead has a :RANG <integer>, where 0, 1, and 2 correspond to 10 mV, 100 mV, and 1 V, then we can use the following control.
Extreme5000.voltage = Instrument.control(
":RANG?", ":RANG %d",
"""Control the voltage range in Volts (float in 10 mV, 100 mV and 1 V).
""",
validator=truncated_discrete_set,
values=[10e-3, 100e-3, 1],
map_values=True
)
Now the actual GPIB/SCIP command is “:RANG 1” for a value of 100 mV, since the index of 100 mV in the values list is 1.
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.voltage = 100e-3
>>> extreme.read()
'1'
>>> extreme.voltage = 1
>>> extreme.voltage
1
Dictionaries provide a more flexible method for mapping between real-values and those required by the instrument. If instead the :RANG <integer> took 1, 2, and 3 to correspond to 10 mV, 100 mV, and 1 V, then we can replace our previous control with the following.
Extreme5000.voltage = Instrument.control(
":RANG?", ":RANG %d",
"""Control the voltage range in Volts (float in 10 mV, 100 mV and 1 V).
""",
validator=truncated_discrete_set,
values={10e-3:1, 100e-3:2, 1:3},
map_values=True
)
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.voltage = 10e-3
>>> extreme.read()
'1'
>>> extreme.voltage = 100e-3
>>> extreme.voltage
0.1
The dictionary now maps the keys to specific values. The values and keys can be any type, so this can support properties that use strings:
Extreme5000.channel = Instrument.control(
":CHAN?", ":CHAN %d",
"""Control the measurement channel (string strictly in 'X', 'Y', 'Z').""",
validator=strict_discrete_set,
values={'X':1, 'Y':2, 'Z':3},
map_values=True
)
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.channel = 'X'
>>> extreme.read()
'1'
>>> extreme.channel = 'Y'
>>> extreme.channel
'Y'
As you have seen, the Instrument.control function can be significantly extended by using validators and maps.
Boolean properties
The idea of using maps can be leveraged to implement properties where the user-facing values are booleans, so you can interact in a pythonic way using True and False:
Extreme5000.output_enabled = Instrument.control(
"OUTP?", "OUTP %d",
"""Control the instrument output is enabled (boolean).""",
validator=strict_discrete_set,
map_values=True,
values={True: 1, False: 0}, # the dict values could also be "on" and "off", etc. depending on the device
)
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.output_enabled = True
>>> extreme.read()
'1'
>>> extreme.output_enabled = False
>>> extreme.output_enabled
False
>>> # Invalid input raises an exception
>>> extreme.output_enabled = 34
Traceback (most recent call last):
...
ValueError: Value of 34 is not in the discrete set {True: 1, False: 0}
Good names for boolean properties are chosen such that they could also be a yes/no question: “Is the output enabled?” -> output_enabled, display_active, etc.
Processing of set values
The Instrument.control, and Instrument.setting allow a keyword argument set_process which must be a function that takes a value after validation and performs processing before value mapping. This function must return the processed value. This can be typically used for unit conversions as in the following example:
Extreme5000.current = Instrument.setting(
":CURR %g",
"""Set the measurement current in A (float strictly from 0 to 10).""",
validator=strict_range,
values=[0, 10],
set_process=lambda v: 1e3*v, # convert current to mA
)
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.current = 1 # set current to 1000 mA
Processing of return values
Similar to set_process the Instrument.control, and Instrument.measurement functions allow a get_process argument which if specified must be a function that takes a value and performs processing before value mapping. The function must return the processed value. In analogy to the example above this can be used for example for unit conversion:
Extreme5000.current = Instrument.control(
":CURR?", ":CURR %g",
"""Control the measurement current in A (float strictly from 0 to 10).""",
validator=strict_range,
values=[0, 10],
set_process=lambda v: 1e3*v, # convert to mA
get_process=lambda v: 1e-3*v, # convert to A
)
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.current = 3.1
>>> extreme.current
3.1
Another use-case of set-process, get-process is conversion from/to a pint.Quantity. Modifying above example to set or return a quantity, we get:
from pymeasure.units import ureg
Extreme5000.current = Instrument.control(
":CURR?", ":CURR %g",
"""Control the measurement current (float).""",
set_process=lambda v: v.m_as(ureg.mA), # send the value as mA to the device
get_process=lambda v: ureg.Quantity(v, ureg.mA), # convert to quantity
)
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.current = 3.1 * ureg.A
>>> extreme.current.m_as(ureg.A)
3.1
Note
This is, how quantities can be used in pymeasure instruments right now. Issue 666 develops a more convenient implementation of quantities in the property factories.
get_process can also be used to perform string processing. Let’s say your instrument returns a value with its unit (e.g. 1.23 nF), which has to be removed. This could be achieved by the following code:
Extreme5000.capacity = Instrument.measurement(
":CAP?",
"""Measure the capacity in nF (float).""",
get_process=lambda v: float(v.replace('nF', ''))
)
The same can be also achieved by the preprocess_reply keyword argument to Instrument.control or Instrument.measurement. This function is forwarded to Adapter.values and runs directly after receiving the reply from the device. One can therefore take advantage of the built in casting abilities and simplify the code accordingly:
Extreme5000.capacity = Instrument.measurement(
":CAP?",
"""Measure the capacity in nF (float).""",
preprocess_reply=lambda v: v.replace('nF', '')
# notice how we don't need to cast to float anymore
)
Checking the instrument for errors
If you need to separately ask your instrument about its error state after getting/setting, use the parameters check_get_errors and check_set_errors of control(), respectively.
If those are enabled, the methods check_get_errors() and check_set_errors(), respectively, will be called be called after device communication has concluded.
In the default implementation, for simplicity both methods call check_errors().
To read the automatic response of instruments that respond to every set command with an acknowledgment or error, override check_set_errors() as needed.
Using multiple values
Seldomly, you might need to send/receive multiple values in one command.
The Instrument.control function can be used with multiple values at one time, passed as a tuple. Say, we may set voltages and frequencies in our “Extreme 5000”, and the commands for this are :VOLTFREQ? and :VOLTFREQ <float>,<float>, we could use the following property:
Extreme5000.combination = Instrument.control(
":VOLTFREQ?", ":VOLTFREQ %g,%g",
"""Simultaneously control the voltage in Volts and the frequency in Hertz (both float).
This property is set by a tuple.
"""
)
In use, we could set the voltage to 200 mV, and the Frequency to 931 Hz, and read both values immediately afterwards.
>>> extreme = Extreme5000("GPIB::1")
>>> extreme.combination = (0.2, 931) # Executes ":VOLTFREQ 0.2,931"
>>> extreme.combination # Reads ":VOLTFREQ?"
[0.2, 931.0]
This interface is not too convenient, but luckily not often needed.
Dynamic properties
As described in previous sections, Python properties are a very powerful tool to easily code an instrument’s programming interface. One very interesting feature provided in PyMeasure is the ability to adjust properties’ behaviour in subclasses or dynamically in instances. This feature allows accommodating some interesting use cases with a very compact syntax.
Dynamic features of a property are enabled by setting its dynamic parameter to True.
Afterwards, creating specifically-named attributes (either in class definitions or on instances) allows modifying the parameters used at the time of property definition. You need to define an attribute whose name is <property name>_<property_parameter> and assign to it the desired value. Pay attention not to inadvertently define other class attribute or instance attribute names matching this pattern, since they could unintentionally modify the property behaviour.
Note
To clearly distinguish these special attributes from normal class/instance attributes, they can only be set, not read.
The mechanism works for all the parameters in properties, except dynamic and docs – see Instrument.control, Instrument.measurement, Instrument.setting.
Dynamic validity range
Let’s assume we have an instrument with a command that accepts a different valid range of values depending on its current state. The code below shows how this can be accomplished with dynamic properties.
Extreme5000.voltage = Instrument.control(
":VOLT?", ":VOLT %g",
"""Control the voltage in Volts (float).""",
validator=strict_range,
values=[-1, 1],
dynamic = True,
)
def set_bipolar_mode(self, enabled = True):
"""Safely switch between bipolar/unipolar mode."""
# some code to switch off the output first
# ...
if enabled:
self.mode = "BIPOLAR"
# set valid range of "voltage" property
self.voltage_values = [-1, 1]
else:
self.mode = "UNIPOLAR"
# note the "propertyname_parametername" form of the attribute
self.voltage_values = [0, 1]
Now our voltage property has a dynamic validity range, either [-1, 1] or [0, 1].
A side effect of this is that the property’s docstring should be less specific, to avoid it containing dynamically changed information (like the admissible value range).
In this example, the property name was voltage and the parameter to adjust was values, so we used self.voltage_values to set our desired values.
Instruments with similar features
When instruments have a similar set of features, it makes sense to use inheritance to obtain most of the functionality from a parent instrument class, instead of copy-pasting code.
Note
Don’t forget to update the instrument’s name attribute accordingly, by either supplying an appropriate argument (if available) during the super().__init__() call, or by setting it anew below that call.
In some cases, one only needs to add additional properties and methods. In other cases, some of the already present properties/methods need to be completely replaced by defining them again in the derived class. Often, however, only some details need to be changed. This can be dealt with efficiently using dynamic properties.
Instrument family with different parameter values
A common case is to have a family of similar instruments with some parameter range different for each family member. In this case you would update the specific class parameter range without rewriting the entire property:
class FictionalInstrumentFamily(Instrument):
frequency = Instrument.setting(
"FREQ %g",
"""Set the frequency (float).""",
validator=strict_range,
values=[0, 1e9],
dynamic=True,
# ... other possible parameters follow
)
#
# ... complete class implementation here
#
class FictionalInstrument_1GHz(FictionalInstrumentFamily):
pass
class FictionalInstrument_3GHz(FictionalInstrumentFamily):
frequency_values = [0, 3e9]
class FictionalInstrument_9GHz(FictionalInstrumentFamily):
frequency_values = [0, 9e9]
Notice how easily you can derive the different family members from a common class, and the fact that the attribute is now defined at class level and not at instance level.
Instruments with similar command syntax
Another use case involves maintaining compatibility between instruments with commands having different syntax, like in the following example.
class MultimeterA(Instrument):
voltage = Instrument.measurement(get_command="VOLT?",...)
# ...full class definition code here
class MultimeterB(MultimeterA):
# Same as brand A multimeter, but the command to read voltage
# is slightly different
voltage_get_command = "VOLTAGE?"
In the above example, MultimeterA and MultimeterB use a different command to read the voltage, but the rest of the behaviour is identical.
MultimeterB can be defined subclassing MultimeterA and just implementing the difference.