βNMR Automatic Run Control

Introduction

Control Panel

Edit the plan file in your preferred text editor. Every time it is saved, the autorun program re-reads it.

If there are problems with the syntax of a plan file, the autorun processor usually only reports the first error it encounters, and goes "idle". Check the message log for error messages. There is a stand-alone command, ~musrdaq/musr/musr_midas/mui/checkplan.tcl (alias "checkplan"; usage "checkplan filename") that performs checks on a plan file, useful for verifying a hand-edited plan before enabling autoruns.

Auto-run Control Parameters

Autoruns Operation Enabled
ODB:  /autorun/enable,  boolean-int (1/0)
Set this to control whether the autorun process operates at all. It does not actually shut down when disabled, but it checks only this parameter, waiting to be enabled again.

Autorun State  Autoruns status read-back
ODB:  /autorun/state,   int   interpreted as:

Most state values are set by the autorun server, strictly for monitoring its progress, but a value of "reload" (9) may be set by other clients to force the autorun server to re-read the plan file, and perhaps resume processing after being idle (1); the load&Go button should trigger reloading this way, but it may not be working just yet. (The other way to force a reload is to modify the plan file itself, perhaps like touch plan.dat.)

Plan file  Full file specification for the run plan
ODB:  /autorun/plan file,   string
The autorun processor watches this file for changes, and if any occur, it re-reads the run plan.

Pausing Runs  Enable/Disable run pausing
ODB:  /autorun/enable pausing,   boolean-int (1/0)
Tells the autoruns processor whether to keep checking requirements after starting a run, and to pause the run while requirements are not satisfied. See below for "Requirements" in an autorun plan. (A Camp alarm with a hardware veto gives better response.)

Refresh Period  Cycle time of autorun processor
ODB:  /autorun/refresh seconds,   int
Tells how often the autorun processor checks status and looks for a new plan. Sensible values range from 5 to 30 seconds.

Target Cycles  Desired total cycles for TD/Type-2 runs
ODB:  /autorun/target cycles,   int
Tells how many frontend-fsc-cycles to run for Type-2 modes.

Target Counts  Desired total counts for TD/Type-2 runs
ODB:  /autorun/target counts,   int
Tells how many events to accumulate in histograms before ending the run.

Count Histogram  What "Target Counts" applies to
ODB:  /autorun/count histogram,   int
The "Target Counts" may be compared with the counts in any particular histogram or with the total of all histograms, as indicated by the "Counting Histogram" setting. Enter zero to use the total of all histograms.

Time Limit  Maximum time before ending a run
ODB:  /autorun/time limit (minutes),   float
Use a very high value or zero if there is to be no time limit. Between runs, this value may be reset by any specifications in the run plan.

Reload & Start  Apply the settings.
If autoruns are enabled, but idle, then force reloading the plan, even if it hasn't changed.

Run plan file: commands and syntax

Commands may be broken across multiple lines by ending the partial line(s) with "\".

