Model

Manager

This module provides high-level functions to manage most functionality of model. It contains entrypoint wrappers to get accelerator classes or their instances.

omc3.model.manager.get_accelerator(opt, other_opt) → Accelerator

Returns (opt.accel, help_requested):

opt.accel is the Accelerator instance of the desired accelerator, as given at the commandline.

omc3.model.manager.get_accelerator_class(opt, other_opt) → type[Accelerator]

Returns only the accelerator-class (non-instanciated). Only opt.accel is needed.

omc3.model.manager.get_parsed_opt(opt, other_opt) → dict

Get all accelerator related options as a dict.

Constants

This module provides high-level functions to manage most functionality of model. Specific constants to be used in model, to help with consistency.

class omc3.model.constants.Fetcher(*values)

Accelerator

This module provides high-level classes to define most functionality of model.accelerators. It contains entrypoint the parent Accelerator class as well as other support classes.

class omc3.model.accelerators.accelerator.AccElementTypes

Defines the strings for the element types BPMS, MAGNETS and ARC_BPMS.

class omc3.model.accelerators.accelerator.Accelerator(opt)

Abstract class to serve as an interface to implement the rest of the accelerators.

find_modifier(modifier: Path | str)

Try to find a modifier file, which might be given only by its name. By default this is looking for full-path, model-dir and in the acc-models-path, but should probably be overwritten by the accelerator sub-classes.

classmethod get_dir() → Path

Default directory for accelerator. Should be overwritten if more specific.

classmethod get_element_types_mask(list_of_elements: list[str], types) → np.ndarray

Returns a boolean mask for elements in list_of_elements that belong to any of the specified types. Needs to handle: bpm, magnet, arc_bpm (see AccElementTypes)

Parameters:

• list_of_elements -- list of elements.

• types -- the kinds of elements to look for.

Returns:

A boolean array of elements of specified kinds.

get_exciter_bpm(plane: str, commonbpms: list[str])

Returns the BPM next to the exciter. The Accelerator instance knows already which excitation method is used.

Parameters:

• plane -- X or Y.

• commonbpms -- list of common BPMs (e.g. intersection of input BPMs.

Returns:

tuple(int, str), str)`

Return type:

`((index, bpm_name), exciter_name)

classmethod get_file(filename: str) → Path

Default location for accelerator files. Should be overwritten if more specific.

classmethod get_variables(frm=None, to=None, classes=None)

Gets the variables with elements in the given range and the given classes. None means everything.

verify_object()

Verifies that this instance of an Accelerator is properly instantiated.

exception omc3.model.accelerators.accelerator.AcceleratorDefinitionError

Raised when an Accelerator instance is wrongly used, for example by calling a method that should have been overwritten.

omc3.model.accelerators.accelerator.find_called_files_with_tag(madx_file: Path, model_dir: Path, tag: str) → list[Path] | None

Parse lines that call a file and are tagged with the given tag and return a list of paths to these files.

This is mainly used to find the modifier tag in lines and return called file in these lines.

The modifier tag is used by the model creator to mark which line defines modifiers see e.g. get_base_madx_script() in lhc.py

An example for a match to the regex: call, file = ‘modifiers.madx’; !@modifiers.

ESRF

Accelerator-Class for the ESRF machine.

Model Creation Keyword Args:

--Optional--

• dpp (float):

  Deltap/p to use.

  default: 0.0

• driven_excitation (str):

  Denotes driven excitation by AC-dipole (acd) or by ADT (adt)

  choices: ('acd', 'adt')

• drv_tunes (float):

  Driven tunes without integer part.

• energy (float):

  Energy in GeV.

• model_dir (str):

  Path to model directory; loads tunes and excitation from model!

• modifiers (str):

  Path to the optics file to use (modifiers file).

• nat_tunes (float):

  Natural tunes without integer part.

• xing:

  If True, x-ing angles will be applied to model

  action: store_true

class omc3.model.accelerators.esrf.Esrf(*args, **kwargs)

class omc3.model.accelerators.generic.Generic(*args, **kwargs)

LHC

Accelerator-Class for the LHC collider.

Model Creation Keyword Args:

--Required--

• beam (int):

  Beam to use.

  choices: (1, 2)

• year (str):

  Year of the optics (or hllhc1.3).

  choices: ('2012', '2015', '2016', '2017', '2018', '2022', 'hllhc1.3')

