Correction

Global Correction

Iterative Correction Scheme.

The response matrices \(R_{O}\) for the observables \(O\) (e.g. BBX, PHASEX, …) are loaded from a file and then the equation

(1)\[R_{O} \cdot \delta var = O_{meas} - O_{model}\]

is being solved for \(\delta var\) via a chosen method (at the moment only numpys pinv, which creates a pseudo-inverse via svd is used).

The response matrices are hereby merged into one matrix for all observables to solve for all \(\delta var\) at the same time.

To normalize the observables to another weights (W) can be applied.

Furthermore, an errorcut, specifying the maximum errorbar for a BPM to be used, and modelcut, specifying the maximum distance between measurement and model for a BPM to be used, can be defined. Data from BPMs outside of those cut-values will be discarded. These cuts are defined for each observable separately.

After each iteration the model variables are changed by \(-\delta var\) and the observables are recalculated by Mad-X. (1) is then solved again.

Input arguments are split into correction arguments and accelerator arguments. The former are listed below, the latter depend on the accelerator you want to use. Check Model to see which ones are needed.

Arguments:

--Required--

• meas_dir:

  Path to the directory containing the measurement files.

• output_dir:

  Path to the directory where to write the output files.

--Optional--

• beta_filename:

  Prefix of the beta file to use. E.g.: getkmodbeta

  default: beta_phase_

• errorcut (float):

  Reject BPMs whose error bar is higher than the corresponding input. Input in order of optics_params.

• fullresponse_path:

  Path to the fullresponse binary file. If not given, calculates the response analytically.

• max_iter (int):

  Maximum number of correction re-iterations to perform. A value of 0 means the correction is calculated once.

  default: 3

• method (str):

  Optimization method to use.

  choices: ('pinv', 'omp')

  default: pinv

• min_corrector_strength (float):

  Minimum (absolute) strength of correctors.

  default: 0.0

• modelcut (float):

  Reject BPMs whose deviation to the model is higher than the corresponding input. Input in order of optics_params.

• n_correctors (int):

  Maximum number of correctors to use. (Method: ‘omp’)

• optics_params (str):

  List of parameters to correct upon (e.g. BETX BETY)

  choices: ('PHASEX', 'PHASEY', 'BETX', 'BETY', 'DX', 'DY', 'NDX', 'Q', 'F1001R', 'F1001I', 'F1010R', 'F1010I')

  default: ['PHASEX', 'PHASEY', 'BETX', 'BETY', 'NDX', 'Q']

• output_filename:

  Identifier of the output files.

  default: changeparameters_iter

• svd_cut (float):

  Cutoff for small singular values of the pseudo inverse. (Method: ‘pinv’)Singular values smaller than rcond*largest_singular_value are set to zero

  default: 0.01

• update_response:

  Update the (analytical) response per iteration.

  action: store_true

• use_errorbars:

  Take into account the measured errorbars in the correction.

  action: store_true

• variable_categories:

  List of names of the variables classes to use.

  default: ['MQM', 'MQT', 'MQTL', 'MQY']

• weights (float):

  Weight to apply to each measured quantity. Input in order of optics_params.

Possible problems and notes (lmalina, 2020):

• error-based weights default? likely - but be careful with low tune errors vs svd cut in pseudoinverse

• manual creation of pd.DataFrame varslist, deltas? maybe tunes in tfs_pandas single value or a column?

• There should be some summation/renaming for iterations

• For two beam correction

• The two beams can be treated separately until the calculation of correction

• Values missing in the response (i.e. correctors of the other beam) shall be treated as zeros

• Missing a part that treats the output from LSA

omc3.global_correction.global_correction_entrypoint(opt: DotDict, accel_opt) → None

Do the global correction. Iteratively.

Response Creator

Provides a response generation wrapper. The response matrices can be either created by omc3.correction.response_madx or analytically via omc3.correction.response_twiss.

Input arguments are split into response creation arguments and accelerator arguments. The former are listed below, the latter depend on the accelerator you want to use. Check Model to see which ones are needed.

Arguments:

--Optional--

• outfile_path (str):

  Name of fullresponse file.

• creator (str):

  Create either with madx or analytically from twiss file.

  choices: ('madx', 'twiss')

  default: madx

• debug:

  Print debug information.

  action: store_true

• delta_k (float):

  Delta K1 to be applied to quads for sensitivity matrix (madx-only).

  default: 2e-05

• optics_params (str):

  List of parameters to correct upon (e.g. BBX BBY; twiss-only).

• variable_categories:

  List of the variables classes to use.

  default: ['MQM', 'MQT', 'MQTL', 'MQY']

omc3.response_creator.create_response_entrypoint(opt: DotDict, other_opt) → dict[str, DataFrame]

Entry point for creating pandas-based response matrices.

The response matrices can be either created by response_madx or TwissResponse.

Correction Test

