instrument

Instrument interface and associated decorator tools.

This module contains the Instrument and Singleton interface and metaclass, as well as the InstrumentTimeoutError exception and LOCK_NOT_ACQUIRED dummy class.

The @acquire_lock and retry_on_fail decorators are also provided here.

Functions

`acquire_lock`([try_once, timeout])	Instrument Member Functon Decorator that attempts to obtain a global mutex on the singleton class of the function this decorator decorated.
`retry_on_fail`([attempts, exceptions])	Instrument Member Functon Decorator that attempts to retry the given instrument member function on failure, after reconnecting to instrument, if required (via context closure and re-establishment).

Classes

`Flock`(filepath)	Flock()-based file locking class matching interfaces of threading.Lock and fasteners.InterProcessLock.
`Instrument`(resource)	Base Instrument class - all instruments should derive from this.
`LOCK_NOT_ACQUIRED`()	Dummy enum-like class to represent return value when lock could not be acquired by acquire_lock().
`Multiton`(name, bases, namespace[, key])	Multiton metaclass provides global instance access to instruments/instrument types based off first argument in constructor (a bit silly, but I can't think of a way around this at the moment).
`Singleton`	Singleton class provides global instance access to instruments/instrument types.

Exceptions

`ChannelError`	Exception to be throw when missing channel is addressed.
`InstrumentTimeoutError`(function, ...[, message])	Exception to be throw when instruments time out.

acquire_lock

icicle.instrument.acquire_lock(try_once=False, timeout=0.1)

Instrument Member Functon Decorator that attempts to obtain a global mutex on the singleton class of the function this decorator decorated.

Can be disabled by passing keyword argument no_lock=True in a call to the decorated function.

Parameters:

try_once – If true, attempt to get lock doesn’t block. Returns LOCK_NOT_ACQUIRED on failure if true, continuously retries if false.
timeout – Number of seconds to retry for until timeout. If = -1, infinite.

Returns:

Wrapped function.

Note

DECORATOR

retry_on_fail

icicle.instrument.retry_on_fail(attempts=3, exceptions=())

Instrument Member Functon Decorator that attempts to retry the given instrument member function on failure, after reconnecting to instrument, if required (via context closure and re-establishment).

Parameters:

attempts – Number of times to retry function call.
exceptions – Exception classes to catch and ignore.

Returns:

Wrapped function.

Note

DECORATOR

Flock

class icicle.instrument.Flock(filepath)

Bases: object

Flock()-based file locking class matching interfaces of threading.Lock and fasteners.InterProcessLock.

__init__(filepath)

Parameters:: filepath – path to lockfile

acquire(blocking=False, timeout=None)

Acquire flock() on file at path filepath. Requires write access to file.

Parameters:

blocking – whether attempt should block.
timeout – maximum wait to repeat non-blocking attempts. Only used if blocking is false.

release()

Release flock() on file at path filepath. Requires write access to file.

Parameters:

blocking – whether attempt should block.
timeout – maximum wait to repeat non-blocking attempts. Only used if blocking is false.

Instrument

class icicle.instrument.Instrument(resource)

Bases: object

Base Instrument class - all instruments should derive from this. Will be singleton’d at implementation level.

Implements the global lock for each instrument to ensure only one instruction is executed at a time.

Tracks connected/disconnected state. Connection occurs within the context handler (see an implementation).

__init__(resource)

Instrument Constructor.

Constructs lock.

class Channel(instrument)

Bases: object

Base Channel class - all channel types should derive from this.

Provides a context handler for handling the connected instrument(s) context. Tracks connected/disconnected state of associated instrument.

property connected

Returns:: whether underlying instrument/channel is connected.
Return type:: bool

property instrument

Returns:: associated instrument.
Return type:: icicle.instrument.Instrument

property status

Returns:: channel status. If not implemented in channel, returns 0xDEAD.
Return type:: bool

LOCK_PATH = PosixPath('/tmp/icicle')

LOCK_TYPE = 2

class LockType(*values)

Bases: Enum

FLOCK = 2

LOCKFILE = 1

MUTEX = 0

class MeasureChannel(instrument, channel, measure_type, unit='')

Bases: Channel

Generic measurement channel for e.g. digital multimeter.

Accepted measurement types should be configured via the MEASURE_TYPES dictionary in the relevant instrument class.

as_string()

Returns:: value and unit as string.
Return type:: str

property channel

Returns:: which physical output, channel or connection is being controlled by this PowerChannel.
Return type:: bool

property measure_type

Returns:: measurement type.
Return type:: str

property unit

Returns:: measurement unit.
Return type:: str

property value

Performs measurement and returns value.

Returns:: measured value.
Return type:: float

class MeasureChannelWrapper(wrapped_channel, wrapper_type, unit='')

Bases: MeasureChannel

as_string()

Returns:: value and unit as string.
Return type:: str

property measure_type

Returns:: wrapped measurement type.
Return type:: str

property status

Returns:: channel status, defaulting to wrapped instrument status if not overrriden in subclass.
Return type:: str

property unit

Returns:: measurement unit.
Return type:: str

property value

Performs measurement in wrapped MeasureChannel and returns transformed result.

Returns:: measured value.
Return type:: float

property wrapper_type

Returns:: measurement wrapper type.
Return type:: str

class PowerChannel(instrument, channel, measure_voltage, measure_current)

Bases: Channel

Base class for single power output channels encompassing a voltage, current, and associated limits.

In general two Instrument.MeasureChannel objects should be provided to this class to measure the current voltage and current.

property channel

Returns:: which output is being controlled by this PowerChannel.
Return type:: bool

property current

Returns:: currently set channel current.
Return type:: float

property current_limit

Returns:: currently set channel current limit.
Return type:: float

property current_trip

Returns:: whether current limit has been tripped on this channel.
Return type:: bool

property measure_current

Returns:: measured (actual) current on channel.

property measure_voltage

Returns:: measured (actual) voltage on channel.

reset_current_trip()

Attempts to reset current trip condition.

Returns:: success/failure of operation.
Return type:: bool

reset_voltage_trip()

Attempts to reset voltage trip condition.

Returns:: success/failure of operation.
Return type:: bool

property state

Returns:: whether this power channel is on or off (True/False).
Return type:: bool

sweep(target_value, delay=1, step_size=None, n_steps=None, measure=False, set_property='voltage', measure_function=None, measure_args=None, measure_fields=None, log_function=None, spacing=17, execute_each_step=None, break_loop=None)

Implementation of a voltage/current sweep.

Parameters:

target_value – value of setting to sweep to (from current)
delay – delay between sweep steps (in seconds)
step_size – step size between sweep steps
n_steps – number of steps to perform (alternative to step_size - specify one but not both)
measure – whether to measure at each step of sweep
set_property – whether to sweep voltage or current
measure_function – function to use for additional measure() call, e.g. on another instrument. The data is appended to the existing set and measure data returned from the channel.
measure_args – additional keyword arguments to pass to measure()
measure_fields – field description to put in log header for measure fields
log_function – function to call to send text for logging
spacing – spacing between columns in log output
execute_each_step – accepts a callback function (no arguments) to be executed at each step of the sweep.
break_loop – accepts a callback function that should evaluate to a boolean. If true it will break the sweep loop.

Returns:

final parameter value, data

property voltage

Returns:: currently set channel voltage.
Return type:: float

property voltage_limit

Returns:: currently set channel voltage limit.
Return type:: float

property voltage_trip

Returns:: whether voltage limit has been tripped on this channel.
Return type:: bool

class TemperatureChannel(instrument, channel, measure_temperature, measure_speed)

Bases: Channel

Base class for single temperature control channel encompassing a temperature, and a speed control.

In general two Instrument.MeasureChannel objects should be provided to this class to measure the current temperature and speed.

property channel

Returns:: which output is being controlled by this PowerChannel.
Return type:: bool

property measure_speed

Returns:: measured (actual) current on channel.

property measure_temperature

Returns:: measured (actual) voltage on channel.

property speed

Returns:: currently set speed current.
Return type:: float

property state

Returns:: whether this power channel is on or off (True/False).
Return type:: bool

property temperature

Returns:: currently set channel temperature.
Return type:: float

channel(channel_type, channel, **kwargs): Gets an associated Instrument.MeasureChannel, Instrument.PowerChannel or Instrument.WrapperChannel

close()

connected()

get_flock()

get_lockfile()

static load_instrument_class(instrument, instrument_class)

Static function that finds an instrument class and loads it based on the module name and class name.

Parameters:

instrument – Name of instrument module (e.g. keithley2410)
instrument_class – Class of instrument (e.g. Keithley2410)

Returns:

instrument class

measure(*args, **kwargs): MEASURE template - should be implemented to make measurement on device.

off(*args, **kwargs): OFF template - should be implemented to turn off device or channel.

on(*args, **kwargs): ON template - should be implemented to turn on device or channel.

open()

query(*args, **kwargs): QUERY template - should be implemented to query device state.

classmethod register(child)

Class decorator to register a device-level class:Instrument subclass with the Instrument class registry for later lookup from name strings.

Usage:

@Instrument.register
class TestInstrument(Instrument):
    ...

Parameters:: child (class:Instrument) – the child class to be registered.
Returns:: child class, after decorator step.
Return type:: class:Instrument

registered_classes = {'AdcBoard': <class 'icicle.adc_board.AdcBoard'>, 'Binder': <class 'icicle.binder_climate_chamber.Binder'>, 'CaenDT8033N': <class 'icicle.caenDT8033N.CaenDT8033N'>, 'HMP4040': <class 'icicle.hmp4040.HMP4040'>, 'HP34401A': <class 'icicle.hp34401a.HP34401A'>, 'ITkDCSInterlock': <class 'icicle.itkdcsinterlock.ITkDCSInterlock'>, 'Keithley2000': <class 'icicle.keithley2000.Keithley2000'>, 'Keithley2410': <class 'icicle.keithley2410.Keithley2410'>, 'Keithley6500': <class 'icicle.keithley6500.Keithley6500'>, 'KeysightE3633A': <class 'icicle.keysighte3633a.KeysightE3633A'>, 'Lauda': <class 'icicle.lauda.Lauda'>, 'MP1': <class 'icicle.mp1.MP1'>, 'PIDController': <class 'icicle.pidcontroller.PIDController'>, 'RelayBoardDOUBLE': <class 'icicle.relay_board.RelayBoardDOUBLE'>, 'RelayBoardQUAD': <class 'icicle.relay_board.RelayBoardQUAD'>, 'RelayBoardRD53A': <class 'icicle.relay_board.RelayBoardRD53A'>, 'TTI': <class 'icicle.tti.TTI'>, 'TTITSX': <class 'icicle.ttiTSX.TTITSX'>}: Dynamic point for registration of instrument classes.

reset(*args, **kwargs): RESET template - should be implemented to reset device.

property resource

Returns:: Resource string or identifier for this instrument.
Return type:: str

set(*args, **kwargs): SET template - should be implemented to set and query back device state.

property sim

Returns:: Whether this instrument instance is set up with a simulation backend.
Return type:: bool

status(*args, **kwargs): STATUS template - should be implemented to return device/channel status.

sweep(target_setting, target_value, delay=1, step_size=None, n_steps=None, measure=False, set_function=None, set_args=None, query_function=None, query_args=None, measure_function=None, measure_args=None, conversion=<function Instrument.<lambda>>, log_function=None, execute_each_step=None, break_monitoring=None)

Device-independent implementation of a parameter sweep.

Parameters:

target_setting – name of setting that set() call should target.
target_value – value of setting to sweep to (from current).
delay – delay between sweep steps (in seconds)
step_size – step size between sweep steps
n_steps – number of steps to perform (alternative to step_size - specify one but not both)
set_function – function to use for set() call. Defaults to self.set
set_args – additional keyword arguments to pass to set()
measure – whether to measure at each step of sweep.
measure_function – function to use for measure() call. Defaults to self.measure
measure_args – additional keyword arguments to pass to measure()
query_args – additional keyword arguments to pass to query() at each step.
conversion – function to convert query return value back to float.
execute_each_step – accepts a callback function (no arguments) to be executed at each step of the sweep.
break_monitoring – accepts a callback function that should evaluate to a boolean. If true it will break the sweep loop.

Returns:

final parameter value[, measure data]

sweep_print_header(measured_unit)

Function that returns the specific header for each of the instruments. This should be overridden in each of the instruments that perform a sweep.

In some cases like sldo_vi_curve, self is not the device that performs the measurement. Therefore, this function sometimes needs the information about what is measured. This is what @param measured_unit is for.

validate_channel(channel, raise_exception=False)

Check if a channel exists on this device.

Parameters:: channel – Channel number to validate as an output.

LOCK_NOT_ACQUIRED

class icicle.instrument.LOCK_NOT_ACQUIRED

Bases: object

Dummy enum-like class to represent return value when lock could not be acquired by acquire_lock().

__init__()

Multiton

class icicle.instrument.Multiton(name, bases, namespace, key='resource')

Bases: type

Multiton metaclass provides global instance access to instruments/instrument types based off first argument in constructor (a bit silly, but I can’t think of a way around this at the moment). _instances member is dict of instruments by key.

__init__(name, bases, namespace, **kwargs)

get_instance(key=None)

Singleton

class icicle.instrument.Singleton

Bases: type

Singleton class provides global instance access to instruments/instrument types. _instances member is dict of instruments by class name.

__init__(*args, **kwargs)

ChannelError

icicle.instrument.ChannelError(): Exception to be throw when missing channel is addressed.

InstrumentTimeoutError

icicle.instrument.InstrumentTimeoutError(function, instrument_class, message=''): Exception to be throw when instruments time out.