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. help_requested is a boolean stating if help was requested at any point

omc3.model.manager.get_accelerator_class(opt, other)

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

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.

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.

get_base_madx_script(best_knowledge=False)

Returns job (string) to create the basic accelerator sequence.

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

Returns the set of corrector variables between frm and to, with classes in classes. None means select all.

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) → 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.

get_update_correction_script(outpath: Path | str, corr_files: Sequence[Path | str]) → str

Returns job (string) to create an updated model from changeparameters input (used in iterative correction).

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.

class omc3.model.accelerators.accelerator.Element(name, s)

Generic corrector element class that holds name and position (s) of the corrector. This element should represent a physical element of the accelerator.

class omc3.model.accelerators.accelerator.Variable(name, elements, classes)

Generic corrector variable class that holds name, position (s) and physical elements it affects. These variables should be logical variables that have and effect in the model if modified.

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 Tev.

• 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)

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 Tev.

• 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)

Parent Class for LHC-types.

get_base_madx_script(best_knowledge: bool = False) → str

Returns job (string) to create the basic accelerator sequence.

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)

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_update_correction_script(outpath: Path | str, corr_files: Sequence[Path | str]) → str

Returns job (string) to create an updated model from changeparameters input (used in iterative correction).

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 Tev.

• 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_base_madx_script(best_knowledge=False)

Returns job (string) to create the basic accelerator sequence.

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 Tev.

• 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_base_madx_script(best_knowledge=False)

Returns job (string) to create the basic accelerator sequence.

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 Tev.

• 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.

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 Tev.

• 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.

LHC Model Creator

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

class omc3.model.model_creators.lhc_model_creator.LhcBestKnowledgeCreator

classmethod check_run_output(accel: Lhc) → 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. Checks the accelerator instance. Called by the model_creator.create_instance_and_model

Parameters:

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

classmethod get_madx_script(accel: Lhc) → str

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

Parameters:

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

Returns:

The string of the MAD-X script used to used to create the model.

classmethod get_options(accel_inst, opt) → bool

Parses additional commandline options (if any). To be overridden by subclasses. If there are options that ask for some output print, and no valid model to be created, return False.

Parameters:

options -- The remaining options (e.g. if called by model_creater, those not yet consumed by the model creator)

Returns: True if enough options are given to provide a valid model

class omc3.model.model_creators.lhc_model_creator.LhcCouplingCreator

classmethod get_madx_script(accel: Lhc) → str

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

Parameters:

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

Returns:

The string of the MAD-X script used to used to create the model.

class omc3.model.model_creators.lhc_model_creator.LhcModelCreator

classmethod get_correction_check_script(accel: Lhc, corr_file: str = 'changeparameters_couple.madx', chrom: bool = False) → str

Returns the MAD-X script used to verify global corrections. This script should create twiss files for before (twiss_no.dat) and after (twiss_corr.dat) correction.

Parameters:

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

• corr_file (str) -- File containing the corrections (madx-readable).

• chrom (bool) -- Flag for chromatic corrections deltapm and deltapp.

Returns:

The string of the MAD-X script used to verify global corrections.

classmethod get_madx_script(accel: Lhc) → str

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

Parameters:

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

Returns:

The string of the MAD-X script used to used to create the model.

classmethod get_options(accel_inst, opt) → bool

Parses additional commandline options (if any). To be overridden by subclasses. If there are options that ask for some output print, and no valid model to be created, return False.

Parameters:

options -- The remaining options (e.g. if called by model_creater, those not yet consumed by the model creator)

Returns: True if enough options are given to provide a valid model

classmethod prepare_run(accel: Lhc) → 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. Called by the model_creator.create_accel_and_instance

Parameters:

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

PS Model Creator

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

class omc3.model.model_creators.ps_model_creator.PsModelCreator

classmethod get_madx_script(accel: PsBase) → str

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

Parameters:

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

Returns:

The string of the MAD-X script used to used to create the model.

PS Booster Model Creator

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

class omc3.model.model_creators.psbooster_model_creator.BoosterModelCreator

classmethod get_madx_script(accel: PsBase) → str

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

Parameters:

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

Returns:

The string of the MAD-X script used to used to create the model.

classmethod prepare_run(accel: PsBase)

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. Called by the model_creator.create_accel_and_instance

Parameters:

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

Segment Creator

This module provides convenience functions for model creation of a segment.