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.

• example: 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> [<outputfile>] 
         -controlQuantityDefinition=<file>
         [-gain=<real-value>] [-interval=<real-value>] 
         [-steps=<integer=value>] [-updateInterval=<integer=value>]
         [{-integration | -proportional}] [-holdPresentValues] 
         [-verbose] [-dryRun]
         [-testValues=<SDDSfile>] [-warning]  
         [-ezcaTiming=<timeout>,<retries>] [-groupEzca]
  Perform simple feedback on APS control system process variables using ezca 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
    

    $${\bf u_n} = - K {\bf x_n}$$ (1)

    
    
    or
    

    $${\bf u_n} = {\bf u_{n-1}} - K {\bf x_n}.$$ (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 suceeds. 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:
  • -controlQuantityDefinition=<file> -- an optional cross-reference file which matches the simplified names used in the inputfile to real PV names. Required string column are SymbolicName and ControlName. The data in column SymbolicName must match all column names in the input file, and string column data in the input file. Data in ControlName must be valid process variable names.
  • -gain=<real-value> -- quantity multiplying the inputfile matrix. If the gain matrix is exactly equal to the inverse response matrix between the control and measurement process variables, then this value should be less than one. If instability occurs in the feedback, then the program should be re-run with a reduced value for gain.
  • -interval=<real-value> -- Specifies the interval between readings. The time interval is implemented with a call to usleep between calls to the control system. Because the calls to the control system may take up a significant amount of time, the average effective time interval may be longer than specified.
  • -steps=<integer-value> -- Number of iterations for the feedback before normal exiting.
  • -updateInterval -- Obsolete.
  • -integral | -proportional -- Switch the control law to either integral or proportional 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. In this case, the control law equations are
    

    $${\bf u_n} = - K ({\bf x_n} - {\bf x_0})$$ (3)

    
    
    or
    

    $${\bf u_n} = {\bf u_{n-1}} - K ({\bf x_n} - {\bf x_0}).$$ (4)

    
    
    where $x_0$ is the vector of initial values of measurement PVs (i.e. values before running the program).
  • -verbose -- prints out a message when data is taken.
  • -dryrun -- readback variables are read, but the control variables aren't changed.
  • -testValues=<file> -- 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, SleepTime (optional).
  • -warning -- prints warning messages.
  • -ezcaTiming[=<timeout>,<retries>] -- Sets EZCA timeout and retry parameters.

• see also:
  • sddsexperiment
• author: L. Emery, ANL