optimization_setup

- type: setup command.
- function: define overall optimization parameters and methods.

&optimization_setup STRING equation = NULL; STRING mode = "minimize"; STRING method = "simplex"; double tolerance = -0.01; double target = 0; long center_on_orbit = 0; long center_momentum_also = 1; long soft_failure = 1; long n_passes = 2; long n_evaluations = 500; long n_restarts = 0; long matrix_order = 1; STRING log_file = NULL; STRING term_log_file = NULL; long output_sparsing_factor = 0; long balance_terms = 0; double restart_worst_term_factor = 1; long restart_worst_terms = 1; long verbose = 1; long balance_terms = 0; double simplex_divisor = 3; double simplex_pass_range_factor = 1; long include_simplex_1d_scans = 1; long start_from_simplex_vertex1 = 0; long restart_random_numbers = 0; STRING interrupt_file = "%s.interrupt"; &end

`equation`

-- An`rpn`equation for the optimization function, expressed in terms of any parameters of any optimization variables, the ``final'' parameters of the beam (as recorded in the`final`

output file available in the`run_setup`

namelist), and selected quantities from Twiss parameter, tune shift with amplitude, closed orbit, beam moments, driving terms, and other computations. The optimization variables or covariables may appear in the equation in the form`<element-name>.<parameter-name>`

, all in capital letters. In addition, initial values of variables and covariables are available in the form`<element-name>.<parameter-name>0`

.Data from MARK elements with

`FITPOINT=1`and from beam position monitors with`CO_FITPOINT=1`may be used via symbols of the form. See the documentation for the*elementName*#*occurenceNum*.*parameterName*`MARK`,`MONI`,`HMON`, and`VMON`elements for detailed discussion and listing.If response matrix calculation is requested, response matrix values are available in variables with names

*Plane*`R_`*bpmName*`#`

*occurence*`_`*corrName*`#`

*occurence*`.`*corrParam*, where*Plane*is`H`(horizontal) or`V`(vertical) and*corrParam*is the parameter of the corrector used for changing the orbit (e.g.,`HKICK`or`VKICK`for a`KICKER`element).If cross-plane response matrix calculation is requested, response matrix values are available in variables with names

*BpmPlaneCorrPlane*`R_`*bpmName*`#`

*occurence*`_`*corrName*`#`

*occurence*`.`*corrParam*, where*BpmPlane*and*CorrPlane*are`H`(horizontal) or`V`(vertical) and*corrParam*is the parameter of the corrector used for changing the orbit (e.g.,`HKICK`or`VKICK`for a`KICKER`element).Many quantities are made available for optimization if

`twiss_output`

command is given with`output_at_each_step=1`

:- Final Twiss parameters, e.g.,
`betax`

,`alphax`

,`etax`

. The names are the same as the column names in the twiss output file. - Statistics of Twiss parameters in the form
`<statistic>.<parameter-name>`

, where`<statistic>`

is`min`

,`max`

,`ave`

,`p99`

,`p98`

, or`p96`

.`p99`

is the 99 pencentile value, a similarly for`p98`

and`p96`

. - Tunes and chromaticities via symbols
`nux`

,`dnux/dp`

, (and corresponding symbols for y). - First- and second-order momentum compaction factors via symbols
`alphac`

and`alphac2`

. - If radiation integral computation is requested, one may use
`ex0`

and`Sdelta0`

for the equilibrium emittance and momentum spread, plus`J<plane>`

and`tau<plane>`

for the damping partition and damping time, where`<plane>`

is`x`

,`y`

, or`delta`

. One may also use`I1`

through`I5`

for the individual radiation integrals. - If
`compute_driving_terms=1`

, then the quantities`h11001`,`h00111`,`h20001`,`h00201`,`h10002`,`h21000`,`h30000`,`h10110`,`h10020`,`h10200`,`h22000`,`h11110`,`h00220`,`h31000`,`h40000`,`h20110`,`h11200`,`h20020`,`h20200`,`h00310`,`h00400`,`dnux/dJx`,`dnux/dJy`, and`dnuy/dJy`may be used. Table 2 explains the meaning of the terms. - The coupling integral and emittance ratio due to x-y coupling may
be accessed using the symbols
`couplingIntegral`

and`emittanceRatio`

. See section 3.1.4.4 of [19]. - If higher-order chromaticity is requested, then one may use the
symbols
`dnux/dp2`,`dnux/dp3`,`dnuy/dp2`,`dnuy/dp3`,`etax2`,`etax3`,`etay2`,`etay3`,`nuxChromLower`,`nuxChromUpper`,`nuyChromLower`, and`nuyChromUpper`. - If the
`tune_shift_with_amplitude`

command was also given and one may use the symbols`dnux/dAx`,`dnux/dAy`,`dnuy/dAx`,`dnuy/dAy`,`dnux/dAx2`,`dnux/dAy2`,`dnux/dAxAy`,`dnuy/dAx2`,`dnuy/dAy2`,`dnuy/dAxAy`,`nuxTswaLower`,`nuxTswaUpper`,`nuyTswaLower`, and`nuyTswaUpper`.

If the

`floor_coordinates`

command was given, one may use`X`

,`Z`

, and`theta`

to refer to the final values of the floor coordinates.If the

`sasefel`

command was given, one may use variables of the form`SASE.<property>`

, where`<property>`

is one of`gainLength`

,`saturationLength`

,`saturationPower`

, or`lightWavelength`

