Yaml Files

hutch-python uses a conf.yml file for basic configuration. This is a standard yaml file with the following valid keys: hutch, db, load, load_level, experiment, obj_config, daq_type, daq_host, and daq_platform, exclude_devices.

hutch

The hutch key expects a single string, the hutch name.

hutch: xpp

This key is used to:

  • pick objects to load from happi

  • automatically select the active experiment

  • create the correct daq object

  • create the xxx.db module

  • display the hutch banner

db

The db key expects a single string, the file path.

db: /reg/g/pcds/pyps/apps/hutch-python/device_config/db.json

The file path can be either relative to the conf.yml file or absolute. In practice, you would only change this string for development purposes.

This key is used to:

  • load objects from happi

  • set up the xxx_beampath object

load

The load key expects a string or a list of strings, the modules to load.

load: xpp.beamline

load:
  - xpp.beamline
  - xpp.random_stuff

Both of these formats are valid.

This key is used to include hutch-specific code. hutch-python will attempt to do a from module import * for each of these modules.

load_level

The load_level key expects one of the following strings, corresponding to the amount of ophyd devices to load:

  • UPSTREAM: The hutch’s devices, and devices upstream from the requested hutch. If there are multiple paths to the requested hutch, all paths’ devices are loaded.

  • STANDARD: Devices gathered via UPSTREAM, plus devices that share the “beamline” field in happi with the UPSTREAM devices. (The current standard)

  • ALL: All devices in the happi database. Use this option at your own risk.

load_level: UPSTREAM

experiment

The experiment key expects a dictionary with proposal and run, both strings. It is not needed to provide an experiment key unless you would like to load an experiment other than the active experiment; handy for debugging.

experiment:
  proposal: ls25
  run: 16

This key is used to force the questionnaire and experiment file to be from a particular experiment.

obj_conf

The obj_conf key expects a single string, a file path.

obj_config: /cds/group/pcds/pyps/apps/hutch-python/xxx/tabs.yml

The file path can be either relative to the conf.yml file or absolute. This key is used to customize objects after they have been loaded. Currently, this supports modifying:

  • attributes visible by tab-completion

  • the kind of an object

on a class-wide or device-by-device basis.

For more information, see Object Configuration.

daq_type

The daq_type key is optional. If omitted, the default value is ‘lcls1’ for backwards compatibility with existing hutch python setups. This key expects a string with one of four valid values: ‘lcls1’, ‘lcls1-sim’, ‘lcls2’, or ‘nodaq’, to pick between creating an LCLS1-style daq, a simulated LCLS1-style daq, an LCLS2-style daq, or no daq respectively.

daq_host

The daq collection host as a string. This is a required key when using the lcls2 daq_type, and is ignored with any other daq_type. It will be used in the creation of the lcls2 daq object.

daq_platform

A dictionary description of which daq platform to use. This is used to determine whether to use the primary or secondary elog in hutches with two daqs, and is used to set up the lcls2 daq_type. If omitted entirely, platform 0 and the primary elog will be used. This dictionary has a required key, “default” that points to an integer that is the normal platform to use, associated with the primary experiment. Additional keys are interpreted as hostnames to use alternate platforms for. Alternate platforms will post to the secondary elog.

exclude_devices

The exclude_devices key is optional. exclude_devices expects a string that starts with a “-” symbol on each line. The string is the name of a device that should not be loaded.

This feature reduces the amount of unnecessary information shown in the console at load time. The list uses the following format:

exclude_devices:
   - crix_cryo_y
   - at2k2_calc
   - tmo_lamp_sqr1

additional_devices

The additional_devices key is optional. This key allows hutch-python to load additional devices that are on a different beamline or in a different hutch/area. The first entry below additional_devices is a search name, such as ‘tmo_sqr1_search’. Search names are arbitrarily determined by the user but should start with a letter or number. Each search name is followed by a happi search key, such as “beamline” and a value. For example, “beamline: TMO”. This tells hutch-python to gather all devices on the TMO beamline and load them. A second search criterion can be added below “beamline: TMO” to constrain the search further, so that only those devices that fit both search criteria will be loaded. For example, adding “device_class: pcdsdevices.sqr1.SQR1” below “beamline: TMO” tells hutch-python to load devices from the TMO beamline whose “device_class” key has a value of “pcdsdevices.sqr1.SQR1”. More lines can be added to obtain even more specific search results.

A search value can contain a wildcard symbol (*). For example, “name: tmo_*”.

In the example below hutch-python will load all devices from “tmo_sqr1_search”, “las_search”, and “crix_search”.

additional_devices:
   tmo_sqr1_search:
      beamline: TMO
      device_class: pcdsdevices.sqr1.SQR1
      z: -1, 1
   las_search:
     name: LAS
   crix_search:
      name: crix_*

Full File Example

hutch: xpp

db: /reg/g/pcds/pyps/apps/hutch-python/device_config/db.json

load:
  - xpp.beamline