qcodes.instrument.channel

Base class for the channel of an instrument

class qcodes.instrument.channel.AutoLoadableChannelList(parent: qcodes.instrument.base.Instrument, name: str, chan_type: type, chan_list: Optional[Sequence[qcodes.instrument.channel.AutoLoadableInstrumentChannel]] = None, snapshotable: bool = True, multichan_paramclass: type = <class 'qcodes.instrument.channel.MultiChannelInstrumentParameter'>, **kwargs: Any)

Bases: qcodes.instrument.channel.ChannelList

Extends the QCoDeS ChannelList class to add the following features: - Automatically create channel objects on initialization - Make a add method to create channel objects

Parameters

• parent – the instrument to which this channel should be attached

• name – the name of the channel list

• chan_type – the type of channel contained within this list

• chan_list – An optional iterable of channels of type chan_type. This will create a list and immediately lock the ChannelList.

• snapshotable – Optionally disables taking of snapshots for a given channel list. This is used when objects stored inside a channel list are accessible in multiple ways and should not be repeated in an instrument snapshot.

• multichan_paramclass – The class of the object to be returned by the ChannelList __getattr__ method. Should be a subclass of MultiChannelInstrumentParameter.

• **kwargs – Keyword arguments to be passed to the load_from_instrument method of the channel class. Note that the kwargs are NOT passed to the __init__ of the super class.

Raises

• ValueError – If chan_type is not a subclass of InstrumentChannel

• ValueError – If multichan_paramclass is not a subclass of MultiChannelInstrumentParameter (note that a class is a subclass of itself).

__add__(other: qcodes.instrument.channel.ChannelTuple) → qcodes.instrument.channel.T

Return a new ChannelTuple containing the channels from both ChannelTuple self and r.

Both ChannelTuple must hold the same type and have the same parent.

Parameters

other – Right argument to add.

__getattr__(name: str) → Union[qcodes.instrument.channel.MultiChannelInstrumentParameter, Callable[[...], None], qcodes.instrument.channel.InstrumentModuleType]

Look up an attribute by name. If this is the name of a parameter or a function on the channel type contained in this container return a multi-channel function or parameter that can be used to get or set all items in a channel list simultaneously. If this is the name of a channel, return that channel.

Params:

name: The name of the parameter, function or channel that we want to operate on.

__getitem__(i: Union[int, slice, Tuple[int, ...]]) → Union[qcodes.instrument.channel.InstrumentModuleType, qcodes.instrument.channel.T]

Return either a single channel, or a new ChannelTuple containing only the specified channels

Parameters

i – Either a single channel index or a slice of channels to get

append(obj: qcodes.instrument.channel.InstrumentModuleType) → None

Append a Channel to this list. Requires that the ChannelList is not locked and that the channel is of the same type as the ones in the list.

Parameters

obj – New channel to add to the list.

clear() → None

Clear all items from the ChannelList.

count(obj: qcodes.instrument.channel.InstrumentModuleType) → int

Returns number of instances of the given object in the list

Parameters

obj – The object to find in the ChannelTuple.

extend(objects: Iterable[qcodes.instrument.channel.InstrumentModuleType]) → None

Insert an iterable of objects into the list of channels.

Parameters

objects – A list of objects to add into the ChannelList.

get_channel_by_name(*names: str) → Union[qcodes.instrument.channel.InstrumentModuleType, qcodes.instrument.channel.T]

Get a channel by name, or a ChannelTuple if multiple names are given.

Parameters

*names – channel names

get_validator() → qcodes.instrument.channel.ChannelTupleValidator

Returns a validator that checks that the returned object is a channel in this ChannelList.

Raises

AttributeError – If the ChannelList is not locked.

index(obj: qcodes.instrument.channel.InstrumentModuleType, start: int = 0, stop: int = 9223372036854775807) → int

Return the index of the given object

Parameters

• obj – The object to find in the channel list.

• start – Index to start searching from.

• stop – Index to stop searching at.

insert(index: int, obj: qcodes.instrument.channel.InstrumentModuleType) → None

Insert an object into the ChannelList at a specific index.

Parameters

• index – Index to insert object.

• obj – Object of type chan_type to insert.

invalidate_cache() → None

Invalidate the cache of all parameters on the ChannelTuple.

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

Load metadata into this classes metadata dictionary.

Parameters

metadata – Metadata to load.

lock() → None

Lock the channel list. Once this is done, the ChannelList is locked and any future changes to the list are prevented. Note this is not recommended and may be deprecated in the future. Use to_channel_tuple to convert this into a tuple instead.

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

print_readable_snapshot(update: bool = False, max_chars: int = 80) → None

remove(obj: qcodes.instrument.channel.InstrumentModuleType) → None

Removes obj from ChannelList if not locked.

Parameters

obj – Channel to remove from the list.

reverse()

S.reverse() – reverse IN PLACE

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 instrument as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

Parameters

• update – If True, update the state by querying the instrument. If None only update if the state is known to be invalid. If False, just use the latest values in memory and never update.

• params_to_skip_update – List of parameter names that will be skipped in update even if update is True. This is useful if you have parameters that are slow to update but can be updated in a different way (as in the qdac). If you want to skip the update of certain parameters in all snapshots, use the snapshot_get attribute of those parameters instead.

