Simulation

LHC Simulation Class

Run a cpymad MAD-X simulation for the LHC optics (2018) without errors. In addition, extra functionality is added to install kcdx decapole correctors into the MCTX and assign powering for decapole and dodecapole circuits.

The class LHCBeam is setting up and running cpymad. This class can be useful for a lot of different studies, by extending it with extra functionality.

class ir_amplitude_detuning.simulation.lhc_simulation.FakeLHCBeam(beam: int, outputdir: Path)[source]: Mock of LHCBeam to use in calculations without the functions noticing. Used in the main-functions to load tfs-files without running MAD-X again.

class ir_amplitude_detuning.simulation.lhc_simulation.LHCBeam(beam: int, outputdir: Path, xing: dict, optics: str | Path | None, year: int = 2018, tune_x: float = 62.28, tune_y: float = 60.31, chroma: float = 3, emittance: float = 7.29767146889e-09, n_particles: float = 10000000000.0)[source]

Object containing all the information about the machine setup and performing the MAD-X commands to run the simulation.

check_kctx_limits()[source]: Check the corrector kctx limits.

closest_tune_approach(df: TfsDataFrame | None = None)[source]

Calculate and print out the closest tune approach from the twiss DataFrame given. If no frame is given, it gets the current twiss.

Parameters:: df (TfsDataFrame) -- Twiss DataFrame.

correct_coupling()[source]: Correct the current coupling in the machine.

get_ampdet(output_id: str) → TfsDataFrame[source]

Write out current amplitude detuning via PTC.

Parameters:: output_id (str) -- ID to use in the output (see output_path). If not given, no output is written.
Returns:: Containing the PTC output data.
Return type:: TfsDataFrame

get_last_twiss(index_regex='BPM|M|IP') → TfsDataFrame[source]

Returns the twiss table of the last calculated twiss.

Parameters:: index_regex (str) -- Filter DataFrame index (NAME) by this pattern.
Returns:: DataFrame containing the optics.
Return type:: TfsDataFrame

get_other_beam()[source]: Return the respective other beam number.

get_twiss(output_id=None, index_regex='BPM|M|IP', **kwargs) → TfsDataFrame[source]

Uses the twiss command to get the current optics in the machine as TfsDataFrame.

Parameters:

output_id (str) -- ID to use in the output (see output_path). If not given, no output is written.
index_regex (str) -- Filter DataFrame index (NAME) by this pattern.

Returns:

DataFrame containing the optics.

Return type:

TfsDataFrame

install_circuits_into_mctx()[source]

Installs kcdx and (and reinstalls kctx) into the Dodecapole Correctors.

This allows for decapole and dodecapole correction with the MCTX magnets for test purposes.

log_orbit()[source]: Log the current orbit.

match_tune()[source]: Match the machine to the preconfigured tunes.

output_path(type_: str, output_id: str, dir_: Path | None = None, suffix: str = '.tfs') → Path[source]

Returns the output path for standardized tfs names in the default output directory.

Parameters:

type (str) -- Type of the output file (e.g. ‘twiss’, ‘errors’, ‘ampdet’)
output_id (str) -- Name of the output (e.g. ‘nominal’)
dir (Path) -- Override default directory.
suffix (str) -- suffix of the output file.

Returns:

Path to the output file

Return type:

Path

reinstate_loggers()[source]: Set the saved logger handlers to the current logger.

reset_detuning_circuits()[source]: Reset all kcdx and kctx circuits (to zero).

save_nominal(id_='nominal')[source]: Save nominal machine into Dataclass slots and (if id_ is not None) output to tfs.

setup_machine()[source]: Nominal machine setup function. Initialized the beam and applies optics, crossing.

write_tfs(df: TfsDataFrame, type_: str, output_id: str)[source]

Write the given TfsDataFrame with the standardized name (see output_path) and the index NAME.

Parameters:

df (TfsDataFrame) -- DataFrame to write.
type (str) -- Type of the output file (see output_path)
output_id (str) -- Name of the output (see output_path)

class ir_amplitude_detuning.simulation.lhc_simulation.LHCCorrectors[source]

Container for the corrector definitions used in the LHC.

As the LHC does not have decapoe correctors, all correctors are installed into the MCTX and powered via kcdx3 and kctx3 circuits. The decapole correctors are hence only used for simulation purposes. For HiLumi, which has more actual IR correctors that can be used, you will need to adapt the simulation and correctors a bit, but it should be straightforward.

Note that in the correction algorithm only the normal-oriented fields are implemented. You will need to add a5 if you are planning on using this corrector.

