correct

mode — Either “trajectory” or “orbit”, indicating correction of a trajectory or a closed orbit.

method — For trajectories, may be “one-to-one”, “one-to-best”, “one-to-next”, “thread”, “global”, or “coupled”. “One-to-one” and “one-to-next” are the same: steering is performed by pairing one corrector with the next downstream BPM. “One-to-best” attempts to find a BPM with a large response to each corrector. “Thread” does corrector sweeps to work the beam through a beamline with apertures; it is quite slow. “Global” simply uses the global response matrix; it is the best choice if the trajectory is not lost on an aperture. “Coupled” is like global, but should be used for strongly-coupled transport lines; in this case, only HMON and VMON elements are permitted for monitors and only EHKICK, EVKICK, HKICK, and VKICK elements are permitted for correctors. For closed orbit, must be “global”.

trajectory_output — The (incomplete) name of an SDDS file to which the trajectories or orbits will be written. Recommended value: “%s.traj” or “%s.orb”.

corrector_output — The (incomplete) name of an SDDS file to which information about the final corrector strengths will be written. Recommended value: “%s.cor”. N.B.: although this file looks as if it can be used with the load_parameters command, care must be exercised because the data for the horizontal and vertical planes is on separate pages. Typically, one will need to use sddscombine -merge=Step ... in order to place the data from both planes on the same page. Also, be aware that if all correctors have the same name, using change_defined_values=1 on load_parameters will not produce the expected results. See the documentation for load_parameters for more details.

statistics — The (incomplete) name of an SDDS file to which statistical information about the trajectories (or orbits) and corrector strengths will be written. Recommended value: “%s.scor”.

bpm_output — The (incomplete) name of an SDDS file to which post-correction BPM errors will be written. The errors are the residual after correction, and include the effects of offsets (DX and DY), setpoints (XSETPOINT, YSETPOINT, and SETPOINT), and tilts (TILT). Recommended value: “%s.bpm”.

corrector_tweek[2] — The amount by which to change the correctors in order to compute correction coefficients for transport lines. [The word “tweak” is misspelled “tweek” in the code.] The default value, 1 mrad, may be too large for systems with small apertures. If you get an error message about “tracking failed for test particle,” try decreasing this value.

corrector_limit[2] — The maximum strength allowed for a corrector.

correction_fraction[2] — The fraction of the computed correction strength to actually use for any one iteration.

correction_accuracy[2] — The desired accuracy of the correction in terms of the RMS BPM values.

do_correction[2] — Flags to allow disabling correction in one or both planes (if set to zero).

remove_smallest_SVs, keep_largest_SVs, minimum_SV_ratio, auto_limit_SVs — These parameters control the elimination of singular vectors from the inverse response matrix, which can help deal with degeneracy in the correctors and reduce corrector strength. By default, the number of singular vectors is limited to the number of BPMs, which is a basic condition for stability; this can be defeated by setting auto_limit_SVs to 0 for the desired planes. Set remove_smallest_SVs to require removal of a given number of vectors with the smallest singular values; this is ignored if auto_limit_SVs is also requested and would remove more SVs. Set keep_largest_SVs to require keeping at most a given number of the largest SVs. Set minimum_SV_ratio to require removal of any vectors with singular values less than a given factor of the largest singular value.

Tikhonov_relative_alpha[2] , Tikhonov_n[2] — Used for invoking Tikhonov regularization of the singular value spectrum prior to creating the inverse matrices. If Tikhonov_relative_alpha is positive, the Tikhonov α parameter is set to the given value times the largest singular value for the plane in question. If Tikhonov_relative_alpha is zero or negative and Tikhonov_n is greater than 0, the Tikhonov α parameter is set to the singular value of the indicated vector; e.g., using 10 means α is equal to the 11^th largest singular value (indexing starts at zero). Can be used together with singular-value removal controls.

remove_pegged[2] — If nonzero, then for the plane in question pegged correctors will be removed from the correction matrix. This results in recomputation of the matrix, following which correction continues with the reduced set of correctors. The pegged corrector is left at its last value.

threading_divisor — In threading mode trajectory correction, each corrector is varied between 0 and ±θ_max, where θ_max is the strength limit. This parameter sets the number of steps to divide the corrector range into on the positive and negative sides. A smaller value results in faster execution but is less reliable.

threading_correctors — In threading mode trajectory correction, gives the number of correctors upstream of the loss point to use for threading the beam further through the system.

bpm_noise[2] — The BPM noise level.

bpm_noise_cutoff[2] — Cutoff values for the random distributions of BPM noise.

bpm_noise_distribution[2] — May be either “gaussian”, “uniform”, or “plus_or_minus”.

verbose — If non-zero, information about the correction is printed during computations.

fixed_length — Indicates that the closed orbit length should be kept the same as the design orbit length by changing the momentum offset of the beam.

fixed_length_matrix — Indicates that for fixed-length orbit correction, the fixed-length matrix should be computed and used. This will improve convergence but isn’t always needed.

n_xy_cycles — Number of times to alternate between correcting the x and y planes.

force_alternation — Forces alternation between x and y correction even if one plane appears to have converged.

minimum_cycles — The minimum number of x-y cycles to perform, even if the correction does not improve.

n_iterations — Number of iterations of the correction in each plane for each x/y cycle.

prezero_correctors — Flag indicating whether to set the correctors to zero before starting.

track_before_and_after — Flag indicating whether tracking should be done both before and after correction.

start_from_centroid — Flag indicating that correction should start from the beam centroid. For orbit correction, only the beam momentum centroid is relevant.

use_actual_beam — Flag indicating that correction should employ tracking of the beam distribution rather than a single particle. This is valid for trajectory correction only.

closed_orbit_accuracy — Target accuracy of closed orbit computation.

closed_orbit_accuracy_requirement — Required accuracy of closed orbit computation.

closed_orbit_iterations — Number of iterations of closed orbit computation.

closed_orbit_iteration_fraction — Fraction of change in closed orbit to use at each iteration.

closed_orbit_fraction_multiplier — Multiplier to apply to the iteration fraction if iteration is converging.

closed_orbit_multiplier_interval — Interval in number of iterations at which to adjust the iteration fraction.

closed_orbit_tracking_turns — If non-zero, the absolute value gives the number of turns to track for detemination of the closed orbit by averaging. This may be useful if the regular closed orbit algorithm complains about convergence issues. If less than zero, then only this method is used. If greater than zero, then regular orbit determination is tried first, and tracking is used as a fallback.

use_perturbed_matrix — If nonzero, specifies that prior to each correction elegant shall recompute the response matrix. This is useful if the lattice is changing significantly between corrections.

disable — If nonzero, the command is ignored.

use_response_from_computed_orbits — If nonzero, in-plane response matrices are computed using differences of closed orbits, which is slower but may be more accurate. For cross-plane matrices, this is always the case.

7.17 correct