Examples

Setup Commissioning 2022

Source on github.

In this example, the dodecapole corrections are calculated based on the measurements performed during the commissioning in 2022.

This data has been analyzed via the amplitude detuning analysis tool of omc3 and the resulting detuning values have been entered manually below to be used here.

You can find the data in https://gitlab.cern.ch/jdilly/lhc_amplitude_detuning_summary/ and Table 7.2 of [DillyThesis2024] . Some more information can be found in Chapter 7.4.1 of the same document. In particular, Table 7.3 contrains, in the “Commissioning 2022” rows, the results of the correction performed here. The values are slightly different, due to the use of the wrong tunes (.31, .32) in the simulation. As you can see from the plots, this does not change the trends: The resulting detuning values are depicted in Figure 7.4 (blue and orange values).

class examples.commissioning_2022.LHCSimParams

LHC simulation parameters for Commissioning in 2022.

class examples.commissioning_2022.MeasuredDetuning

Measured detuning values for different crossing schemes in 10^3 m^-1. Note: Keys are beam numbers, 2 and 4 can be used interchangeably (but consistently) here.

examples.commissioning_2022.check_correction(lhc_beams: dict[int, LHCBeam] | None = None)

Check the corrections via PTC.

examples.commissioning_2022.do_correction(lhc_beams: dict[int, LHCBeam] | None = None)

Calculate the dodecapole corrections for the LHC for the set targets.

Also calculates the individual contributions per corrector order and IP to the individual detuning terms.

examples.commissioning_2022.get_targets(lhc_beams: LHCBeams | None = None) → Sequence[Target]

Define the targets to be used.

Here:

Calculate the values for the dodecapole correctors in the LHC to compensate for the shift in measured detuning from the flat to the full crossing scheme (i.e. crossing active in IP1 and IP5). The optics used are only with crossing scheme in IP1 and IP5 active, assuming zero detuning at flat-orbit in the simulation.

Note

The detuning target should be the opposite of the measured detuning, such that the calculated correction compensates the measured detuning. This is why here it is “flat-full”.

examples.commissioning_2022.plot_corrector_strengths()

Plot the corrector strengths.

examples.commissioning_2022.plot_detuning_comparison()

Plot the measured detuning values. As well as the target (i.e. the detuning that should be compensated) and the reached detuning values by the correction.

examples.commissioning_2022.plot_simulation_comparison()

Plot the target detuning and how close the different simulation results are.

Note, that we here show the actual target. In the other examples we usually plot the detuning change from flat to full crossing, i.e. the inverse of the target here.

Shows:

• Target vs. PTC

• Target vs. calculated contributions from IP1 & IP5

• PTC vs. calculated contributions from IP1 & IP5

• Calculated contributions from IP1 & IP5 vs. IP1

examples.commissioning_2022.simulation()

Create LHC optics with the set crossing scheme.

Here:

IP1 and IP5 crossing active.

Setup MD3311 (2018)

Source on github.

Example for a filled template based on the 2018 measurements from commissioning and MD3311.

You can find the data in https://gitlab.cern.ch/jdilly/lhc_amplitude_detuning_summary/ and Table 7.2 of [DillyThesis2024] . The extensive simulations studies are discussed in Chapter 7.3 of the same document and partially recreated here.

class examples.md3311.CorrectionConstraints

Constraints to be used in the calculations.

class examples.md3311.LHCSimParams

LHC simulation parameters for 2018 MD3311.

class examples.md3311.MeasuredDetuning

Measured detuning values for different crossing schemes in 10^3 m^-1. Note: Keys are beam numbers, 2 and 4 can be used interchangeably (but consistently) here.

examples.md3311.check_correction(lhc_beams: dict[int, LHCBeam] | None = None)

Check the corrections via PTC. (Not used for plotting here).

examples.md3311.do_correction(lhc_beams: dict[int, LHCBeam] | None = None)

Calculate the dodecapole corrections for the LHC for the set targets.

Also calculates the individual contributions per corrector order and IP to the individual detuning terms.

examples.md3311.get_targets(lhc_beams: LHCBeams | None = None) → Sequence[Target]

Define the targets to be used.

Here:

Calculate the values for the dodecapole correctors in the LHC to compensate for the shift in measured detuning from the flat to the full crossing scheme (i.e. crossing active in IP1 and IP5) and from flat to the IP5 crossing scheme.

The defined targets are as in Scenarios D, G and approximately I in Figure 7.1 of [DillyThesis2024] .

Note

The detuning target should be the opposite of the measured detuning, such that the calculated correction compensates the measured detuning. This is why here it is “flat-full”.

