qcodes.parameters

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 ParameterBase (except CombinedParameter). The ParameterBase 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.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.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.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__.

Classes:

ArrayParameter(name, shape[, instrument, ...])

A gettable parameter that returns an array of values.

CombinedParameter(parameters, name[, label, ...])

A combined parameter.

DelegateGroup(name, parameters[, ...])

The DelegateGroup combines DelegateParameter s that are to be gotten or set using one GroupedParameter.

DelegateGroupParameter(name, source[, ...])

DelegateParameter(name, source, *args, **kwargs)

The DelegateParameter wraps a given source Parameter.

ElapsedTimeParameter(name[, label])

Parameter to measure elapsed time.

Function(name[, instrument, call_cmd, args, ...])

Defines a function that an instrument can execute.

Group(parameters[, set_cmd, get_cmd, ...])

The group combines GroupParameter s that are to be gotten or set via the same command.

GroupParameter(name[, instrument, initial_value])

Group parameter is a Parameter, whose value can be set or get only with other group parameters.

GroupedParameter(name, group[, unit, label])

The GroupedParameter wraps one or more DelegateParameter s, such that those parameters can be accessed as if they were one parameter.

InstrumentRefParameter(name[, instrument, ...])

An instrument reference parameter.

ManualParameter(name[, instrument, ...])

A simple alias for a parameter that does not have a set or a get function.

MultiChannelInstrumentParameter(channels, ...)

Parameter to get or set multiple channels simultaneously.

MultiParameter(name, names, shapes[, ...])

A gettable parameter that returns multiple values with separate names, each of arbitrary shape.

ParamDataType

alias of Any

ParamRawDataType

alias of Any

Parameter(name[, instrument, label, unit, ...])

A parameter represents a single degree of freedom.

ParameterBase(name, instrument[, ...])

Shared behavior for all parameters.

ParameterWithSetpoints(name, *[, vals, ...])

A parameter that has associated setpoints.

ScaledParameter(output[, division, gain, ...])

Parameter Scaler

SweepFixedValues(parameter[, keys, start, ...])

A fixed collection of parameter values to be iterated over during a sweep.

SweepValues(parameter, **kwargs)

Base class for sweeping a parameter.

Functions:

combine(*parameters, name[, label, unit, ...])

Combine parameters into one sweepable parameter

create_on_off_val_mapping([on_val, off_val])

Returns a value mapping which maps inputs which reasonably mean "on"/"off" to the specified on_val/off_val which are to be sent to the instrument.

expand_setpoints_helper(parameter[, results])

A helper function that takes a ParameterWithSetpoints and acquires the parameter along with it's setpoints.

invert_val_mapping(val_mapping)

Inverts the value mapping dictionary for allowed parameter values

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

Bases: ParameterBase

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.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.

  • setpointsarray 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.

Methods:

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

validate(value)

Validate the value supplied.

Attributes:

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

setpoint_full_names

Full names of setpoints including instrument names if available

__str__() str

Include the instrument name with the Parameter name if possible.

property abstract: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: InstrumentBase | None

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

property setpoint_full_names: Sequence[str] | None

Full names of setpoints including instrument names if available

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

Bases: 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

  • units – Deprecated argument left for backwards compatibility. Do not use.

  • aggregator – A function to aggregate the set values into one

Methods:

set(index)

Set multiple parameters.

sweep(*array)

Creates a new combined parameter to be iterated over.

snapshot_base([update, params_to_skip_update])

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

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

snapshot([update])

Decorate a snapshot dictionary with metadata.

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: ndarray) 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: bool | None = False, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any][source]

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

Parameters:
  • updateTrue or False.

  • params_to_skip_update – Unused in this subclass.

Returns:

Base snapshot.

Return type:

dict

load_metadata(metadata: Mapping[str, Any]) None

Load metadata into this classes metadata dictionary.

Parameters:

metadata – Metadata to load.

