sddsexperimentvaries process variables and measures process variables, with optional statistical analysis. An input file of namelist commands gives the specific instructions. The results are recorded in one or more SDDS files.
sddsexperiment LTP:H1.exp LTP:H1.sddswhere the contents of the file
&measurement control_name = "LTP:PH1:x", column_name="LTP:PH1:x", units=mm, number_to_average = 10, &end &variable control_name = "LTP:H1:CurrentAO", column_name="LTP:H1:CurrentAO" ! the corrector is varied in 5 steps from -1.0 to 1.0 amps. index_number = 0, index_limit = 5, initial_value = -1.0, final_value = 1.0, &end &execute post_change_pause=4, intermeasurement_pause=1 &end
where the line starting with a ``!'' is a comment.
usage: sddsexperiment <inputfile> [<outputfile-rootname>] [-echoinput] [-dryrun] [-summarize] [-verbose] [-ezcaTiming=<timeout>,<retries>]
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
measurementnamelist, 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> . . . &endwhere 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.
&<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.
readback_toleranceare 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
The fields of
&variable associated for the range and steps are ignored in this case.
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
&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
sddsexperimentrun, counters must be defined in an increasing order with no gaps starting from counter 0. That is, the first
variablecommand of the file must have
index_number= 0. The second
variablecommand 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
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 is nested within counter . Therefore it might be efficient
to assign devices with slower response times to
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_limitof the first variable definition for that counter need to be defined. If
index_limitis defined in
variablecommands of the same
index_numbervalue, then the first
index_limitremain 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,
initial_value, is multiplied. New values of
final_valueare calculated while keeping the midpoint of the range the same.
function-- Optional. A string of rpn operations used to transform the range specified by
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_DEFNSis used to read a rpn definition file at the start of the execution of
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
One can have other
variable namelists with the same
that don't use a file for the values.
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_columngives the column name of the setpoints data in 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
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_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_nameprocess variable. This pause time is in addition to other pauses defined.
readback_attempts-- Optional. Number of allowed readings of the
readback_nameprocess variable and readback pauses after a variable change has occured. 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 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.
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.
filenameis read in. For those optional columns above that are not defined, then the following
measurement_filefields will act as defaults (note the different spellings):
measurement_file, as both commands merely adds to an internal list of measurement PV.
&measurement STRING control_name = NULL STRING column_name = NULL STRING symbol = NULL STRING units = "unknown" 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
control_name-- Required. Process variable name to measure.
column_name-- Required. Column name for the measurement data recorded in the output file.
symbol-- Optional. Symbol field for the above column definition of the measurement data.
units-- Optional. Units field for the above column definition of the measurement data.
number_to_average-- Optional. Number of readings to average. The output data is the average value. The individual readings are not recorded.
include_standard_deviation-- Optional. Calculate the standard deviation (a measure of the distribution) of the measurement, and generate a column in the output file for this quantity.
include_sigma-- Optional. Calculate the sigma (error of the mean) of the measurement, and generate a column in the output file for this quantity.
upper_limit-- Optional. Defines a range of validity for the individual measurements. 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.
limits_all-- Optional. If non-zero, then out-of-limits data for this PV causes all PVS to be remeasured. By default, only the out-of-limit PV is remeasured.
&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 intput file is substituted . If
outputfileis 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
outlimit_pause-- Optional. Number of seconds to pause after an invalid range measurement error occured. 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 repitition.
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 long variable_definitions = 1 long measurement_definitions = 1 &end
variable_definitions-- Optional. If non-null, then all the variable definitions are erased.
measurement_definitions-- Optional. If non-null, then all the measurement definitions are erased.
&list_control_quantities STRING filename = NULL &end
filename-- Required. Name of file. Columns defined are
&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_numberabove 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_measuring-- Optional. At a counter advance or rollover the command can be executed in one of three ways:
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 STRING command = NULL &end
command-- Command or script to run. The command is run immediately when the namelist command is processed
The output file contains one data column for each measurement and control process variable.
The names of these data columns are taken from the
column_name field of the
variable commands. The data are written
as double precision floating point numbers.
In addition, some time columns and parameters are defined:
sddsplotto make the best coice of time unit conversions for time axis labeling.
This file contains process variable names, readback column names, and units as string data. This data can be used for cross-referencing. The columns defined in this file are:
control_namefield given in the
column_namefield given in the
unitsfield given in the
-echoinput-- echos input file to stdout.
-dryrun-- the ``variable'' process variables are left untouched during the execution. The ``measurement'' process variables are still read. The pauses are still in effect. System calls are not made.
-summarize-- gives a summary of the experiment before executing it.
-verbose[=very]-- prints out information during the execution such as notification of setting and reading process variables. The option
veryprints out the average measurement values.
-ezcaTiming=<timeout>,<retries>-- sets EZCA timeout and retry parameters
-describeinput-- Printouts the list of namelist commands and fields of the input file.