7.21 compute_lattice_response_matrix

• type: setup command.
• function: compute and save the response matrix R_ij,k = ∂o_i,k)∕∂K_1,j used by correct_lattice, where o_i,k ∈{β_i,x,β_i,y,η_i,x} enumerates the three observables at measurement location i. The saved matrix can be reused via load_lattice_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 response matrix using parallel resources, then use load_lattice_response_matrix when performing lattice 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 response matrix is written. The format includes the measuremetn location and knob element names and occurrences, the element parameter that was perturbed, plus all three response columns (dBetaxDK1, dBetayDK1, dEtaxDK1), so load_lattice_response_matrix can reconstruct the entire location/knob inventory from this single file. Suggested value: “%s.lrm”.
• correction_elements — Whitespace/comma-separated list of wildcard patterns (one per family) selecting the elements that act as correction knobs in the matrix. Required. Same semantics as on correct_lattice: first-match-wins on element name; element types lacking the family’s items[k] parameter are silently skipped.
• 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 FSE") the resulting matrix file records the per-knob item in its KnobParameter column so load_lattice_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.
• bind_name_pattern — Optional family-binding specification recorded with the saved matrix. Same semantics as on correct_lattice (each entry collapses every matching knob into one family group; see the correct_lattice documentation for details). The intent here is to carry the binding alongside the matrix so a subsequent load_lattice_response_matrix + correct_lattice inherits it without restating the patterns. A correct_lattice that does set its own bind_name_pattern overrides what the matrix file carries.
• measurement_elements, measurement_types — Parallel whitespace/comma-separated wildcard lists specifying the elements at which the linear lattice functions are measured. Both lists must have the same token count; an element is selected if for some index i its name matches measurement_elements[i] and its type matches measurement_types[i]. measured via LOCO). For example, the default values are measurement_elements="* * *", measurement_types="MONI HMON VMON", which selects all monitor elements of any of the three types; whereas measurement_elements="*", measurement_types="*QUAD*" selects every quadrupole element.
• 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 β_x, β_y, and η_x on the knob, but large enough to avoid numerical noise.
• measurement_noise, measurement_noise_cutoff — RMS amplitude (fractional for β_x and β_y, in meters for η_x) and Gaussian cutoff (in units of σ) of simulated independent noise added to every observable 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.
• 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_lattice (whether in this run or a later one via load_lattice_response_matrix) can therefore omit correction_elements / items entirely and inherit them from the file. If they are supplied on correct_lattice they must agree with the values recorded in the matrix file, or the run is aborted with an explicit diagnostic. The exclude, measurement_elements, and measurement_types values are recorded implicitly through the resolved measurement-point and knob inventories.