2.12 sddscontrollaw

• description: sddscontrollaw performs simple feedback on process variables. The input file defines a gain matrix in a simple control law equation. The set of process variables for measurement are given by the names of the numerical data columns, and the set of process variables for control are given by a string column. By default, the feedback tries to regulate the values of the measurement to zero. The output file is a log of all process variables during the feedback. For robustness, a file of tests for a set of process variables may be defined so that the feedback may be suspended when any tests fail.
• examples: The trajectory of the LTP beamline and the energy of the linac upstream of the LTP beamline is controlled with this command:
  sddscontrollaw LTP.InvR12 LTPfeedback.out -interval=5 -steps=3600  
          -gain=0.75 -warning

  where the contents of the file LTP.InvR12 are

  SDDS1  
  &column  
   name = "CorrectorNames",  type = "string", &end  
  ! LTP:PH* are readbacks of beam position monitors  
  &column  
   name = "LTP:PH1",  type = "double", &end  
  &column  
   name = "LTP:PH2",  type = "double", &end  
  &column  
   name = "LTP:PH3",  type = "double", &end  
  &column  
   name = "LTP:PH4",  type = "double", &end  
  &data  
   mode = ascii, &end  
  ! LTP:H[124] are dipole steering magnets.  
  LTP:H1          1.45e-01  7.95e-02  1.84e-01 -3.70e-02  
  LTP:H2          0.00e-00  2.12e-01  3.34e-01  8.39e-02  
  ! Sled timing controls the linac energy.  
  L5:SledTiming   0.00e-00  0.00e-00  8.25e-03  9.45e-03  
  LTP:H4          0.00e-00  0.00e-00 -9.81e-03  1.44e-01