In a MAD-X simulation (pre-calculated) corrections are applied to the (nominal) model and the difference between this new matched model and the nominal model are evaluated. These are the changes in the optics parameters as expected from the corrections and are later subtracted from the original model-measurement DELTA (see below). In new folders, either the given output folder or sub-folders, based on the name of the correction applied, the measurement data will be written out into the standard optics tfs-files with three additional columns:

DIFF-column:

Difference between the corrected and uncorrected model, i.e. the expected correction influence (with inverted sign). The beta-diff is beta-beating. The difference normalized-dispersion is also properly calculated.

EXP-column :

This column is calculated by subtracting the DIFF-column from the original DELTA-column (i.e. the difference between measurement and model) and is therefore the expected difference of model and measurement (i.e. DELTA-Measurement) after correction. For beta-beating this might be only approximate as it assumes, that the model used to calculate the DELTA-columns in the measurement and the nominal model used for the corrections are identical (if e.g. best-knowledge model is used, the expectation is only approximate).

ERREXP-column:

This is the error on the EXP-column. This is the measurement error in most cases, apart from in beta and normalized dispersion, where we account for beating and normalization.

There will also be the RMS values of the DIFF and EXP columns in the headers of the files. If error- and/or measurement cuts were given, additional RMS headers will be present, taking these cuts into account. This is the only use for the given cuts and optics parameters.

If plotting is activated, also plots for each correction (DIFFerence and EXPected) as well as a plot for all corrections (only EXPected) will be saved into the output folder(s).

Arguments:

--Required--

• corrections (PathOrStr):

  Paths to the correction files/directories to use. If files are given, these will all be applied as corrections at the same time. If folders are given, these are assumed to individually containing the correction files. See then also file_pattern.

• meas_dir (PathOrStr):

  Path to the directory containing the measurement files.

• output_dir (PathOrStr):

  Path to the directory where to write the output files. If the corrections input consists of multiple folders, their name will be used to sort the output data into subfolders.

--Optional--

• beta_filename:

  Prefix of the beta file to use. E.g.: beta_phase_

  default: beta_phase_

• change_marker:

  Changes marker for each line in the plot.

  action: store_true

• combine_by:

  Combine plots into one. Either files, planes (not separated into two axes) or both.

  choices: ['files', 'planes']

• errorbar_alpha (float):

  Alpha value for error bars

  default: 0.6

• errorcut (float):

  Reject BPMs whose error bar is higher than the corresponding input. Input in order of optics_params.

• file_pattern (str):

  Filepattern to use to find correction files in folders (as regex).

  default: ^changeparameters*?\.madx$

• individual_to_input:

  Save plots for the individual corrections into the corrections input folders. Otherwise they go with suffix into the output_folders.

  action: store_true

• ip_positions:

  Input to plot IP-Positions into the plots. Either ‘LHCB1’ or ‘LHCB2’ for LHC defaults, a dictionary of labels and positions or path to TFS file of a model.

• ip_search_pattern:

  In case your IPs have a weird name. Specify regex pattern.

  default: IP\d$

• lines_manual (DictAsString):

  List of manual lines to plot. Need to contain arguments for axvline, and may contain the additional keys “text” and “loc” which is one of [‘bottom’, ‘top’, ‘line bottom’, ‘line top’] and places the text at the given location.

  default: []

• manual_style (DictAsString):

  Additional style rcParameters which update the set of predefined ones.

  default: {}

• modelcut (float):

  Reject BPMs whose deviation to the model is higher than the corresponding input. Input in order of optics_params.

• ncol_legend (int):

  Number of bpm legend-columns. If < 1 no legend is shown.

  default: 3

• optics_params (str):

  List of parameters for which the cuts should be applied (e.g. BETX BETY)

  choices: ('PHASEX', 'PHASEY', 'BETX', 'BETY', 'NDX', 'Q', 'DX', 'DY', 'F1001R', 'F1001I', 'F1010R', 'F1010I')

• plot:

  Activate plotting.

  action: store_true

• plot_styles (str):

  Which plotting styles to use, either from plotting.styles.*.mplstyles or default mpl.

  default: ['standard', 'correction_test']

• share_xaxis:

  In case of multiple axes per figure, share x-axis.

  action: store_true

• show:

  Shows plots.

  action: store_true

• suppress_column_legend:

  Does not show column name in legend e.g. when combining by files (see also ncol_legend).

  action: store_true

• x_axis:

  Which parameter to use for the x axis.

  choices: ['location', 'phase-advance']

  default: location

• x_lim (MultiClass):

  Limits on the x axis (Tupel)

• y_lim (MultiClass):

  Limits on the y axis (Tupel)

omc3.check_corrections.correction_test_entrypoint(opt: DotDict, accel_opt) → None

Entrypoint function to test the given corrections.

Todo

Instead of writing everything out, it could return dictionaries of the TFSDataFrames and Figures. But I don’t see a usecase at the moment (jdilly 2023)