qcodes.instrument.parameter

The Parameter module implements Parameter interface that are the basis of measurements and control within QCoDeS.

Anything that you want to either measure or control within QCoDeS should satisfy the Parameter interface. Most of the time that is easiest to do by either using or subclassing one of the classes defined here, but you can also use any class with the right attributes.

All parameter classes are subclassed from ._BaseParameter (except CombinedParameter). The _BaseParameter provides functionality that is common to all parameter types, such as ramping and scaling of values, adding delays (see documentation for details).

This module defines the following basic classes of parameters as well as some more specialized ones:

Parameter is the base class for scalar-valued parameters.
Two primary ways in which it can be used:
1. As an Instrument parameter that sends/receives commands. Provides a standardized interface to construct strings to pass to the Instrument.write() and Instrument.ask() methods
2. As a variable that stores and returns a value. For instance, for storing of values you want to keep track of but cannot set or get electronically.
ParameterWithSetpoints is intended for array-values parameters.
This Parameter class is intended for anything where a call to the instrument returns an array of values. This notebook gives more detailed examples of how this parameter can be used and this notebook explains writing driver using ParameterWithSetpoints.

ParameterWithSetpoints is supported in a qcodes.dataset.measurements.Measurement but is not supported by the legacy qcodes.loops.Loop and qcodes.measure.Measure measurement types.
DelegateParameter is intended for proxy-ing other parameters.
It forwards its get and set to the underlying source parameter, while allowing to specify label/unit/etc that is different from the source parameter.
ArrayParameter is an older base class for array-valued parameters.
For any new driver we strongly recommend using ParameterWithSetpoints which is both more flexible and significantly easier to use. This Parameter is intended for anything for which each get call returns an array of values that all have the same type and meaning. Currently not settable, only gettable. Can be used in a qcodes.dataset.measurements.Measurement as well as in the legacy qcodes.loops.Loop and qcodes.measure.Measure measurements - in which case these arrays are nested inside the loop’s setpoint array. To use, provide a get method that returns an array or regularly-shaped sequence, and describe that array in super().__init__.
MultiParameter is the base class for multi-valued parameters.
Currently not settable, only gettable, but can return an arbitrary collection of scalar and array values and can be used in qcodes.dataset.measurements.Measurement as well as the legacy qcodes.loops.Loop and qcodes.measure.Measure measurements. To use, provide a get method that returns a sequence of values, and describe those values in super().__init__.

