Configuration File Support

The instruments package provides support for loading instruments from a configuration file, so that instrument parameters can be abstracted from the software that connects to those instruments. Configuration files recognized by instruments are YAML files that specify for each instrument a class responsible for loading that instrument, along with a URI specifying how that instrument is connected.

Configuration files are loaded by the use of the load_instruments function, documented below.

Functions

instruments.load_instruments(conf_file_name, conf_path='/')[source]

Given the path to a YAML-formatted configuration file and a path within that file, loads the instruments described in that configuration file. The subsection of the configuration file is expected to look like a map from names to YAML nodes giving the class and instrument URI for each instrument. For example:

ddg:
    class: !!python/name:instruments.srs.SRSDG645
    uri: gpib+usb://COM7/15

Loading instruments from this configuration will result in a dictionary of the form {'ddg': instruments.srs.SRSDG645.open_from_uri('gpib+usb://COM7/15')}.

Each instrument configuration section can also specify one or more attributes to set. These attributes are specified using a attrs section as well as the required class and uri sections. For instance, the following dictionary creates a ThorLabs APT motor controller instrument with a single motor model configured:

rot_stage:
    class: !!python/name:instruments.thorabsapt.APTMotorController
    uri: serial:///dev/ttyUSB0?baud=115200
    attrs:
        channel[0].motor_model: PRM1-Z8

Unitful attributes can be specified by using the !Q tag to quickly create instances of u.Quantity. In the example above, for instance, we can set a motion timeout as a unitful quantity:

attrs:
    motion_timeout: !Q 1 minute

When using the !Q tag, any text before a space is taken to be the magnitude of the quantity, and text following is taken to be the unit specification.

By specifying a path within the configuration file, one can load only a part of the given file. For instance, consider the configuration:

instruments:
    ddg:
        class: !!python/name:instruments.srs.SRSDG645
        uri: gpib+usb://COM7/15
prefs:
    ...

Then, specifying "/instruments" as the configuration path will cause this function to load the instruments named in that block, and ignore all other keys in the YAML file.

Parameters:

conf_file_name (str) – Name of the configuration file to load instruments from. Alternatively, a file-like object may be provided.
conf_path (str) – "/" separated path to the section in the configuration file to load.

Return type:

dict

Warning

The configuration file must be trusted, as the class name references allow for executing arbitrary code. Do not load instruments from configuration files sent over network connections.

Note that keys in sections excluded by the conf_path argument are still processed, such that any side effects that may occur due to such processing will occur independently of the value of conf_path.