snapshot(update: bool | None = False) dict[str, 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.parameters.DelegateGroup(name: str, parameters: Sequence[DelegateGroupParameter], parameter_names: Iterable[str] | None = None, setter: Callable[..., Any] | None = None, getter: Callable[..., Any] | None = None, formatter: Callable[..., Any] | None = None, **kwargs: Any)[source]

Bases: Group

The DelegateGroup combines DelegateParameter s that are to be gotten or set using one GroupedParameter. Each DelegateParameter maps to one source parameter that is individually set or gotten on an instrument. These parameters can originate from the same or different instruments.

The class DelegateGroup is used within the GroupedParameter class in order to get and set the DelegateParameter s either via their default get and set methods or via a custom get or set method.

The value to be set can be passed to the set method either via a dictionary, where the keys are the names of the DelegateParameter s contained in the DelegateGroup, or a single value, if a custom setter is defined or if the group only contains a single DelegateParameter.

The value returned by the get method is passed through a formatter. By default, the formatter returns the DelegateParameter values in a namedtuple, where the keys are the names of the DelegateParameter s. In the special case where the DelegateGroup only contains one DelegateParameter, the formatter simply returns the individual value. Optionally, the formatter can be customized and specified via the constructor. The formatter takes as input the values of the DelegateParameter s as positional arguments in the order at which the DelegateParameter s are specified.

Parameters:
  • name – Name of the DelegateGroup

  • parameters – DelegateParameters to group together

  • parameter_names – Optional names of parameters, defaults to the parameter name attributes

  • setter – Optional function to call for setting the grouped parameters, should take one argument value. Defaults to set_parameters(), which sets each parameter using its .set() method.

  • getter – Optional function to call for getting the grouped parameters. Defaults to .get_parameters(), which runs the get() method for each parameter.

  • formatter – Optional formatter for value returned by get_parameters(), defaults to a namedtuple with the parameter names as keys.

Methods:

set(value)

get()

get_parameters()

set_parameters(parameters_dict)

Sets the value of one or more parameters within a group to the given values by calling the set_cmd while updating rest.

update()

Update the values of all the parameters within the group by calling the get_cmd.

Attributes:

source_parameters

Get source parameters of each DelegateParameter

instrument

The root_instrument that this parameter belongs to.

parameters

All parameters in this group as a dict from parameter name to Parameter

set(value: ParamDataType | Mapping[str, ParamDataType]) None[source]
get() Any[source]
get_parameters() Any[source]
property source_parameters: tuple[Parameter | None, ...]

Get source parameters of each DelegateParameter

property instrument: InstrumentBase | None

The root_instrument that this parameter belongs to.

property parameters: OrderedDict[str, GroupParameter]

All parameters in this group as a dict from parameter name to Parameter

set_parameters(parameters_dict: Mapping[str, ParamDataType]) None

Sets the value of one or more parameters within a group to the given values by calling the set_cmd while updating rest.

Parameters:
  • parameters_dict – The dictionary of one or more parameters within

  • set. (the group with the corresponding values to be)

update() None

Update the values of all the parameters within the group by calling the get_cmd.

class qcodes.parameters.DelegateGroupParameter(name: str, source: Parameter | None, instrument: InstrumentBase | None = None, initial_value: float | str | None = None, **kwargs: Any)[source]

Bases: DelegateParameter, GroupParameter

Methods:

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

increment(value)

Increment the parameter with a value

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

validate(value)

Validate the supplied value.

Attributes:

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

group

The group that this parameter belongs to.

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

label

Label of the data used for plots etc.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

source

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

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

unit

The unit of measure.

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

__getitem__(keys: Any) 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: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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 group: Group | None

The group that this parameter belongs to.

increment(value: Any) None

Increment the parameter with a value

Parameters:

value – Value to be added to the parameter.

property instrument: InstrumentBase | None

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:
property label: str

Label of the data used for plots etc. Read from source if not explicitly overwritten. Set to None to disable overwrite.

load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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 source: Parameter | None

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.

property step: float | None

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: float | None = None, num: int | None = None) 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: InstrumentBase | None

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.

property unit: str

The unit of measure. Read from source if not explicitly overwritten. Set to None to disable overwrite.

validate(value: ParamDataType) None

Validate the supplied value. If it has a source parameter, validate the value as well with the source validator.

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

