2.36 squishPVs

• description: squishPVs minimizes the values of a set of readback process variables (for example bpm readbacks) by varying one setpoint process variable (for example a corrector magnet setpoint) which has a physical influence on the readback process variables. An input file defines one or more data sets of correction groups, each consisting of a list of readback PVs and one actuator PV. The method simulates the manual tweaking of physical devices that is often necessary when the readbacks are very noisy or when obtaining a response matrix is not worth the trouble.

  The name squishPVs comes from the apparent squishing of the real-time trajectory display when squishPVs is running.

• examples: The first-turn horizontal trajectory of the APS ring is minimized with this command:
  squishPVs xTrajCorr.sdds

  where correction groups are defined in the file xTrajCorr.sdds. Part of the first correction group in the file xTrajCorr.sdds is shown below:

  SDDS1  
  &description  
   text = "Input file for first turn correction", &end  
  &parameter  
   name = "CorrectorPV",  type = "string", &end  
  &parameter  
   name = "Gain",  type = "double", &end  
  ! LowerLimit and UpperLimit parameters are optional  
  &parameter  
   name = "LowerLimit", type = "double", &end  
  &parameter  
   name = "UpperLimit", type = "double", &end  
  &column  
   name = "BpmPV",  type = "string", &end  
  ! Offset PVs are optional  
  &column  
   name = "OffsetPV", type = "string", &end  
  ! Fixed offsets are optional and default to 0  
  &column  
   name = "OffsetValue", type = "double" &end  
  ! Weights are optional and default to 1  
  &column  
   name = "Weight", type = "double", &end  
  &data  
   mode = "ascii", &end  
  ! table number 1  
  ! CorrectorPV:  
  S1A:H1:CurrentAO  
  1.000000000000000e+00                   ! Gain  
  -150                                    ! LowerLimit  
  150                                     ! UpperLimit  
  360                                     ! number of rows  
  S1A:P1:ms:x S1A:P1:ms:x:SetpointAO 0.1 1  
  S1A:P2:ms:x S1A:P2:ms:x:SetpointAO 0.2 2  
  S1A:P3:ms:x S1A:P3:ms:x:SetpointAO 0.3 1  
  S1A:P4:ms:x S1A:P4:ms:x:SetpointAO 0.4 1  
  S1B:P5:ms:x S1B:P5:ms:x:SetpointAO 0.5 2  
  S1B:P4:ms:x S1B:P4:ms:x:SetpointAO 0.4 1  
  ...

• synopsis:
  usage: squishPVs <inputfile>  
      [-count=<pvName>,<lower>,<upper>,<number>]  
      [-averages=<number>,<seconds-between-readings>] [-stepSize=<value>]  
      [-subdivisions=<number>,<factor>]  
      [-upstep=count=<number>,factor=<value>]  
      [-repeat={number=<integer> | forever}[,pause=<seconds>]]  
      [-pendIOtime=<seconds>]  
      [-settlingTime=<seconds>] [-verbose]  
      [-criterion={mav|rms|min|max|average}] [-maximize]  
      [-threshold=<value>] [-actionLevel=<value>]  
      [-testValues=<file>,[limit=<number>]]  
      [-runControlPV={string=<string>|parameter=<string>},pingTimeout=<value>]  
      [-runControlDescription={string=<string>|parameter=<string>}]

• files:
  • input file:

    The input file data pages define correction groups. A correction group consists of a list of readback PVs and one corrector PV. The required column and parameters are:

    • BpmPV — String column of readback PVs. The name BpmPV is due to the original application of squishPV where the first turn trajectory is reduced by tweaked by corrector magnets.
    • OffsetPV — Optional string column of PVs to subtract from corresponding BpmPV. This will have the effect of optimizing toward the values of the offsets for positive weights (the default). The default offsets are all 0.
    • Weight — Optional double-precision column of values by which to multiply the readback-offset values. The default weight is 1.
    • CorrectorPV — String parameter of the corrector PV used in the correction group.
    • Gain — Double parameter for factor by which to multiply the value of the command line option stepSize.
• switches:
  • -count=<pvName>,<lower>,<upper>,<number> — Optional. Specifies a condition after which a reading will be taken. The process variable <pvName> is read at 1 second intervals. If this PV is within the validity limits specified for this number of readbacks, then the PVs of the correction group are read.
  • -averages=<number>,<seconds-between-readings> — Optional. Number of PV readings to average and the number of seconds to wait between readings.
  • -stepSize=<value> — Optional. Initial step size to attempt for corrector PVs.
  • -subdivisions=<number>,<factor> — Optionally specifies number and size of interval subdivisions.
  • -upstep=count=<number>,factor=<value> — Optionally specifies the number of steps to take in one direction before increasing the step size by the given factor.
  • -repeat=number=<integer> | forever[,pause=<seconds>] — Specifies repeated optimization, either a given number of times or indefinitely, with a pause in between. This is useful if a system needs periodic tuning up.
  • -pendIOtime=<seconds> — Optionally specifies the channel-access pendIO timeout for reading PVs.
  • -settlingTime=<seconds> — Optionally specifies the settling time after corrector PV changes.
  • -criterion=mav|rms|min|max|average — Optionally specifies the criterion for optimization. Mean-absolute-value is the default.
  • -threshold=<value> — Specifies that the change in the criterion must be below the specified value in order to be considered a genuine improvement.
  • -actionLevel=<value> — Specifies that the criterion must be above the given value in order for optimization to start.
  • -maximize — Specifies that the criterion should be maximized. The default is minimization.
  • -verbose — Optionally requests output during run.
  • -testValues=<file>,[limit=<number>] – file is a 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. limits is the maximum number of failure times. The program will be terminated when the continuous failure times reaches the limit.
  • -runControlPV=string=<string>|parameter=<string>,pingTimeout=<value> — Specifies a run control PV by name or parameter with optional ping timeout.
  • -runControlDescription=string=<string>|parameter=<string> — Specifies a run control description PV by name or parameter.
• see also:
  • sddscontrollaw()
• author: Michael Borland, ANL/APS.