qcodes.instrument.parameter
The Parameter module implements Parameter interface that are the basis of measurements and control within QCoDeS.
Anything that you want to either measure or control within QCoDeS should satisfy the Parameter interface. Most of the time that is easiest to do by either using or subclassing one of the classes defined here, but you can also use any class with the right attributes.
All parameter classes are subclassed from ._BaseParameter
(except
CombinedParameter). The _BaseParameter provides functionality that is common
to all parameter types, such as ramping and scaling of values, adding delays
(see documentation for details).
This module defines the following basic classes of parameters as well as some more specialized ones:
Parameter
is the base class for scalar-valued parameters.Two primary ways in which it can be used:
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.measurements.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.measurements.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.measurements.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__
.
- class qcodes.instrument.parameter.ArrayParameter(name: str, shape: Sequence[int], instrument: Optional[InstrumentBase] = None, label: Optional[str] = None, unit: Optional[str] = None, setpoints: Optional[Sequence[Any]] = None, setpoint_names: Optional[Sequence[str]] = None, setpoint_labels: Optional[Sequence[str]] = None, setpoint_units: Optional[Sequence[str]] = None, docstring: Optional[str] = None, snapshot_get: bool = True, snapshot_value: bool = False, snapshot_exclude: bool = False, metadata: Optional[Mapping[Any, Any]] = None, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter._BaseParameter
A gettable parameter that returns an array of values. Not necessarily part of an instrument.
For new driver we strongly recommend using
ParameterWithSetpoints
which is both more flexible and significantly easier to 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.measurements.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.
- property setpoint_full_names: Optional[Sequence[str]]
Full names of setpoints including instrument names if available
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- get_raw() Any
get_raw
is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively 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: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_raw(value: Any) None
set_raw
is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively 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) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- class qcodes.instrument.parameter.CombinedParameter(parameters: Sequence[qcodes.instrument.parameter.Parameter], name: str, label: Optional[str] = None, unit: Optional[str] = None, units: Optional[str] = None, aggregator: Optional[Callable[[...], Any]] = None)[source]
Bases:
qcodes.utils.metadata.Metadatable
A combined parameter. It sets all the combined parameters at every point of the sweep. The sets are called in the same order the parameters are, and sequentially.
- Parameters
*parameters – The parameters to combine.
name – The name of the parameter
label – The label of the combined parameter
unit – The unit of the combined parameter
aggregator – A function to aggregate the set values into one
- set(index: int) List[Any] [source]
Set multiple parameters.
- Parameters
index – the index of the setpoints one wants to set
- Returns
list of values that where actually set
- sweep(*array: numpy.ndarray) qcodes.instrument.parameter.CombinedParameter [source]
Creates a new combined parameter to be iterated over. One can sweep over either:
n array of length m
one nxm array
where n is the number of combined parameters and m is the number of setpoints
- Parameters
*array – Array(s) of setpoints.
- Returns
combined parameter
- load_metadata(metadata: Mapping[str, Any]) None
Load metadata into this classes metadata dictionary.
- Parameters
metadata – Metadata to load.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = False, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any] [source]
State of the combined parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).- Parameters
update –
True
orFalse
.params_to_skip_update – Unused in this subclass.
- Returns
Base snapshot.
- Return type
- class qcodes.instrument.parameter.DelegateParameter(name: str, source: Optional[qcodes.instrument.parameter.Parameter], *args: Any, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter.Parameter
The
DelegateParameter
wraps a given 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.- property source: Optional[qcodes.instrument.parameter.Parameter]
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.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any] [source]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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
- __getitem__(keys: Any) qcodes.instrument.sweep_values.SweepFixedValues
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- increment(value: Any) None
Increment the parameter with a value
- Parameters
value – Value to be added to the parameter.
- property instrument: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_to(value: Any, allow_changes: bool = False) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- property step: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) qcodes.instrument.sweep_values.SweepFixedValues
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns
Collection of parameter values to be iterated over.
- Return type
SweepFixedValues
Examples
>>> sweep(0, 10, num=5) [0.0, 2.5, 5.0, 7.5, 10.0] >>> sweep(5, 10, step=1) [5.0, 6.0, 7.0, 8.0, 9.0, 10.0] >>> sweep(15, 10.5, step=1.5) >[15.0, 13.5, 12.0, 10.5]
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- class qcodes.instrument.parameter.GetLatest(parameter: qcodes.instrument.parameter._BaseParameter)[source]
Bases:
qcodes.utils.helpers.DelegateAttributes
Wrapper for a class:.Parameter that just returns the last set or measured value stored in the class:.Parameter itself. If get has never been called on the parameter or the time since get was called is larger than
max_val_age
, get will be called on the parameter. If the parameter does not implement get, set should be called (or the initial_value set) before calling get on this wrapper. It is an error to setmax_val_age
for a parameter that does not have a get function.The functionality of this class is subsumed and improved in parameter’s cache that is accessible via
.cache
attribute of theParameter
. Use ofparameter.cache
is recommended over use ofparameter.get_latest
.Examples
>>> # Can be called: >>> param.get_latest() >>> # Or used as if it were a gettable-only parameter itself: >>> Loop(...).each(param.get_latest)
- Parameters
parameter – Parameter to be wrapped.
- delegate_attr_objects: List[str] = ['parameter']
A list of names (strings) of objects which are (or will be) attributes of
self
, whose attributes should be passed through toself
.
- omit_delegate_attrs: List[str] = ['set']
A list of attribute names (strings) to not delegate to any other dictionary or object.
- get() Any [source]
Return latest value if time since get was less than max_val_age, otherwise perform get() and return result. A get() will also be performed if the parameter never has been captured.
It is recommended to use
parameter.cache.get()
instead.
- get_timestamp() Optional[datetime.datetime] [source]
Return the age of the latest parameter value.
It is recommended to use
parameter.cache.timestamp
instead.
- class qcodes.instrument.parameter.InstrumentRefParameter(name: str, instrument: Optional[InstrumentBase] = None, label: Optional[str] = None, unit: Optional[str] = None, get_cmd: Optional[Union[str, Callable[[...], Any], Literal[False]]] = None, set_cmd: Optional[Union[str, Callable[[...], Any], Literal[False]]] = None, initial_value: Optional[Union[float, str]] = None, max_val_age: Optional[float] = None, vals: Optional[qcodes.utils.validators.Validator[Any]] = None, docstring: Optional[str] = None, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter.Parameter
An instrument reference parameter.
This parameter is useful when one needs a reference to another instrument from within an instrument, e.g., when creating a meta instrument that sets parameters on instruments it contains.
- Parameters
name – The name of the parameter that one wants to add.
instrument – The “parent” instrument this parameter is attached to, if any.
initial_value – Starting value, may be None even if None does not pass the validator. None is only allowed as an initial value and cannot be set after initiation.
**kwargs – Passed to InstrumentRefParameter parent class
- __getitem__(keys: Any) qcodes.instrument.sweep_values.SweepFixedValues
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- get_raw() Any
get_raw
is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively 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: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_raw(value: Any) None
set_raw
is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively 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) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) qcodes.instrument.sweep_values.SweepFixedValues
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns
Collection of parameter values to be iterated over.
- Return type
SweepFixedValues
Examples
>>> sweep(0, 10, num=5) [0.0, 2.5, 5.0, 7.5, 10.0] >>> sweep(5, 10, step=1) [5.0, 6.0, 7.0, 8.0, 9.0, 10.0] >>> sweep(15, 10.5, step=1.5) >[15.0, 13.5, 12.0, 10.5]
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- class qcodes.instrument.parameter.ManualParameter(name: str, instrument: Optional[InstrumentBase] = None, initial_value: Any = None, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter.Parameter
A simple alias for a parameter that does not have a set or a get function. Useful for parameters that do not have a direct instrument mapping.
- __getitem__(keys: Any) qcodes.instrument.sweep_values.SweepFixedValues
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- get_raw() Any
get_raw
is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively 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: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_raw(value: Any) None
set_raw
is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively 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) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) qcodes.instrument.sweep_values.SweepFixedValues
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns
Collection of parameter values to be iterated over.
- Return type
SweepFixedValues
Examples
>>> sweep(0, 10, num=5) [0.0, 2.5, 5.0, 7.5, 10.0] >>> sweep(5, 10, step=1) [5.0, 6.0, 7.0, 8.0, 9.0, 10.0] >>> sweep(15, 10.5, step=1.5) >[15.0, 13.5, 12.0, 10.5]
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- class qcodes.instrument.parameter.MultiParameter(name: str, names: Sequence[str], shapes: Sequence[Sequence[int]], instrument: Optional[InstrumentBase] = None, labels: Optional[Sequence[str]] = None, units: Optional[Sequence[str]] = None, setpoints: Optional[Sequence[Sequence[Any]]] = None, setpoint_names: Optional[Sequence[Sequence[str]]] = None, setpoint_labels: Optional[Sequence[Sequence[str]]] = None, setpoint_units: Optional[Sequence[Sequence[str]]] = None, docstring: Optional[str] = None, snapshot_get: bool = True, snapshot_value: bool = False, snapshot_exclude: bool = False, metadata: Optional[Mapping[Any, Any]] = None, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter._BaseParameter
A gettable parameter that returns multiple values with separate names, each of arbitrary shape. Not necessarily part of an instrument.
Subclasses should define a
.get_raw
method, which returns a sequence of values. This method is automatically wrapped to provide a.get
method. When used in a legacy method``Loop`` 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.
- property short_names: Tuple[str, ...]
short_names is identical to names i.e. the names of the parameter parts but does not add the instrument name.
It exists for consistency with instruments and other parameters.
- property full_names: Tuple[str, ...]
Names of the parameter components including the name of the instrument and submodule that the parameter may be bound to. The name parts are separated by underscores, like this:
instrument_submodule_parameter
- property setpoint_full_names: Optional[Sequence[Sequence[str]]]
Full names of setpoints including instrument names, if available
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- get_raw() Any
get_raw
is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively 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: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_raw(value: Any) None
set_raw
is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively 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) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- class qcodes.instrument.parameter.Parameter(name: str, instrument: Optional[InstrumentBase] = None, label: Optional[str] = None, unit: Optional[str] = None, get_cmd: Optional[Union[str, Callable[[...], Any], Literal[False]]] = None, set_cmd: Optional[Union[str, Callable[[...], Any], Literal[False]]] = False, initial_value: Optional[Union[float, str]] = None, max_val_age: Optional[float] = None, vals: Optional[qcodes.utils.validators.Validator[Any]] = None, docstring: Optional[str] = None, initial_cache_value: Optional[Union[float, str]] = None, bind_to_instrument: bool = True, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter._BaseParameter
A parameter represents a single degree of freedom. Most often, this is the standard parameter for Instruments, though it can also be used as a variable, i.e. storing/retrieving a value, or be subclassed for more complex uses.
By default only gettable, returning its last value. This behaviour can be modified in two ways:
Providing a
get_cmd
/set_cmd
, which can do the following: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.
- 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.
- __getitem__(keys: Any) qcodes.instrument.sweep_values.SweepFixedValues [source]
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- increment(value: Any) None [source]
Increment the parameter with a value
- Parameters
value – Value to be added to the parameter.
- sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) qcodes.instrument.sweep_values.SweepFixedValues [source]
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns
Collection of parameter values to be iterated over.
- Return type
SweepFixedValues
Examples
>>> sweep(0, 10, num=5) [0.0, 2.5, 5.0, 7.5, 10.0] >>> sweep(5, 10, step=1) [5.0, 6.0, 7.0, 8.0, 9.0, 10.0] >>> sweep(15, 10.5, step=1.5) >[15.0, 13.5, 12.0, 10.5]
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- property instrument: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_to(value: Any, allow_changes: bool = False) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- class qcodes.instrument.parameter.ParameterWithSetpoints(name: str, *, vals: Optional[qcodes.utils.validators.Validator[Any]] = None, setpoints: Optional[Sequence[qcodes.instrument.parameter._BaseParameter]] = None, snapshot_get: bool = False, snapshot_value: bool = False, **kwargs: Any)[source]
Bases:
qcodes.instrument.parameter.Parameter
A parameter that has associated setpoints. The setpoints is nothing more than a list of other parameters that describe the values, names and units of the setpoint axis for this parameter.
In most cases this will probably be a parameter that returns an array. It is expected that the setpoint arrays are 1D arrays such that the combined shape of the parameter e.g. if parameter is of shape (m,n) setpoints is a list of parameters of shape (m,) and (n,)
In all other ways this is identical to
Parameter
. See the documentation ofParameter
for more details.- property setpoints: Sequence[qcodes.instrument.parameter._BaseParameter]
Sequence of parameters to use as setpoints for this parameter.
- Getter
Returns a list of parameters currently used for setpoints.
- Setter
Sets the parameters to be used as setpoints from a sequence. The combined shape of the parameters supplied must be consistent with the data shape of the data returned from get on the parameter.
- validate_consistent_shape() None [source]
Verifies that the shape of the Array Validator of the parameter is consistent with the Validator of the Setpoints. This requires that both the setpoints and the actual parameters have validators of type Arrays with a defined shape.
- validate(value: Any) None [source]
Overwrites the standard
validate
method to also check the the parameter has consistent shape with its setpoints. This only makes sense if the parameter has an Arrays validatorArguments are passed to the super method
- __getitem__(keys: Any) qcodes.instrument.sweep_values.SweepFixedValues
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- get_raw() Any
get_raw
is called to perform the actual data acquisition from the instrument. This method should either be overwritten to perform the desired operation or alternatively 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: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_raw(value: Any) None
set_raw
is called to perform the actual setting of a parameter on the instrument. This method should either be overwritten to perform the desired operation or alternatively 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) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) qcodes.instrument.sweep_values.SweepFixedValues
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns
Collection of parameter values to be iterated over.
- Return type
SweepFixedValues
Examples
>>> sweep(0, 10, num=5) [0.0, 2.5, 5.0, 7.5, 10.0] >>> sweep(5, 10, step=1) [5.0, 6.0, 7.0, 8.0, 9.0, 10.0] >>> sweep(15, 10.5, step=1.5) >[15.0, 13.5, 12.0, 10.5]
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be thehardware_instrument
, howeverunderlying_instrument
can be implemented to return thehardware_instrument
.By default it returns the
root_instrument
of the parameter.
- cache: qcodes.instrument.parameter._CacheProtocol = ()
- get_latest: qcodes.instrument.parameter.GetLatest = ()
- get: Callable[[...], Any] = ()
- class qcodes.instrument.parameter.ScaledParameter(output: qcodes.instrument.parameter.Parameter, division: Optional[Union[float, qcodes.instrument.parameter.Parameter]] = None, gain: Optional[Union[float, qcodes.instrument.parameter.Parameter]] = None, name: Optional[str] = None, label: Optional[str] = None, unit: Optional[str] = None)[source]
Bases:
qcodes.instrument.parameter.Parameter
Parameter
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.
- __getitem__(keys: Any) qcodes.instrument.sweep_values.SweepFixedValues
Slice a Parameter to get a SweepValues object to iterate over during a sweep
- property full_name: str
Name of the parameter including the name of the instrument and submodule that the parameter may be bound to. The names are separated by underscores, like this:
instrument_submodule_parameter
.
- get_ramp_values(value: Union[float, Sized], step: Optional[float] = None) Sequence[Union[float, Sized]]
Return values to sweep from current value to target value. This method can be overridden to have a custom sweep behaviour. It can even be overridden by a generator.
- Parameters
value – target value
step – maximum step size
- Returns
List of stepped values, including target value.
- increment(value: Any) None
Increment the parameter with a value
- Parameters
value – Value to be added to the parameter.
- property instrument: Optional[InstrumentBase]
Return the first instrument that this parameter is bound to. E.g if this is bound to a channel it will return the channel and not the instrument that the channel is bound too. Use
root_instrument()
to get the real instrument.
- property inter_delay: float
Delay time between consecutive set operations. The actual time will not be shorter than this, but may be longer if the underlying set call takes longer.
Typically used in conjunction with step to create an effective ramp rate, but can also be used without a step to enforce a delay between sets.
- Getter
Returns the current inter_delay.
- Setter
Sets the value of the inter_delay.
- Raises
TypeError – If delay is not int nor float
ValueError – If delay is negative
- load_metadata(metadata: 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.
- restore_at_exit(allow_changes: bool = True) qcodes.instrument.parameter._SetParamContext
Use a context manager to restore the value of a parameter after a
with
block.By default, the parameter value may be changed inside the block, but this can be prevented with
allow_changes=False
. This can be useful, for example, for debugging a complex measurement that unintentionally modifies a parameter.Example
>>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.restore_at_exit(): ... p.set(3) ... print(f"value inside with block: {p.get()}") # prints 3 >>> print(f"value after with block: {p.get()}") # prints 2 >>> with p.restore_at_exit(allow_changes=False): ... p.set(5) # raises an exception
- property root_instrument: Optional[InstrumentBase]
Return the fundamental instrument that this parameter belongs too. E.g if the parameter is bound to a channel this will return the fundamental instrument that that channel belongs to. Use
instrument()
to get the channel.
- set_to(value: Any, allow_changes: bool = False) qcodes.instrument.parameter._SetParamContext
Use a context manager to temporarily set a parameter to a value. By default, the parameter value cannot be changed inside the context. This may be overridden with
allow_changes=True
.Examples
>>> from qcodes import Parameter >>> p = Parameter("p", set_cmd=None, get_cmd=None) >>> p.set(2) >>> with p.set_to(3): ... print(f"p value in with block {p.get()}") # prints 3 ... p.set(5) # raises an exception >>> print(f"p value outside with block {p.get()}") # prints 2 >>> with p.set_to(3, allow_changes=True): ... p.set(5) # now this works >>> print(f"value after second block: {p.get()}") # still prints 2
- property short_name: str
Short name of the parameter. This is without the name of the instrument or submodule that the parameter may be bound to. For full name refer to
full_name()
.
- snapshot(update: Optional[bool] = False) Dict[Any, Any]
Decorate a snapshot dictionary with metadata. DO NOT override this method if you want metadata in the snapshot instead, override
snapshot_base()
.- Parameters
update – Passed to snapshot_base.
- Returns
Base snapshot.
- snapshot_base(update: Optional[bool] = True, params_to_skip_update: Optional[Sequence[str]] = None) Dict[Any, Any]
State of the parameter as a JSON-compatible dict (everything that the custom JSON encoder class
qcodes.utils.helpers.NumpyJSONEncoder
supports).If the parameter has been initiated with
snapshot_value=False
, the snapshot will NOT include 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: Optional[float]
Stepsize that this Parameter uses during set operation. Stepsize must be a positive number or None. If step is a positive number, this is the maximum value change allowed in one hardware call, so a single set can result in many calls to the hardware if the starting value is far from the target. All but the final change will attempt to change by +/- step exactly. If step is None stepping will not be used.
- Getter
Returns the current stepsize.
- Setter
Sets the value of the step.
- Raises
TypeError – if step is set to not numeric or None
ValueError – if step is set to negative
TypeError – if step is set to not integer or None for an integer parameter
TypeError – if step is set to not a number on None
- sweep(start: float, stop: float, step: Optional[float] = None, num: Optional[int] = None) qcodes.instrument.sweep_values.SweepFixedValues
Create a collection of parameter values to be iterated over. Requires start and stop and (step or num) The sign of step is not relevant.
- Parameters
start – The starting value of the sequence.
stop – The end value of the sequence.
step – Spacing between values.
num – Number of values to generate.
- Returns
Collection of parameter values to be iterated over.
- Return type
SweepFixedValues
Examples
>>> sweep(0, 10, num=5) [0.0, 2.5, 5.0, 7.5, 10.0] >>> sweep(5, 10, step=1) [5.0, 6.0, 7.0, 8.0, 9.0, 10.0] >>> sweep(15, 10.5, step=1.5) >[15.0, 13.5, 12.0, 10.5]
- property underlying_instrument: Optional[InstrumentBase]
Returns an instance of the underlying hardware instrument that this parameter communicates with, per this parameter’s implementation.
This is useful in the case where a parameter does not belongs to an instrument instance that represents a real hardware instrument but actually uses a real hardware instrument in its implementation (e.g. via calls to one or more parameters of that real hardware instrument). This is also useful when a parameter does belong to an instrument instance but that instance does not represent the real hardware instrument that the parameter interacts with: hence
root_instrument
of the parameter cannot be 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.
- cache: qcodes.instrument.parameter._CacheProtocol = ()
- get_latest: qcodes.instrument.parameter.GetLatest = ()
- get: Callable[[...], Any] = ()
- property wrapped_parameter: qcodes.instrument.parameter.Parameter
The attached unscaled parameter
- qcodes.instrument.parameter.combine(*parameters: qcodes.instrument.parameter.Parameter, name: str, label: Optional[str] = None, unit: Optional[str] = None, units: Optional[str] = None, aggregator: Optional[Callable[[Sequence[Any]], Any]] = None) qcodes.instrument.parameter.CombinedParameter [source]
Combine parameters into one sweepable parameter
A combined parameter sets all the combined parameters at every point of the sweep. The sets are called in the same order the parameters are, and sequentially.
- Parameters
*parameters – The parameters to combine.
name – The name of the paramter.
label – The label of the combined parameter.
unit – the unit of the combined parameter.
aggregator – a function to aggregate the set values into one.
- qcodes.instrument.parameter.expand_setpoints_helper(parameter: qcodes.instrument.parameter.ParameterWithSetpoints, results: Optional[Any] = None) List[Tuple[qcodes.instrument.parameter._BaseParameter, Any]] [source]
A helper function that takes a
ParameterWithSetpoints
and acquires the parameter along with it’s setpoints. The data is returned in a format prepared to insert into the dataset.- Parameters
parameter – A
ParameterWithSetpoints
to be acquired and 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.