2.21 sddsoptimize

• description: sddsoptimize optimizes the RMS of a set of readback process variables by automatically varying setpoint process variables (or knobs composed of setpoint PVs), which have a physical influence on the readback process variables, through simplex or 1dscan method.
• examples: The trajectory of the booster BPMs is controlled with this command:
  sddsoptimize -measFile=booster.h.moni -varFile=vv -simplex=evaluations=50,divisions=12  
    -knobFiles=booster.cokn -verbose

  where the contents of the file booster.h.moni are

  SDDS1  
  &column  
   name = "ControlName",  type = "string", &end  
  &column  
   name = "ReadbackName",  type = "string", &end  
  &column  
   name = "ReadbackUnits",  type = "string", &end  
  &data  
   mode = ascii, no_row_counts=1 &end  
  oag:B1C0P1:ms:x B1C0P1:ms:x mm  
  oag:B1C0P2:ms:x B1C0P2:ms:x mm  
  oag:B1C1P1:ms:x B1C1P1:ms:x mm  
  oag:B1C1P2:ms:x B1C1P2:ms:x mm  
  .......  
  

  the contents of the file vv are

  SDDS1  
  &parameter name=PauseAfterChange, type=double, &end  
  &column name=ControlName, type=string,  &end  
  &column name=LowerLimit, type=double,  &end  
  &column name=UpperLimit, type=double,  &end  
  &column name=InitialChange, type=double,  &end  
  &data mode=ascii,no_row_counts=1,&end  
  oag:B1C1H:KickAO -2  2  2  
  oag:B1C2H:KickAO -2.500000000000000e+01  2.500000000000000e+01  2.000000000000000e-01  
  oag:B1C3H:KickAO -2.500000000000000e+01  2.500000000000000e+01  2.000000000000000e-01  
  B:h11cos         -25                     25                     0.1  
  B:h12sin         -25                     25                     0.1  
  B:h12cos         -25                     25                     0.1  
  .....  
  

  the contents of the file booster.cokn are

  SDDS1  
  &parameter name=ControlName, type=string, &end  
  &parameter name=KnobDescription, type=string, &end  
  &parameter name=Gain, type=double, &end  
  &parameter name=ControlType, type=string, &end  
  &parameter name=ControlUnits, type=string, &end  
  &parameter name=Filename, description="Name of file from which this page came", type=string, &end  
  &parameter name=NumberCombined, description="Number of files combined to make this file", type=long, &end  
  &column name=ControlName, type=string,  &end  
  &column name=Weight, type=double,  &end  
  &data mode=asc_ii,no_row_counts=1. &end  
  ....  
  ....  
  !.page 2  
  B:h11cos  
  h plane 11th harm. cos (1 mrad/click)  
  1.0  
  pv  
  rad  
  11HarmCosineh.cokn  
  8  
  oag:B1C0H:KickAO 0.99997256549446789  
  oag:B1C1H:KickAO -0.21202791415796657  
  oag:B1C2H:KickAO -0.93188756664225914  
  .....  
  .....  
  

• synopsis:
  usage: sddsoptimize [-measFile=<file>|-measScript=<script>] [-varScript=<script>]  
  [-restartFile=<file>] [-pendIOtime=<seconds>] [-conditioning=<script>]  
  -varFile=<file> -knobFiles=<file1>[,<file2>...]  
  [-simplex=[restarts=<nRestarts>][,cycles=<nCycles>][,evaluations=<nEvals>][,no1dscans]  
    [,divisions=<int>][,randomSigns]]  
  [-rcds=[cycles=<number>][,evaluations=<number>][,step=<value>][,noise=<value>][,dmatFile=<file>]  
    [,useMinForBracket][,verbose]]  
  [-1dscan=[divisions=<value>][,cycles=<number>][,evaluations=<value>][,refresh]]  
  [-logFile=<file>] [-extraLogFile=<file>] [-dryRun] [-verbose] [-tolerance=<value>] [-maximize]  
  [-target=<value>] [-testValues=file=<file>[,limit=<count>]]  
  [-runControlPV={string=<string>|parameter=<string>},pingTimeout=<value>,pingInterval=<value>]  
  [-runControlDescription={string=<string>|parameter=<string>}]

  Perform optimization on APS control system process variables using simplex, 1dscan, or RCDS methods.