Returns

base snapshot

Return type

dict

to_channel_tuple() → qcodes.instrument.channel.ChannelTuple

Returns a ChannelTuple build from this ChannelList containing the same channels but without the ability to be modified.

add(**kwargs: Any) → qcodes.instrument.channel.AutoLoadableInstrumentChannel

Add a channel to the list

Parameters

kwargs – Keyword arguments passed to the new_instance method of the channel class

Returns

Newly created instance of the channel class

class qcodes.instrument.channel.AutoLoadableInstrumentChannel(parent: Union[qcodes.instrument.base.Instrument, qcodes.instrument.channel.InstrumentChannel], name: str, exists_on_instrument: bool = False, channel_list: Optional[qcodes.instrument.channel.AutoLoadableChannelList] = None, **kwargs: Any)

Bases: qcodes.instrument.channel.InstrumentChannel

This subclass provides extensions to auto-load channels from instruments and adds methods to create and delete channels when possible. Please note that channel in this context does not necessarily mean a physical instrument channel, but rather an instrument sub-module. For some instruments, these sub-modules can be created and deleted at will.

Instantiate a channel object. Note that this is not the same as actually creating the channel on the instrument. Parameters defined on this channels will not be able to query/write to the instrument until it has been created on the instrument

Parameters

• parent – The instrument through which the instrument channel is accessible

• name – channel name

• exists_on_instrument – True if the channel exists on the instrument

• channel_list – Reference to the list that this channel is a member of; this is used when deleting the channel so that it can remove itself from the list

classmethod load_from_instrument(parent: qcodes.instrument.base.Instrument, channel_list: Optional[qcodes.instrument.channel.AutoLoadableChannelList] = None, **kwargs: Any) → List[qcodes.instrument.channel.AutoLoadableInstrumentChannel]

Load channels that already exist on the instrument

Parameters

• parent – The instrument through which the instrument channel is accessible

• channel_list – The channel list this channel is a part of

• **kwargs – Keyword arguments needed to create the channels

Returns

List of instrument channel instances created for channels that already exist on the instrument

classmethod new_instance(parent: qcodes.instrument.base.Instrument, create_on_instrument: bool = True, channel_list: Optional[qcodes.instrument.channel.AutoLoadableChannelList] = None, **kwargs: Any) → qcodes.instrument.channel.AutoLoadableInstrumentChannel

Create a new instance of the channel on the instrument: This involves finding initialization arguments which will create a channel with a unique name and create the channel on the instrument.

Parameters

• parent – The instrument through which the instrument channel is accessible

• create_on_instrument – When True, the channel is immediately created on the instrument

• channel_list – The channel list this channel is going to belong to

• **kwargs – Keyword arguments needed to create a new instance.

create() → None

Create the channel on the instrument

__getitem__(key: str) → Union[Callable[[...], Any], qcodes.instrument.parameter.Parameter]

Delegate instrument[‘name’] to parameter or function ‘name’.

__getstate__() → None

Prevent pickling instruments, and give a nice error message.

__repr__() → str

Custom repr to give parent information

add_function(name: str, **kwargs: Any) → None

Bind one Function to this instrument.

Instrument subclasses can call this repeatedly in their __init__ for every real function of the instrument.

This functionality is meant for simple cases, principally things that map to simple commands like *RST (reset) or those with just a few arguments. It requires a fixed argument count, and positional args only. If your case is more complicated, you’re probably better off simply making a new method in your Instrument subclass definition.

Parameters

• name – How the Function will be stored within instrument.Functions and also how you address it using the shortcut methods: instrument.call(func_name, *args) etc.

• **kwargs – constructor kwargs for Function

Raises

KeyError – If this instrument already has a function with this name.

add_parameter(name: str, parameter_class: type = <class 'qcodes.instrument.parameter.Parameter'>, **kwargs: Any) → None

Bind one Parameter to this instrument.

Instrument subclasses can call this repeatedly in their __init__ for every real parameter of the instrument.

In this sense, parameters are the state variables of the instrument, anything the user can set and/or get.

Parameters

• name – How the parameter will be stored within instrument.parameters and also how you address it using the shortcut methods: instrument.set(param_name, value) etc.

• parameter_class – You can construct the parameter out of any class. Default parameter.Parameter.

• **kwargs – Constructor arguments for parameter_class.

Raises

• KeyError – If this instrument already has a parameter with this name and the parameter being replaced is not an abstract parameter.

• ValueError – If there is an existing abstract parameter and the unit of the new parameter is inconsistent with the existing one.

add_submodule(name: str, submodule: Union[InstrumentModule, ChannelTuple]) → None

Bind one submodule to this instrument.

Instrument subclasses can call this repeatedly in their __init__ method for every submodule of the instrument.

Submodules can effectively be considered as instruments within the main instrument, and should at minimum be snapshottable. For example, they can be used to either store logical groupings of parameters, which may or may not be repeated, or channel lists. They should either be an instance of an InstrumentModule or a ChannelTuple.

Parameters

• name – How the submodule will be stored within instrument.submodules and also how it can be addressed.

• submodule – The submodule to be stored.

Raises

• KeyError – If this instrument already contains a submodule with this name.