examples.md3311.plot_corrector_strengths()

Plot the corrector strengths for the different targets.

examples.md3311.plot_detunig_compensation()

Plot the detuning to be compensated (inverse of target) and how close the different simulation results get.

This plot shows how well the expected detuning from the corrector powering will match global detuning as well as the individual contributions from the IPs, for each target individually.

You can see from the plots, that for the first target the global contribution is well matched, yet the individual IPs overshoot (but conpensate each other).

When trying to match the IPs we loose some global accuracy and get also a small amount of positive crossterm.

Constraining the crossterm to be negative, does not seem to be possible and hence the correction tries to keep it at zero, by compensating the contributions from IP1 and IP5 exactly. This comes at the cost of even worse accuracy for the other terms, globally and per IP.

examples.md3311.simulation()

Create LHC optics with the set crossing scheme.

Here:

IP1 and IP5 crossing active.

Setup for MD6863 (2022)

Source on github.

In this example, the dodecapole corrections are calculated based on the measurements performed during MD6863 in 2022.

This setup is the most complicated one of the examples given in this package, as we are not only calculating the correction, but also extract the data directly from the omc3 output directories. In fact, you can modify this example easily below, to even run the detuning analysis in omc3 first.

To achieve this automation, a naming scheme for the output-directories is assumed (see get_config_from_name()), that allows this script to sort the measurements into the different machine settings used, these are:

• With full crossing scheme in IP1 and IP5

• With flat crossing scheme in IP1 and IP5

• With positive crossing scheme in IP5

• With negative crossing scheme in IP5

The naming scheme is as follows:

b$BEAM_1_$XING1_5_$XING5_ampdet_$PLANE_b6_$CORR

Where:

• $BEAM is the beam number

• $XING1 and $XING5 are the IP1 and IP5 crossing schemes, respectively, in signed-integer murad or ‘off’ for flat

• $PLANE is the plane of the kick, either ‘H’ or ‘V’ or ‘X’ or ‘Y’

• $CORR is the whether there is b6 correction, either ‘in’ or ‘out’

The resulting data is then used to calculate the correction.

You can find the detunig as well in https://gitlab.cern.ch/jdilly/lhc_amplitude_detuning_summary/ and Table 7.2 of [DillyThesis2024] ; there are minor differences due to different analysis settings.

Some more information can be found in Chapter 7.4.1 of [DillyThesis2024] . In particular, Table 7.3 contains, in the “MD6863” rows, the results of the corrections performed here.

The resulting detuning values are depicted in Figures 7.5, 7.7 and 7.10.

class examples.md6863.LHCSimParams

LHC simulation parameters for 2022 MD6863.

class examples.md6863.Labels(*values)

Labels for the different measurement configurations (as enum to avoid typos).

class examples.md6863.MeasuredDetuning(flat: BeamDict[int, Detuning | DetuningMeasurement] | None = None, full: BeamDict[int, Detuning | DetuningMeasurement] | None = None, ip5p: BeamDict[int, Detuning | DetuningMeasurement] | None = None, ip5m: BeamDict[int, Detuning | DetuningMeasurement] | None = None, corrected: BeamDict[int, Detuning | DetuningMeasurement] | None = None)

Dataclass to hold the detuning data per scheme/configuration.

merge_first_order_crossterms() → MeasuredDetuning

Create average of the first order crossterm on all measurements.

class examples.md6863.MeasurementConfig(beam: int, xing: str, kick_plane: str, b6corr: bool)

Configuration for a measurement. Used to quickly organize the data from the md6863_data folder into the different “schemes” as defined in this file.

class examples.md6863.XingSchemes

Crossing schemes used in the measurements.

examples.md6863.check_correction(lhc_beams_per_setup: dict[Labels, dict[int, LHCBeam]] | None = None)

Check the corrections via PTC. (Not used for plotting here).

examples.md6863.convert_summary_to_detuning(summary: pd.DataFrame) → MeasuredDetuning

Convert the summary DataFrame to a dictionary of detuning data.

Parameters:

summary (pd.DataFrame) -- The summary DataFrame.

Returns:

A dictionary of detuning data per scheme and beam.

Return type:

MeasuredDetuning

examples.md6863.do_correction(lhc_beams_per_setup: dict[Labels, dict[int, LHCBeam]] | None = None)

Calculate the dodecapole corrections for the LHC for the set targets.

Also calculates the individual contributions per corrector order and IP to the individual detuning terms.

examples.md6863.extract_data_for_both_planes_and_beams(summary: pd.DataFrame, xing: str, b6corr: bool) → DetuningPerBeam

Extract the data for both planes and beams from the summary DataFrame.

