correct

- type: setup command.
- sequence: must follow
`run_setup`

and precede beam definition (`bunched_beam`

or`sdds_beam`

). - function: set up for correction of the trajectory or closed orbit.

&correct STRING mode = "trajectory"; STRING method = "global"; STRING trajectory_output = NULL; STRING corrector_output = NULL; STRING statistics = NULL; double corrector_tweek[2] = {1e-3, 1e-3}; double corrector_limit[2] = {0, 0}; double correction_fraction[2] = {1, 1}; double correction_accuracy[2] = {1e-6, 1e-6}; long do_correction[2] = {1, 1}; long remove_smallest_SVs[2] = {0, 0}; long keep_largest_SVs[2] = {0, 0}; double minimum_SV_ratio[2] = {0, 0}; long auto_limit_SVs[2] = {1, 1}; long removed_pegged[2] = {0, 0}; long threading_divisor[2] = {100, 100}; long threading_correctors[2] = {-1, -1}; double bpm_noise[2] = {0, 0}; double bpm_noise_cutoff[2] = {1.0, 1.0}; STRING bpm_noise_distribution[2] = {"uniform", "uniform"}; long verbose = 1; long fixed_length = 0; long fixed_length_matrix = 0; long n_xy_cycles = 1; long minimum_cycles = 1; long n_iterations = 1; long prezero_correctors = 1; long track_before_and_after = 0; long start_from_centroid = 1; long use_actual_beam = 0; double closed_orbit_accuracy = 1e-12; long closed_orbit_iterations = 10; double closed_orbit_iteration_fraction = 1; long use_perturbed_matrix = 0; long disable = 0; long use_response_from_computed_orbits = 0; &end

In the case of array variables with dimension 2, the first entry is for the horizontal plane and the second is for the vertical plane.

`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'', or ``global''. ``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. 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''.`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.`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 , where 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.`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`

-- 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.`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.