• TypeError – If the submodule that we are trying to add is not an instance of an Metadatable object.

property ancestors: List[qcodes.instrument.base.InstrumentBase]

Returns a list of instruments, starting from the current instrument and following to the parent instrument and the parents parent instrument until the root instrument is reached.

ask_raw(cmd: str) → str

call(func_name: str, *args: Any) → Any

Shortcut for calling a function from its name.

Parameters

• func_name – The name of a function of this instrument.

• *args – any arguments to the function.

Returns

The return value of the function.

delegate_attr_dicts: List[str] = ['parameters', 'functions', 'submodules']

A list of names (strings) of dictionaries which are (or will be) attributes of self, whose keys should be treated as attributes of self.

delegate_attr_objects: List[str] = []

A list of names (strings) of objects which are (or will be) attributes of self, whose attributes should be passed through to self.

property full_name: str

get(param_name: str) → Any

Shortcut for getting a parameter from its name.

Parameters

param_name – The name of a parameter of this instrument.

Returns

The current value of the parameter.

invalidate_cache() → None

Invalidate the cache of all parameters on the instrument. Calling this method will recursively mark the cache of all parameters on the instrument and any parameter on instrument modules as invalid.

This is useful if you have performed manual operations (e.g. using the frontpanel) which changes the state of the instrument outside QCoDeS.

This in turn means that the next snapshot of the instrument will trigger a (potentially slow) reread of all parameters of the instrument if you pass update=None to snapshot.

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 instrument This is equivalent to full_name for backwards compatibility.

property name_parts: List[str]

omit_delegate_attrs: List[str] = []

A list of attribute names (strings) to not delegate to any other dictionary or object.

property parent: qcodes.instrument.base.InstrumentBase

Returns the parent instrument. By default this is None. Any SubInstrument should subclass this to return the parent instrument.

print_readable_snapshot(update: bool = False, max_chars: int = 80) → None

Prints a readable version of the snapshot. The readable snapshot includes the name, value and unit of each parameter. A convenience function to quickly get an overview of the status of an instrument.

Parameters

• update – If True, update the state by querying the instrument. If False, just use the latest values in memory. This argument gets passed to the snapshot function.

• max_chars – the maximum number of characters per line. The readable snapshot will be cropped if this value is exceeded. Defaults to 80 to be consistent with default terminal width.

property root_instrument: qcodes.instrument.base.InstrumentBase

set(param_name: str, value: Any) → None

Shortcut for setting a parameter from its name and new value.

Parameters

• param_name – The name of a parameter of this instrument.

• value – The new value to set.

property short_name: str

Short name of the instrument

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]

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

Parameters

• update – If True, update the state by querying the instrument. If None update the state if known to be invalid. If False, just use the latest values in memory and never update state.

• params_to_skip_update – List of parameter names that will be skipped in update even if update is True. This is useful if you have parameters that are slow to update but can be updated in a different way (as in the qdac). If you want to skip the update of certain parameters in all snapshots, use the snapshot_get attribute of those parameters instead.

Returns

base snapshot

Return type

dict

validate_status(verbose: bool = False) → None

Validate the values of all gettable parameters

The validation is done for all parameters that have both a get and set method.

Parameters

verbose – If True, then information about the parameters that are being check is printed.

write_raw(cmd: str) → None

parameters: Dict[str, _BaseParameter] = {}

All the parameters supported by this instrument. Usually populated via add_parameter().

functions: Dict[str, Function] = {}

All the functions supported by this instrument. Usually populated via add_function().

submodules: Dict[str, Union['InstrumentModule', 'ChannelTuple']] = {}

All the submodules of this instrument such as channel lists or logical groupings of parameters. Usually populated via add_submodule().

instrument_modules: Dict[str, 'InstrumentModule'] = {}

All the instrument_modules of this instrument Usually populated via add_submodule().

metadata: Dict[str, Any] = {}

remove() → None

Delete the channel from the instrument and remove from channel list

write(cmd: str) → None

Write to the instrument only if the channel is present on the instrument

ask(cmd: str) → str

Ask the instrument only if the channel is present on the instrument

property exists_on_instrument: bool

class qcodes.instrument.channel.ChannelList(parent: qcodes.instrument.base.InstrumentBase, name: str, chan_type: Type[qcodes.instrument.channel.InstrumentModuleType], chan_list: Optional[Sequence[qcodes.instrument.channel.InstrumentModuleType]] = None, snapshotable: bool = True, multichan_paramclass: type = <class 'qcodes.instrument.channel.MultiChannelInstrumentParameter'>)

Bases: qcodes.instrument.channel.ChannelTuple, MutableSequence[qcodes.instrument.channel.InstrumentModuleType]

Mutable Container for channelized parameters that allows for sweeps over all channels, as well as addressing of individual channels.

This behaves like a python list i.e. it implements the collections.abc.MutableSequence interface.

Note it may be useful to use the mutable ChannelList while constructing it. E.g. adding channels as they are created, but in most use cases it is recommended to convert this to a ChannelTuple before adding it to an instrument. This can be done using the to_channel_tuple method.

Parameters

• parent – The instrument to which this ChannelList should be attached.

• name – The name of the ChannelList.