--Optional--

• ats:

  Marks ATS optics

  action: store_true

• dpp (float):

  Delta p/p to use.

  default: 0.0

• driven_excitation (str):

  Denotes driven excitation by AC-dipole (acd) or by ADT (adt)

  choices: ('acd', 'adt')

• drv_tunes (float):

  Driven tunes without integer part.

• energy (float):

  Energy in GeV.

• model_dir (str):

  Path to model directory; loads tunes and excitation from model!

• modifiers (str):

  Path to the optics file to use (modifiers file).

• nat_tunes (float):

  Natural tunes without integer part.

• xing:

  If True, x-ing angles will be applied to model

  action: store_true

class omc3.model.accelerators.lhc.Lhc(*args, **kwargs)

Accelerator class for the Large Hadron Collider.

find_modifier(modifier: Path | str)

Try to find a modifier file, which might be given only by its name. This is looking for full-path, model-dir and in the acc-models-path’s optics-dir.,

get_exciter_bpm(plane: str, commonbpms: list[str]) → tuple[str, str]

Returns the name of the BPM closest to the exciter (i.e. ADT or AC-Dipole) as well as the name of the exciter element.

get_ips() → Iterator[tuple[str]]

Returns an iterable with this accelerator’s IPs.

Returns:

(ip name, left BPM name, right BPM name)

Return type:

An iterator returning tuples with

get_variables(frm: float | None = None, to: float | None = None, classes: Iterable[str] | None = None)

Gets the variables with elements in the given range and the given classes. None means everything.

sort_variables_by_location(variables: Iterable[str], frm: float | None = None, to: str | None = None) → list[str]

Sorts the variables by location and filters them between frm and to. If frm is larger than to it loops back around to the start the accelerator. This is a useful function for the LHC that’s why it is “public” but it is not part of the Accelerator-Class Interface.

Parameters:

• variables (Iterable) -- Names of variables to sort

• frm (float) -- S-position to filter from

• to (float) -- S-position to filter to

verify_object() → None

Verifies if everything is defined which should be defined. Will Raise an AcceleratorDefinitionError if one of the checks is invalid.

PS

Accelerator-Class for the PS machine.

Model Creation Keyword Args:

--Optional--

• dpp (float):

  Deltap/p to use.

  default: 0.0

• driven_excitation (str):

  Denotes driven excitation by AC-dipole (acd) or by ADT (adt)

  choices: ('acd', 'adt')

• drv_tunes (float):

  Driven tunes without integer part.

• energy (float):

  Energy in GeV.

• model_dir (str):

  Path to model directory; loads tunes and excitation from model!

• modifiers (str):

  Path to the optics file to use (modifiers file).

• nat_tunes (float):

  Natural tunes without integer part.

• xing:

  If True, x-ing angles will be applied to model

  action: store_true

class omc3.model.accelerators.ps.Ps(*args, **kwargs)

Parent Class for PS-types.

get_exciter_bpm(plane, bpms)

Returns the BPM next to the exciter. The Accelerator instance knows already which excitation method is used.

Parameters:

• plane -- X or Y.

• commonbpms -- list of common BPMs (e.g. intersection of input BPMs.

Returns:

tuple(int, str), str)`

Return type:

`((index, bpm_name), exciter_name)

get_file(filename: str) → Path

Get filepaths for PS files.

verify_object()

Verifies that this instance of an Accelerator is properly instantiated.

PS Booster

Accelerator-Class for the PSB machine.

Model Creation Keyword Args:

--Optional--

• dpp (float):

  Deltap/p to use.

  default: 0.0

• driven_excitation (str):

  Denotes driven excitation by AC-dipole (acd) or by ADT (adt)

  choices: ('acd', 'adt')

• drv_tunes (float):

  Driven tunes without integer part.

• energy (float):

  Energy in GeV.

• model_dir (str):

  Path to model directory; loads tunes and excitation from model!

• modifiers (str):

  Path to the optics file to use (modifiers file).

• nat_tunes (float):

  Natural tunes without integer part.

• ring (int):

  Ring to use.

  choices: (1, 2, 3, 4)

• xing:

  If True, x-ing angles will be applied to model

  action: store_true

class omc3.model.accelerators.psbooster.Psbooster(*args, **kwargs)

Parent Class for Psbooster-types.

get_exciter_bpm(plane, bpms)