class qcodes.parameters.DelegateParameter(name: str, source: Parameter | None, *args: Any, **kwargs: Any)[source]

Bases: 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.

Attributes:

source

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

snapshot_value

If True the value of the parameter will be included in the snapshot.

unit

The unit of measure.

label

Label of the data used for plots etc.

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

short_name

Short name of the parameter.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

settable

Is it allowed to call set on this parameter?

Methods:

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

increment(value)

Increment the parameter with a value

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

snapshot_base([update, params_to_skip_update])

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

validate(value)

Validate the supplied value.

property source: Parameter | None

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.

property snapshot_value: bool

If True the value of the parameter will be included in the snapshot.

property unit: str

The unit of measure. Read from source if not explicitly overwritten. Set to None to disable overwrite.

property label: str

Label of the data used for plots etc. Read from source if not explicitly overwritten. Set to None to disable overwrite.

__getitem__(keys: Any) 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: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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 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: bool | None = False) dict[str, 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 step: float | None

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: float | None = None, num: int | None = None) 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: InstrumentBase | None

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

property settable: bool

Is it allowed to call set on this parameter?

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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any][source]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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

validate(value: ParamDataType) None[source]

Validate the supplied value. If it has a source parameter, validate the value as well with the source validator.

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.parameters.ElapsedTimeParameter(name: str, label: str = 'Elapsed time', **kwargs: Any)[source]

Bases: Parameter

Parameter to measure elapsed time. Measures wall clock time since the last reset of the instance’s clock. The clock is reset upon creation of the instance. The constructor passes kwargs along to the Parameter constructor.

Parameters:

name – The local name of the parameter. See the documentation of qcodes.parameters.Parameter for more details.

Methods:

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

reset_clock()

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

increment(value)

Increment the parameter with a value

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

validate(value)

Validate the value supplied.

Attributes:

t0

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

label

Label of the data used for plots etc.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

unit

The unit of measure.

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

get_raw() float[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.

reset_clock() None[source]
property t0: float
__getitem__(keys: Any) 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: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
property label: str

Label of the data used for plots etc.

load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: float | None = None, num: int | None = None) 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: InstrumentBase | None

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.

property unit: str

The unit of measure. Use '' (the empty string) for unitless.

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

class qcodes.parameters.Function(name: str, instrument: InstrumentBase | None = None, call_cmd: str | Callable[..., Any] | None = None, args: Sequence[Validator[Any]] | None = None, arg_parser: Callable[..., Any] | None = None, return_parser: Callable[..., Any] | None = None, docstring: str | None = None, **kwargs: Any)[source]

Bases: MetadatableWithName

Defines a function that an instrument can execute.

This class is meant for simple cases, principally things that map to simple commands like *RST (reset) or those with just a few arguments. It requires a fixed argument count, and positional args only.

You execute this function object like a normal function, or use its .call method.

Note

Parsers only apply if call_cmd is a string. The function form of call_cmd should do its own parsing.

Note

We do not recommend the usage of Function for any new driver. Function does not add any significant features over a method defined on the class.

Parameters:
  • name – the local name of this function

  • instrument – an instrument that handles this function. Default None.

  • call_cmd

    command to execute on the instrument:

    • a string (with positional fields to .format, “{}” or “{0}” etc) you can only use a string if an instrument is provided, this string will be passed to instrument.write

    • a function (with arg count matching args list)

  • args – list of Validator objects, one for each arg to the Function

  • arg_parser – function to transform the input arg(s) to encoded value(s) sent to the instrument. If there are multiple arguments, this function should accept all the arguments in order, and return a tuple of values.

  • return_parser – function to transform the response from the instrument to the final output value. may be a type casting function like int or float. If None (default), will not wait for or read any response.

  • 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 (particularly not builtin help())

  • **kwargs – Arbitrary keyword arguments passed to parent class

Methods:

validate(*args)

Check that all arguments to this Function are allowed.

call(*args)

Call methods wraps __call__

get_attrs()

Attributes recreated as properties in the RemoteFunction proxy.

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

Override this with the primary information for a subclass.

Attributes:

short_name