• chan_type – The type of channel contained within this list.

• chan_list – An optional iterable of channels of type chan_type. This will create a list and immediately lock the ChannelList.

• snapshotable – Optionally disables taking of snapshots for a given ChannelList. This is used when objects stored inside a ChannelList are accessible in multiple ways and should not be repeated in an instrument snapshot.

• multichan_paramclass – The class of the object to be returned by the __getattr__ method of ChannelList. Should be a subclass of MultiChannelInstrumentParameter.

Raises

• ValueError – If chan_type is not a subclass of InstrumentChannel

• ValueError – If multichan_paramclass is not a subclass of MultiChannelInstrumentParameter (note that a class is a subclass of itself).

append(obj: qcodes.instrument.channel.InstrumentModuleType) → None

Append a Channel to this list. Requires that the ChannelList is not locked and that the channel is of the same type as the ones in the list.

Parameters

obj – New channel to add to the list.

clear() → None

Clear all items from the ChannelList.

remove(obj: qcodes.instrument.channel.InstrumentModuleType) → None

Removes obj from ChannelList if not locked.

Parameters

obj – Channel to remove from the list.

extend(objects: Iterable[qcodes.instrument.channel.InstrumentModuleType]) → None

Insert an iterable of objects into the list of channels.

Parameters

objects – A list of objects to add into the ChannelList.

insert(index: int, obj: qcodes.instrument.channel.InstrumentModuleType) → None

Insert an object into the ChannelList at a specific index.

Parameters

• index – Index to insert object.

• obj – Object of type chan_type to insert.

get_validator() → qcodes.instrument.channel.ChannelTupleValidator

Returns a validator that checks that the returned object is a channel in this ChannelList.

Raises

AttributeError – If the ChannelList is not locked.

lock() → None

Lock the channel list. Once this is done, the ChannelList is locked and any future changes to the list are prevented. Note this is not recommended and may be deprecated in the future. Use to_channel_tuple to convert this into a tuple instead.

to_channel_tuple() → qcodes.instrument.channel.ChannelTuple

Returns a ChannelTuple build from this ChannelList containing the same channels but without the ability to be modified.

__add__(other: qcodes.instrument.channel.ChannelTuple) → qcodes.instrument.channel.T

Return a new ChannelTuple containing the channels from both ChannelTuple self and r.

Both ChannelTuple must hold the same type and have the same parent.

Parameters

other – Right argument to add.

__getattr__(name: str) → Union[qcodes.instrument.channel.MultiChannelInstrumentParameter, Callable[[...], None], qcodes.instrument.channel.InstrumentModuleType]

Look up an attribute by name. If this is the name of a parameter or a function on the channel type contained in this container return a multi-channel function or parameter that can be used to get or set all items in a channel list simultaneously. If this is the name of a channel, return that channel.

Params:

name: The name of the parameter, function or channel that we want to operate on.

__getitem__(i: Union[int, slice, Tuple[int, ...]]) → Union[qcodes.instrument.channel.InstrumentModuleType, qcodes.instrument.channel.T]

Return either a single channel, or a new ChannelTuple containing only the specified channels

Parameters

i – Either a single channel index or a slice of channels to get

count(obj: qcodes.instrument.channel.InstrumentModuleType) → int

Returns number of instances of the given object in the list

Parameters

obj – The object to find in the ChannelTuple.

get_channel_by_name(*names: str) → Union[qcodes.instrument.channel.InstrumentModuleType, qcodes.instrument.channel.T]

Get a channel by name, or a ChannelTuple if multiple names are given.

Parameters

*names – channel names

index(obj: qcodes.instrument.channel.InstrumentModuleType, start: int = 0, stop: int = 9223372036854775807) → int

Return the index of the given object

Parameters

• obj – The object to find in the channel list.

• start – Index to start searching from.

• stop – Index to stop searching at.

invalidate_cache() → None

Invalidate the cache of all parameters on the ChannelTuple.

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

Load metadata into this classes metadata dictionary.

Parameters

metadata – Metadata to load.

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

print_readable_snapshot(update: bool = False, max_chars: int = 80) → None

reverse()

S.reverse() – reverse IN PLACE

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 instrument as a JSON-compatible dict (everything that the custom JSON encoder class qcodes.utils.helpers.NumpyJSONEncoder supports).

Parameters

• update – If True, update the state by querying the instrument. If None only update if the state is known to be invalid. If False, just use the latest values in memory and never update.

• params_to_skip_update – List of parameter names that will be skipped in update even if update is True. This is useful if you have parameters that are slow to update but can be updated in a different way (as in the qdac). If you want to skip the update of certain parameters in all snapshots, use the snapshot_get attribute of those parameters instead.

Returns

base snapshot

Return type

dict

class qcodes.instrument.channel.ChannelListValidator(channel_list: qcodes.instrument.channel.ChannelTuple)

Bases: qcodes.instrument.channel.ChannelTupleValidator

Alias for backwards compatibility. Do not use

is_numeric = False

property valid_values: Tuple[qcodes.utils.validators.T, ...]

validate(value: qcodes.instrument.channel.InstrumentChannel, context: str = '') → None

Checks to see that value is a member of the ChannelTuple referenced by this validator

Parameters