Parameters:

• summary (pd.DataFrame) -- The summary DataFrame.

• xing (str) -- The xing scheme.

• b6corr (bool) -- Whether to apply the b6 correction.

Returns:

A dictionary of detuning data, merged for both planes, by beams as keys.

Return type:

DetuningPerBeam

examples.md6863.format_detuning_measurements(detuning: MeasuredDetuning) → str

Format the detuning data for printing.

Parameters:

detuning (MeasuredDetuning) -- The detuning data per scheme and beam.

examples.md6863.get_config_from_name(name: str) → MeasurementConfig

Create a MeasurementConfig from a measurement name, as used in the md6863_data folder. The MeasurementConfig contains the beam number, the kick plane and the xing scheme as well as the b6 correction and is only used to quickly organize the data into the different “schemes” as defined in this file.

Parameters:

name (str) -- The name of the measurement (i.e. the folder name).

Returns:

The measurement configuration.

Return type:

MeasurementConfig

examples.md6863.get_detuning_data(redo_analysis: bool = False) → MeasuredDetuning

Extract the detuning measurement values from the analysed data in the md6863_data folder.

The values are automatically corrected for the influence of forced oscillations (see [DillyAmplitudeDetuning2023]). This data is presented in Table 7.2 of [DillyThesis2024] ; the values might be slightly different due to different analysis settings, but should be within errorbar.

As the raw kick-data and BBQ data is also present in these folders, you can choose to re-analyse the data for detuning values by setting redo_analysis to True, otherwise simply the already analysed kick_ampdet_xy.tfs files are loaded. To change the analysis settings, you need to manually edit do_detuning_analysis().

Parameters:

redo_analysis (AnalysisOption, optional) -- Whether to re-analyse the data. Defaults to ‘never’.

examples.md6863.get_targets(lhc_beams_per_setup: dict[Labels, LHCBeams] | None = None) → Sequence[Target]

Define the targets to be used.

Here:

Calculate the values for the dodecapole correctors in the LHC to compensate for the shift in measured detuning from the flat to the full crossing scheme (i.e. crossing active in IP1 and IP5) and from flat to the IP5 crossing schemes.

The defined targets are as in Chapter 7.4.1 of [DillyThesis2024] , named there “w/o IP5” (here: “global”) and “w/ IP5” (here: “local_and_global”).

Note

The detuning target should be the opposite of the measured detuning, such that the calculated correction compensates the measured detuning. This is why here it is “flat-xing”.

examples.md6863.plot_corrector_strengths()

Plot the corrector strengths for the different targets. These are similar to the green and red values in Fig. 7.12 of [DillyThesis2024] .

examples.md6863.plot_measurement_comparison()

Plot the measured detuning values.

examples.md6863.plot_target_comparison()

Plot the detuning to be compensated (inverse of target) and how close the different simulation results get.

As we have two targets here, multiple plots are created:

• Comparison with measured detuning values (Fig. 7.5 in [DillyThesis2024]): During MD only the “global” target correction could be applied, as this correction was calculated while the IP5 measurements were still ongoing. Therefore we can only compare the “global” target here to measurements after correction.

• Comparison of individual contributions from IP1 and IP5 (Fig. 7.10 in [DillyThesis2024]): Here we can compare the calculated contributions from both corrections (i.e. the two targets) to the measured detuning differences from full crossing, the individual contributions from IP1 and IP5 and the contribution from IP5 dodecapoles only. In Fig. 7.10 of [DillyThesis2024] only the result from the “local_and_global” target is shown, as this is the more complete correction. This function however creates plots for both targets.

Note

We always show the detuning difference from flat to the respective crossing scheme, i.e. the expected detuning coming from the crossing scheme change.

• AmpDet from IP5+ = Ampdet at IP5 positive crossing - AmpDet at flat

• AmpDet from Full = AmpDet at full crossing - AmpDet at flat = AmpDet from IP1 + AmpDet from IP5

• AmpDet from IP1 = AmpDet from Full - AmpDet from IP5

• AmpDet from IP5 dodecapoles =

  0.5 * (AmpDet from IP5+ + AmpDet from IP5-) =

  - 0.5 * (AmpDet at IP5+ + AmpDet at IP5- - 2 * AmpDet at flat)

  (See Eqs. 7.6 - 7.8 in [DillyThesis2024])

examples.md6863.simulation() → dict[str, dict[int, LHCBeam]]

Create LHC all optics with their respective crossing schemes.

Here:

• Flat orbit.

• IP1 and IP5 crossing active.

• IP5 positive crossing only (IP1 flat).

• IP5 negative crossing only (IP1 flat).