Name excluding name of any instrument that this function may be bound to.

full_name

Name of the function including the name of the instrument and submodule that the function may be bound to.

name_parts

List of the parts that make up the full name of this function

instrument

validate(*args: Any) None[source]

Check that all arguments to this Function are allowed.

Parameters:

*args – Variable length argument list, passed to the call_cmd

call(*args: Any) Any[source]

Call methods wraps __call__

Parameters:

*args – argument to pass to Command __call__ function

get_attrs() list[str][source]

Attributes recreated as properties in the RemoteFunction proxy.

Returns (list): __doc__, _args, and _arg_count get proxied

property short_name: str

Name excluding name of any instrument that this function may be bound to.

property full_name: str

Name of the function including the name of the instrument and submodule that the function may be bound to. The names are separated by underscores, like this: instrument_submodule_function.

property name_parts: list[str]

List of the parts that make up the full name of this function

property instrument: InstrumentBase | None
load_metadata(metadata: Mapping[str, Any]) None

Load metadata into this classes metadata dictionary.

Parameters:

metadata – Metadata to load.

snapshot(update: bool | None = False) dict[str, 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: bool | None = False, params_to_skip_update: Sequence[str] | None = None) dict[str, Any]

Override this with the primary information for a subclass.

class qcodes.parameters.Group(parameters: Sequence[GroupParameter], set_cmd: str | None = None, get_cmd: str | Callable[[], str] | None = None, get_parser: Callable[[str], Mapping[str, Any]] | None = None, separator: str = ',', single_instrument: bool = True)[source]

Bases: object

The group combines GroupParameter s that are to be gotten or set via the same command. The command has to be a string, for example, a VISA command.

The Group’s methods are used within GroupParameter in order to properly implement setting and getting of a single parameter in the situation where one command sets or gets more than one parameter.

The command used for setting values of parameters has to be a format string which contains the names of the parameters the group has been initialized with. For example, if a command has syntax CMD a_value, b_value, where a_value and b_value are values of two parameters with names a and b, then the command string has to be CMD {a}, {b}, and the group has to be initialized with two GroupParameter s a_param and b_param, where a_param.name=="a" and b_param.name=="b".

Note that by default, it is assumed that the command used for getting values returns a comma-separated list of values of parameters, and their order corresponds to the order of GroupParameter s in the list that is passed to the Group’s constructor. Through keyword arguments of the Group’s constructor, it is possible to change the separator, and even the parser of the output of the get command.

The get and set commands are called via the instrument that the first parameter belongs to. It is assumed that all the parameters within the group belong to the same instrument.

Example

class InstrumentWithGroupParameters(VisaInstrument):
    def __init__(self, name, address, **kwargs):
        super().__init__(name, address, **kwargs)

        ...

        # Here is how group of group parameters is defined for
        # a simple case of an example "SGP" command that sets and gets
        # values of "enabled" and "gain" parameters (it is assumed that
        # "SGP?" returns the parameter values as comma-separated list
        # "enabled_value,gain_value")
        self.add_parameter('enabled',
                           label='Enabled',
                           val_mapping={True: 1, False: 0},
                           parameter_class=GroupParameter)
        self.add_parameter('gain',
                           label='Some gain value',
                           get_parser=float,
                           parameter_class=GroupParameter)
        self.output_group = Group([self.enabled, self.gain],
                                  set_cmd='SGP {enabled}, {gain}',
                                  get_cmd='SGP?')

        ...
Parameters:
  • parameters – a list of GroupParameter instances which have to be gotten and set via the same command; the order of parameters in the list should correspond to the order of the values returned by the get_cmd.

  • set_cmd – Format string of the command that is used for setting the values of the parameters; for example, CMD {a}, {b}.

  • get_cmd – String of the command that is used for getting the values of the parameters; for example, CMD?. Can also be a callable that returns a command string, this is useful for the cases where the command string is dynamic; for example, lambda: f"CMD {get_id_that_specifies_the_command()} ?".

  • separator – A separator that is used when parsing the output of the get_cmd in order to obtain the values of the parameters; it is ignored in case a custom get_parser is used.

  • get_parser – A callable with a single string argument that is used to parse the output of the get_cmd; the callable has to return a dictionary where parameter names are keys, and the values are the values (as directly obtained from the output of the get command; note that parsers within the parameters will take care of individual parsing of their values).

  • single_instrument – A flag to indicate that all parameters belong to a

  • instrument (single)

  • True. (which in turn does additional checks. Defaults to)