• value – the value to be checked against the reference channel list.

• context – the context of the call, used as part of the exception raised.

class qcodes.instrument.channel.ChannelTuple(parent: qcodes.instrument.base.InstrumentBase, name: str, chan_type: Type[qcodes.instrument.channel.InstrumentModuleType], chan_list: Optional[Sequence[qcodes.instrument.channel.InstrumentModuleType]] = None, snapshotable: bool = True, multichan_paramclass: type = <class 'qcodes.instrument.channel.MultiChannelInstrumentParameter'>)

Bases: qcodes.utils.metadata.Metadatable, Sequence[qcodes.instrument.channel.InstrumentModuleType]

Container for channelized parameters that allows for sweeps over all channels, as well as addressing of individual channels.

This behaves like a python tuple i.e. it implements the collections.abc.Sequence interface.

Parameters

• parent – The instrument to which this ChannelTuple should be attached.

• name – The name of the ChannelTuple.

• chan_type – The type of channel contained within this tuple.

• chan_list – An optional iterable of channels of type chan_type.

• snapshotable – Optionally disables taking of snapshots for a given ChannelTuple. This is used when objects stored inside a ChannelTuple are accessible in multiple ways and should not be repeated in an instrument snapshot.

• multichan_paramclass – The class of the object to be returned by the __getattr__ method of ChannelTuple. Should be a subclass of MultiChannelInstrumentParameter.

Raises

• ValueError – If chan_type is not a subclass of InstrumentChannel

• ValueError – If multichan_paramclass is not a subclass of MultiChannelInstrumentParameter (note that a class is a subclass of itself).

__getitem__(i: int) → qcodes.instrument.channel.InstrumentModuleType

__getitem__(i: Union[slice, Tuple[int, ...]]) → qcodes.instrument.channel.T

Return either a single channel, or a new ChannelTuple containing only the specified channels

Parameters

i – Either a single channel index or a slice of channels to get

__add__(other: qcodes.instrument.channel.ChannelTuple) → qcodes.instrument.channel.T

Return a new ChannelTuple containing the channels from both ChannelTuple self and r.

Both ChannelTuple must hold the same type and have the same parent.

Parameters

other – Right argument to add.

index(obj: qcodes.instrument.channel.InstrumentModuleType, start: int = 0, stop: int = 9223372036854775807) → int

Return the index of the given object

Parameters

• obj – The object to find in the channel list.

• start – Index to start searching from.

• stop – Index to stop searching at.

count(obj: qcodes.instrument.channel.InstrumentModuleType) → int

Returns number of instances of the given object in the list

Parameters

obj – The object to find in the ChannelTuple.

get_channel_by_name(*names: str) → Union[qcodes.instrument.channel.InstrumentModuleType, qcodes.instrument.channel.T]

Get a channel by name, or a ChannelTuple if multiple names are given.

Parameters

*names – channel names

get_validator() → qcodes.instrument.channel.ChannelTupleValidator

Returns a validator that checks that the returned object is a channel in this ChannelTuple

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

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

Parameters

• update – If True, update the state by querying the instrument. If None only update if the state is known to be invalid. If False, just use the latest values in memory and never update.

• params_to_skip_update – List of parameter names that will be skipped in update even if update is True. This is useful if you have parameters that are slow to update but can be updated in a different way (as in the qdac). If you want to skip the update of certain parameters in all snapshots, use the snapshot_get attribute of those parameters instead.

Returns

base snapshot

Return type

dict

__getattr__(name: str) → Union[qcodes.instrument.channel.MultiChannelInstrumentParameter, Callable[[...], None], qcodes.instrument.channel.InstrumentModuleType]

Look up an attribute by name. If this is the name of a parameter or a function on the channel type contained in this container return a multi-channel function or parameter that can be used to get or set all items in a channel list simultaneously. If this is the name of a channel, return that channel.

Params:

name: The name of the parameter, function or channel that we want to operate on.

print_readable_snapshot(update: bool = False, max_chars: int = 80) → None

invalidate_cache() → None

Invalidate the cache of all parameters on the ChannelTuple.

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.

class qcodes.instrument.channel.ChannelTupleValidator(channel_list: qcodes.instrument.channel.ChannelTuple)

Bases: qcodes.utils.validators.Validator[qcodes.instrument.channel.InstrumentChannel]

A validator that checks that the returned object is a member of the ChannelTuple with which the validator was constructed.

This class will not normally be created directly, but created from a channel list using the ChannelTuple.get_validator method.

Parameters

channel_list – the ChannelTuple that should be checked against. The channel list must be locked and populated before it can be used to construct a validator.

validate(value: qcodes.instrument.channel.InstrumentChannel, context: str = '') → None

Checks to see that value is a member of the ChannelTuple referenced by this validator

Parameters

• value – the value to be checked against the reference channel list.

• context – the context of the call, used as part of the exception raised.

is_numeric = False

property valid_values: Tuple[qcodes.utils.validators.T, ...]

class qcodes.instrument.channel.InstrumentChannel(parent: qcodes.instrument.base.InstrumentBase, name: str, **kwargs: Any)

Bases: qcodes.instrument.channel.InstrumentModule

__getitem__(key: str) → Union[Callable[[...], Any], qcodes.instrument.parameter.Parameter]

