7.23 correct_lattice

• type: setup command. Execution is deferred to the simulation steps loop (like chromaticity and correct_tunes), where the correction is performed once per simulation step between coupling correction and tune correction.
• function: drive the linear lattice functions β_x, β_y, and η_x at the measurement locations toward design values loaded from a user-supplied reference twiss file by adjusting selected normal-quadrupole knobs. This emulates the LOCO-style [15] β-beat and dispersion channels of real-machine optics correction, except that the LOCO lattice measurement is not simulated. Instead, we assume that measurements can be performed, with optional user-defined errors.
• sequence: must follow run_setup and twiss_output. A track command (or another action command that triggers the steps loop) must follow in order for the correction to actually run.
• N.B.: can use parallel resources (Pelegant) for response matrix computation. However, the recommended sequence is to compute the response matrix using parallel resources with compute_lattice_response_matrix, then use load_lattice_response_matrix when performing the correction, particularly when post-correction simulation does not require parallel resources. Correction itself does not benefit from parallel resources since it is based on direct lattice function calculations, not simulated LOCO [15].
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

• correction_elements — Whitespace/comma-separated list of wildcard patterns (one per family) selecting elements whose parameter will be adjusted to correct the lattice functions. Required unless a prior compute_lattice_response_matrix or load_lattice_response_matrix has already populated the knob inventory. Each element matched by some pattern that is not also matched by an exclude pattern becomes one knob (one SVD column unless joined into a bundle by bind_name_pattern); an element matched by multiple patterns is assigned to the first matching family (first-match-wins). Element types that do not expose the family’s items[k] parameter as a double are silently skipped.
• items — Parallel whitespace-separated list of parameter names, one per entry in correction_elements. Defaults to "K1" applied to every family when omitted. When supplied the token count must match correction_elements.
• lower_limits, upper_limits — Parallel space-separated signed bounds on the parameter value, one per family. Either list may be omitted to disable that side of the clamp for every knob; when supplied the token count must match correction_elements. After every iteration the SVD-derived step is uniformly scaled, if necessary, so that no knob ends up below its family’s lower_limits or above its family’s upper_limits value (signed; not magnitudes).
• exclude — Optional whitespace-separated list of patterns of element names to drop from the knob inventory even if they match one of the correction_elements entries.
• measurement_elements, measurement_types — Parallel wildcard lists selecting the elements at which the linear lattice functions are measured; same semantics as in compute_lattice_response_matrix (see that command’s documentation for the parallel-list selection rule and examples). Ignored when a preloaded matrix carries its own measurement-point list.
• bind_name_pattern — Optional comma- or space-separated list of patterns (with */? wildcards) defining families of knobs whose correction strengths should be bound together. Each entry of the list defines one family group: every knob whose element name matches that entry is placed in a single group and receives the same ΔK from the SVD solver, which is applied identically to every member of the group. Knobs whose names do not match any entry remain independent, one SVD column each. A knob matched by multiple entries is placed in the earliest-listed match (first match wins). Example: bind_name_pattern = "*Q1 *Q2 *Q3" collapses every element ending in Q1, every element ending in Q2, and every element ending in Q3 into three bound family knobs (rather than three groups per distinct name); this is the natural way to enforce family symmetry across a periodic ring whose elements have per-sector unique names (S1:Q1, S2:Q1, ..., S40:Q1). Precedence: if a prior compute_lattice_response_matrix or load_lattice_response_matrix already supplied a binding (the matrix file records the pattern as a BindNamePattern parameter), the value on correct_lattice overrides it when given and is inherited when omitted (NULL). With no preloaded binding and NULL here, every knob is independent.
• n_iterations — Maximum number of correction iterations per simulation step.
• convergence — Iteration stops early when the weighted RMS residual at the BPMs falls below this value.
• change_tolerance — Stagnation cutoff on relative iteration-to-iteration improvement. Iteration stops when the fractional drop (r_k-1 - r_k )∕r_k-1 in the weighted RMS residual is non-negative but smaller than this value. Default 0.1 stops when an iteration improved the residual by less than 10%. Set to 0 to disable the check and rely solely on convergence / n_iterations. A negative improvement (residual grew) is not treated as stagnation: the adaptive_step machinery at the top of the next iteration can roll back and shrink the step instead. Must be in [0,1).
• correction_fraction — Fraction of the SVD-derived step applied at each iteration. Values < 1 improve stability by avoiding overshoot. Must be in (0,1].
• use_perturbed_matrix — Controls how often the response matrix is (re)computed inside this command:
  • 0 (default): build the matrix once during correct_lattice setup and reuse it for all iterations and all simulation steps. Cheap; accurate when the knobs are weak and the optics change very little.
  • 1: rebuild the matrix at the start of each call to the per-step correction routine (once per simulation step).
  • > 1: rebuild before each iteration within a call. Most accurate far from the design, but ~ n_iter × n_knobs extra twiss recomputations per step.

  If a compute_lattice_response_matrix or load_lattice_response_matrix command has already provided a matrix, this control is honored on top of the preloaded matrix.