Methods:

set_parameters(parameters_dict)

Sets the value of one or more parameters within a group to the given values by calling the set_cmd while updating rest.

update()

Update the values of all the parameters within the group by calling the get_cmd.

Attributes:

parameters

All parameters in this group as a dict from parameter name to Parameter

instrument

The root_instrument that this parameter belongs to.

set_parameters(parameters_dict: Mapping[str, ParamDataType]) None[source]

Sets the value of one or more parameters within a group to the given values by calling the set_cmd while updating rest.

Parameters:
  • parameters_dict – The dictionary of one or more parameters within

  • set. (the group with the corresponding values to be)

update() None[source]

Update the values of all the parameters within the group by calling the get_cmd.

property parameters: OrderedDict[str, GroupParameter]

All parameters in this group as a dict from parameter name to Parameter

property instrument: InstrumentBase | None

The root_instrument that this parameter belongs to.

class qcodes.parameters.GroupParameter(name: str, instrument: InstrumentBase | None = None, initial_value: float | int | str | None = None, **kwargs: Any)[source]

Bases: Parameter

Group parameter is a Parameter, whose value can be set or get only with other group parameters. This happens when an instrument has commands which set and get more than one parameter per call.

The set_raw method of a group parameter forwards the call to the group, and the group then makes sure that the values of other parameters within the group are left unchanged. The get_raw method of a group parameter also forwards the call to the group, and the group makes sure that the command output is parsed correctly, and the value of the parameter of interest is returned.

After initialization, the group parameters need to be added to a group. See Group for more information.

Parameters:
  • name – Name of the parameter.

  • instrument – Instrument that this parameter belongs to; this instrument is used by the group to call its get and set commands.

  • initial_value – Initial value of the parameter. Note that either none or all of the parameters in a Group should have an initial value.

  • **kwargs – All kwargs used by the Parameter class, except set_cmd and get_cmd.

Attributes:

group

The group that this parameter belongs to.

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

label

Label of the data used for plots etc.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

unit

The unit of measure.

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

Methods:

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

increment(value)

Increment the parameter with a value

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

validate(value)

Validate the value supplied.

property group: Group | None

The group that this parameter belongs to.

get_raw() ParamRawDataType[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: ParamRawDataType) 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.

__getitem__(keys: Any) 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: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
property label: str

Label of the data used for plots etc.

load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: float | None = None, num: int | None = None) 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: InstrumentBase | None

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.

property unit: str

The unit of measure. Use '' (the empty string) for unitless.

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

class qcodes.parameters.GroupedParameter(name: str, group: DelegateGroup, unit: str | None = None, label: str | None = None, **kwargs: Any)[source]

Bases: ParameterBase

The GroupedParameter wraps one or more DelegateParameter s, such that those parameters can be accessed as if they were one parameter.

The GroupedParameter uses a DelegateGroup to keep track of the DelegateParameter s. Mainly, this class is a thin wrapper around the DelegateGroup, and mainly exists in order to allow for it to be used as a ParameterBase.

This class can be seen as the opposite of a GroupParameter, which is a class to create parameters that are set with a single get and set string command on the same instrument but need to be accessed separately. In contrast, the GroupedParameter allows grouped access to parameters that are normally separate, and can be associated with different instruments.

Parameters:
  • name – Grouped parameter name.

  • group – Group that contains the target parameter(s).

  • unit – The unit of measure. Use '' for unitless.

  • label – Optional label, defaults to parameter name.

  • method (default set)

Attributes:

group

The group that contains the target parameters.

parameters

Get delegate parameters wrapped by this GroupedParameter

source_parameters

Get source parameters of each DelegateParameter

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

Methods:

get_raw()

Get parameter raw value

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

Set parameter raw value

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

validate(value)