class qcodes.instrument.parameter.ArrayParameter(name: str, shape: Sequence[int], instrument: Optional[InstrumentBase] = None, label: Optional[str] = None, unit: Optional[str] = None, setpoints: Optional[Sequence[Any]] = None, setpoint_names: Optional[Sequence[str]] = None, setpoint_labels: Optional[Sequence[str]] = None, setpoint_units: Optional[Sequence[str]] = None, docstring: Optional[str] = None, snapshot_get: bool = True, snapshot_value: bool = False, snapshot_exclude: bool = False, metadata: Optional[Mapping[Any, Any]] = None, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter._BaseParameter

A gettable parameter that returns an array of values. Not necessarily part of an instrument.

For new driver we strongly recommend using ParameterWithSetpoints which is both more flexible and significantly easier to use

Subclasses should define a .get_raw method, which returns an array. This method is automatically wrapped to provide a .get method.

ArrayParameter can be used in both a qcodes.dataset.measurements.Measurement as well as in the legacy qcodes.loops.Loop and qcodes.measure.Measure measurements

When used in a Loop or Measure operation, this will be entered into a single DataArray, with extra dimensions added by the Loop. The constructor args describe the array we expect from each .get call and how it should be handled.

For now you must specify upfront the array shape, and this cannot change from one call to the next. Later we intend to require only that you specify the dimension, and the size of each dimension can vary from call to call.

Parameters

name – The local name of the parameter. Should be a valid identifier, i.e. no spaces or special characters. If this parameter is part of an Instrument or Station, this is how it will be referenced from that parent, i.e. instrument.name or instrument.parameters[name]
shape – The shape (as used in numpy arrays) of the array to expect. Scalars should be denoted by (), 1D arrays as (n,), 2D arrays as (n, m), etc.
instrument – The instrument this parameter belongs to, if any.
label – Normally used as the axis label when this parameter is graphed, along with unit.
unit – The unit of measure. Use '' for unitless.
setpoints – array can be a DataArray, numpy.ndarray, or sequence. The setpoints for each dimension of the returned array. An N-dimension item should have N setpoint arrays, where the first is 1D, the second 2D, etc. If omitted for any or all items, defaults to integers from zero in each respective direction. Note: if the setpoints will be different each measurement, leave this out and return the setpoints (with extra names) in .get.
setpoint_names – One identifier (like name) per setpoint array. Ignored if a setpoint is a DataArray, which already has a name.
setpoint_labels – One label (like labels) per setpoint array. Ignored if a setpoint is a DataArray, which already has a label.
setpoint_units – One unit (like v) per setpoint array. Ignored if a setpoint is a DataArray, which already has a unit.
docstring – documentation string for the __doc__ field of the object. The __doc__ field of the instance is used by some help systems, but not all.
snapshot_get – Prevent any update to the parameter, for example if it takes too long to update. Default True.
snapshot_value – Should the value of the parameter be stored in the snapshot. Unlike Parameter this defaults to False as ArrayParameters are potentially huge.
snapshot_exclude –
True prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot.

Default False.
metadata – Extra information to include with the JSON snapshot of the parameter.

property setpoint_full_names: Optional[Sequence[str]]: Full names of setpoints including instrument names if available

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

get_raw() → Any: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

property gettable: bool: Is it allowed to call get on this parameter?

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_raw(value: Any) → None: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

class qcodes.instrument.parameter.CombinedParameter(parameters: Sequence[qcodes.instrument.parameter.Parameter], name: str, label: Optional[str] = None, unit: Optional[str] = None, units: Optional[str] = None, aggregator: Optional[Callable[[...], Any]] = None)[source]

Bases: qcodes.utils.metadata.Metadatable

A combined parameter. It sets all the combined parameters at every point of the sweep. The sets are called in the same order the parameters are, and sequentially.

Parameters

*parameters – The parameters to combine.
name – The name of the parameter
label – The label of the combined parameter
unit – The unit of the combined parameter
aggregator – A function to aggregate the set values into one

set(index: int) → List[Any][source]

Set multiple parameters.

Parameters: index – the index of the setpoints one wants to set
Returns: list of values that where actually set

sweep(*array: numpy.ndarray) → qcodes.instrument.parameter.CombinedParameter[source]

Creates a new combined parameter to be iterated over. One can sweep over either:

n array of length m

one nxm array

where n is the number of combined parameters and m is the number of setpoints

Parameters: *array – Array(s) of setpoints.
Returns: combined parameter

snapshot_base(update: Optional[bool] = False, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any][source]

State of the combined parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

Parameters

update – True or False.
params_to_skip_update – Unused in this subclass.

Returns

Base snapshot.

Return type

dict

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

class qcodes.instrument.parameter.DelegateParameter(name: str, source: Optional[qcodes.instrument.parameter.Parameter], *args: Any, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter.Parameter

The DelegateParameter wraps a given source Parameter. Setting/getting it results in a set/get of the source parameter with the provided arguments.

The reason for using a DelegateParameter instead of the source parameter is to provide all the functionality of the Parameter base class without overwriting properties of the source: for example to set a different scaling factor and unit on the DelegateParameter without changing those in the source parameter.

The DelegateParameter supports changing the source Parameter. gettable, settable and snapshot_value properties automatically follow the source parameter. If source is set to None gettable and settable will always be False. It is therefore an error to call get and set on a DelegateParameter without a source. Note that a parameter without a source can be snapshotted correctly.

unit and label can either be set when constructing a DelegateParameter or inherited from the source Parameter. If inherited they will automatically change when changing the source. Otherwise they will remain fixed.

Note

DelegateParameter only supports mappings between the DelegateParameter and Parameter that are invertible (e.g. a bijection). It is therefor not allowed to create a DelegateParameter that performs non invertible transforms in its get_raw method.

A DelegateParameter is not registered on the instrument by default. You should pass bind_to_instrument=True if you want this to be the case.

property source: Optional[qcodes.instrument.parameter.Parameter]

The source parameter that this DelegateParameter is bound to or None if this DelegateParameter is unbound.

Getter: Returns the current source.
Setter: Sets the source.

get_raw() → Any[source]: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

set_raw(value: Any) → None[source]: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any][source]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

__getitem__(keys: Any) → qcodes.instrument.sweep_values.SweepFixedValues: Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

property gettable: bool: Is it allowed to call get on this parameter?

increment(value: Any) → None

Increment the parameter with a value

Parameters: value – Value to be added to the parameter.

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) → qcodes.instrument.sweep_values.SweepFixedValues

Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.