Lines that begin with certain characters (!#%;) are comments, and are ignored, as are blank lines.

In the command syntax below, bold indicates a literal keyword, italics indicate some sort of value, "|" separates multiple possibilities, and "[ ]" brackets indicate some optional parameter. The "|", "[", and "]" characters should not be typed into a run plan!

One command is absolutely required, and it comes first:

Run:  number

The run number must be consecutive with the previous. The Run command begins the commands for that particular run; all ensuing commands apply to that run, until the next Run command.

The remaining commands can be in any order.

In the case of TI (type-1) runs, there is the required sweep range:

SweepRange:  from  delim  to  delim  step

The delimiter delim signifies white-space and/or punctuation characters or even any of the letters in "toby";   e.g.,  "10,100:2"  or  "5000 7000 500"  or  "1 to 10 by 1". People might try to use  "200-300:10"  for a range, but "-" is not a legal delimiter - the dangers of misinterpreting a minus sign are too great, so that is not an allowed form. All the values (from, to, step) are integers.

Other commands (all the commands listed below) are strictly optional, and, if omitted, they retain the previous settings; that is, the values will not be actively set to any values, but will be retained by the respective Midas or Camp systems.

There are four possible commands to control when the run should be ended:

Typically, one should use Counts to tell the total number of events to accumulate in a TD run; it can be given in "real" number form, and with an optional "M" suffix to indicate "millions" (3200000, 32e5, and 3.2M are all the same). This parameter will replace the value in the ODB at the beginning of a run, but a user may manually change it in the ODB while the run is in progress. If no Counts command is given for a run, the existing value of "/autorun/total counts" from the ODB is kept. If the optional hist_number is specified, then the counts are checked for that histogram only, rather than the total of all histograms.

The Elapsed setting (alias "time_limit") tells the longest time that may be spent on a run. The elapsed_time can be in many formats, and a simple number is interpreted as minutes; all of the following are equal:  1:30,  5400 s,  90 min,  1.5hr,  01:30:00,  90.  Units are any strings that begin with "s", "m", or "h". Notice that "1:30" means 1.5 hours, not 1.5 minutes! For 1.5 minutes you would need "0:01:30" (or "1.5 min" or "90s"). You can specify both Counts and Elapsed, in which case the run ends when either is satisfied. Note that but using an elapsed time limit may result in runs with no data if the beam is off for a long time.

The Sweeps command is for TI runs only, and tells how many sweeps to make. It updates the corresponding parameter in the ODB: "/Equipment/MUSR_I_acq/settings/input/num sweeps".

The Cycles command is for TD runs only, and tells how many cycles to perform.

Arrange to have autorun error and warning messages forwarded by email with

Email:  addr  [ , addr ... ]

providing a list of email addresses, separated by commas. When there are problems, the corresponding messages will be emailed to these addresses. If you have an address that gets forwarded to a cell phone or pager, that would be good to use.

Several commands apply to the run headers, corresponding to the Midas "edit on start" variables.

Sample:   ...
Orientation:   ...
Operator:   ...
Experiment:   number
Temperature:   temperature  |  Camp_var
Field:     field  |  Camp_var

Note that temperature and field may be entered as numbers (with implicit units of Kelvin and Gauss), as numbers with units (provided the conversion to Kelvin or Gauss is known to the program), or as a the full Camp path for a temperature or field variable.

Title:   ...

The run title allows automatic insertion of other header fields using the tags <Sample>, <Operator>, <Experiment>, <Temperature>, <Field>, and <Orientation> (yes, you type the "angle brackets" around the tag name). For example:

Title: <Sample> annealed, T=<Temperature>, B=<Field> <Orientation>, p=+2%

The autorun system will replace these tags with the appropriate header values, both at the beginning of the run and at intervals throughout the run; this ensures that automatic Temperature and Field headers, as well as any manual settings, are propagated to the run title. The system will STOP updating the title if the user manually sets it to something different.

For time-integral runs, there is also the percentage tolerance for the beam normalization:

Tolerance:   number   [ % ]

(The percent sign is optional, and does not affect the interpretation of the number.)

Any Odb parameter can be set using the SetOdb command:

SetOdb:  odb_variable   value

where odb_variable is the full Odb path to the variable, enclosed in quotes if the name contains any spaces. The value should also be quoted if it contains spaces (use double-quotes, not apostrophes).

You can control the beamline:

SetEpics:  Epics_var   value

The SetEpics command (with spelling variants) sets a particular beam element to a value. Epics variables are always in upper case, and contain colons (":") as separators; they usually begin with the beamline name. To find the Epics_var, go to the beamline control and click the middle mouse button on the entry field (underlined blue number) where you would type the value. The Epics_var will be displayed in a small pop-up window (the text is "selected", so you can immediately "paste" it into the plan file).

SetEpics: M20:HELMHOLTZ:CUR 215

Make Camp settings using either or both of:

SetCamp:  Camp_var   value
Camp_cmd:  Camp_command

(SetCamp has aliases set_camp, camp_set and CampSet, because we all forget.)

The Camp_var argument is a complete Camp variable path, including all slashes, such as "/Helios/mag_field".

The value argument should be numeric or a text string, as appropriate for the particular Camp_var. Numeric values may be given as arithmetic expressions. For selection variables, one must use the exact same string as used by Camp, including capitalization, or an integer index, counting from zero. As a special shortcut, abbreviations of the form <Camp_var> (with explicit angle-brackets) may be used as (or in) the value argument, indicating that the value of another Camp variable should be substituted.

The Camp_command is any command (or inline Tcl script) as documented in Appendix B of the Camp Software Manual.

Examples are:

SetCamp: /Magnet/mag_field 0.25
SetCamp: /Sample/control_set 15
SetCamp: /Diffuser/control_set </Sample/control_set> - 0.5
SetCamp: /field_control/setpoint </Hall/field>
SetCamp: /Diffuser/heat_range MED
camp_cmd: insLoad /defibrulator medical.kit

The autorun controller will perform all those Camp commands at once, as soon as the preceding run has ended. This doesn't meet the full needs for setting Camp devices, particularly in cases such as the field control example above, where one would like to reference the /Hall/field value after the magnet has stabilized. One way to handle this is to schedule some settings after a fixed time delay:

After elapsed_time :  SetCamp:  . . .  |  camp_cmd:  . . .

where the forms of elapsed_time is similar to the run time-limit, except that a bare number is interpreted as seconds (six minutes could be given by any of 6m, 0:06, 0.1h, 360s, 360). This is the first of two composite commands, where a required colon (:) must separate the "After" declaration from the ensuing, delayed, command. Note that only the Camp-related commands can be deferred with After; any others give a syntax error (because they aren't allowed).

Before a run can begin, we must know that the experimental conditions have responded to the Camp variable settings, so we specify "requirements"

The run will not begin until every requirement is satisfied simultaneously, and there are no Camp alarms active. (Thus, you can enforce many typical constraints by setting alarms in Camp, rather than giving requirement commands.)

For numeric Camp variables, one should usually use the "stable" form of the command. The autorun system will collect values of the primary Camp_var, retaining those over the latest elapsed_time. To satisfy the requirement, all retained values must be within error of either: the latest value (blank comparison fields), or the given number ("at"), or the current value of the comparison variable ("equal"). (Notice that  Require /foo/bar stable  is the same as  Require /foo/bar stable equal /foo/bar.)

The default elapsed_time, if none was specified, is 1 minute. If either Camp_var is readable but not being polled, the autorun system will tell Camp to read the variable before performing each requirement-check.

Numeric variables can also be tested to be "above" or "below" some value.

For string or selection variables, use the "is" form for the requirement. If the string contains spaces, then it should be quoted.

Examples:

Require: /diffuser/control_read stable equal /diffuser/control_set within 0.5
Require: /sample/sample_read stable within 0.5 for 2 m
Require: /Hall_Probe/field stable at 1.0 for 30
Require: /shield/sample_read below 100
Require: /Magnet/ramp_status is Persistent

(Note that the last example specifies "Persistent"; "persistent" would not work because the actual value in Camp is capitalized. Make sure the requirement string exactly matches what Camp displays.)

Here is another example, part of a temperature scan, where the desired temperature is specified just once, on the diffuser set-point.

Run: 1234
Title: <Sample>, <Temperature>, automatically
Temperature: /sample/sample_read
Require: /sample/sample_read stable equal /diffuser/control_set within 3
Require: /sample/sample_read stable within 0.5 for 2m
Setcamp: /diffuser/control_set 22

The run will begin when the sample temperature levels off (within 0.5 K) for 2 minutes, and within 3 K of the diffuser setpoint (i.e., between 19 and 25 K). Whatever the average sample temperature is, over the course of the run, it will be recorded in the temperature field of the run header, and thence the run title of the data file. Note that, in this example as always, the Setcamp command is performed before ever checking requirements; entering the Setcamp declaration after the requirements does not imply that the settings are performed after requirements are satisfied. For that feature, see the When command.

Max_wait:  elapsed_time

In case of conflicting requirements, or some other problem where the requirements are never satisfied, there is a Max_wait command. After waiting for elapsed_time (default units are seconds, just as for After) the autorun sequencer will start the next run even if the requirements are not satisfied.

For greater control over the timing of Camp settings than is provided by the After command, one can schedule them the same way as specifying a requirement:

When:  requirement_specification :  SetCamp:   ...  |  camp_cmd:   ...  |  After   ...  |  blank
The requirement_specification is any valid parameter list for the Require command (above), and is followed by a mandatory colon separator. Only the Camp-related commands (SetCamp, camp_cmd, and their aliases) and the After command may be scheduled this way, or you can specify a null action with no scheduled command.

Conditions specified by When must all be satisfied at some point before a run can begin, but they need not remain satisfied until the run begins. This makes a When command with a null action subtly different from the same Require command: all Require conditions must be simultaneously satisfied when the run begins, whereas all When actions (or null actions) must have been performed sometime before the run begins.

If a Camp setting must be delayed until after the run begins, then you must use an After command, either alone or scheduled by a When command, like

When: /sample/sample_read stable within .5: After 5m: setCamp /sample/setup/P 20

A typical use is to start controlling a variable after a previous setting is complete:

When: /Hall/field stable within .5: setCamp /field_cont/setpoint </Hall/field>
When: /Hall/field stable within .5: setCamp /field_cont/function 2
When: /sample/sample_read below 8: setCamp /sample/heat_range LOW
When: /diffuser/sample_read stable equal /diffuser/control_set within 1 for 1.5m: \
        After 3m: setCamp /nv_cont/function 2

(Note the use of \ to join multiple lines when commands get too long, and the substitution for the current value of the field readback.) This example turns on (feedback) field control when the magnet current reaches its setpoint, and turns on needle-valve control three minutes after the cryostat diffuser temperature gets close to its setpoint. Notably, it also specifies the same requirements for beginning the run; thus, presuming the (diffuser) temperature is the last to stabilize, the needle-valve control will begin about three minutes after the run begins.

In the example (and in practice) note the use of multiple When commands having the same requirement but different actions. To save typing and computer processing, these can be written as a block

When:  requirement_specification  do  
   ...
enddo

where multiple camp-setting commands are surrounded by "do...enddo", or their equivalents, curly braces "{...}", and controlled by a single When command. For example,

When: /Hall/field stable within .5 {
  setCamp /field_cont/setpoint </Hall/field>
  setCamp /field_cont/function 2
}

Note which commands go on separate lines in this example. You cannot combine those multiple lines.

That completes the definition of the plan file. Please relate your experiences, frustrations, and suggestions to Donald.