Validate the value supplied.

property group: DelegateGroup

The group that contains the target parameters.

property parameters: dict[str, GroupParameter]

Get delegate parameters wrapped by this GroupedParameter

property source_parameters: tuple[Parameter | None, ...]

Get source parameters of each DelegateParameter

get_raw() ParamDataType | Mapping[str, ParamDataType][source]

Get parameter raw value

__str__() str

Include the instrument name with the Parameter name if possible.

property abstract: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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: ParamDataType | Mapping[str, ParamDataType]) None[source]

Set parameter raw value

Parameters:

value – Parameter value to set

Returns:

Returns the parameter value

Return type:

float

set_to(value: Any, allow_changes: bool = False) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: InstrumentBase | None

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

class qcodes.parameters.InstrumentRefParameter(name: str, instrument: InstrumentBase | None = None, label: str | None = None, unit: str | None = None, get_cmd: str | Callable[..., Any] | Literal[False] | None = None, set_cmd: str | Callable[..., Any] | Literal[False] | None = None, initial_value: float | str | None = None, max_val_age: float | None = None, vals: Validator[Any] | None = None, docstring: str | None = None, **kwargs: Any)[source]

Bases: 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

Methods:

get_instr()

Returns the instance of the instrument with the name equal to the value of this parameter.

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

increment(value)

Increment the parameter with a value

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

validate(value)

Validate the value supplied.

Attributes:

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

label

Label of the data used for plots etc.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

unit

The unit of measure.

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

get_instr() InstrumentBase[source]

Returns the instance of the instrument with the name equal to the value of this parameter.

__getitem__(keys: Any) 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: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
property label: str

Label of the data used for plots etc.

load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: float | None = None, num: int | None = None) 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: InstrumentBase | None

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.

property unit: str

The unit of measure. Use '' (the empty string) for unitless.

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

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

Bases: 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.

Methods:

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

increment(value)

Increment the parameter with a value

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

validate(value)

Validate the value supplied.

Attributes:

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

label

Label of the data used for plots etc.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

unit

The unit of measure.

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

__getitem__(keys: Any) 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: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
property label: str

Label of the data used for plots etc.

load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: float | None = None, num: int | None = None) 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: InstrumentBase | None

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.

property unit: str

The unit of measure. Use '' (the empty string) for unitless.

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

class qcodes.parameters.MultiChannelInstrumentParameter(channels: Sequence[InstrumentModuleType], param_name: str, *args: Any, **kwargs: Any)[source]

Bases: MultiParameter, Generic[InstrumentModuleType]

Parameter to get or set multiple channels simultaneously.

Will normally be created by a ChannelList and not directly by anything else.

Parameters:
  • channels – A list of channels which we can operate on simultaneously.

  • param_name – Name of the multichannel parameter

Methods:

get_raw()

Return a tuple containing the data from each of the channels in the list.

set_raw(value)

Set all parameters to this/these value(s).

__class_getitem__(params)

Parameterizes a generic class.

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

validate(value)

Validate the value supplied.

Attributes:

full_names

Overwrite full_names because the instrument name is already included in the name.

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

setpoint_full_names

Full names of setpoints including instrument names, if available

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

short_names

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

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

get_raw() tuple[ParamRawDataType, ...][source]

Return a tuple containing the data from each of the channels in the list.

set_raw(value: ParamRawDataType | Sequence[ParamRawDataType]) None[source]

Set all parameters to this/these value(s).

Parameters:

value – The value(s) to set to. The type is given by the underlying parameter.

property full_names: tuple[str, ...]

Overwrite full_names because the instrument name is already included in the name. This happens because the instrument name is included in the channel name merged into the parameter name above.

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__str__() str

Include the instrument name with the Parameter name if possible.

property abstract: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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 setpoint_full_names: Sequence[Sequence[str]] | None

Full names of setpoints including instrument names, if available

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().

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.

