7.20 compute_coupling_response_matrix

• type: setup command.
• function: compute and save the response matrix (derivatives of η_y and/or cross-plane steering response with respect to correction parameters), for use with correct_coupling, so that subsequent runs can reuse the same matrix via load_coupling_response_matrix without rebuilding it.
• sequence: must follow run_setup and twiss_output so a periodic twiss solution is available when the response is computed.
• N.B.: can use parallel resources (Pelegant). The recommended sequence is to compute the correction matrix using parallel resources, then use load_coupling_response_matrix when performing coupling correction, particularly when post-correction simulation does not require parallel resources.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

• filename — The (incomplete) name of the SDDS file to which the η_y response matrix is written. The format includes the BPM/skew element names and occurrences plus the matrix entries, so load_coupling_response_matrix can reconstruct the entire knob/BPM inventory from this single file. Suggested value: “%s.ccrm”.
• cross_filename — The (incomplete) name of a second SDDS file to which the cross-plane response matrix is written. When supplied, the cross-plane channel is built alongside η_y during this command, using cross_h_steering, cross_v_steering, the cross-plane BPM patterns, and cross_steering_kick below. The file records the H/V probe-corrector inventory (name, occurrence, item), the cross-plane BPM inventory, the response coefficients, and the spec strings themselves as parameters so load_coupling_response_matrix can reconstruct everything without the user re-supplying it. Suggested value: “%s.cprm”.
• correction_elements — Whitespace/comma-separated list of wildcard patterns (one per family) selecting the elements that act as correction knobs in the matrix. Required. First-match-wins on element name; element types lacking the family’s items[k] parameter are silently skipped. Same semantics as on correct_coupling.
• items — Parallel whitespace-separated list of parameter names, one per family. Defaults to "K1" applied to every family. When the family items differ (e.g., items = "K1 KNL") the resulting matrix file records the per-knob item in its KnobParameter column so load_coupling_response_matrix reconstructs the per-knob inventory correctly.
• 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 selecting the beam position monitor (observation) points. Default bpm_type_pattern="MONI" picks all two-plane monitor elements. Note that the locations don’t have to be BPMs, but that makes the most sense.
• response_perturbation — Finite-difference step in item used to build each column of R (one-sided difference). Must be small enough to be in the linear regime of the dependence of η_y on the knob, but large enough to avoid numerical noise.
• measurement_noise, measurement_noise_cutoff — RMS amplitude (in meters) and Gaussian cutoff (in units of σ) of simulated independent noise added to every η_y reading taken while the matrix is being built. Each of the baseline and the n_knobs perturbed readings receives a fresh independent draw, matching how a noisy measurement on a real machine accumulates noise into the response matrix. Default 0 produces a noise-free (design) matrix. Same semantics as on correct_coupling.
• cross_h_steering, cross_v_steering, cross_x_bpm_*_pattern, cross_y_bpm_*_pattern, cross_steering_kick, cross_measurement_noise — Same semantics as on correct_coupling; see that command’s documentation. Only consulted when cross_filename is supplied; recorded verbatim into the cross-plane file so a subsequent load_coupling_response_matrix carries them through.
• verbosity — Higher values print more diagnostic information while the matrix is being built.

The values of correction_elements and items are recorded verbatim in the saved file as the CorrectionElements and CorrectionItems SDDS parameters (the joined whitespace-separated family lists), and the resolved per-knob inventory is recorded explicitly through the element names, occurrences, and the per-knob KnobParameter column. A subsequent correct_coupling (whether in this run or a later one via load_coupling_response_matrix) can therefore omit correction_elements / items entirely and inherit them from the file. If they are supplied on correct_coupling they must agree with the values recorded in the matrix file, or the run is aborted with an explicit diagnostic. The exclude, bpm_name_pattern, and bpm_type_pattern values are recorded implicitly through the resolved BPM and knob inventories. A previously-built response matrix can be downsized using the program sddsprocess to reduce the number of correction elements or observation locations.