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:
As an
Instrument
parameter that sends/receives commands. Provides a standardized interface to construct strings to pass to theInstrument.write()
andInstrument.ask()
methodsAs 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 aqcodes.dataset.Measurement
but is not supported by the legacyqcodes.loops.Loop
andqcodes.measure.Measure
measurement types.
DelegateParameter
is intended for proxy-ing other parameters.It forwards its
get
andset
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 eachget
call returns an array of values that all have the same type and meaning. Currently not settable, only gettable. Can be used in aqcodes.dataset.Measurement
as well as in the legacyqcodes.loops.Loop
andqcodes.measure.Measure
measurements - in which case these arrays are nested inside the loop’s setpoint array. To use, provide aget
method that returns an array or regularly-shaped sequence, and describe that array insuper().__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 legacyqcodes.loops.Loop
andqcodes.measure.Measure
measurements. To use, provide aget
method that returns a sequence of values, and describe those values insuper().__init__
.
Classes:
|
A gettable parameter that returns an array of values. |
|
A combined parameter. |
|
The DelegateGroup combines |
|
|
|
The |
|
Parameter to measure elapsed time. |
|
Defines a function that an instrument can execute. |
|
The group combines |
|
Group parameter is a |
|
The GroupedParameter wraps one or more |
|
An instrument reference parameter. |
|
A simple alias for a parameter that does not have a set or a get function. |
|
Parameter to get or set multiple channels simultaneously. |
|
A gettable parameter that returns multiple values with separate names, each of arbitrary shape. |
alias of |
|
alias of |
|
|
A parameter represents a single degree of freedom. |
|
Shared behavior for all parameters. |
|
A parameter that has associated setpoints. |
|
|
|
A fixed collection of parameter values to be iterated over during a sweep. |
|
Base class for sweeping a parameter. |
Functions:
|
Returns a value mapping which maps inputs which reasonably mean "on"/"off" to the specified |
|
Combine parameters into one sweepable parameter |
|
A helper function that takes a |
|
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 useSubclasses 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 aqcodes.dataset.Measurement
as well as in the legacyqcodes.loops.Loop
andqcodes.measure.Measure
measurementsWhen used in a
Loop
orMeasure
operation, this will be entered into a singleDataArray
, with extra dimensions added by theLoop
. 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
orStation
, this is how it will be referenced from that parent, i.e.instrument.name
orinstrument.parameters[name]
shape – The shape (as used in numpy arrays) of the array to expect. Scalars should be denoted by (), 1D arrays as (n,), 2D arrays as (n, m), etc.
instrument – The instrument this parameter belongs to, if any.
label – Normally used as the axis label when this parameter is graphed, along with
unit
.unit – The unit of measure. Use
''
for unitless.setpoints –
array
can be a DataArray, numpy.ndarray, or sequence. The setpoints for each dimension of the returned array. An N-dimension item should have N setpoint arrays, where the first is 1D, the second 2D, etc. If omitted for any or all items, defaults to integers from zero in each respective direction. Note: if the setpoints will be different each measurement, leave this out and return the setpoints (with extra names) in.get
.setpoint_names – One identifier (like
name
) per setpoint array. Ignored if a setpoint is a DataArray, which already has a name.setpoint_labels – One label (like
labels
) per setpoint array. Ignored if a setpoint is a DataArray, which already has a label.setpoint_units – One unit (like
v
) per setpoint array. Ignored if a setpoint is a DataArray, which already has a unit.docstring – documentation string for the
__doc__
field of the object. The__doc__
field of the instance is used by some help systems, but not all.snapshot_get – Prevent any update to the parameter, for example if it takes too long to update. Default
True
.snapshot_value – Should the value of the parameter be stored in the snapshot. Unlike Parameter this defaults to False as ArrayParameters are potentially huge.
snapshot_exclude –
True
prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot.Default
False
.metadata – Extra information to include with the JSON snapshot of the parameter.
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 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:
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Tuple of all validators associated with the parameter.
The first validator of the parameter.
Full names of setpoints including instrument names if available
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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
- 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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.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:
update –
True
orFalse
.params_to_skip_update – Unused in this subclass.
- Returns:
Base snapshot.
- Return type:
- 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 oneGroupedParameter
. EachDelegateParameter
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 theGroupedParameter
class in order to get and set theDelegateParameter
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 theDelegateGroup
, or a single value, if a custom setter is defined or if the group only contains a singleDelegateParameter
.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 theDelegateParameter
s. In the special case where theDelegateGroup
only contains oneDelegateParameter
, 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 theDelegateParameter
s as positional arguments in the order at which theDelegateParameter
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
()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:
Get source parameters of each DelegateParameter
The
root_instrument
that this parameter belongs to.All parameters in this group as a dict from parameter name to
Parameter
- 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)
- 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 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:
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
The group that this parameter belongs to.
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
The source parameter that this
DelegateParameter
is bound to orNone
if thisDelegateParameter
is unbound.Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
The first validator of the parameter.
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- Returns:
base snapshot
- property source: Parameter | None¶
The source parameter that this
DelegateParameter
is bound to orNone
if thisDelegateParameter
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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_instrument
.By default it returns the
root_instrument
of the parameter.
- 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 sourceParameter
. 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 theDelegateParameter
without changing those in the source parameter.The
DelegateParameter
supports changing the sourceParameter
.gettable
,settable
andsnapshot_value
properties automatically follow the source parameter. If source is set toNone
gettable
andsettable
will always beFalse
. It is therefore an error to call get and set on aDelegateParameter
without a source. Note that a parameter without a source can be snapshotted correctly.unit
andlabel
can either be set when constructing aDelegateParameter
or inherited from the sourceParameter
. If inherited they will automatically change when changing the source. Otherwise they will remain fixed.Note
DelegateParameter only supports mappings between the
DelegateParameter
andParameter
that are invertible (e.g. a bijection). It is therefor not allowed to create aDelegateParameter
that performs non invertible transforms in itsget_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:
The source parameter that this
DelegateParameter
is bound to orNone
if thisDelegateParameter
is unbound.Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
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 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 supplied value.
- property source: Parameter | None¶
The source parameter that this
DelegateParameter
is bound to orNone
if thisDelegateParameter
is unbound.- Getter:
Returns the current source.
- Setter:
Sets the source.
- get_raw() Any [source]¶
get_raw
is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
method on the parameter instance.
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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.
- 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.
- 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.__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 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:
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.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__
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:
Name excluding name of any instrument that this function may be bound to.
Name of the function including the name of the instrument and submodule that the function may be bound to.
List of the parts that make up the full name of this function
- 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 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 instrument: InstrumentBase | None¶
- load_metadata(metadata: Mapping[str, Any]) None ¶
Load metadata into this classes metadata dictionary.
- Parameters:
metadata – Metadata to load.
- 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 withinGroupParameter
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
, wherea_value
andb_value
are values of two parameters with namesa
andb
, then the command string has to beCMD {a}, {b}
, and the group has to be initialized with twoGroupParameter
sa_param
andb_param
, wherea_param.name=="a"
andb_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 theGroup
’s constructor. Through keyword arguments of theGroup
’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 theget_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 customget_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:
All parameters in this group as a dict from parameter name to
Parameter
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. Theget_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, exceptset_cmd
andget_cmd
.
Attributes:
The group that this parameter belongs to.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
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 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.
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
method on the parameter instance.
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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.
- 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.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 aDelegateGroup
to keep track of theDelegateParameter
s. Mainly, this class is a thin wrapper around theDelegateGroup
, and mainly exists in order to allow for it to be used as aParameterBase
.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, theGroupedParameter
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:
The group that contains the target parameters.
Get delegate parameters wrapped by this GroupedParameter
Get source parameters of each DelegateParameter
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Tuple of all validators associated with the parameter.
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 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
- 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 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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:
- 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.
- 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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
- 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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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:
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 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:
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
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
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.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 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:
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
The first validator of the parameter.
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.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 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:
Overwrite full_names because the instrument name is already included in the name.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Full names of setpoints including instrument names, if available
Is it allowed to call set on this parameter?
Short name of the parameter.
short_names is identical to names i.e. the names of the parameter parts but does not add the instrument name.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Tuple of all validators associated with the parameter.
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]): ….
- 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 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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
- 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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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`` orMeasure
operation, each of these values will be entered into a differentDataArray
. 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
orinstrument.parameters[name]
.names – A name for each item returned by a
.get
call. Will be used as the basis of theDataArray
names when this parameter is used to create aDataSet
.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
''
orNone
for unitless values.setpoints –
array
can be a DataArray, numpy.ndarray, or sequence. The setpoints for each returned array. An N-dimension item should have N setpoint arrays, where the first is 1D, the second 2D, etc. If omitted for any or all items, defaults to integers from zero in each respective direction. Note: if the setpoints will be different each measurement, leave this out and return the setpoints (with extra names) in.get
.setpoint_names – One identifier (like
name
) per setpoint array. Ignored if a setpoint is a DataArray, which already has a name.setpoint_labels – One label (like
labels
) per setpoint array. Ignored if a setpoint is a DataArray, which already has a label.setpoint_units – One unit (like
V
) per setpoint array. Ignored if a setpoint is a DataArray, which already has a unit.docstring – Documentation string for the
__doc__
field of the object. The__doc__
field of the instance is used by some help systems, but not allsnapshot_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 is identical to names i.e. the names of the parameter parts but does not add the instrument name.
Names of the parameter components including the name of the instrument and submodule that the parameter may be bound to.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Full names of setpoints including instrument names, if available
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Tuple of all validators associated with the parameter.
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 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
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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
- 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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.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:
Providing a
get_cmd
/set_cmd
, which can do the following:callable, with zero args for get_cmd, one arg for set_cmd
VISA command string
None, in which case it retrieves its last value for
get_cmd
, and stores a value forset_cmd
False, in which case trying to get/set will raise an error.
Creating a subclass with an explicit
get_raw()
/set_raw()
method.This enables more advanced functionality. The
get_raw()
andset_raw()
methods are automatically wrapped to provideget
andset
.
It is an error to do both 1 and 2. E.g supply a
get_cmd
/set_cmd
and implementget_raw
/set_raw
To detect if a parameter is gettable or settable check the attributes
gettable
andsettable
on the parameter.Parameters have a
cache
object that stores internally the currentvalue
andraw_value
of the parameter. Callingcache.get()
(orcache()
) simply returns the most recent set or measured value of the parameter.Parameter also has a
.get_latest
method that duplicates the behavior ofcache()
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
orinstrument.parameters[name]
.instrument – The instrument this parameter belongs to, if any.
label – Normally used as the axis label when this parameter is graphed, along with
unit
.unit – The unit of measure. Use
''
for unitless.snapshot_get –
False
prevents any update to the parameter during a snapshot, even if the snapshot was called withupdate=True
, for example, if it takes too long to update, or if the parameter is only meant for measurements hence calling get on it during snapshot may be an error. Default True.snapshot_value –
False
prevents parameter value to be stored in the snapshot. Useful if the value is large.snapshot_exclude –
True
prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot. DefaultFalse
.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 useval_mapping
withget_parser
, in which caseget_parser
acts on the return value from the instrument first, thenval_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()
(orcache.get()
, orget_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 withinitial_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 withinitial_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 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:
The unit of measure.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Tuple of all validators associated with the parameter.
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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- set_raw(value: Any) None ¶
set_raw
is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
method on the parameter instance.
- 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 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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.
- 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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
- 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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.
- __getitem__(keys: Any) SweepFixedValues [source]¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- increment(value: Any) None [source]¶
Increment the parameter with a value
- Parameters:
value – Value to be added to the parameter.
- sweep(start: float, stop: float, step: float | None = None, num: int | None = None) SweepFixedValues [source]¶
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters:
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns:
Collection of parameter values to be iterated over.
- Return type:
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]
- class qcodes.parameters.ParameterBase(name: str, instrument: InstrumentBase | None, snapshot_get: bool = True, metadata: Mapping[Any, Any] | None = None, step: float | None = None, scale: float | Iterable[float] | None = None, offset: float | Iterable[float] | None = None, inter_delay: float = 0, post_delay: float = 0, val_mapping: Mapping[Any, Any] | None = None, get_parser: Callable[..., Any] | None = None, set_parser: Callable[..., Any] | None = None, snapshot_value: bool = True, snapshot_exclude: bool = False, max_val_age: float | None = None, vals: Validator[Any] | None = None, abstract: bool | None = False, bind_to_instrument: bool = True, register_name: str | None = None)[source]¶
Bases:
MetadatableWithName
Shared behavior for all parameters. Not intended to be used directly, normally you should use
Parameter
,ArrayParameter
,MultiParameter
, orCombinedParameter
. Note thatCombinedParameter
is not yet a subclass ofParameterBase
- Parameters:
name – the local name of the parameter. Must be a valid identifier, ie no spaces or special characters or starting with a number. If this parameter is part of an Instrument or Station, this should match how it will be referenced from that parent, ie
instrument.name
orinstrument.parameters[name]
instrument – the instrument this parameter belongs to, if any
snapshot_get – False prevents any update to the parameter during a snapshot, even if the snapshot was called with
update=True
, for example if it takes too long to update. Default True.snapshot_value – False prevents parameter value to be stored in the snapshot. Useful if the value is large.
snapshot_exclude – True prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot. Default False
step – max increment of parameter value. Larger changes are broken into multiple steps this size. When combined with delays, this acts as a ramp.
scale – Scale to multiply value with before performing set. the internally multiplied value is stored in
cache.raw_value
. Can account for a voltage divider.offset – Compensate for a parameter specific offset. (just as scale) get value = raw value - offset. set value = argument + offset. If offset and scale are used in combination, when getting a value, first an offset is added, then the scale is applied.
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 bidirectional 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 useval_mapping
withget_parser
, in which caseget_parser
acts on the return value from the instrument first, thenval_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 – a Validator object for this parameter
max_val_age – The max time (in seconds) to trust a saved value obtained from
cache.get
(orget_latest
). If this parameter has not been set or measured more recently than this, perform an additional measurement.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.
register_name – Specifies if the parameter should be registered in datasets using a different name than the parameter’s full_name
Attributes:
The first validator of the parameter.
Tuple of all validators associated with the parameter.
Note that this property will be deprecated soon.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Delay time after start of set operation, for each set.
Delay time between consecutive set operations.
Name of the parameter.
Short name of the parameter.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the first instrument that this parameter is bound to.
Return the fundamental instrument that this parameter belongs too.
List of the parts that make up the full name of this parameter
Is it allowed to call get on this parameter?
Is it allowed to call set on this parameter?
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Methods:
add_validator
(vals)Add a validator for the parameter.
Remove the last validator added to the parameter and return it.
extra_validator
(vals)Contextmanager to to temporarily add a validator to the parameter within the given context.
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.
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).get_ramp_values
(value[, step])Return values to sweep from current value to target value.
validate
(value)Validate the value supplied.
load_metadata
(metadata)Load metadata into this classes metadata dictionary.
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.
restore_at_exit
([allow_changes])Use a context manager to restore the value of a parameter after a
with
block.- 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.
- add_validator(vals: Validator) None [source]¶
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.
- remove_validator() Validator | None [source]¶
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.
- property validators: tuple[Validator, ...]¶
Tuple of all validators associated with the parameter.
- Getter:
All validators associated with the parameter.
- extra_validator(vals: Validator) Generator[None, None, None] [source]¶
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 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.
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- Returns:
base snapshot
- get_ramp_values(value: float | Sized, step: float | None = None) Sequence[float | Sized] [source]¶
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.
- validate(value: Any) None [source]¶
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 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property inter_delay: float¶
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter:
Returns the current inter_delay.
- Setter:
Sets the value of the inter_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property name: str¶
Name of the parameter. This is identical to
short_name()
.
- 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 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
.
- 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 theregister_name
argument if it was passed at initialization.
- 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 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.
- load_metadata(metadata: Mapping[str, Any]) None ¶
Load metadata into this classes metadata dictionary.
- Parameters:
metadata – Metadata to load.
- set_to(value: Any, allow_changes: bool = False) _SetParamContext [source]¶
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
- 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.
- restore_at_exit(allow_changes: bool = True) _SetParamContext [source]¶
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 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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_instrument
.By default it returns the
root_instrument
of the parameter.
- class qcodes.parameters.ParameterWithSetpoints(name: str, *, vals: Validator[Any] | None = None, setpoints: Sequence[ParameterBase] | None = None, snapshot_get: bool = False, snapshot_value: bool = False, **kwargs: Any)[source]¶
Bases:
Parameter
A parameter that has associated setpoints. The setpoints is nothing more than a list of other parameters that describe the values, names and units of the setpoint axis for this parameter.
In most cases this will probably be a parameter that returns an array. It is expected that the setpoint arrays are 1D arrays such that the combined shape of the parameter e.g. if parameter is of shape (m,n) setpoints is a list of parameters of shape (m,) and (n,)
In all other ways this is identical to
Parameter
. See the documentation ofParameter
for more details.Attributes:
Sequence of parameters to use as setpoints for this parameter.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Label of the data used for plots etc.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
The unit of measure.
Tuple of all validators associated with the parameter.
The first validator of the 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.
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 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.
Verifies that the shape of the Array Validator of the parameter is consistent with the Validator of the Setpoints.
validate
(value)Overwrites the standard
validate
method to also check the the parameter has consistent shape with its setpoints.- property setpoints: Sequence[ParameterBase]¶
Sequence of parameters to use as setpoints for this parameter.
- Getter:
Returns a list of parameters currently used for setpoints.
- Setter:
Sets the parameters to be used as setpoints from a sequence. The combined shape of the parameters supplied must be consistent with the data shape of the data returned from get on the parameter.
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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 forParameter
a suitable method is automatically generated ifget_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aget
method on the parameter instance.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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 forParameter
a suitable method is automatically generated ifset_cmd
is supplied to the parameter constructor. The method is automatically wrapped to provide aset
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 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_instrument
.By default it returns the
root_instrument
of the parameter.
- validate_consistent_shape() None [source]¶
Verifies that the shape of the Array Validator of the parameter is consistent with the Validator of the Setpoints. This requires that both the setpoints and the actual parameters have validators of type Arrays with a defined shape.
- 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.ScaledParameter(output: Parameter, division: float | Parameter | None = None, gain: float | Parameter | None = None, name: str | None = None, label: str | None = None, unit: str | None = None)[source]¶
Bases:
Parameter
Parameter
ScalerTo be used when you use a physical voltage divider or an amplifier to set or get a quantity.
Initialize the parameter by passing the parameter to be measured/set and the value of the division OR the gain.
The scaling value can be either a scalar value or a Qcodes Parameter.
The parameter scaler acts a your original parameter, but will set the right value, and store the gain/division in the metadata.
Examples
Resistive voltage divider >>> vd = ScaledParameter(dac.chan0, division = 10)
Voltage multiplier >>> vb = ScaledParameter(dac.chan0, gain = 30, name = ‘Vb’)
Transimpedance amplifier >>> Id = ScaledParameter(multimeter.amplitude, … division = 1e6, name = ‘Id’, unit = ‘A’)
- Parameters:
output – Physical Parameter that need conversion.
division – The division value.
gain – The gain value.
label – Label of this parameter, by default uses ‘output’ label but attaches _amplified or _attenuated depending if gain or division has been specified.
name – Name of this parameter, by default uses ‘output’ name but attaches _amplified or _attenuated depending if gain or division has been specified.
unit – Resulting unit. It uses the one of ‘output’ by default.
Classes:
Role
(value[, names, module, qualname, type, ...])Attributes:
Label of the data used for plots etc.
The unit of measure.
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to.
Is it allowed to call get on this parameter?
Return the first instrument that this parameter is bound to.
Delay time between consecutive set operations.
Name of the parameter.
List of the parts that make up the full name of this parameter
Delay time after start of set operation, for each set.
Note that this property will be deprecated soon.
Name that will be used to register this parameter in a dataset By default, this returns
full_name
or the value of theregister_name
argument if it was passed at initialization.Return the fundamental instrument that this parameter belongs too.
Is it allowed to call set on this parameter?
Short name of the parameter.
If True the value of the parameter will be included in the snapshot.
Stepsize that this Parameter uses during set operation.
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter's implementation.
Tuple of all validators associated with the parameter.
The first validator of the parameter.
The attached unscaled 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 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.
get_raw
()set_raw
(value)Set the value on the wrapped parameter, accounting for the scaling
- class Role(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Bases:
Enum
Attributes:
Methods:
__contains__
(member)Return True if member is a member of this enum raises TypeError if member is not an enum member
__getitem__
(name)Return the member matching name.
__iter__
()Return members in definition order.
__len__
()Return the number of members (no aliases)
- GAIN = 1¶
- DIVISION = 2¶
- classmethod __contains__(member)¶
Return True if member is a member of this enum raises TypeError if member is not an enum member
note: in 3.12 TypeError will no longer be raised, and True will also be returned if member is the value of a member in this enum
- classmethod __getitem__(name)¶
Return the member matching name.
- classmethod __iter__()¶
Return members in definition order.
- classmethod __len__()¶
Return the number of members (no aliases)
- __getitem__(keys: Any) SweepFixedValues ¶
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- 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.
- 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:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- 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 post_delay: float¶
Delay time after start of set operation, for each set. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay after every set. One might think of post_delay as how long a set operation is supposed to take. For example, there might be an instrument that needs extra time after setting a parameter although the command for setting the parameter returns quickly.
- Getter:
Returns the current post_delay.
- Setter:
Sets the value of the post_delay.
- Raises:
TypeError – If delay is not int nor float
ValueError – If delay is negative
- property raw_value: Any¶
Note that this property will be deprecated soon. Use
cache.raw_value
instead.Represents the cached raw value of the parameter.
- Getter:
Returns the cached raw value of the parameter.
- 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 theregister_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.
- 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 thevalue
andraw_value
of the parameter.- Parameters:
update – If True, update the state by calling
parameter.get()
unlesssnapshot_get
of the parameter isFalse
. Ifupdate
isNone
, use the current value from thecache
unless the cache is invalid. IfFalse
, never callparameter.get()
.params_to_skip_update – No effect but may be passed from superclass
- 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:
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 thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_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.SweepFixedValues(parameter: ParameterBase, keys: Any | None = None, start: float | None = None, stop: float | None = None, step: float | None = None, num: int | None = None)[source]¶
Bases:
SweepValues
A fixed collection of parameter values to be iterated over during a sweep.
- Parameters:
parameter – the target of the sweep, an object with set and optionally validate methods
keys – one or a sequence of items, each of which can be: - a single parameter value - a sequence of parameter values - a slice object, which MUST include all three args
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
A SweepFixedValues object is normally created by slicing a Parameter p:
>>> sv = p[1.2:2:0.01] # slice notation sv = p[1, 1.1, 1.3, 1.6] # explicit individual values sv = p[1.2:2:0.01, 2:3:0.02] # sequence of slices sv = p[logrange(1,10,.01)] # some function that returns a sequence
You can also use list operations to modify these:
>>> sv += p[2:3:.01] # (another SweepFixedValues of the same parameter) sv += [4, 5, 6] # (a bare sequence) sv.extend(p[2:3:.01]) sv.append(3.2) sv.reverse() sv2 = reversed(sv) sv3 = sv + sv2 sv4 = sv.copy()
note though that sweeps should only require set and __iter__ - ie “for val in sv”, so any class that implements these may be used in sweeps. That allows things like adaptive sampling, where you don’t know ahead of time what the values will be or even how many there are.
Methods:
append
(value)Append a value.
extend
(new_values)Extend sweep with new_values
copy
()Copy this SweepFixedValues.
reverse
()Reverse SweepFixedValues in place.
snapshot_base
([update, params_to_skip_update])Snapshot state of SweepValues.
load_metadata
(metadata)Load metadata into this classes metadata dictionary.
snapshot
([update])Decorate a snapshot dictionary with metadata.
validate
(values)Check that all values are allowed for this Parameter.
- extend(new_values: Sequence[Any] | SweepFixedValues) None [source]¶
Extend sweep with new_values
- Parameters:
new_values – new values to append
- Raises:
TypeError – if new_values is not Sequence, nor SweepFixedValues
- copy() SweepFixedValues [source]¶
Copy this SweepFixedValues.
- Returns:
SweepFixedValues of copied values
- snapshot_base(update: bool | None = False, params_to_skip_update: Sequence[str] | None = None) dict[Any, Any] [source]¶
Snapshot state of SweepValues.
- Parameters:
update – Place holder for API compatibility.
params_to_skip_update – Place holder for API compatibility.
- Returns:
base snapshot
- Return type:
- load_metadata(metadata: Mapping[str, Any]) None ¶
Load metadata into this classes metadata dictionary.
- Parameters:
metadata – Metadata to load.
- class qcodes.parameters.SweepValues(parameter: ParameterBase, **kwargs: Any)[source]¶
Bases:
Metadatable
Base class for sweeping a parameter.
Must be subclassed to provide the sweep values Intended use is to iterate over in a sweep, so it must support:
>>> .__iter__ # (and .__next__ if necessary). >>> .set # is provided by the base class
Optionally, it can have a feedback method that allows the sweep to pass measurements back to this object for adaptive sampling:
>>> .feedback(set_values, measured_values)
Todo
Link to adawptive sweep
- Parameters:
parameter – the target of the sweep, an object with set, and optionally validate methods
**kwargs – Passed on to Metadatable parent
- Raises:
TypeError – when parameter is not settable
See AdaptiveSweep for an example
example usage:
>>> for i, value in eumerate(sv): sv.set(value) sleep(delay) vals = measure() sv.feedback((i, ), vals) # optional - sweep should not assume # .feedback exists
note though that sweeps should only require set and __iter__ - ie “for val in sv”, so any class that implements these may be used in sweeps.
That allows things like adaptive sampling, where you don’t know ahead of time what the values will be or even how many there are.
Methods:
validate
(values)Check that all values are allowed for this Parameter.
__iter__
()must be overridden (along with __next__ if this returns self) by a subclass to tell how to iterate over these values
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.
- validate(values: Sequence[Any]) None [source]¶
Check that all values are allowed for this Parameter.
- Parameters:
values – values to be validated.
- __iter__() Iterator[Any] [source]¶
must be overridden (along with __next__ if this returns self) by a subclass to tell how to iterate over these values
- load_metadata(metadata: Mapping[str, Any]) None ¶
Load metadata into this classes metadata dictionary.
- Parameters:
metadata – Metadata to load.
- qcodes.parameters.create_on_off_val_mapping(on_val: T | bool = True, off_val: T | bool = False) OrderedDict[str | bool, T | bool] [source]¶
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. This value mapping is such that, when inverted,on_val
/off_val
are mapped to booleanTrue
/False
.
- qcodes.parameters.combine(*parameters: Parameter, name: str, label: str | None = None, unit: str | None = None, units: str | None = None, aggregator: Callable[..., Any] | None = None) CombinedParameter [source]¶
Combine parameters into one sweepable parameter
A combined parameter sets all the combined parameters at every point of the sweep. The sets are called in the same order the parameters are, and sequentially.
- Parameters:
*parameters – The parameters to combine.
name – The name of the paramter.
label – The label of the combined parameter.
unit – The unit of the combined parameter.
units – Deprecated argument left for backwards compatibility. Do not use.
aggregator – A function to aggregate the set values into one.
- qcodes.parameters.expand_setpoints_helper(parameter: ParameterWithSetpoints, results: ParamDataType | None = None) list[tuple[ParameterBase, ParamDataType]] [source]¶
A helper function that takes a
ParameterWithSetpoints
and acquires the parameter along with it’s setpoints. The data is returned in a format prepared to insert into the dataset.- Parameters:
parameter – A
ParameterWithSetpoints
to be acquired and expandedresults – The data for the given parameter. Typically the output of parameter.get(). If None this function will call parameter.get
- Returns:
A list of tuples of parameters and values for the specified parameter and its setpoints.