.Finally, one may use any of the names from the ``final'' output file (see

`run_setup`

), e.g.,`Sx`

(x beamsize) or`eny`

(y normalized emittance). These refer to tracked properties of the beam.The equation may be left blank, in which case the user must give one or more

`optimization_term`

commands. These use the same symbols, of course.There are several

`rpn`functions that are useful in constructing a good optimization equation. These are ``soft-edge'' greater-than, less-than, and not-equal functions, which have the names`segt`,`selt`, and`sene`, respectively. The usage is as follows:*V1**V2**T*`segt`. Returns a nonzero value if and only if value*V1*is greater than*V2*. The returned value is . Typically used to constraint a quantity from above. E.g., to limit the maximum horizontal beta function to 10m with a tolerance of , one would use`max.betax 10 .1 segt`

.*V1**V2**T*`selt`. Returns a nonzero value if and only if value*V1*is less than value*V2*. The returned value is . Typically used to constrain a value from below. E.g., to limit a beta function to greater than 3 m with a tolerance of 0.1 m, one would use`betax 3 .1 selt`

.*V1**V2**T*`sene`. Returns a nonzero value if and only if*V1*and*V2*differ by more than*tol*. If , returns . If , returns .

- Final Twiss parameters, e.g.,
`mode`

-- May be either ``minimize'' or ``maximize''.`method`

-- May be one of ``simplex'', ``grid'', ``powell'', ``randomwalk'', ``randomsample'', or ``sample''. Recommended methods are ``simplex'' and ``randomwalk''. The latter is very useful when the lattice is unstable or nearly so.`tolerance`

-- The convergence criterion for the optimization, with a negative value indicating a fractional criterion.`target`

-- The value which, if reached, results in immediate termination of the optimization, whether it has converged or not.`center_on_orbit`

-- A flag indicating whether to center the beam transverse coordinates on the closed orbit before tracking.`center_momentum_also`

-- A flag indicating whether to center the momentum coordinate also.`soft_failure`

-- A flag indicating, if set, that failure of an optimization pass should not result in termination of the optimization.`n_evaluations`

-- The number of allowed evaluations of the optimization function. If simplex optimization is used, this is the number of allowed evaluations per pass.`n_passes`

-- The number of optimization passes made to achieve convergence (``simplex'' only). A pass ends (roughly) when the number of evaluations is completed or the function doesn't change within the tolerance. A new pass involves starting the optimization again using step sizes determined from the range of the simplex and the factor`simplex_pass_factor`

.`n_restarts`

-- The number of complete restarts of the optimization (simplex only). This is an additional loop around the`n_passes`

loop. The difference is that a restart involves using the optimized result but the original step sizes. It is highly recommended that this feature be used if convergence problems are seen.`restart_worst_term_factor`

,`restart_worst_terms`

-- Often when there are convergence problems, it is because a few terms are causing difficulty. Convergence can often be obtained by*increasing*the weighting of these terms. If`restart_worst_term_factor`

is positive, then`elegant`

will multiply the weight of the`restart_worst_terms`

largest terms by this factor at the beginning of a restart.`matrix_order`

-- Specifies the highest order of matrix elements that should be available for fitting. Elements up to third order are available for the terminal point of the beamline, and up to secod order for interior fit points. Names for first-, second-, and third-order elements are of the form`R`*ij*,`T`*ijk*, and`U`*ijkl*.`log_file`

-- A file to which progress reports will be written as optimization proceeds. For SDDS data, use the`final`

output file from the`run_setup`

namelist.`term_log_file`

-- This names a file to which the values of the optimization terms are written at the completion of optimization, which can be convenient when large numbers of terms are used. For example, by using`sddssort`

one could find which terms are contributing most to the penalty value.`output_sparsing_factor`

-- If set to a value larger than 0, results in sparsing of output to the ``final'' file (see`run_setup`

). This can make a significant difference in the optimization speed.`balance_terms`

-- If nonzero, then all terms of the optimization expression have their weights adjusted so they make equal contributions to the penalty function. This can help prevent optimization of a single term at the expense of others. It is performed only for the initial value of the optimization function.`simplex_divisor`

-- The factor by which simplex step sizes are changed as the optimization algorithm searches for a valid initial simplex.`simplex_pass_range_factor`

-- When starting a new pass, the simplex optimizer takes the range over the previous simplex of each variable times this factor as the starting step size for that variable. This can be useful if the optimization brings the system close to an instability. In such a case, the simplex routine may have trouble constructing an initial simplex if the range of the variables is large. Setting this control to a value less than 1 may help.`include_simplex_1d_scans`

-- If nonzero, optimizer performs single-variable scans prior to starting simplex optimization. This is usually a good idea, but in some cases it will cause problems. For example, if your design is on the edge of being unstable, you may get some many errors from the initial steps that the single-variable optimizer can't continue. Disabling the single-variable scans will sometimes solve this.`start_from_simplex_vertex1`

-- If nonzero, optimizer uses the initial simplex vertex as the starting point for each new 1d scan. Otherwise, it uses the result of the previous scan.`restart_random_numbers`

-- If nonzero, the random number generators used by`elegant`are reset for each evaluation of the optimization function. This is valuable if one is optimizing tracking results that involve random processes (e.g., ISR or scattering).`interrupt_file`

-- Gives the name of a file that will be monitored by the program as it runs. If the file is created or modified while optimization is running, the optimizer will complete the present step and cleanly terminate, allowing subsequent commands, if any, to proceed.