• synopsis:
  usage: sddscontrollaw <inputfile> [-searchPath=<dir-path>] [-actuatorColumn=<string>]  
         [<outputfile>] [-infiniteLoop] [-pendIOTime] [-filterFile=<file>]  
         [-generations[=digits=<integer>][,delimiter=<string>][,rowlimit=<number>]  
           [,timelimit=<secs>] | -dailyFiles]  
         [-controlQuantityDefinition=<file>]  
         [-gain={<real-value>|PVname=<name>}]  
         {[-interval={<real-value>|PVname=<name>}] | -triggerPV=<PVname>[,modulus=<integer>]}  
         [-steps=<integer=value>]  
         [-updateInterval=<integer=value>]  
         [{-integration | -proportional}]  
         [-holdPresentValues] [-offsets=<offsetFile>]  
         [-PVOffsets=<filename>] [-endOfLoopPV=<pvName>]  
         [-average={<number>|PVname=<name>}[,interval=<seconds>]]  
         [-despike[=neighbors=<integer>][,passes=<integer>][,averageOf=<integer>][,threshold=<value>]  
           [,pvthreshold=<pvname][,file=<filename>][,countLimit=<integer>]  
           [,startThreshold=<value>,endThreshold=<value>,stepsThreshold=<integer>]  
           [,rampThresholdPV=<string>]]  
         [-deltaLimit={value=<value>|file=<filename>}]  
         [-readbackLimit={value=<value>|minValue=<value>,maxValue=<value>|file=<filename>}]  
         [-actionLimit={value=<value>|file=<filename>}]  
         [-testValues=<SDDSfile>] [-statistics=<filename>[,mode=<full|brief>]]  
         [-auxiliaryOutput=matrixFile=<file>,controlQuantityDefinition=<file>,  
             filterFile=<file>],controlLogFile=<file>[,mode=<integral|proportional>]  
         [-runControlPV={string=<string>|parameter=<string>},pingTimeout=<value>  
         [-runControlDescription={string=<string>|parameter=<string>}]  
         [-launcherPV=<pvname>]  
         [-verbose] [-dryRun] [-warning]  
         [-servermode=pid=<file>,command=<file>]  
         [-controlLogFile=<file>]  
         [-glitchLogFile=file=<string>,[readbackRmsThreshold=<value>][,controlRmsThreshold=<value>]  
           [,rows=<integer]]  
         [-CASecurityTest] [-waveforms=<filename>,<type>] [-postChangeExecution=<string>]  
   
  Perform simple feedback on APS control system process variables using ca calls.

• files:
  • input file:

    The input file is an SDDS file with a string column and at least one numerical column. The first string column encountered gives the list of control process variables, the other string columns being ignored. The names of the numerical columns are the measurement process variables. The numerical data columns form a matrix which will be used in a simple control-law equation such as

    (1)

    or

    (2)

    The quantity x_n is the vector of measurement process variable values at step n, K is the matrix, u_n is the vector of control process variables calculated to reduce the values of the measurement process variables on the next iteration. The first equation refers to proportional control, while the second one refers to integral control. For trajectory or orbit correction in accelerators, where x_n are beam position monitor readbacks, and u_n are steering magnet setpoints, one chooses the integral control equation.

  • control quantity definition file:

    An optional control quantity definition file may be specified. This file allows one to use names in the matrix input file that are not really process variables, but more simplified and descriptive names. This situation can occur if the matrix file is obtained from postprocessing of sddsexperiment output data, a common way to generate the correction matrix empirically. The control quantity definition file is a cross-reference file which sddscontrollaw uses to match the input file names to real PV names. Two columns are required:

    • SymbolicName — String. Data must match all column names in the input file, and string column data in the input file.
    • ControlName — String. Corresponding PV names.
  • test values file:

    To make sddscontrollaw more robust, one can implement tests on any process variable, not necessarily those involved in the feedback itself. If any of the tests fail, then the feedback is suspended until the test succeeds. The test consist of checking whether a process variable is within a specified range or not. The testValues file has three required columns and one optional one:

    • ControlName — Required string column. PV names to test.
    • MinimumValue, MaximumValue — Required double columns. Defines a valid range for corresponding PVs. An error is generated when MinimumValue > MaximumValue.
    • SleepTime — Optional double. Specifies sleep (or pause) time before attempting another test.
  • output log file:

    The output file contains one data column for each process variables defined in the input file. By default, the data type is float (single precision). One row is written at every time step.

    Two time columns and a step column are defined:

    • Time — Double. Elapsed time of readback since the start of epoch.
    • ElapsedTime — Double. Elapsed time of readback since the start of execution.
    • TimeOfDay — Double. System time in units of hours. The time does not wrap around at 24 hours.
    • Step — Long. Step number.

    There are two parameters defined:

    • TimeStamp — String. Time stamp for file.
    • Gain — Double. Gain factor specified on the commandline.
• switches:
  • inputfile — gain matrix in sdds format.
  • outputfile — optional file in which the readback and control variables are printed at every step.
  • -searchPath=<string> — the directory path for the input files.
  • -actuatorColumn – String column in the input file to be used for actuator names. The default is the first string column of the input file.
  • -infiniteLoop — repeat corrections indefinitely until terminated.
  • -generations[=digits=<integer>][,delimiter=<string>][,rowlimit=<number>][,timelimit=<secs>] — The output is sent to the file ¡SDDSoutputfile¿-¡N¿, where ¡N¿ is the smallest positive integer such that the file does not already exist. By default, four digits are used for formatting ¡N¿, so that the first generation number is 0001. If a row limit or time limit is given, a new file is started when the given limit is reached.
  • -dailyFiles — The output is sent to the file ¡SDDSoutputfile¿-YYYY-JJJ-MMDD.¡N¿, where YYYY=year, JJJ=Julian day, and MMDD=month+day. A new file is started after midnight. Only one of dailyFiles and generations may be provided.
  • -controlQuantityDefinition=<file> a cross-reference file which matches the simplified names used in the inputfile to PV names. Column names are SymbolicName and controlName.
  • -gain=<real-value>|PVname=<name> — quantity multiplying the inputfile matrix. If the gain matrix is the inverse response matrix then this should be less than one. Can be provided by a real value or a PV name (the value will be read from the PV).
  • -interval=<real-value>|PVname=<name> — time interval between each correction. Can be provided by a real value or a PV name (the value will be read from the PV)
  • -triggerPV=<pvname>[,modulus=<integer>] — use changes in the given PV to trigger corrections; optional modulus specifies that only every n-th trigger is recognized.
  • -steps=<integer=value> — total number of corrections.
  • -updateInterval=<integer=value> — number of steps between each outputfile updates.
  • -integral | -proportional — switch the control law to either integral orproportional control; use integral control for orbit correction; the default control law is integral control.
  • -holdPresentValues — causes regulation of the readback variables to the values at the start of the running.

    (3)

    or

    (4)

    where x₀ is the vector of initial values of measurement PVs (i.e. values before running the program)

  • -offsets=<offsetFile> — Gives a file of offset values to be subtracted from the readback values to obtain the values to be held to zero. Expected to contain at least two columns: ControlName and Offset.
  • -PVOffsets=<filename> — Gives a file of offset PVs to be read and their values are subtracted from the readback values of the primary readbacks. Expected to contain at least two columns: ControlName (the names of the primary readbacks), OffsetControlName (the name of the offset PVs).
  • -endOfLoopPV=<pvName> — writes the current step value to the named PV at the end of each loop.
  • -filterFile=<file> — file providing actuator filtering coefficients; must contain DeviceName and a0, a1, ..., b0, b1, ... columns.
  • -auxiliaryOutput=matrixFile=<file>,controlQuantityDefinition=<file>,filterFile=<file>, controlLogFile=<file>[,mode=<integral|proportional>] — reads in an additional matrix to calculate values for PVs (not necessarily corrector PVs) based on the correction that is being done. The formula y = (gain) M (delta_C) is used for integral mode and y = (gain) M (C) forproportional mode. Time filtering is available through a filter file with a0, b0, a1, etc, coefficients. A control quantity definition file for the matrix is available as option. The default mode is integral, if mode=proportional is given, proporptional control will be applied.
  • -verbose — prints extra information.
  • -dryRun — readback variables are read, but the control variables aren’t changed.
  • -average=<number>|PVname=<name>[,interval=<seconds>] — number of readbacks to average before making a correction. Default interval is one second. Units of the specified interval is seconds. The total time for averaging will not add to the time between corrections.
  • -testValues=<filename> — sdds format file containing minimum and maximum values of PV’s specifying a range outside of which the feedback is temporarily suspended. Column names are ControlName, MinimumValue, MaximumValue. Optional column names are SleepTime, ResetTime, Despike, and GlitchLog.
  • -statistics=<filename>[,mode=<full|brief>] — write readback and control statistics to the specified file; mode may be full or brief (default full).
  • -deltaLimit=value=<value>|file=<filename> — Specifies maximum change made in one step for any actuator, either as a single value or as a column of values (column name DeltaName) from a file. The calculated change vector is scaled to enforce these limits, if necessary.
  • -readbackLimit=value=<value>|minValue=<value>,maxValue=<value>|file=<filename> — Specifies the maximum negative and positive error to recognize for each PV. The values can be specified as a single value, as two values, or as columns of values in a file (clumns should be minValue and maxValue).
  • -actionLimit=value=<value>|file=<filename> — Specifies minimum values in readback before any action is taken, either as a single value or as a column of values (column name ActionLimit) from a file.
  • -warning — prints warning messages.
  • -pendIoTime=<real-value> — specifies maximum time to wait for connections and return values. Default is 30.0s
  • -runControlPV=string=<string>|parameter=<string>,pingTimeout=<value> — specifies a string parameter in ¡inputfile¿ whose value is a runControl PV name.
  • -runControlDescription=string=<string>|parameter=<string> — specifies a string parameter in ¡inputfile¿ whose value is a runControl PV description record.
  • -launcherPV=<pvname> — base name for launcher PVs used for status and control messaging.
  • -despike=[neighbors=<integer>][,passes=<integer>][,averageOf=<integer>]
    [,threshold=<value>][,pvthreshold=<pvname>][,file=<filename>][,countLimit=<integer>]
    [,startThreshold=<value>,endThreshold=<value>,stepsThreshold=<integer>]
    [,rampThresholdPV=<string>] — specifies despiking of readback variables, under the assumption that consecutive readbacks are nearest neighbors. If a file is specified, then the PVs with column Despike value of 0 will not get despiked. If the testsValues file has a Despike column defined, the test PVs with a nonzero value for Despike will get despiked with the same option parameters. If countLimit is greater than 0 and there are more than N readings outside the despiking threshold, then no despiking is done. If startThreshold, endThreshold and stepsThreshold are provided, then ramp the despiking threshold from startThreshold to endThreshold over stepsThreshold correction steps. It then remains at endThreshold, unless the threshold pv is given with -despike. In that case, the threshold can be changed via the PV. If rampThresholdPV is provided, the threshold will be reramped whenever the value of rampThresholdPV is no-zero and it is reset to 0 after reramping.
  • -servermode=pid=<file>,command=<file> allows one to change the commandline options while the program is running. Program reads the command file for new options whenever SIGUSR1 is received, and exits when SIGUSR2 is received. The process id is stored in file specified by pid.
  • -controlLogFile=<file> — At each change of actuators, the old and new values of the actuators are written to this file. The previous instance of the file is over-written at the same time.
  • -glitchLogFile=file=<string>,[readbackRmsThreshold=<value>][,controlRmsThreshold=<value>] [,rows=<integer] — Readback and control data values are written at each glitch event defined by the by the RMS thresholds specified as sub-options.
  • -CASecurityTest — checks the channel access write permission of the control PVs. If at least one PV has a write restriction then the program suspends the runcontrol record.
  • -waveforms=<filename>,<type> — the waveform file name, and the type of waveforms. ¡type¿=readback, offset, actuator or ffSetpoint or test. The waveform file contains ”WaveformPV” parameter, ”DeviceName” and ”Index” columns, which is the index of DeviceName in the vector. Note that for actuators, if the reading and writing name are different, two parameters ”ReadWaveformPV” and ”WriteWaveformPV” should be given. For testing waveforms, there are two additional required columns: MaximumValue and MinimumValue, and one optional short column - Ignore: which set the flags of whether ignore the pvs in the waveform. If Ignore column does not exist, then the readbacks and controls will consider to be testing pvs in the waveforms.
  • -postChangeExecution=<string> — execute the specified command after applying control changes.
• examples:
       sddscontrollaw sddscontrollaw.inv2 -searchPath=/home/oxygen/OAG/sddsEpicsTests -interval=1  
         -steps=10 -gain=.75  
         -controlQuantityDefinition=sddscontrollaw.cqdf -testValues=sddscontrollaw.test -despike  
         -average=3,interval=.1 -verbose  
       
       sddscontrollaw sddscontrollaw.inv -searchPath=/home/oxygen/OAG/sddsEpicsTests  -interval=1  
         -steps=15 -gain=1.2 -holdPresentValues -verbose  
       
       sddscontrollaw sddscontrollaw.inv -searchPath=/home/oxygen/OAG/sddsEpicsTests  -interval=1  
         -steps=15 -gain=1.1 -offsets=sddscontrollaw.offsets -verbose  
       

• see also:
  • sddsexperiment()
• author: Louis Emery, Hairong Shang, Robert Soliday, ANL/APS.