7.22 correct_coupling

• 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 orbit correction and tune correction.
• function: minimize the vertical dispersion η_y and/or cross-plane response matrix at the selected BPMs by adjusting selected skew-quadrupole (or equivalent) knobs.
• 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 correction matrix computation. However, the recommended sequence is to compute the correction matrix using parallel resources with the compute_coupling_response_matrix, then use load_coupling_response_matrix when performing coupling correction, particularly when post-correction simulation does not require parallel resources. Correction itself will benefit from parallel resources when the cross-plane matrix is included.
• 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 coupling. Required unless a prior compute_coupling_response_matrix or load_coupling_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 another command); 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; otherwise elegant bombs with an explicit message.
• 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). Uniform scaling preserves the SVD direction at the cost of a shorter step.
• 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.
• bpm_name_pattern, bpm_type_pattern — Pattern lists for the observation BPMs; same semantics as in compute_coupling_response_matrix. Ignored when a preloaded matrix carries its own BPM list. Note that locations other than BPMs may be specified, though this may not make physical sense.
• n_iterations — Maximum number of correction iterations.
• convergence — Iteration stops early when the RMS η_y at the BPMs falls below this value (in meters).
• 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_coupling setup and reuse it for all iterations and all simulation steps. Cheap; accurate when the skew 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 near a coupling resonance, but ~ n_iter × n_skew extra twiss recomputations per step.

  If a compute_coupling_response_matrix or load_coupling_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 RMS η_y larger than at the start of the previous iteration, and the skew-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 — If nonzero (default), after each iteration’s step is applied the lattice is checked for stability; if the resulting twiss is unstable, the step is rolled back, the working SV-cutoff threshold is multiplied by auto_sv_threshold_factor, and the SVD is re-solved. This is repeated until the lattice is stable, the SV-cutoff drops every singular value (in which case no step is applied this iteration), or 20 retries have elapsed (in which case the step is rolled back and the iteration is treated as a no-op). The working threshold is local to each iteration; the next iteration starts again from the namelist svd_threshold. Set to 0 to disable the retry loop and accept the first-attempt step even when it leaves the lattice unstable.
• auto_sv_threshold_factor — Multiplicative bump applied to the working SV threshold on each retry inside auto_sv_threshold. Default 3 corresponds to roughly half a decade per retry.
• measurement_noise — RMS amplitude (in meters) of independent Gaussian measurement noise added to every η_y reading at every BPM. Each reading – the baseline measurement, the perturbed measurements used to build the response matrix, and the 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. Default 0 disables the noise.
• measurement_noise_cutoff — Cutoff on the Gaussian noise distribution, in units of the standard deviation measurement_noise. Ignored when measurement_noise is zero.
• 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").
• etay_file — The (incomplete) name of an SDDS file recording, for each iteration, the value of η_y at every BPM, with a parameter giving the iteration’s RMS η_y.
• 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_coupling_response_matrix.
• etay_weight — Weight applied to every η_y row of the residual vector before the weighted SVD solve. Default 1.0 reproduces the original η_y-only behavior. Set to 0 to disable the η_y channel entirely (useful when combined with the cross-plane channel).
• cross_response_weight — Weight applied to every cross-plane row of the residual vector. When both etay_weight and cross_response_weight are positive the two channels are combined in a single SVD solve, scaled by their respective weights.
• cross_h_steering, cross_v_steering — Comma-separated lists selecting the probe steering correctors used to measure the cross-plane orbit response. Each entry has the form TYPE/ITEM[/NAMEPATTERN], where TYPE is an element type (EHKICK, EVKICK, HKICK, VKICK, EKICKER, KQUAD, DQCOR, ...), ITEM is the parameter name of the steering knob on that type (KICK for the pure correctors; HKICK/VKICK for combined-function elements), and the optional NAMEPATTERN (defaulting to *) restricts the selection to elements whose names match. Example: "EHKICK/KICK, EKICKER/HKICK, KQUAD/HKICK/*H*". At least one of cross_h_steering / cross_v_steering must be supplied when cross_response_weight > 0.
• cross_x_bpm_name_pattern, cross_x_bpm_type_pattern — Pattern lists selecting BPMs that read the horizontal centroid (used for the V-corrector → x cross-plane block). Defaults include MONI and HMON.
• cross_y_bpm_name_pattern, cross_y_bpm_type_pattern — Pattern lists selecting BPMs that read the vertical centroid (used for the H-corrector → y cross-plane block). Defaults include MONI and VMON.
• cross_steering_kick — Magnitude (in radians) of the probe kick applied to each steering corrector when measuring the cross-plane orbit response. Must be small enough that the orbit response is in the linear regime, but large enough to be well above closed-orbit numerical noise. Default 10^-5.
• cross_measurement_noise — RMS amplitude (in meters) of Gaussian noise added to every cross-plane orbit reading. Cutoff is shared with measurement_noise_cutoff. Default 0 disables the noise.
• rms_log — The (incomplete) name of an SDDS file recording, per call to the correction routine, the per-iteration RMS residual broken down by channel. Each page has columns Iteration (0 = initial state; k+1 = state after iteration k), EtayRms (RMS η_y at the BPMs, unweighted, in meters), CrossRms (RMS cross-plane response, m per rad of probe kick; 0 when the channel is off), and WeightedRms (the actual optimization metric driven by the SVD). Parameters record the channel weights in effect.
• reset_correctors_each_step — If nonzero (the default), the skew-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 skew strengths. See the description under &correct for the wider behavior.
• verbosity — Higher values print more diagnostic information.