Returns the BPM next to the exciter. The Accelerator instance knows already which excitation method is used.

Parameters:

• plane -- X or Y.

• commonbpms -- list of common BPMs (e.g. intersection of input BPMs.

Returns:

tuple(int, str), str)`

Return type:

`((index, bpm_name), exciter_name)

verify_object()

Verifies that this instance of an Accelerator is properly instantiated.

SuperKEKB

Accelerator-Class for the SuperKEKB machine.

Model Creation Keyword Args:

--Required--

• ring (str):

  HER or LER ring.

  choices: ('ler', 'her')

--Optional--

• dpp (float):

  Deltap/p to use.

  default: 0.0

• driven_excitation (str):

  Denotes driven excitation by AC-dipole (acd) or by ADT (adt)

  choices: ('acd', 'adt')

• drv_tunes (float):

  Driven tunes without integer part.

• energy (float):

  Energy in GeV.

• model_dir (str):

  Path to model directory; loads tunes and excitation from model!

• modifiers (str):

  Path to the optics file to use (modifiers file).

• nat_tunes (float):

  Natural tunes without integer part.

• xing:

  If True, x-ing angles will be applied to model

  action: store_true

class omc3.model.accelerators.skekb.SKekB(*args, **kwargs)

KEK’s SuperKEKB accelerator.

verify_object()

Verifies that this instance of an Accelerator is properly instantiated.

SPS

class omc3.model.accelerators.sps.Sps(*args, **kwargs)

SPS accelerator.

find_modifier(modifier: Path | str)

Try to find a modifier file, which might be given only by its name. This is looking for full-path, model-dir and in the acc-models-path’s strength-dir.,

get_variables(frm: float | None = None, to: float | None = None, classes: Iterable[str] | None = None)

Gets the variables with elements in the given range and the given classes. None means everything.

Iota

Accelerator-Class for the Iota machine.

Model Creation Keyword Args:

--Optional--

• dpp (float):

  Deltap/p to use.

  default: 0.0

• driven_excitation (str):

  Denotes driven excitation by AC-dipole (acd) or by ADT (adt)

  choices: ('acd', 'adt')

• drv_tunes (float):

  Driven tunes without integer part.

• energy (float):

  Energy in GeV.

• model_dir (str):

  Path to model directory; loads tunes and excitation from model!

• modifiers (str):

  Path to the optics file to use (modifiers file).

• nat_tunes (float):

  Natural tunes without integer part.

• particle (str):

  Particle type.

  choices: ('p', 'e')

• xing:

  If True, x-ing angles will be applied to model

  action: store_true

class omc3.model.accelerators.iota.Iota(*args, **kwargs)

classmethod verify_object()

Verifies that this instance of an Accelerator is properly instantiated.

PETRA

Accelerator-Class for the PETRA machine. Model creation not implemented yet.

class omc3.model.accelerators.petra.Petra(opt)

get_exciter_bpm(plane, commonbpms)

Returns the BPM next to the exciter. The Accelerator instance knows already which excitation method is used.

Parameters:

• plane -- X or Y.

• commonbpms -- list of common BPMs (e.g. intersection of input BPMs.

Returns:

tuple(int, str), str)`

Return type:

`((index, bpm_name), exciter_name)

verify_object()

Verifies that this instance of an Accelerator is properly instantiated.

Model Creator Manager

A manager that helps you find the optimal model creator of your favorite accelerator.

class omc3.model.model_creators.manager.CreatorType(*values)

omc3.model.model_creators.manager.get_model_creator_class(accel: type[Accelerator] | Accelerator | str, creator_type: CreatorType) → type[ModelCreator]

Returns the model creator for the given accelerator and creator type. This function will raise a ValueError if the accelerator or creator type is unknown.

Parameters:

• accel -- The accelerator to use, can be class, instance or name.

• creator_type -- The type of model creator to use.

Returns:

The model creator class.

LHC Model Creator

This module provides convenience functions for model creation of the LHC.

class omc3.model.model_creators.lhc_model_creator.LhcBestKnowledgeCreator(accel: Lhc, *args, **kwargs)

get_base_madx_script() → str

Returns the base LHC madx script.

get_madx_script() → str

Get madx script to create a LHC model.

prepare_options(opt) → bool

Use the fetcher to list choices if requested.

prepare_run()

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