snapshot(update: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: InstrumentBase | None

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

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

Bases: ParameterBase

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.

  • setpointsarray 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.

Attributes:

short_names

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

full_names

Names of the parameter components including the name of the instrument and submodule that the parameter may be bound to.

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

setpoint_full_names

Full names of setpoints including instrument names, if available

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

Methods:

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

validate(value)

Validate the value supplied.

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

__str__() str

Include the instrument name with the Parameter name if possible.

property abstract: bool | None
add_validator(vals: Validator) None

Add a validator for the parameter. The parameter is validated against all validators in reverse order of how they are added.

Parameters:

vals – Validator to add to the parameter.

extra_validator(vals: Validator) Generator[None, None, None]

Contextmanager to to temporarily add a validator to the parameter within the given context. The validator is removed from the parameter when the context ends.

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: float | Sized, step: float | None = None) Sequence[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: InstrumentBase | None

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:
load_metadata(metadata: Mapping[str, 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:
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.

property register_name: str

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

remove_validator() Validator | None

Remove the last validator added to the parameter and return it. Returns None if there are no validators associated with the parameter.

Returns:

The last validator added to the parameter or None if there are no validators associated with the parameter.

restore_at_exit(allow_changes: bool = True) _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: InstrumentBase | None

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) _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.parameters 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 setpoint_full_names: Sequence[Sequence[str]] | None

Full names of setpoints including instrument names, if available

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: bool | None = False) dict[str, 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: bool | None = True, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any]

State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class 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: float | None

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: InstrumentBase | None

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.

property validators: tuple[Validator, ...]

Tuple of all validators associated with the parameter.

Getter:

All validators associated with the parameter.

property vals: Validator | None

The first validator of the parameter. None if no validators are set for this parameter.

Getter:

Returns the first validator or None if no validators.

Setter:

Sets the first validator. Set to None to remove the first validator.

Raises:

RuntimeError – If removing the first validator when more than one validator is set.

qcodes.parameters.ParamDataType

alias of Any

qcodes.parameters.ParamRawDataType

alias of Any

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

Bases: ParameterBase

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:

  1. 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.

  2. 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_getFalse 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_valueFalse prevents parameter value to be stored in the snapshot. Useful if the value is large.

  • snapshot_excludeTrue 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.

Methods:

get_raw()

get_raw is called to perform the actual data acquisition from the instrument.

set_raw(value)

set_raw is called to perform the actual setting of a parameter on the instrument.

__str__()

Include the instrument name with the Parameter name if possible.

add_validator(vals)

Add a validator for the parameter.

extra_validator(vals)

Contextmanager to to temporarily add a validator to the parameter within the given context.

get_ramp_values(value[, step])

Return values to sweep from current value to target value.

load_metadata(metadata)

Load metadata into this classes metadata dictionary.

remove_validator()

Remove the last validator added to the parameter and return it.

restore_at_exit([allow_changes])

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

set_to(value[, allow_changes])

Use a context manager to temporarily set a parameter to a value.

snapshot([update])

Decorate a snapshot dictionary with metadata.

snapshot_base([update, params_to_skip_update])

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

validate(value)

Validate the value supplied.

__getitem__(keys)

Slice a Parameter to get a SweepValues object to iterate over during a sweep

increment(value)

Increment the parameter with a value

sweep(start, stop[, step, num])

Create a collection of parameter values to be iterated over.

Attributes:

unit

The unit of measure.

abstract

full_name

Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.

gettable

Is it allowed to call get on this parameter?

instrument

Return the first instrument that this parameter is bound to.

inter_delay

Delay time between consecutive set operations.

label

Label of the data used for plots etc.

name

Name of the parameter.

name_parts

List of the parts that make up the full name of this parameter

post_delay

Delay time after start of set operation, for each set.

raw_value

Note that this property will be deprecated soon.

register_name

Name that will be used to register this parameter in a dataset By default, this returns full_name or the value of the register_name argument if it was passed at initialization.

root_instrument

Return the fundamental instrument that this parameter belongs too.

settable

Is it allowed to call set on this parameter?

short_name

Short name of the parameter.

snapshot_value

If True the value of the parameter will be included in the snapshot.

step

Stepsize that this Parameter uses during set operation.

underlying_instrument

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

validators

Tuple of all validators associated with the parameter.

vals

The first validator of the parameter.

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 alternative