Main Modules

LHC Detuning Corrections

Caution

THIS FILE CANNOT BE RUN AS A SCRIPT !!!

It does contain the main simulation functions for the LHC scenarios, but to set the parameters needed (e.g. the measurement), see the examples.

This module contains the main function to run an LHC simulation with the given parameters via MAD-X and calculate the corrections based on the provided targets.

This module is similar to the main function to run and calculate the correction, but also allows to use different crossing-schemes. That is, you can specify a crossing scheme per measurement and the feed-down is calculated based on that scheme. As the simulation takes a while and multiple measurements might rely on the same crossing scheme, the optics are calculated and saved first. They can be then either read or passed to the correction function.

class ir_amplitude_detuning.lhc_detuning_corrections.CorrectionResults(name: str, series: pd.Series, dataframe: tfs.TfsDataFrame, madx: str)[source]

Class to store the results of a correction calculation.

name

The name of the correction target.

Type:: str

series

Series of the correction KNL values for each corrector.

Type:: pd.Series

dataframe

Same information as the Series, but in a DataFrame format, with the corrector-magnet names as index and the other data split into columns. See generate_knl_tfs().

Type:: tfs.TfsDataFrame

madx

The MAD-X code to apply the correction.

Type:: str

ir_amplitude_detuning.lhc_detuning_corrections.calculate_corrections(beams: Sequence[int], outputdir: Path, targets: Sequence[Target], method: Method = auto) → dict[str, CorrectionResults][source]

Calculate corrections based on targets and given correctors.

Parameters:

beams (Sequence[int]) -- The beam numbers to calculate corrections for.
outputdir (Path) -- The output directory.
targets (Sequence[Target]) -- The targets to calculate corrections for.
method (Method) -- The method to use for calculating the corrections (see ir_amplitude_detuning.detuning.calculations()).

Returns:

The results for each target.

Return type:

dict[str, CorrectionResults]

ir_amplitude_detuning.lhc_detuning_corrections.check_corrections_analytically(outputdir: Path, optics: TwissPerBeam, results: CorrectionResults) → dict[int, pd.DataFrame][source]

Calculate the effective detuning for each beam and write the results into a tfs file.

Parameters:

outputdir (Path) -- The output directory.
optics (TwissPerBeam) -- The machine optics.
results (CorrectionResults) -- The calculated correction results.

ir_amplitude_detuning.lhc_detuning_corrections.check_corrections_ptc(outputdir: Path, lhc_beams: dict[int, LHCBeam] | None = None, beams: Sequence[int] | None = None, xing: dict[str, dict] | None = None, optics: Path | None = None, year: int = 2018, tune_x: float = 62.28, tune_y: float = 60.31)[source]

Check the corrections via PTC.

This installs decapole corrector magnets and reads the corrections from the settings file. If lhc_beams are given, the output paths will be adapted and these used, otherwise new LHCBeam s will be set up.

PTC is run for the nominal machine as well as all settings.* files found in the output directory. The PTC output ids are parsed from the settings file names.

Parameters:

outputdir (Path) -- Output directory.
lhc_beams (dict[int, LHCBeam]) -- Pre-run LHC beams.
beams (Sequence[int]) -- Beams (if lhc_beams is None).
xing (dict[str, dict]) -- Crossing scheme (if lhc_beams is None).
optics (Path) -- Path to the optics file (if lhc_beams is None).
year (int) -- Year (if lhc_beams is None).
tune_x (float) -- Horizontal tune (if lhc_beams is None).
tune_y (float) -- Vertical tune (if lhc_beams is None).

ir_amplitude_detuning.lhc_detuning_corrections.create_optics(beams: Sequence[int], outputdir: Path, output_id: str = '', xing: dict[str, str | float] | None = None, optics: str | Path | None = None, year: int = 2018, tune_x: float = 62.28, tune_y: float = 60.31) → dict[int, LHCBeam][source]

Run MAD-X to create optics for all crossing-schemes.

The optics are saved in subfolders of the output directory.

Parameters:

beams (Sequence[int]) -- The beam numbers.
outputdir (Path) -- The output directory.
output_id (str, optional) -- The output id. Defaults to ‘’.
xing (dict[str, dict], optional) -- The crossing scheme. Defaults to None, which is set to the top-energy collision scheme below.
optics (str, optional) -- The optics. Defaults to “round3030”.
year (int, optional) -- The year. Defaults to 2018.
tune_x (float, optional) -- The horizontal tune. Defaults to 62.31.
tune_y (float, optional) -- The vertical tune. Defaults to 60.32.

Returns:

The LHC beams, i.e. a dictionary of LHCBeam objects.

Return type:

LHCBeams

ir_amplitude_detuning.lhc_detuning_corrections.detuning_tfs_out_with_and_without_errors(lhc_out: LHCBeam | FakeLHCBeam, id_: str, df: pd.DataFrame)[source]

Write out the detuning results, given as DataFrame into a tfs file. If the input DataFrame contains MeasureValue objects, the values and errors are extracted and two files are written: One with only the values and one with the values and errors.

Parameters:

lhc_out (LHCBeam | FakeLHCBeam) -- LHCBeam object to find the correct output path.
id (str) -- The identifier (e.g. target name) of the calculation.
df (pd.DataFrame) -- The calculated detuning terms.

ir_amplitude_detuning.lhc_detuning_corrections.generate_knl_tfs(values: pd.Series) → tfs.TfsDataFrame[source]

Generate a TFS dataframe with the corrector values.

Parameters:: values (pd.Series) -- The correction values. Assumes the index are Corrector objects.

ir_amplitude_detuning.lhc_detuning_corrections.generate_madx_command(values: pd.Series) → str[source]

Generate a MAD-X command to set the corrector values.

Parameters:: values (pd.Series) -- The correction values. Assumes the index are the Corrector objects.

ir_amplitude_detuning.lhc_detuning_corrections.get_label_outputdir(outputdir: Path, label: str, beam: int) → Path[source]

Get the outputdir sub-dir for a given label and beam.

Parameters:

outputdir (Path) -- The output directory.
label (str) -- The label for the sub-dir (e.g. a name for the optics)
beam (int) -- The beam number.

ir_amplitude_detuning.lhc_detuning_corrections.get_nominal_optics(beams: LHCBeams | Sequence[int], outputdir: Path | None = None, label: str = '') → TwissPerBeam[source]

Return previously generated nominal machine optics as a dictionary of TfsDataFrames per Beam, either directly from the LHCBeams objects (if given) or reading from the labeled sub-folder in the output-path.

Parameters:

beams (LHCBeams | Sequence[int]) -- The LHCBeams objects or a sequence of beam numbers.
outputdir (Path) -- The output directory.
label (str) -- The label for the sub-dir (e.g. a name for the optics)

ir_amplitude_detuning.lhc_detuning_corrections.get_optics(year: int) → str[source]: Return the path to the 30cm (round) optics file for the given year.