Delegate instrument[‘name’] to parameter or function ‘name’.

__getstate__() → None

Prevent pickling instruments, and give a nice error message.

__repr__() → str

Custom repr to give parent information

add_function(name: str, **kwargs: Any) → None

Bind one Function to this instrument.

Instrument subclasses can call this repeatedly in their __init__ for every real function of the instrument.

This functionality is meant for simple cases, principally things that map to simple commands like *RST (reset) or those with just a few arguments. It requires a fixed argument count, and positional args only. If your case is more complicated, you’re probably better off simply making a new method in your Instrument subclass definition.

Parameters

• name – How the Function will be stored within instrument.Functions and also how you address it using the shortcut methods: instrument.call(func_name, *args) etc.

• **kwargs – constructor kwargs for Function

Raises

KeyError – If this instrument already has a function with this name.

add_parameter(name: str, parameter_class: type = <class 'qcodes.instrument.parameter.Parameter'>, **kwargs: Any) → None

Bind one Parameter to this instrument.

Instrument subclasses can call this repeatedly in their __init__ for every real parameter of the instrument.

In this sense, parameters are the state variables of the instrument, anything the user can set and/or get.

Parameters

• name – How the parameter will be stored within instrument.parameters and also how you address it using the shortcut methods: instrument.set(param_name, value) etc.

• parameter_class – You can construct the parameter out of any class. Default parameter.Parameter.

• **kwargs – Constructor arguments for parameter_class.

Raises

• KeyError – If this instrument already has a parameter with this name and the parameter being replaced is not an abstract parameter.

• ValueError – If there is an existing abstract parameter and the unit of the new parameter is inconsistent with the existing one.

add_submodule(name: str, submodule: Union[InstrumentModule, ChannelTuple]) → None

Bind one submodule to this instrument.

Instrument subclasses can call this repeatedly in their __init__ method for every submodule of the instrument.

Submodules can effectively be considered as instruments within the main instrument, and should at minimum be snapshottable. For example, they can be used to either store logical groupings of parameters, which may or may not be repeated, or channel lists. They should either be an instance of an InstrumentModule or a ChannelTuple.

Parameters

• name – How the submodule will be stored within instrument.submodules and also how it can be addressed.

• submodule – The submodule to be stored.

Raises

• KeyError – If this instrument already contains a submodule with this name.

• TypeError – If the submodule that we are trying to add is not an instance of an Metadatable object.

property ancestors: List[qcodes.instrument.base.InstrumentBase]

Returns a list of instruments, starting from the current instrument and following to the parent instrument and the parents parent instrument until the root instrument is reached.

ask(cmd: str) → str

ask_raw(cmd: str) → str

call(func_name: str, *args: Any) → Any

Shortcut for calling a function from its name.

Parameters

• func_name – The name of a function of this instrument.

• *args – any arguments to the function.

Returns

The return value of the function.

delegate_attr_dicts: List[str] = ['parameters', 'functions', 'submodules']

A list of names (strings) of dictionaries which are (or will be) attributes of self, whose keys should be treated as attributes of self.

delegate_attr_objects: List[str] = []

A list of names (strings) of objects which are (or will be) attributes of self, whose attributes should be passed through to self.

property full_name: str

get(param_name: str) → Any

Shortcut for getting a parameter from its name.

Parameters

param_name – The name of a parameter of this instrument.

Returns

The current value of the parameter.

invalidate_cache() → None

Invalidate the cache of all parameters on the instrument. Calling this method will recursively mark the cache of all parameters on the instrument and any parameter on instrument modules as invalid.

This is useful if you have performed manual operations (e.g. using the frontpanel) which changes the state of the instrument outside QCoDeS.

This in turn means that the next snapshot of the instrument will trigger a (potentially slow) reread of all parameters of the instrument if you pass update=None to snapshot.

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 instrument This is equivalent to full_name for backwards compatibility.

property name_parts: List[str]

omit_delegate_attrs: List[str] = []

A list of attribute names (strings) to not delegate to any other dictionary or object.

property parent: qcodes.instrument.base.InstrumentBase

Returns the parent instrument. By default this is None. Any SubInstrument should subclass this to return the parent instrument.

print_readable_snapshot(update: bool = False, max_chars: int = 80) → None

Prints a readable version of the snapshot. The readable snapshot includes the name, value and unit of each parameter. A convenience function to quickly get an overview of the status of an instrument.

Parameters

• update – If True, update the state by querying the instrument. If False, just use the latest values in memory. This argument gets passed to the snapshot function.

• max_chars – the maximum number of characters per line. The readable snapshot will be cropped if this value is exceeded. Defaults to 80 to be consistent with default terminal width.

property root_instrument: qcodes.instrument.base.InstrumentBase

set(param_name: str, value: Any) → None

Shortcut for setting a parameter from its name and new value.

Parameters

• param_name – The name of a parameter of this instrument.

• value – The new value to set.

property short_name: str

Short name of the instrument

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]

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

Parameters

• update – If True, update the state by querying the instrument. If None update the state if known to be invalid. If False, just use the latest values in memory and never update state.

