Driver Utils¶
-
class
instrumental.drivers.
Instrument
¶ Base class for all instruments.
-
_after_init
()¶ Called just after _initialize
-
_before_init
()¶ Called just before _initialize
-
classmethod
_create
(paramset, **other_attrs)¶ Factory method meant to be used by
instrument()
-
_fill_out_paramset
()¶
-
_initialize
(**settings)¶
-
_load_state
(state_path=None)¶ Load instrument state from a pickle file
-
_save_state
(state_path=None)¶ Save instrument state to a pickle file
-
close
()¶
-
get
(facet_name, use_cache=False)¶
-
observe
(name, callback)¶ Add a callback to observe changes in a facet’s value
The callback should be a callable accepting a
ChangeEvent
as its only argument. ThisChangeEvent
is a namedtuple withname
,old
, andnew
fields.name
is the facet’s name,old
is the old value, andnew
is the new value.
-
save_instrument
(name, force=False)¶ Save an entry for this instrument in the config file.
Parameters: - name (str) – The name to give the instrument, e.g. ‘myCam’
- force (bool, optional) – Force overwrite of the old entry for instrument
name
. By default, Instrumental will raise an exception if you try to write to a name that’s already taken. Ifforce
is True, the old entry will be commented out (with a warning given) and a new entry will be written.
-
_abc_cache
= <_weakrefset.WeakSet object>¶
-
_abc_negative_cache
= <_weakrefset.WeakSet object>¶
-
_abc_negative_cache_version
= 39¶
-
_abc_registry
= <_weakrefset.WeakSet object>¶
-
_all_instances
= {}¶
-
_instances
= <_weakrefset.WeakSet object>¶
-
_prop_funcs
= {}¶
-
_props
= []¶
-
_state_path
¶
-
-
instrumental.drivers.
instrument
(inst=None, **kwargs)¶ Create any Instrumental instrument object from an alias, parameters, or an existing instrument.
- reopen_policy : str of (‘strict’, ‘reuse’, ‘new’), optional
- How to handle the reopening of an existing instrument. ‘strict’ - disallow reopening an instrument with an existing instance which hasn’t been cleaned up yet. ‘reuse’ - if an instrument is being reopened, return the existing instance ‘new’ - always create a new instance of the instrument class. Not recommended unless you know exactly what you’re doing. The instrument objects are not synchronized with one another. By default, follows the ‘reuse’ policy.
>>> inst1 = instrument('MYAFG') >>> inst2 = instrument(visa_address='TCPIP::192.168.1.34::INSTR') >>> inst3 = instrument({'visa_address': 'TCPIP:192.168.1.35::INSTR'}) >>> inst4 = instrument(inst1)
-
instrumental.drivers.
list_instruments
(server=None, module=None, blacklist=None)¶ Returns a list of info about available instruments.
May take a few seconds because it must poll hardware devices.
It actually returns a list of specialized dict objects that contain parameters needed to create an instance of the given instrument. You can then get the actual instrument by passing the dict to
instrument()
.>>> inst_list = get_instruments() >>> print(inst_list) [<NIDAQ 'Dev1'>, <TEKTRONIX 'TDS 3032'>, <TEKTRONIX 'AFG3021B'>] >>> inst = instrument(inst_list[0])
Parameters: - server (str, optional) – The remote Instrumental server to query. It can be an alias from your instrumental.conf
file, or a str of the form
(hostname|ip-address)[:port]
, e.g. ‘192.168.1.10:12345’. Is None by default, meaning search on the local machine. - blacklist (list or str, optional) – A str or list of strs indicating driver modules which should not be queried for instruments.
Strings should be in the format
'subpackage.module'
, e.g.'cameras.pco'
. This is useful for very slow-loading drivers whose instruments no longer need to be listed (but may still be in use otherwise). This can be set permanently in yourinstrumental.conf
. - module (str, optional) – A str to filter what driver modules are checked. A driver module gets checked only if it
contains the substring
module
in its full name. The full name includes both the driver group and the module, e.g.'cameras.pco'
.
- server (str, optional) – The remote Instrumental server to query. It can be an alias from your instrumental.conf
file, or a str of the form
-
instrumental.drivers.
list_visa_instruments
()¶ Returns a list of info about available VISA instruments.
May take a few seconds because it must poll the network.
It actually returns a list of specialized dict objects that contain parameters needed to create an instance of the given instrument. You can then get the actual instrument by passing the dict to
instrument()
.>>> inst_list = get_visa_instruments() >>> print(inst_list) [<TEKTRONIX 'TDS 3032'>, <TEKTRONIX 'AFG3021B'>] >>> inst = instrument(inst_list[0])
-
class
instrumental.drivers.
ParamSet
(cls=None, **params)¶ -
__init__
(cls=None, **params)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
create
(**settings)¶
-
get
(key, default=None)¶
-
items
()¶
-
keys
()¶
-
lazyupdate
(other)¶ Add values from
other
for keys that are missing
-
matches
(other)¶ True iff all common keys have matching values
-
to_ini
(name)¶
-
update
(other)¶
-
values
()¶
-
-
class
instrumental.drivers.
VisaMixin
¶ -
_end_transaction
()¶
-
_flush_message_queue
()¶ Write all queued messages at once
-
_start_transaction
()¶
-
query
(message, *args, **kwds)¶ Query the instrument’s VISA resource with
message
Flushes the message queue if called within a transaction.
-
transaction
(**kwds)¶ Transaction context manager to auto-chain VISA messages
Queues individual messages written with the
write()
method and sends them all at once, joined by ‘;’. Messages are actually sent (1) when a call toquery()
is made and (2) upon the end of transaction.This is especially useful when using higher-level functions that call
write()
, as it lets you combine multiple logical operations into a single message (if only using writes), which can be faster than sending lots of little messages.Be cognizant that a visa resource’s write and query methods are not transaction-aware, only VisaMixin’s are. If you need to call one of these methods (e.g. write_raw), make sure you flush the message queue manually with
_flush_message_queue()
.As an example:
>>> with myinst.transaction(): ... myinst.write('A') ... myinst.write('B') ... myinst.query('C?') # Query forces flush. Writes "A;B" and queries "C?" ... myinst.write('D') ... myinst.write('E') # End of transaction block, writes "D;E"
-
write
(message, *args, **kwds)¶ Write a string message to the instrument’s VISA resource
Calls
format(*args, **kwds)
to format the message. This allows for clean inclusion of parameters. For example:>>> inst.write('source{}:value {}', channel, value)
-
_abc_cache
= <_weakrefset.WeakSet object>¶
-
_abc_negative_cache
= <_weakrefset.WeakSet object>¶
-
_abc_negative_cache_version
= 39¶
-
_abc_registry
= <_weakrefset.WeakSet object>¶
-
_in_transaction
¶
-
_instances
= <_weakrefset.WeakSet object>¶
-
_prop_funcs
= {}¶
-
_props
= []¶
-
resource
¶ VISA resource
-
-
instrumental.drivers.
_get_visa_instrument
(params)¶ Returns the VISA instrument corresponding to ‘visa_address’. Uses caching to avoid multiple network accesses.
Helpful utilities for writing drivers.
-
instrumental.drivers.util.
check_units
(*pos, **named)¶ Decorator to enforce the dimensionality of input args and return values.
Allows strings and anything that can be passed as a single arg to
pint.Quantity
.@check_units(value='V') def set_voltage(value): pass # `value` will be a pint.Quantity with Volt-like units
-
instrumental.drivers.util.
unit_mag
(*pos, **named)¶ Decorator to extract the magnitudes of input args and return values.
Allows strings and anything that can be passed as a single arg to
pint.Quantity
.@unit_mag(value='V') def set_voltage(value): pass # The input must be in Volt-like units and `value` will be a raw number # expressing the magnitude in Volts
-
instrumental.drivers.util.
check_enums
(**kw_args)¶ Decorator to type-check input arguments as enums.
Allows strings and anything that can be passed to
as_enum
.@check_enums(mode=SampleMode) def set_mode(mode): pass # `mode` will be of type SampleMode
-
instrumental.drivers.util.
as_enum
(enum_type, arg)¶ Check if arg is an instance or key of enum_type, and return that enum
-
instrumental.drivers.util.
visa_timeout_context
(*args, **kwds)¶ Context manager for temporarily setting a visa resource’s timeout.
with visa_timeout_context(rsrc, 100): ... # `rsrc` will have a timeout of 100 ms within this block