class omc3.model.model_creators.lhc_model_creator.LhcCorrectionModelCreator(accel: Lhc, twiss_out: Path | str, corr_files: Sequence[Path | str], update_dpp: bool = False)

Creates an updated model from multiple changeparameters inputs (used in iterative correction).

property files_to_check: list[str]

Returns the list of files to check after model creation, should only be used in post_run. Override in subclass if you need to check a different set of files.

get_madx_script() → str

Get the madx script for the correction model creator, which updates the model after correcion.

prepare_run() → None

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

class omc3.model.model_creators.lhc_model_creator.LhcModelCreator(accel: Lhc, *args, **kwargs)

get_base_madx_script() → str

Returns the base LHC madx script.

get_madx_script() → str

Get madx script to create a LHC model.

get_update_deltap_script(deltap: float | str) → str

Update the dpp in the LHC.

Parameters:

deltap (float | str) -- The dpp to update the LHC to.

prepare_options(opt)

Use the fetcher to list choices if requested.

prepare_run() → None

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

class omc3.model.model_creators.lhc_model_creator.LhcSegmentCreator(accel: Accelerator, segment: Segment, measurables: Iterable[Propagable], corrections: MADXInputType = None, *args, **kwargs)

property files_to_check: list[str]

Returns the list of files to check after model creation, should only be used in post_run. Override in subclass if you need to check a different set of files.

get_madx_script() → str

Get madx script to create a LHC model.

PS Model Creator

This module provides convenience functions for model creation of the PS.

class omc3.model.model_creators.ps_model_creator.PsModelCreator(accel: Accelerator, logfile: Path = None, acc_models_path: Path = None)

get_base_madx_script() → str

Returns the MAD-X script used to set-up the basic accelerator in MAD-X, without actually creating the twiss-output, as some modifications to the accelerator may come afterwards (depending on which model-creator is calling this).

get_madx_script() → str

Returns the MAD-X script used to create the model (directory).

prepare_run() → None

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

PS Booster Model Creator

This module provides convenience functions for model creation of the PSB.

class omc3.model.model_creators.psbooster_model_creator.PsboosterModelCreator(accel: Accelerator, logfile: Path = None, acc_models_path: Path = None)

get_base_madx_script() → str

Returns the MAD-X script used to set-up the basic accelerator in MAD-X, without actually creating the twiss-output, as some modifications to the accelerator may come afterwards (depending on which model-creator is calling this).

get_madx_script() → str

Returns the MAD-X script used to create the model (directory).

prepare_run()

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

SPS Model Creator

class omc3.model.model_creators.sps_model_creator.SpsCorrectionModelCreator(accel: Accelerator, twiss_out: Path | str, corr_files: Sequence[Path | str], update_dpp: bool = False)

Creates an updated model from multiple changeparameters inputs (used in iterative correction).

prepare_run() → None

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

class omc3.model.model_creators.sps_model_creator.SpsModelCreator(accel: Accelerator, logfile: Path = None, acc_models_path: Path = None)

get_base_madx_script() → str

Returns the MAD-X script used to set-up the basic accelerator in MAD-X, without actually creating the twiss-output, as some modifications to the accelerator may come afterwards (depending on which model-creator is calling this).

get_madx_script() → str

Returns the MAD-X script used to create the model (directory).

prepare_options(opt) → bool

Use the fetcher to list choices if requested.

class omc3.model.model_creators.sps_model_creator.SpsSegmentCreator(accel: Accelerator, segment: Segment, measurables: Iterable[Propagable], corrections: MADXInputType = None, *args, **kwargs)

Abstract Model Creator Class

This module provides the template for all model creators.

class omc3.model.model_creators.abstract_model_creator.CorrectionModelCreator(accel: Accelerator, twiss_out: Path | str, corr_files: Sequence[Path | str], update_dpp: bool = False)

property files_to_check: list[str]

Returns the list of files to check after model creation, should only be used in post_run. Override in subclass if you need to check a different set of files.

get_madx_script() → str

Get the madx script for the correction model creator, which updates the model after correcion.

This is a basic implementation which does not update the dpp, but should work for generic accelerators.

class omc3.model.model_creators.abstract_model_creator.ModelCreator(accel: Accelerator, logfile: Path = None, acc_models_path: Path = None)

Abstract class for the implementation of a model creator. All mandatory methods and convenience functions are defined here.

property files_to_check: list[str]