• params_to_skip_update – List of parameter names that will be skipped in update even if update is True. This is useful if you have parameters that are slow to update but can be updated in a different way (as in the qdac). If you want to skip the update of certain parameters in all snapshots, use the snapshot_get attribute of those parameters instead.

Returns

base snapshot

Return type

dict

validate_status(verbose: bool = False) → None

Validate the values of all gettable parameters

The validation is done for all parameters that have both a get and set method.

Parameters

verbose – If True, then information about the parameters that are being check is printed.

write(cmd: str) → None

write_raw(cmd: str) → None

parameters: Dict[str, _BaseParameter] = {}

All the parameters supported by this instrument. Usually populated via add_parameter().

functions: Dict[str, Function] = {}

All the functions supported by this instrument. Usually populated via add_function().

submodules: Dict[str, Union['InstrumentModule', 'ChannelTuple']] = {}

All the submodules of this instrument such as channel lists or logical groupings of parameters. Usually populated via add_submodule().

instrument_modules: Dict[str, 'InstrumentModule'] = {}

All the instrument_modules of this instrument Usually populated via add_submodule().

metadata: Dict[str, Any] = {}

class qcodes.instrument.channel.InstrumentModule(parent: qcodes.instrument.base.InstrumentBase, name: str, **kwargs: Any)

Bases: qcodes.instrument.base.InstrumentBase

Base class for a module in an instrument. This could be in the form of a channel (e.g. something that the instrument has multiple instances of) or another logical grouping of parameters that you wish to group together separate from the rest of the instrument.

Parameters

• parent – The instrument to which this module should be attached.

• name – The name of this module.

__repr__() → str

Custom repr to give parent information

write(cmd: str) → None

write_raw(cmd: str) → None

ask(cmd: str) → str

ask_raw(cmd: str) → str

property parent: qcodes.instrument.base.InstrumentBase

Returns the parent instrument. By default this is None. Any SubInstrument should subclass this to return the parent instrument.

property root_instrument: qcodes.instrument.base.InstrumentBase

property name_parts: List[str]

__getitem__(key: str) → Union[Callable[[...], Any], qcodes.instrument.parameter.Parameter]

Delegate instrument[‘name’] to parameter or function ‘name’.

__getstate__() → None

Prevent pickling instruments, and give a nice error message.

add_function(name: str, **kwargs: Any) → None

Bind one Function to this instrument.

Instrument subclasses can call this repeatedly in their __init__ for every real function of the instrument.

This functionality is meant for simple cases, principally things that map to simple commands like *RST (reset) or those with just a few arguments. It requires a fixed argument count, and positional args only. If your case is more complicated, you’re probably better off simply making a new method in your Instrument subclass definition.

Parameters

• name – How the Function will be stored within instrument.Functions and also how you address it using the shortcut methods: instrument.call(func_name, *args) etc.

• **kwargs – constructor kwargs for Function

Raises

KeyError – If this instrument already has a function with this name.

add_parameter(name: str, parameter_class: type = <class 'qcodes.instrument.parameter.Parameter'>, **kwargs: Any) → None

Bind one Parameter to this instrument.

Instrument subclasses can call this repeatedly in their __init__ for every real parameter of the instrument.

In this sense, parameters are the state variables of the instrument, anything the user can set and/or get.

Parameters

• name – How the parameter will be stored within instrument.parameters and also how you address it using the shortcut methods: instrument.set(param_name, value) etc.

• parameter_class – You can construct the parameter out of any class. Default parameter.Parameter.

• **kwargs – Constructor arguments for parameter_class.

Raises

• KeyError – If this instrument already has a parameter with this name and the parameter being replaced is not an abstract parameter.

• ValueError – If there is an existing abstract parameter and the unit of the new parameter is inconsistent with the existing one.

add_submodule(name: str, submodule: Union[InstrumentModule, ChannelTuple]) → None

Bind one submodule to this instrument.

Instrument subclasses can call this repeatedly in their __init__ method for every submodule of the instrument.

Submodules can effectively be considered as instruments within the main instrument, and should at minimum be snapshottable. For example, they can be used to either store logical groupings of parameters, which may or may not be repeated, or channel lists. They should either be an instance of an InstrumentModule or a ChannelTuple.

Parameters

• name – How the submodule will be stored within instrument.submodules and also how it can be addressed.

• submodule – The submodule to be stored.

Raises

• KeyError – If this instrument already contains a submodule with this name.

• TypeError – If the submodule that we are trying to add is not an instance of an Metadatable object.

property ancestors: List[qcodes.instrument.base.InstrumentBase]

Returns a list of instruments, starting from the current instrument and following to the parent instrument and the parents parent instrument until the root instrument is reached.

call(func_name: str, *args: Any) → Any

Shortcut for calling a function from its name.

Parameters

• func_name – The name of a function of this instrument.

• *args – any arguments to the function.

Returns

The return value of the function.

delegate_attr_dicts: List[str] = ['parameters', 'functions', 'submodules']

A list of names (strings) of dictionaries which are (or will be) attributes of self, whose keys should be treated as attributes of self.

delegate_attr_objects: List[str] = []

A list of names (strings) of objects which are (or will be) attributes of self, whose attributes should be passed through to self.

property full_name: str

get(param_name: str) → Any

Shortcut for getting a parameter from its name.