• adaptive_step — If nonzero, the effective correction_fraction is halved whenever an iteration leaves the weighted RMS residual larger than at the start of the previous iteration, and the knob values are simultaneously rolled back to the previous iteration’s start. The next iteration then tries a smaller step from the better operating point rather than compounding the bad step.
• response_perturbation — Finite-difference step used when this command builds the matrix itself (only relevant when use_perturbed_matrix>0 or when no preloaded matrix exists).
• svd_threshold — Singular values below svd_threshold times the largest singular value are dropped from the pseudo-inverse, regularizing the solution.
• n_singular_values — If > 0, additionally cap the number of retained singular values at this many of the largest.
• auto_sv_threshold, auto_sv_threshold_factor — Same rollback-and-retry-with-bumped-SV-cutoff behaviour as documented under &correct_coupling. Defaults: auto_sv_threshold = 1, auto_sv_threshold_factor = 3.0.
• beta_measurement_noise, eta_measurement_noise — RMS amplitude (fractional for beta functions, in meters for dispersion) of independent Gaussian measurement noise added to every β_x,y and η_x reading at every BPM, respectively. Each reading—baseline, response-matrix construction, and post-correction measurement—gets a fresh, independent draw, matching how a real machine accumulates measurement noise into the response matrix and into the residual at the noise floor of the BPM system. Defaults 0 disable the noise.
• measurement_noise_cutoff — Cutoff on the Gaussian noise distribution, in units of the standard deviation. Ignored when both noise amplitudes are zero.
• reference_file — Required. The name of an SDDS file (typically a twiss_output of the unperturbed design lattice) containing the target values of β_x, β_y, η_x at every BPM. Required columns are ElementName, betax, betay, etax; the optional column ElementOccurence is used when present to disambiguate repeated names. Every BPM matched by the current pattern lists must appear in the reference file, or the run is aborted.
• betax_weight, betay_weight, etax_weight — Per-channel weights applied to the corresponding residual rows (and to the corresponding response-matrix rows) before the SVD solve. This lets the user re-balance the channels so that they are comparable in the ℓ₂ sense (for example, weighting η_x heavily when the design η_x is small compared to the design β_x/β_y). All must be > 0.
• strength_log — The (incomplete) name of an SDDS file recording, for each iteration, the parameter changes applied to each knob. Columns include ElementName, ElementOccurence, s, ElementParameter, PreviousParameterValue, DeltaParameterValue, ParameterValue; the parameters include Iteration and a Stage string that is "uncorrected" for all but the actually-final iteration of the call (which is tagged "corrected").
• response_file — The (incomplete) name of an SDDS file recording the response matrix. This is in addition to any file written by a prior compute_lattice_response_matrix. Each row corresponds to one (BPM, knob) pair with all three observable derivatives (dBetaxDK1, dBetayDK1, dEtaxDK1).
• rms_log — The (incomplete) name of an SDDS file recording the per-iteration convergence history. Each call to the per-step correction routine appends a new page; rows within a page are indexed by Iteration, where 0 is the state before any correction is applied and k + 1 is the state after iteration k has been measured. Columns are Iteration (long), BetaxRms, BetayRms, EtaxRms (each the RMS of the corresponding observable’s residual , in meters, unweighted), and WeightedRms (the RMS of the weighted residual that the SVD solver actually drives down). The per-channel weights in effect for the page are also recorded as parameters BetaxWeight, BetayWeight, EtaxWeight.
• reset_correctors_each_step — If nonzero (the default), the normal-quadrupole knob strengths are snapshotted on the first vary_beamline tick after run_setup and reasserted at the start of every subsequent step, before errors and variations are added. Set to 0 to inherit the previous step’s converged knob strengths. See the description under &correct for the wider behavior.
• verbosity — Higher values print more diagnostic information.