Parameters

start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.

Returns

Collection of parameter values to be iterated over.

Return type

SweepFixedValues

Examples

>>> sweep(0, 10, num=5)
 [0.0, 2.5, 5.0, 7.5, 10.0]
>>> sweep(5, 10, step=1)
[5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> sweep(15, 10.5, step=1.5)
>[15.0, 13.5, 12.0, 10.5]

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

label: str = (): Label of the data used for plots etc.

unit = (): The unit of measure. Use '' for unitless.

class qcodes.instrument.parameter.GetLatest(parameter: qcodes.instrument.parameter._BaseParameter)[source]

Bases: qcodes.utils.helpers.DelegateAttributes

Wrapper for a class:.Parameter that just returns the last set or measured value stored in the class:.Parameter itself. If get has never been called on the parameter or the time since get was called is larger than max_val_age, get will be called on the parameter. If the parameter does not implement get, set should be called (or the initial_value set) before calling get on this wrapper. It is an error to set max_val_age for a parameter that does not have a get function.

The functionality of this class is subsumed and improved in parameter’s cache that is accessible via .cache attribute of the Parameter. Use of parameter.cache is recommended over use of parameter.get_latest.

Examples

>>> # Can be called:
>>> param.get_latest()
>>> # Or used as if it were a gettable-only parameter itself:
>>> Loop(...).each(param.get_latest)

Parameters: parameter – Parameter to be wrapped.

delegate_attr_objects: List[str] = ['parameter']: A list of names (strings) of objects which are (or will be) attributes of self, whose attributes should be passed through to self.

omit_delegate_attrs: List[str] = ['set']: A list of attribute names (strings) to not delegate to any other dictionary or object.

get() → Any[source]

Return latest value if time since get was less than max_val_age, otherwise perform get() and return result. A get() will also be performed if the parameter never has been captured.

It is recommended to use parameter.cache.get() instead.

get_timestamp() → Optional[datetime.datetime][source]

Return the age of the latest parameter value.

It is recommended to use parameter.cache.timestamp instead.

get_raw_value() → Optional[Any][source]

Return latest raw value of the parameter.

It is recommended to use parameter.cache.raw_value instead.

__call__() → Any[source]

Same as get()

It is recommended to use parameter.cache() instead.

delegate_attr_dicts: List[str] = []: A list of names (strings) of dictionaries which are (or will be) attributes of self, whose keys should be treated as attributes of self.

class qcodes.instrument.parameter.InstrumentRefParameter(name: str, instrument: Optional[InstrumentBase] = None, label: Optional[str] = None, unit: Optional[str] = None, get_cmd: Optional[Union[str, Callable[[...], Any], bool]] = None, set_cmd: Optional[Union[str, Callable[[...], Any], bool]] = None, initial_value: Optional[Union[float, str]] = None, max_val_age: Optional[float] = None, vals: Optional[qcodes.utils.validators.Validator[Any]] = None, docstring: Optional[str] = None, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter.Parameter

An instrument reference parameter.

This parameter is useful when one needs a reference to another instrument from within an instrument, e.g., when creating a meta instrument that sets parameters on instruments it contains.

Parameters

name – The name of the parameter that one wants to add.
instrument – The “parent” instrument this parameter is attached to, if any.
initial_value – Starting value, may be None even if None does not pass the validator. None is only allowed as an initial value and cannot be set after initiation.
**kwargs – Passed to InstrumentRefParameter parent class

__getitem__(keys: Any) → qcodes.instrument.sweep_values.SweepFixedValues: Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

get_raw() → Any: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

property gettable: bool: Is it allowed to call get on this parameter?

increment(value: Any) → None

Increment the parameter with a value

Parameters: value – Value to be added to the parameter.

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_raw(value: Any) → None: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) → qcodes.instrument.sweep_values.SweepFixedValues

Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.

Parameters

start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.

Returns

Collection of parameter values to be iterated over.

Return type

SweepFixedValues

Examples

>>> sweep(0, 10, num=5)
 [0.0, 2.5, 5.0, 7.5, 10.0]
>>> sweep(5, 10, step=1)
[5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> sweep(15, 10.5, step=1.5)
>[15.0, 13.5, 12.0, 10.5]

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

label: str = (): Label of the data used for plots etc.

unit = (): The unit of measure. Use '' for unitless.

get_instr() → InstrumentBase[source]: Returns the instance of the instrument with the name equal to the value of this parameter.

class qcodes.instrument.parameter.ManualParameter(name: str, instrument: Optional[InstrumentBase] = None, initial_value: Any = None, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter.Parameter

A simple alias for a parameter that does not have a set or a get function. Useful for parameters that do not have a direct instrument mapping.

__getitem__(keys: Any) → qcodes.instrument.sweep_values.SweepFixedValues: Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

get_raw() → Any: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

property gettable: bool: Is it allowed to call get on this parameter?

increment(value: Any) → None

Increment the parameter with a value

Parameters: value – Value to be added to the parameter.

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_raw(value: Any) → None: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) → qcodes.instrument.sweep_values.SweepFixedValues

Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.

Parameters

start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.

Returns

Collection of parameter values to be iterated over.

Return type

SweepFixedValues

Examples

>>> sweep(0, 10, num=5)
 [0.0, 2.5, 5.0, 7.5, 10.0]
>>> sweep(5, 10, step=1)
[5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> sweep(15, 10.5, step=1.5)
>[15.0, 13.5, 12.0, 10.5]

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

label: str = (): Label of the data used for plots etc.

unit = (): The unit of measure. Use '' for unitless.

class qcodes.instrument.parameter.MultiParameter(name: str, names: Sequence[str], shapes: Sequence[Sequence[int]], instrument: Optional[InstrumentBase] = None, labels: Optional[Sequence[str]] = None, units: Optional[Sequence[str]] = None, setpoints: Optional[Sequence[Sequence[Any]]] = None, setpoint_names: Optional[Sequence[Sequence[str]]] = None, setpoint_labels: Optional[Sequence[Sequence[str]]] = None, setpoint_units: Optional[Sequence[Sequence[str]]] = None, docstring: Optional[str] = None, snapshot_get: bool = True, snapshot_value: bool = False, snapshot_exclude: bool = False, metadata: Optional[Mapping[Any, Any]] = None, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter._BaseParameter

A gettable parameter that returns multiple values with separate names, each of arbitrary shape. Not necessarily part of an instrument.

Subclasses should define a .get_raw method, which returns a sequence of values. This method is automatically wrapped to provide a .get method. When used in a legacy method``Loop`` or Measure operation, each of these values will be entered into a different DataArray. The constructor args describe what data we expect from each .get call and how it should be handled. .get should always return the same number of items, and most of the constructor arguments should be tuples of that same length.

For now you must specify upfront the array shape of each item returned by .get_raw, and this cannot change from one call to the next. Later, we intend to require only that you specify the dimension of each item returned, and the size of each dimension can vary from call to call.

Parameters

name – The local name of the whole parameter. Should be a valid identifier, ie no spaces or special characters. If this parameter is part of an Instrument or Station, this is how it will be referenced from that parent, i.e. instrument.name or instrument.parameters[name].
names – A name for each item returned by a .get call. Will be used as the basis of the DataArray names when this parameter is used to create a DataSet.
shapes – The shape (as used in numpy arrays) of each item. Scalars should be denoted by (), 1D arrays as (n,), 2D arrays as (n, m), etc.
instrument – The instrument this parameter belongs to, if any.
labels – A label for each item. Normally used as the axis label when a component is graphed, along with the matching entry from units.
units – A unit of measure for each item. Use '' or None for unitless values.
setpoints – array can be a DataArray, numpy.ndarray, or sequence. The setpoints for each returned array. An N-dimension item should have N setpoint arrays, where the first is 1D, the second 2D, etc. If omitted for any or all items, defaults to integers from zero in each respective direction. Note: if the setpoints will be different each measurement, leave this out and return the setpoints (with extra names) in .get.
setpoint_names – One identifier (like name) per setpoint array. Ignored if a setpoint is a DataArray, which already has a name.
setpoint_labels – One label (like labels) per setpoint array. Ignored if a setpoint is a DataArray, which already has a label.
setpoint_units – One unit (like V) per setpoint array. Ignored if a setpoint is a DataArray, which already has a unit.
docstring – Documentation string for the __doc__ field of the object. The __doc__ field of the instance is used by some help systems, but not all
snapshot_get – Prevent any update to the parameter, for example if it takes too long to update. Default True.
snapshot_value – Should the value of the parameter be stored in the snapshot. Unlike Parameter this defaults to False as MultiParameters are potentially huge.
snapshot_exclude – True prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot. Default False.
metadata – Extra information to include with the JSON snapshot of the parameter.

property short_names: Tuple[str, ...]

short_names is identical to names i.e. the names of the parameter parts but does not add the instrument name.

It exists for consistency with instruments and other parameters.

property full_names: Tuple[str, ...]: Names of the parameter components including the name of the instrument and submodule that the parameter may be bound to. The name parts are separated by underscores, like this: instrument_submodule_parameter

property setpoint_full_names: Optional[Sequence[Sequence[str]]]: Full names of setpoints including instrument names, if available

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

get_raw() → Any: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

property gettable: bool: Is it allowed to call get on this parameter?

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_raw(value: Any) → None: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

class qcodes.instrument.parameter.Parameter(name: str, instrument: Optional[InstrumentBase] = None, label: Optional[str] = None, unit: Optional[str] = None, get_cmd: Optional[Union[str, Callable[[...], Any], bool]] = None, set_cmd: Optional[Union[str, Callable[[...], Any], bool]] = False, initial_value: Optional[Union[float, str]] = None, max_val_age: Optional[float] = None, vals: Optional[qcodes.utils.validators.Validator[Any]] = None, docstring: Optional[str] = None, initial_cache_value: Optional[Union[float, str]] = None, bind_to_instrument: bool = True, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter._BaseParameter

A parameter represents a single degree of freedom. Most often, this is the standard parameter for Instruments, though it can also be used as a variable, i.e. storing/retrieving a value, or be subclassed for more complex uses.

By default only gettable, returning its last value. This behaviour can be modified in two ways:

Providing a get_cmd/set_cmd, which can do the following:
1. callable, with zero args for get_cmd, one arg for set_cmd
2. VISA command string
3. None, in which case it retrieves its last value for get_cmd, and stores a value for set_cmd
4. False, in which case trying to get/set will raise an error.
Creating a subclass with an explicit get_raw()/set_raw() method.

This enables more advanced functionality. The get_raw() and set_raw() methods are automatically wrapped to provide get and set.

It is an error to do both 1 and 2. E.g supply a get_cmd/set_cmd and implement get_raw/set_raw

To detect if a parameter is gettable or settable check the attributes gettable and settable on the parameter.

Parameters have a cache object that stores internally the current value and raw_value of the parameter. Calling cache.get() (or cache()) simply returns the most recent set or measured value of the parameter.

Parameter also has a .get_latest method that duplicates the behavior of cache() call, as in, it also simply returns the most recent set or measured value.

Parameters

name – The local name of the parameter. Should be a valid identifier, ie no spaces or special characters. If this parameter is part of an Instrument or Station, this is how it will be referenced from that parent, ie instrument.name or instrument.parameters[name].
instrument – The instrument this parameter belongs to, if any.
label – Normally used as the axis label when this parameter is graphed, along with unit.
unit – The unit of measure. Use '' for unitless.
snapshot_get – False prevents any update to the parameter during a snapshot, even if the snapshot was called with update=True, for example, if it takes too long to update, or if the parameter is only meant for measurements hence calling get on it during snapshot may be an error. Default True.
snapshot_value – False prevents parameter value to be stored in the snapshot. Useful if the value is large.
snapshot_exclude – True prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot. Default False.
step – Max increment of parameter value. Larger changes are broken into multiple steps this size. When combined with delays, this acts as a ramp.
scale – Scale to multiply value with before performing set. the internally multiplied value is stored in cache.raw_value. Can account for a voltage divider.
inter_delay – Minimum time (in seconds) between successive sets. If the previous set was less than this, it will wait until the condition is met. Can be set to 0 to go maximum speed with no errors.
post_delay – Time (in seconds) to wait after the start of each set, whether part of a sweep or not. Can be set to 0 to go maximum speed with no errors.
val_mapping – A bi-directional map data/readable values to instrument codes, expressed as a dict: {data_val: instrument_code} For example, if the instrument uses ‘0’ to mean 1V and ‘1’ to mean 10V, set val_mapping={1: ‘0’, 10: ‘1’} and on the user side you only see 1 and 10, never the coded ‘0’ and ‘1’ If vals is omitted, will also construct a matching Enum validator. NOTE only applies to get if get_cmd is a string, and to set if set_cmd is a string. You can use val_mapping with get_parser, in which case get_parser acts on the return value from the instrument first, then val_mapping is applied (in reverse).
get_parser – Function to transform the response from get to the final output value. See also val_mapping.
set_parser – Function to transform the input set value to an encoded value sent to the instrument. See also val_mapping.
vals – Allowed values for setting this parameter. Only relevant if settable. Defaults to Numbers().
max_val_age – The max time (in seconds) to trust a saved value obtained from cache() (or cache.get(), or get_latest(). If this parameter has not been set or measured more recently than this, perform an additional measurement.
initial_value – Value to set the parameter to at the end of its initialization (this is equivalent to calling parameter.set(initial_value) after parameter initialization). Cannot be passed together with initial_cache_value argument.
initial_cache_value – Value to set the cache of the parameter to at the end of its initialization (this is equivalent to calling parameter.cache.set(initial_cache_value) after parameter initialization). Cannot be passed together with initial_value argument.
docstring – Documentation string for the __doc__ field of the object. The __doc__ field of the instance is used by some help systems, but not all.
metadata – Extra information to include with the JSON snapshot of the parameter.
abstract – Specifies if this parameter is abstract or not. Default is False. If the parameter is ‘abstract’, it must be overridden by a non-abstract parameter before the instrument containing this parameter can be instantiated. We override a parameter by adding one with the same name and unit. An abstract parameter can be added in a base class and overridden in a subclass.
bind_to_instrument – Should the parameter be registered as a delegate attribute on the instrument passed via the instrument argument.

get_raw() → Any: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

set_raw(value: Any) → None: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

label: str = (): Label of the data used for plots etc.

unit = (): The unit of measure. Use '' for unitless.

__getitem__(keys: Any) → qcodes.instrument.sweep_values.SweepFixedValues[source]: Slice a Parameter to get a SweepValues object to iterate over during a sweep

increment(value: Any) → None[source]

Increment the parameter with a value

Parameters: value – Value to be added to the parameter.

sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) → qcodes.instrument.sweep_values.SweepFixedValues[source]

Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.

Parameters

start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.

Returns

Collection of parameter values to be iterated over.

Return type

SweepFixedValues

Examples

>>> sweep(0, 10, num=5)
 [0.0, 2.5, 5.0, 7.5, 10.0]
>>> sweep(5, 10, step=1)
[5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> sweep(15, 10.5, step=1.5)
>[15.0, 13.5, 12.0, 10.5]

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

property gettable: bool: Is it allowed to call get on this parameter?

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

class qcodes.instrument.parameter.ParameterWithSetpoints(name: str, *, vals: Optional[qcodes.utils.validators.Validator[Any]] = None, setpoints: Optional[Sequence[qcodes.instrument.parameter._BaseParameter]] = None, snapshot_get: bool = False, snapshot_value: bool = False, **kwargs: Any)[source]

Bases: qcodes.instrument.parameter.Parameter

A parameter that has associated setpoints. The setpoints is nothing more than a list of other parameters that describe the values, names and units of the setpoint axis for this parameter.

In most cases this will probably be a parameter that returns an array. It is expected that the setpoint arrays are 1D arrays such that the combined shape of the parameter e.g. if parameter is of shape (m,n) setpoints is a list of parameters of shape (m,) and (n,)

In all other ways this is identical to Parameter. See the documentation of Parameter for more details.

property setpoints: Sequence[qcodes.instrument.parameter._BaseParameter]

Sequence of parameters to use as setpoints for this parameter.

Getter: Returns a list of parameters currently used for setpoints.
Setter: Sets the parameters to be used as setpoints from a sequence. The combined shape of the parameters supplied must be consistent with the data shape of the data returned from get on the parameter.

validate_consistent_shape() → None[source]: Verifies that the shape of the Array Validator of the parameter is consistent with the Validator of the Setpoints. This requires that both the setpoints and the actual parameters have validators of type Arrays with a defined shape.

validate(value: Any) → None[source]

Overwrites the standard validate method to also check the the parameter has consistent shape with its setpoints. This only makes sense if the parameter has an Arrays validator

Arguments are passed to the super method

__getitem__(keys: Any) → qcodes.instrument.sweep_values.SweepFixedValues: Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

get_raw() → Any: get_raw is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if get_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a get method on the parameter instance.

property gettable: bool: Is it allowed to call get on this parameter?

increment(value: Any) → None

Increment the parameter with a value

Parameters: value – Value to be added to the parameter.

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_raw(value: Any) → None: set_raw is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively for Parameter a suitable method is automatically generated if set_cmd is supplied to the parameter constructor. The method is automatically wrapped to provide a set method on the parameter instance.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) → qcodes.instrument.sweep_values.SweepFixedValues

Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.

Parameters

start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.

Returns

Collection of parameter values to be iterated over.

Return type

SweepFixedValues

Examples

>>> sweep(0, 10, num=5)
 [0.0, 2.5, 5.0, 7.5, 10.0]
>>> sweep(5, 10, step=1)
[5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> sweep(15, 10.5, step=1.5)
>[15.0, 13.5, 12.0, 10.5]

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

label: str = (): Label of the data used for plots etc.

cache: qcodes.instrument.parameter._CacheProtocol = ()

get_latest: qcodes.instrument.parameter.GetLatest = ()

get: Callable[[...], Any] = ()

set: Callable[[...], None] = ()

unit = (): The unit of measure. Use '' for unitless.

class qcodes.instrument.parameter.ScaledParameter(output: qcodes.instrument.parameter.Parameter, division: Optional[Union[float, qcodes.instrument.parameter.Parameter]] = None, gain: Optional[Union[float, qcodes.instrument.parameter.Parameter]] = None, name: Optional[str] = None, label: Optional[str] = None, unit: Optional[str] = None)[source]

Bases: qcodes.instrument.parameter.Parameter

Parameter Scaler

To be used when you use a physical voltage divider or an amplifier to set or get a quantity.

Initialize the parameter by passing the parameter to be measured/set and the value of the division OR the gain.

The scaling value can be either a scalar value or a Qcodes Parameter.

The parameter scaler acts a your original parameter, but will set the right value, and store the gain/division in the metadata.

Examples

Resistive voltage divider >>> vd = ScaledParameter(dac.chan0, division = 10)

Voltage multiplier >>> vb = ScaledParameter(dac.chan0, gain = 30, name = ‘Vb’)

Transimpedance amplifier >>> Id = ScaledParameter(multimeter.amplitude, … division = 1e6, name = ‘Id’, unit = ‘A’)

Parameters

output – Physical Parameter that need conversion.
division – The division value.
gain – The gain value.
label – Label of this parameter, by default uses ‘output’ label but attaches _amplified or _attenuated depending if gain or division has been specified.
name – Name of this parameter, by default uses ‘output’ name but attaches _amplified or _attenuated depending if gain or division has been specified.
unit – Resulting unit. It uses the one of ‘output’ by default.

__getitem__(keys: Any) → qcodes.instrument.sweep_values.SweepFixedValues: Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__() → str: Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str: Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this: instrument_submodule_parameter.

get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) → Sequence[Union[float, Sized]]

Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.

Parameters

value – target value
step – maximum step size

Returns

List of stepped values, including target value.

property gettable: bool: Is it allowed to call get on this parameter?

increment(value: Any) → None

Increment the parameter with a value

Parameters: value – Value to be added to the parameter.

property instrument: Optional[InstrumentBase]: Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use root_instrument() to get the real instrument.

property inter_delay: float

Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

load_metadata(metadata: Dict[Any, Any]) → None

Load metadata into this classes metadata dictionary.

Parameters: metadata – Metadata to load.

property name: str: Name of the parameter. This is identical to short_name().

property name_parts: List[str]: List of the parts that make up the full name of this parameter

property post_delay: float

Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.

Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

TypeError – If delay is not int nor float
ValueError – If delay is negative

property raw_value: Any

Note that this property will be deprecated soon. Use cache.raw_value instead.

Represents the cached raw value of the parameter.

Getter: Returns the cached raw value of the parameter.

restore_at_exit(allow_changes: bool = True) → qcodes.instrument.parameter._SetParamContext

Use a context manager to restore the value of a parameter after a with block.

By default, the parameter value may be changed inside the block, but this can be prevented with allow_changes=False. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.

Example

>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.restore_at_exit():
...     p.set(3)
...     print(f"value inside with block: {p.get()}")  # prints 3
>>> print(f"value after with block: {p.get()}")  # prints 2
>>> with p.restore_at_exit(allow_changes=False):
...     p.set(5)  # raises an exception

property root_instrument: Optional[InstrumentBase]: Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use instrument() to get the channel.

set_to(value: Any, allow_changes: bool = False) → qcodes.instrument.parameter._SetParamContext

Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with allow_changes=True.

Examples

>>> from qcodes import Parameter
>>> p = Parameter("p", set_cmd=None, get_cmd=None)
>>> p.set(2)
>>> with p.set_to(3):
...     print(f"p value in with block {p.get()}")  # prints 3
...     p.set(5)  # raises an exception
>>> print(f"p value outside with block {p.get()}")  # prints 2
>>> with p.set_to(3, allow_changes=True):
...     p.set(5)  # now this works
>>> print(f"value after second block: {p.get()}")  # still prints 2

property settable: bool: Is it allowed to call set on this parameter?

property short_name: str: Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to full_name().

snapshot(update: Optional[bool] = False) → Dict[Any, Any]

Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override snapshot_base().

Parameters: update – Passed to snapshot_base.
Returns: Base snapshot.

snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) → Dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

If the parameter has been initiated with snapshot_value=False, the snapshot will NOT include the value and raw_value of the parameter.

Parameters

update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().
params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool: If True the value of the parameter will be included in the snapshot.

property step: Optional[float]

Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None

sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) → qcodes.instrument.sweep_values.SweepFixedValues

Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.

Parameters

start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.

Returns

Collection of parameter values to be iterated over.

Return type

SweepFixedValues

Examples

>>> sweep(0, 10, num=5)
 [0.0, 2.5, 5.0, 7.5, 10.0]
>>> sweep(5, 10, step=1)
[5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> sweep(15, 10.5, step=1.5)
>[15.0, 13.5, 12.0, 10.5]

property underlying_instrument: Optional[InstrumentBase]

Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.

This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence root_instrument of the parameter cannot be the hardware_instrument, however underlying_instrument can be implemented to return the hardware_instrument.

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

TypeError – If the value is of the wrong type.
ValueError – If the value is outside the bounds specified by the validator.

cache: qcodes.instrument.parameter._CacheProtocol = ()

get_latest: qcodes.instrument.parameter.GetLatest = ()

get: Callable[[...], Any] = ()

set: Callable[[...], None] = ()

class Role(value)[source]

Bases: enum.Enum

An enumeration.

GAIN = 1

DIVISION = 2

label: str = (): Label of the data used for plots etc.

unit = (): The unit of measure. Use '' for unitless.

property division: float

property gain: float

get_raw() → float[source]

Returns: value at which was set at the sample

property wrapped_parameter: qcodes.instrument.parameter.Parameter: The attached unscaled parameter

get_wrapped_parameter_value() → float[source]

Returns: value at which the attached parameter is (i.e. does not account for the scaling)

set_raw(value: float) → None[source]: Set the value on the wrapped parameter, accounting for the scaling

qcodes.instrument.parameter.combine(*parameters: qcodes.instrument.parameter.Parameter, name: str, label: Optional[str] = None, unit: Optional[str] = None, units: Optional[str] = None, aggregator: Optional[Callable[[Sequence[Any]], Any]] = None) → qcodes.instrument.parameter.CombinedParameter[source]

Combine parameters into one sweepable parameter

A combined parameter sets all the combined parameters at every point of the sweep. The sets are called in the same order the parameters are, and sequentially.

Parameters

*parameters – The parameters to combine.
name – The name of the paramter.
label – The label of the combined parameter.
unit – the unit of the combined parameter.
aggregator – a function to aggregate the set values into one.

qcodes.instrument.parameter.expand_setpoints_helper(parameter: qcodes.instrument.parameter.ParameterWithSetpoints, results: Optional[Any] = None) → List[Tuple[qcodes.instrument.parameter._BaseParameter, Any]][source]

A helper function that takes a ParameterWithSetpoints and acquires the parameter along with it’s setpoints. The data is returned in a format prepared to insert into the dataset.

Parameters

parameter – A ParameterWithSetpoints to be acquired and expanded
results – The data for the given parameter. Typically the output of parameter.get(). If None this function will call parameter.get

Returns

A list of tuples of parameters and values for the specified parameter and its setpoints.

qcodes.instrument.parameter.invert_val_mapping(val_mapping: Mapping[Any, Any]) → Dict[Any, Any][source]: Inverts the value mapping dictionary for allowed parameter values