The length is set to 0.615 m, which is the length of the MCTs. The pattern is used to find the correctors in the MAD-X sequence.

ir_amplitude_detuning.simulation.lhc_simulation.drop_allzero_columns(df: TfsDataFrame, keep: Sequence = ()) → TfsDataFrame[source]

Drop columns that contain only zeros, to save harddrive space.

Parameters:

df (TfsDataFrame) -- DataFrame with all data
keep (Sequence) -- Columns to keep even if all zero.

Returns:

DataFrame with only non-zero columns.

Return type:

TfsDataFrame

ir_amplitude_detuning.simulation.lhc_simulation.pathstr(*args: str) → str[source]

Wrapper to get the path (as string! Because MADX wants strings) with the base acc-models-lhc.

Parameters:: args (str) -- Path parts to attach to the base.
Returns:: Full path as string.
Return type:: str

Simulation Results Loaders

Load and sort the simulated detuning data into handy datastructures.

ir_amplitude_detuning.simulation.results_loader.convert_dataframe_to_dict(df: DataFrame) → dict[str, Detuning | DetuningMeasurement][source]

Convert a dataframe containing detuning-term columns into a dictionary of Detuning objects, sorted by the index of the dataframe.

Parameters:: df (pd.Dataframe) -- Dataframe to be converted.

ir_amplitude_detuning.simulation.results_loader.get_calculated_detuning_for_field(folder: Path, beam: int, id_: str, field: Iterable[FieldComponent] | FieldComponent | str, errors: bool = False) → dict[str, Detuning][source]

Load and sort the detuning data for a given set of fields.

Parameters:

folder (Path) -- The folder containing the data.
beam (int) -- The beam number.
id (str) -- The id of the data (target name).
field (Iterable[FieldComponent] | FieldComponent) -- The field(s) to load. If multiple are given they will be converted into a single string, e.g. “b5b6”, as this is how the data should be stored in the dataframe.
errors (bool, optional) -- Whether to load the errors or not.

Returns:

The Detuning data in a dictionary, sorted by the different IPs in the file.

Return type:

dict[str, Detuning]

ir_amplitude_detuning.simulation.results_loader.get_calculated_detuning_for_ip(folder: Path, beam: int, id_: str, ip: str, errors: bool = False) → dict[str, Detuning][source]

Load and sort the detuning data for a given IP.

Parameters:

folder (Path) -- The folder containing the data.
beam (int) -- The beam number.
id (str) -- The id of the data (target name).
ip (str) -- The IP(s) to load. If multiple can be given as a single string, e.g. “15”, as this is how the data should be stored in the dataframe.
errors (bool, optional) -- Whether to load the errors or not.

Returns:

The detuning data for the given IP in a dictionary, sorted by the different fields in the file.

Return type:

pd.DataFrame

ir_amplitude_detuning.simulation.results_loader.get_detuning_change_ptc(folder: Path, ids: Iterable[str], beams: Iterable[int])[source]

Load the detuning data from PTC simulations for the given set of ids (target names) and return their change with respect to the nominal values.

Parameters:

folder (Path) -- The folder containing the data.
ids (str) -- The ids of the data (target names).
beams (int) -- The beam numbers.

ir_amplitude_detuning.simulation.results_loader.get_detuning_from_ptc_output(df: pd.DataFrame, terms: Sequence[str] = (X10, X01, Y10, Y01, X20, X11, X02, Y20, Y11, Y02)) → Detuning[source]

Convert PTC output to a Series.

Parameters:

df (DataFrame) -- DataFrame as given by PTC.
terms (Sequence[str]) -- Terms to extract

ir_amplitude_detuning.simulation.results_loader.load_ptc_detuning(folder: Path, beam: int, id_: str) → Detuning[source]

Load detuning data from PTC output for the given beam and target.

Parameters:

folder (Path) -- The folder containing the data.
beam (int) -- The beam number.
id (str) -- The id of the data (target name).

ir_amplitude_detuning.simulation.results_loader.load_simulation_output_tfs(folder: Path, type_: str, beam: int, id_: str) → tfs.TfsDataFrame[source]

Load simluation output in tfs form. Assumes the simulation writes in the following pattern: {type}.{anything}.b{beam}.{id}.tfs Loads the first matching file it finds.

Parameters:

folder (Path) -- The folder containing the data.
type (str) -- The type of data to load (e.g. ampet, settings).
beam (int) -- The beam number.
id (str) -- The id of the data (e.g. target name).