input file:
The input file consists of namelist commands that set up and execute the experiment. The functions of the
commands are described below.
- variable — specifies a process variable to vary, and the range and steps of the variation. More than
one variable command may be defined, so that many process variables may vary at a time. When
an arbitrary sequence of setpoint values is required, the setpoints can be read in from a file.
- measurement — specifies a process variable to measure at each step during the experiment. Instead
of using many measurement namelist, one can optionally use a sddsmonitor-compatible file.
- execute — start executing the experiment. One group of variable, measurement and execute
commands may follow another in the same file for multiple experiments.
- erase — deletes previous variable or measurement setups.
- list_control_quantities — makes a cross-reference file for process variable names and column
names of the data file.
- system_call — specifies a system call (usually a script) to be executed either before a measurement
or before setting a process variable.
The following text describes all the namelist commands and their respective fields in more detail. The command
definition listing is of the form
&<command-name>
<variable-type> <variable-name> = <default-value>
.
.
.
&end
where the part <variable-type>, which doesn’t appear in an actual command, is used to illustrate the valid
type of the value. The three valid types are:
- double — for a double-precision type, used for most physical quantity variables,
- long — for an integer type, used for indexes and flags.
- STRING — for a character string enclosed in double quotes.
An actual namelist in an input file should look like this:
&<command-name>
[<variable-name> = <value>,]
...
&end
In the namelist definition listings the square brackets denotes an optional component. Not all variables need to
be defined – the defaults may be sufficient. Those that do need to be defined are noted in the
detailed explanations. The only variables that don’t have default values in general are string
variables.
– variable
- function: Specifies a process variable to vary, and the range and steps of the variation. Values
of variables at each measurement step are written to an SDDS output file. The readback-related
fields are used to confirm that the physical device has responded to a setpoint command at
every step (and substep) within some tolerance. Readback is enabled when readback_attempts and
readback_tolerance are defined with non-zero positive values.
When an arbitrary sequence of setpoint values is required (say a binary sequence), the values can
be read in from an SDDS file specified by the values_file field. The fields of &variable associated
for the range and steps are ignored in this case.
With multiple variable commands, variables may be varied in a multi-dimensional grid. For
example, variables may be varied independently of each other, or some groups of variables may
vary together forming one axis of a multi-dimensional grid (see item index_number).
&variable
STRING control_name = NULL
STRING column_name = NULL
STRING symbol = NULL
STRING units = "unknown"
double initial_value = 0
double final_value = 0
long relative_to_original = 0
long index_number = 0
long index_limit = 0
STRING function = NULL
STRING values_file = NULL
STRING values_file_column = NULL
long substeps = 1
double substep_pause = 0
double range_multiplier = 1
STRING readback_name = NULL
double readback_pause = 0.1
double readback_tolerance = 0
long readback_attempts = 10
long reset_to_original = 1
&end
- control_name — Required. Process variable name to vary.
- column_name — Required. Column name for the variable data recorded in the output file.
- symbol — Optional. Symbol field for the above column definition of the variable data.
- units — Optional. Units field for the above column definition of the variable data.
- initial_value — Required. The initial value of the process variable in the variation.
- final_value — Required. The final value of the process variable in the variation.
- index_number — Required. The counter (or index) number with which the defined variation is
associated. In a sddsexperiment run, counters must be defined in an increasing order with no
gaps starting from counter 0. That is, the first variable command of the file must have
index_number = 0. The second variable command must have index_number = 0 or 1. In the
former case, the two variables will move together with the same number of steps according
their respective initial_value and final_value. In the latter case, the two variables will
vary independently of each other with possibly different number of steps in a 2-dimensional
grid.
Counter number n is nested within counter n + 1. Therefore it might be efficient to assign devices with
slower response times to higher index_number counter.
- index_limit — Normally required. Number of steps in the variation. Measurements are taken at each step.
When more than one variable is associated with the same counter, only the index_limit of
the first variable definition for that counter need to be defined. If index_limit is defined in
variable commands of the same index_number value, then the first index_limit remain in
force.
- relative_to_original — Optional. If non-zero, then the variation range is defined relative to the original
process variable value (i.e. the value prior to running the program).
- range_multiplier — Optional. Factor by which the range, final_value - initial_value, is multiplied. New
values of initial_value and final_value are calculated while keeping the midpoint of the range the
same.
- function — Optional. A string of rpn operations used to transform the range specified by initial_value,
final_value, and index_limit. For convenience, a few values are pushed onto the stack and are available to
the user: the original value of the process variable, and the calculated grid value for the process variable
on the current step or substep. The calculated values are recorded in the output file. The
environment variable RPN_DEFNS is used to read a rpn definition file at the start of the execution of
sddsexperiment.
- values_file — Optional. An SDDS data file containing setpoints for the variable. This is useful is one has
arbitrary setpoints values to apply. The values of the fields initial_value, final_value, _substeps,
range_multiplier and index_limit are ignored.
One can have other variable namelists with the same index_number that don’t use a file for the values. The
default index_limit of the other variable will be set to the number of setpoint in the values file. Thus the
values in the file and the values calculated for the other variable will vary together with the same number of
steps.
- values_file_column — Required when values_file is specified. values_file_column gives the column name
of the setpoints data in file values_file.
- substeps — Optional. If greater than one, the steps are subdivided into this number. Measurements are not
made at substeps. Substeps are useful when the physical device associated with the process variable cannot
reliably make steps as large as those that might be defined with initial_value, final_value, and
index_limit.
- substep_pause — Optional. Number of seconds to pause after the variable change of each
substeps.
- readback_name — Optional. Readback process variable name associated with control_name. The default
value for readback_name is control_name.
- readback_tolerance — Optional. Maximum acceptable absolute value of the difference between the
process variable setpoint and its readback. A positive value is required in order to enable
readbacks.
- readback_pause — Optional. Number of seconds to pause after each reading of the readback_name process
variable. This pause time is in addition to other pauses defined.
- readback_attempts — Optional. Number of allowed readings of the readback_name process variable and
readback pauses after a variable change has occurred. After this number of readings, the
program exits. The first readback is attempted immediately (i.e. no pause) after sending
a setpoint command to the control_name. A positive value is required in order to enable
readbacks.
- reset_to_original — Optional. A value of 1 means that the variable is reset to its original value when the
experiment terminates normally or abnormally.
– measurement_file
- function: specifies a SDDS data file containing the names of the process variables to measure at each step
during the experiment.
&measurement_file
STRING filename = NULL
long number_to_average = 1
long include_standard_deviation = 0
long include_sigma = 0
double lower_limit = 0
double upper_limit = 0
long limits_all = 0
&end
- filename — Required. SDDS file containing measurement process variables. The required
and optional column definitions closely resembles those used in sddsmonitor. The columns
are:
- ControlName — Required string data for the process variable names.
- ReadbackName — Optional string data for the measurement data columns names of the
experiment output file. If the column is not present, then the experiment output file’s columns
names uses the measurement process variable names themselves.
- NumberToAverage — Optional long data giving the number of measurements to average at each
step of the experiment. The average value of the measurements for each process variable is
written to the output file. Therefore individual readings are not recorded.
- IncludeStDev — Optional long data. If non-zero, then the standard deviations of measurements
are calculated and a column in the output file for this quantity is generated.
- IncludeSigma — Optional long data. If non-zero, then the sigma of measurements are calculated
and a column in the output file for this quantity is generated.
- LowerLimit, UpperLimit — Optional double data. Must have both or neither. Specifies a range
outside of which the measurement data is to be rejected, and the measurement be retaken. If
the number of invalid measurements (reset to 0 at each measurement step) equals or exceeds
the value of allowed_limit_errors (default of 1) in command execute, then the program aborts.
The average values written to the output file excludes measurements outside this range.
- LimitsAll — Optional long data. If non-zero for a particular PV, then out-of-range data for this
PV causes all other PVs to be remeasured. By default, only the out-of-range PV is remeasured.
Only the first data page of file filename is read in. For those optional columns above that are not
defined, then the following measurement_file fields will act as defaults (note the different
spellings):number_to_average, include_standard_deviation, include_sigma, lower_limit, upper_limit,
limits_all.
– measurement
– execute
- function: start executing the experiment. Some global parameters are defined here.
&execute
STRING outputfile = NULL
double post_change_pause = 0
double intermeasurement_pause = 0
double rollover_pause = 0
long post_change_key_wait = 0
long allowed_timeout_errors = 1
long allowed_limit_errors = 1
double outlimit_pause = 0.1
long repeat_reading = 1
double post_reading_pause = 0.1
double ramp_pause = 0.25
long ramp_steps = 10
&end
- outputfile — Optional. SDDS output file of variable and measurement data. The string
may contain the string “%s” which is substituted with the rootname value of the command
line. If rootname is not given, then the root of the input file is substituted . If outputfile is
null, then the root of the input file is used for the output file. See description of output file
below.
- post_change_pause — Optional. Number of seconds to pause after each change before making
measurements.
- intermeasurement_pause — Optional. Number of seconds to pause between each measurement. Individual
measurements for averaging are taken at this interval.
- rollover_pause — Optional. Number of seconds to pause after a counter has reached its upper limit, and
must rollover to zero. This allows any physical devices associated with the counter to settle after a change
equal to the total range of the variation.
- post_change_key_wait — Optional. If non-zero, then wait for a key press after making variable changes but
before taking measurements. A prompt is given.
- allowed_timeout_errors — Optional. Number of timeout ezca errors allowed before aborting the
program.
- allowed_limit_errors — Optional. Number of invalid range measurement errors allowed before
aborting the program. The valid range of a measurement is specified in the measurement
command.
- outlimit_pause — Optional. Number of seconds to pause after an invalid range measurement error
occurred. This is to permit equipment time to recover from whatever glitch caused the out-of-limit
reading.
- repeat_reading — Optional. The measurements and statistical analyses are repeated this
number of times for each variable settings. A row of data is written to the output file for each
repetition.
- post_reading_pause — Optional. Number of seconds to pause after taking a set of measurements and
making a statistical analysis. If measurements are repeated then the pause is repeated after each set of
measurements.
- ramp_steps — Optional. Number of steps in the variables PV ramp which occurs at the start and the end of
the experiment.
Ramping is necessary for some devices that do not respond well to large changes to their setpoints.
Ramping is done at the start of the experiments to slowly change the variable PVs from their current
values to their initial values. Another ramp is done at the end to slowly bring the variable PVs from their
final values back the original values. Ramping back to original values is also done when the experiment
aborts for some reason.
- ramp_pause — Optional. Time interval at each step of the variables PV ramp which occurs at the start and
the end of the experiment. This is not the same variable as the pause between variable changes during the
experiment.
– erase
– list_control_quantities
– system_call
- function: specifies a system call (usually a script) to be executed repeatedly during the experiment.
&system_call
STRING command = NULL
long index_number = 0
long index_limit = 0
double post_command_pause = 0
double pre_command_pause = 0
long append_counter = 0
STRING counter_format = "%ld"
long call_before_setting = 0
long call_before_measuring = 1
STRING counter_column_name = NULL
&end
- command — Required. Name of shell command or script to execute.
- index_number — Required. Counter number with which the command will be associated. The command is
executed when this counter is advanced or rolled over.
- index_number — Optional. Number of times the command is executed for the associated counter. This field
is used only when the value of index_number above defines a new counter.
- post_command_pause — Optional. Number of seconds to pause after the completion of the
command.
- pre_command_pause — Optional. Number of seconds to pause before executing the command.
- append_counter — Optional. If non-zero, the counter value is appended to the command when the system
call is made.
- counter_format — Optional. Format for the counter if the counter value is appended to the
command.
- call_before_setting, call_before_measuring — Optional. At a counter advance or rollover the command
can be executed in one of three ways:
- before both variable changes and measurements:
call_before_setting=1, call_before_measuring=1
- after variable changes and before measurements:
call_before_setting=0, call_before_measuring=1
- after both variable changes and measurements:
call_before_setting=0, call_before_measuring=0
If multiple measurements are required for averaging, the command is not executed between these
measurements.
- counter_column_name — Optional. If non-null, a column in the output file with this name is defined. The
values written to this column are the number of times the command had been called minus one. This value
doesn’t rollover with its associated counter.
– exec_command