Parameters

param_name – The name of a parameter of this instrument.

Returns

The current value of the parameter.

invalidate_cache() → None

Invalidate the cache of all parameters on the instrument. Calling this method will recursively mark the cache of all parameters on the instrument and any parameter on instrument modules as invalid.

This is useful if you have performed manual operations (e.g. using the frontpanel) which changes the state of the instrument outside QCoDeS.

This in turn means that the next snapshot of the instrument will trigger a (potentially slow) reread of all parameters of the instrument if you pass update=None to snapshot.

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 instrument This is equivalent to full_name for backwards compatibility.

omit_delegate_attrs: List[str] = []

A list of attribute names (strings) to not delegate to any other dictionary or object.

print_readable_snapshot(update: bool = False, max_chars: int = 80) → None

Prints a readable version of the snapshot. The readable snapshot includes the name, value and unit of each parameter. A convenience function to quickly get an overview of the status of an instrument.

Parameters

• update – If True, update the state by querying the instrument. If False, just use the latest values in memory. This argument gets passed to the snapshot function.

• max_chars – the maximum number of characters per line. The readable snapshot will be cropped if this value is exceeded. Defaults to 80 to be consistent with default terminal width.

set(param_name: str, value: Any) → None

Shortcut for setting a parameter from its name and new value.

Parameters

• param_name – The name of a parameter of this instrument.

• value – The new value to set.

property short_name: str

Short name of the instrument

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]

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

Parameters

• update – If True, update the state by querying the instrument. If None update the state if known to be invalid. If False, just use the latest values in memory and never update state.

• params_to_skip_update – List of parameter names that will be skipped in update even if update is True. This is useful if you have parameters that are slow to update but can be updated in a different way (as in the qdac). If you want to skip the update of certain parameters in all snapshots, use the snapshot_get attribute of those parameters instead.

Returns

base snapshot

Return type

dict

validate_status(verbose: bool = False) → None

Validate the values of all gettable parameters

The validation is done for all parameters that have both a get and set method.

Parameters

verbose – If True, then information about the parameters that are being check is printed.

parameters: Dict[str, _BaseParameter] = {}

All the parameters supported by this instrument. Usually populated via add_parameter().

functions: Dict[str, Function] = {}

All the functions supported by this instrument. Usually populated via add_function().

submodules: Dict[str, Union['InstrumentModule', 'ChannelTuple']] = {}

All the submodules of this instrument such as channel lists or logical groupings of parameters. Usually populated via add_submodule().

instrument_modules: Dict[str, 'InstrumentModule'] = {}

All the instrument_modules of this instrument Usually populated via add_submodule().

metadata: Dict[str, Any] = {}

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

Bases: qcodes.instrument.parameter.MultiParameter, Generic[qcodes.instrument.channel.InstrumentModuleType]

Parameter to get or set multiple channels simultaneously.

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

Parameters

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

• param_name – Name of the multichannel parameter

get_raw() → Tuple[Any, ...]

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

set_raw(value: Any) → None

Set all parameters to this value.

Parameters

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

property full_names: Tuple[str, ...]

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

__str__() → str

Include the instrument name with the Parameter name if possible.

property abstract: Optional[bool]

property full_name: str

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

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

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

Parameters

• value – target value

• step – maximum step size

Returns

List of stepped values, including target value.

property gettable: bool

Is it allowed to call get on this parameter?

property instrument: Optional[InstrumentBase]

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

property inter_delay: float

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

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

Getter

Returns the current inter_delay.

Setter

Sets the value of the inter_delay.

Raises

• TypeError – If delay is not int nor float

• ValueError – If delay is negative

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

Load metadata into this classes metadata dictionary.

Parameters

metadata – Metadata to load.

property name: str

Name of the parameter. This is identical to short_name().

property name_parts: List[str]

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

property post_delay: float

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

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

Getter

Returns the current post_delay.

Setter

Sets the value of the post_delay.

Raises

• 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 setpoint_full_names: Optional[Sequence[Sequence[str]]]

Full names of setpoints including instrument names, if available

property settable: bool

Is it allowed to call set on this parameter?

property short_name: str

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

property short_names: Tuple[str, ...]

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

It exists for consistency with instruments and other parameters.

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

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

Parameters

update – Passed to snapshot_base.

Returns

Base snapshot.

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

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

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

Parameters

• update – If True, update the state by calling parameter.get() unless snapshot_get of the parameter is False. If update is None, use the current value from the cache unless the cache is invalid. If False, never call parameter.get().

• params_to_skip_update – No effect but may be passed from superclass

Returns

base snapshot

property snapshot_value: bool

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

property step: Optional[float]

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

Getter

Returns the current stepsize.

Setter

Sets the value of the step.

Raises

• TypeError – if step is set to not numeric or None

• ValueError – if step is set to negative

• TypeError – if step is set to not integer or None for an integer parameter

• TypeError – if step is set to not a number on None

property underlying_instrument: Optional[InstrumentBase]

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

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

By default it returns the root_instrument of the parameter.

validate(value: Any) → None

Validate the value supplied.

Parameters

value – value to validate

Raises

• TypeError – If the value is of the wrong type.

• ValueError – If the value is outside the bounds specified by the validator.