Returns the list of files to check after model creation, should only be used in post_run. Override in subclass if you need to check a different set of files.

full_run()

Does the full run: preparation, running madx, post_run.

abstractmethod get_base_madx_script() → str

Returns the MAD-X script used to set-up the basic accelerator in MAD-X, without actually creating the twiss-output, as some modifications to the accelerator may come afterwards (depending on which model-creator is calling this).

abstractmethod get_madx_script() → str

Returns the MAD-X script used to create the model (directory).

get_update_deltap_script(deltap: float | str) → str

Get the madx snippet that updates the dpp in the machine.

Parameters:

deltap (float | str) -- The dpp to update the machine to.

post_run() → None

Checks that the model creation MAD-X run was successful. It should check that the appropriate directories are created, and that macros and other files are in place. Also assigns the created model output to the accelerator instance (e.g. elements, model, …).

Hint: If you only need to check a different set of files, you can simply override the files_to_check property,

instead of this whole function.

prepare_modifiers()

Loop over the modifiers and make them full paths if found.

abstractmethod prepare_options(opt)

Checks the options specific to the accelerator and applies them to the instance, if they are valid. If there are options missing or wrongly set, raise an AcceleratorDefinitionError.

This function should different from the normal parsing of options, as it is used to print possible choices for the user. In particular it is used for the “fetcher” and sets up the paths to be used later by the model creator.

Parameters:

opt -- The remaining options (i.e. those not yet consumed by the model creator)

prepare_run() → None

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

prepare_symlink()

Prepare the acc-models-symlink. Create symlink if it does not yet exist or points the wrong way. Use the symlink from here on instead of the acc-model-path, also in the modifiers.

This functions can be used by all model creators supporting the acc-models creation.

resolve_path_for_madx(path: Path | str) → Path

Converts a given path to a path relative to the model dir if possible, otherwise returns the absolute path.

Parameters:

path (Path | str) -- The path to convert.

Returns:

The converted path for MAD-X usage.

Return type:

madx_path (Path)

class omc3.model.model_creators.abstract_model_creator.SegmentCreator(accel: Accelerator, segment: Segment, measurables: Iterable[Propagable], corrections: MADXInputType = None, *args, **kwargs)

Model creator for Segments, to be used in the Segment-by-Segment algorithm. These segments propagate the measured values from the beginning of the segment to the end.

This only handles the MAD-X part of things. The input is determined by the passed measurables (Propagable objects), which provide the values via init_conditions_dict() method.

The output is stored in the twiss_forward and twiss_backward files, which in turn can be used for further processing by the implemented Propagables.

property files_to_check: list[str]

Returns the list of files to check after model creation, should only be used in post_run. Override in subclass if you need to check a different set of files.

get_madx_script() → str

Returns the MAD-X script used to create the model (directory).

prepare_run() → None

Prepares the model creation MAD-X run. It should check that the appropriate directories are created, and that macros and other files are in place. Should also check that all necessary data for model creation is available in the accelerator instance.

Here implemented are some usual defaults, so that an implementation of the model-creator might run these easily with super() if desired.

Parameters:

accel (Accelerator) -- Accelerator Instance used for the model creation.

omc3.model.model_creators.abstract_model_creator.check_folder_choices(parent: ~pathlib.Path, msg: str, selection: str, list_choices: bool = False, predicate=<function always_true>, stem_only: bool = False) → Path

A helper function that scans a selected folder for children, which will then be displayed as possible choices. This funciton allows the model-creator to get only the file/folder names, check in the desired folder if the choice is present and return the full path to the selected folder.

Parameters:

• parent (Path) -- The folder to scan.

• msg (str) -- The message to display, on failure.

• selection (str) -- The current selection.

• list_choices (bool) -- Whether to just list the choices. In that case None is returned, instead of an error

• predicate (callable) -- A function that takes a path and returns True. if the path results in a valid choice.

• stem_only (bool) -- If True, only the stem of the path is checked.

Returns:

Full path of the selected choice in parent.

Return type:

Path

Examples

Let’s say we expect a choice for a sequence file in the folder model_root.

` check_folder_choices(model_root, "Expected sequence file", predicate=lambda p: p.suffix == ".seq") `

Or we want all subfolder of scenarios

` check_folder_choices(scenarios, "Expected scenario folder", predicate=lambda p: p.is_dir()) `