• files:
  • variable input file:

    The variable input file is an SDDS file with one string column: ControlName, which is required and gives the list of control correctors (process variables or knobs). It also contains three double columns: LowerLimit, UpperLimit, IntialChange and InitialValue. InitialValue column is optional. Others are required. InitialChange column specifies the initial changes to the correctors. Variable input file has one parameter –PauseBetweenReadings(double), which sets the waiting time in seconds between two settings of the correctors.

  • measurement file:

    This file specifies the measurement to be optimized. It has four columns:

    • ControlName — Required string column. Gives the list of process variables to be controlled.
    • ReadbackName — string, optional.
    • ReadbackUnits — string, optional.
    • Weight – double, optional. Defines the weight of each PV contributed to RMS.

    It has three parameters:

    • Tolerance — double, sets the converging limit.
    • NumberToAverage — long, sets number of average for measurement PVs.
    • PauseBetweenReadings — double, sets interval between two readings.
  • knob file:

    To make sddsoptimize more robust, one can implement optimizaion on knobs, that are composed of set point process variables. The process variables that a knob contains are given in knob file, which contain following parameters and columns:

    • ControlName — Required string parameter. The name of knob, which acts as a corrector as other PVs do.
    • ControlName — Required string column. The names of PVs the knob specified above contains.
    • Weight — Required double columns. Defines the weights of PVs that compose the knob.
    • Gain —Optional double parameter. The value of each PV the knob contains
      is value(PV)=value(knob)*Gain*Weight(PV). When it is not given, set it to 1.
    • ControlType — Optional string parameter. Specifies the control type.
    • ControlUnits — Optional string parameter. Specifies the units of control PVs.
    • KnobDescription – Optional string parameter.
    • Filename— Optional string parameter. The name of the file where this knob comes from.
    • Numbercombined — Optional long parameter. The number of files combined. The resulted knob file contains all the information of the files combined. The content of each page is from the combined file specified in filename parameter.
  • output log file:

    The output file contains one data column for each process variables defined in the variable input file. By default, the data type is double. One row is written at every evaluation. Also two more columns and two parameters are defined:

    • EvalIndex — Long Column. The index of evaluations.
    • currentValue — Double column. The RMS value of measurement at each evaluaion.
    • variableFile — String parameter. The name of input variable file.
    • measurementFile — String parameter. The name of input measurement file.
• switches:
  • -varFile=<file> — Required; defines control correctors or knobs.
  • -measFile=<file> — Specifies the measurement file.
  • -knobFiles=<file1>[,<file2>...] — List of knob definition files.
  • -measScript=<script> — Script for measuring PVs.
  • -varScript=<script> — Script for setting setpoint PVs or tags.
  • -restartFile=<file> — Save optimized values for later use.
  • -logFile=<file> — Write optimization data to an SDDS log.
  • -extraLogFile=<file> — Additional PVs for logging.
  • -pendIOtime=<seconds> — Channel access pendIO timeout.
  • -conditioning=<script> — Conditioning script executed before optimization.
  • -simplex — Parameters for simplex optimization.
  • -rcds — Parameters for robust conjugate direction search.
  • -1dscan — Parameters for one-dimensional scan optimization.
  • -dryRun — Compute settings without applying them.
  • -verbose — Print additional progress information.
  • -target=<value> — Target value for RMS of measurement PVs.
  • -tolerance=<value> — Tolerance when using a measurement script.
  • -maximize — Maximize instead of minimize the measurement.
  • -runControlPV — Specifies the runControl PV record.
  • -runControlDescription — Specifies a runControl PV description record.
  • -testValues=file=<file>[,limit=<count>] — Enforce temporary feedback limits.
• see also:
  • sddsexperiment()
• author: Hairong Shang, ANL/APS.