Converters

converters.astra.from_astrabeam(path: str) → tuple[ndarray, float, ndarray]

Read from a ASTRA beam distribution, and prepare for conversion to a Cheetah ParticleBeam or ParameterBeam.

Adapted from the implementation in Ocelot: https://github.com/ocelot-collab/ocelot/blob/master/ocelot/adaptors/astra2ocelot.py

Parameters:

path – Path to the ASTRA beam distribution file.

Returns:

(particles, energy, q_array) Particle 6D phase space information, mean energy, and the charge array of the particle beam.

converters.bmad.convert_element(name: str, context: dict, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None) → Element

Convert a parsed Bmad element dict to a cheetah Element.

Parameters:

• name – Name of the (top-level) element to convert.

• context – Context dictionary parsed from Bmad lattice file(s).

• sanitize_name – Whether to sanitise the name to be a valid Python variable name.

• device – Device to put the element on. If None, the current default device of PyTorch is used.

• dtype – Data type to use for the element. If None, the current default dtype of PyTorch is used.

Returns:

Converted cheetah Element. If you are calling this function yourself as a user of Cheetah, this is most likely a Segment.

converters.bmad.convert_lattice(bmad_lattice_file_path: Path, environment_variables: dict | None = None, sanitize_names: bool = False, device: device | None = None, dtype: dtype | None = None) → Element

Convert a Bmad lattice file to a Cheetah Segment.

NOTE: This function was designed at the example of the LCLS lattice. While this

lattice is extensive, this function might not properly convert all features of a Bmad lattice. If you find that this function does not work for your lattice, please open an issue on GitHub.

Parameters:

• bmad_lattice_file_path – Path to the Bmad lattice file.

• environment_variables – Dictionary of environment variables to use when parsing the lattice file.

• sanitize_names – Whether to sanitise the names of the elements to be valid Python variable names. This is needed if you want to use the segment.element_name syntax to access the element in a segment.

• device – Device to use for the lattice. If None, the current default device of PyTorch is used.

• dtype – Data type to use for the lattice. If None, the current default dtype of PyTorch is used.

Returns:

Cheetah Segment representing the Bmad lattice.

converters.elegant.convert_beam(file_path: Path, device: device | None = None, dtype: dtype | None = None) → tuple[Tensor, Tensor, Tensor]

Read the beam distribution from an Elegant SDDS file.

Parameters:

• file_path – Path to the SDDS file from which to load the Elegant beam.

• device – Device to use for the beam distribution. If None, the current default device of PyTorch is used.

• dtype – Data type to use for the beam distribution. If None, the current default dtype of PyTorch is used.

Returns:

A tuple containing the particles tensor, the reference energy in eV, and the tensor of particle charges.

converters.elegant.convert_element(name: str, context: dict, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None) → Element

Convert a parsed Elegant element dict to a cheetah Element.

Parameters:

• name – Name of the (top-level) element to convert.

• context – Context dictionary parsed from Elegant lattice file(s).

• sanitize_name – Whether to sanitise the name to be a valid Python variable name. This is needed if you want to use the segment.element_name syntax to access the element in a segment.

• device – Device to use for the lattice. If None, the current default device of PyTorch is used.

• dtype – Data type to use for the lattice. If None, the current default dtype of PyTorch is used.

Returns:

Converted cheetah Element. If you are calling this function yourself as a user of Cheetah, this is most likely a Segment.

converters.elegant.convert_lattice(elegant_lattice_file_path: Path, name: str, sanitize_names: bool = False, device: device | None = None, dtype: dtype | None = None) → Element

Convert a Elegant lattice file to a Cheetah Segment.

Parameters:

• elegant_lattice_file_path – Path to the Elegant lattice file.

• name – Name of the root element.

• sanitize_names – Whether to sanitise the names of the elements as well as the name of the segment to be valid Python variable names. This is needed if you want to use the segment.element_name syntax to access the element in a segment.

• device – Device to use for the lattice. If None, the current default device of PyTorch is used.

• dtype – Data type to use for the lattice. If None, the current default dtype of PyTorch is used.

Returns:

Cheetah Segment representing the Elegant lattice.

converters.elegant.elegant_to_cheetah_coordinates(elegant_coordinates: Tensor, p_central: Tensor) → Tensor

Convert Elegant coordinates to Cheetah coordinates.

Parameters:

• elegant_coordinates – Elegant coordinates of shape (…, num_particles, 6) with columns: [x, x’, y, y’, t, p].

• p_central – The reference momentum in \(\beta * \gamma\) units.

Returns:

Cheetah coordinates of shape (…, num_particles, 7).

converters.nxtables.convert_lattice(filepath: Path) → Element

Read an NX Tables CSV-like file generated for the ARES lattice into a Cheetah Segment.

Parameters:

filepath – Path to the NX Tables file.

Returns:

Converted Cheetah Segment.

converters.nxtables.translate_element(row: list[str], header: list[str]) → dict | None

Translate a row of an NX Tables file to a Cheetah Element.

Parameters:

• row – A row of an NX Tables file as a list of column elements.

• header – The header row of the NX Tables file as a list of column names.

Returns:

Dictionary of Cheetah Element object best representing the row and its center s position if the element is relevant for the Cheetah model, None otherwise.

converters.ocelot.convert_element(element, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None) → Element

Translate an Ocelot element to a Cheetah element.

NOTE: Objects not supported by Cheetah are translated to drift sections. Screen

objects are created only from ocelot.Monitor objects when the string “BSC” is contained in their id attribute. Their screen properties are always set to default values and most likely need adjusting afterwards. BPM objects are only created from ocelot.Monitor objects when their id has a substring “BPM”.

Parameters:

• element – Ocelot element object representing an element of particle accelerator.

• sanitize_name – Whether to sanitise the name to be a valid Python variable name. This is needed if you want to use the segment.element_name syntax to access the element in a segment.

Returns:

Cheetah element object representing an element of particle accelerator.

converters.ocelot.subcell_of_ocelot(cell: list, start: str, end: str) → list

Extract a subcell [start, end] from an Ocelot cell.

converters.utils.fortran_namelist.assign_property(line: str, context: dict) → dict

Assign a property of an element to the context.

Parameters:

• line – Line of a property assignment to be parsed.

• context – Dictionary of variables to assign the property to and from which to read variables.

Returns:

Updated context.

converters.utils.fortran_namelist.assign_variable(line: str, context: dict) → dict

Assign a variable to the context.

Parameters:

• line – Line of a variable assignment to be parsed.

• context – Dictionary of variables to assign the variable to and from which to read variables.

Returns:

Updated context.

converters.utils.fortran_namelist.define_element(line: str, context: dict) → dict

Define an element in the context.

Parameters:

• line – Line of an element definition to be parsed.

• context – Dictionary of variables to define the element in and from which to read variables.

Returns:

Updated context.

converters.utils.fortran_namelist.define_line(line: str, context: dict) → dict

Define a beamline in the context.

Parameters:

• line – Line of a beam line definition to be parsed.

• context – Dictionary of variables to define the beam line in and from which to read variables.

Returns:

Updated context.

converters.utils.fortran_namelist.define_overlay(line: str, context: dict) → dict

Define an overlay in the context.

Parameters:

• line – Line of an overlay definition to be parsed.

• context – Dictionary of variables to define the overlay in and from which to read variables.

Returns:

Updated context.

converters.utils.fortran_namelist.evaluate_expression(expression: str, context: dict) → Any

Evaluate an expression in the context of a dictionary of variables.

Parameters:

• expression – Expression to evaluate.

• context – Dictionary of variables to evaluate the expression in the context of.

Returns:

Result of evaluating the expression.

converters.utils.fortran_namelist.merge_delimiter_continued_lines(lines: list[str], delimiter: str, remove_delimiter: bool = False) → list[str]

Merge lines ending with some character as a delimitter with the following line.

Parameters:

• lines – List of lines to merge.

• delimitter – Character to use as a delimitter.

• remove_delimitter – Whether to remove the delimitter from the merged line.

Returns:

List of lines with ampersand-continued lines merged.

converters.utils.fortran_namelist.parse_lines(lines: str) → dict

Parse a list of lines from a Bmad or Elegant lattice file. They should be cleaned and merged before being passed to this function.

Parameters:

lines – List of lines to parse.

Returns:

Dictionary of variables defined in the lattice file.

converters.utils.fortran_namelist.parse_use_line(line: str, context: dict) → dict

Parse a use line.

Parameters:

• line – Line of a use statement to be parsed.

• context – Dictionary of variables to define the overlay in and from which to read variables.

Returns:

Updated context.

converters.utils.fortran_namelist.read_clean_lines(lattice_file_path: Path) → list[str]

Recursevely read lines from Bmad lattice files, removing comments and empty lines, and replacing lines calling external files with the lines of the external file.

Parameters:

lattice_file_path – Path to the root Bmad lattice file.

Returns:

List of lines from the root Bmad lattice file and all external files.

converters.utils.fortran_namelist.resolve_object_name_wildcard(wildcard_pattern: str, context: dict) → list

Return a list of object names that match the given wildcard pattern.

Parameters:

• wildcard_pattern – Wildcard pattern to match.

• context – Dictionary of variables among which to search for matching object.

Returns:

List of object names that match the given wildcard pattern, both in terms of name and element type.

converters.utils.fortran_namelist.validate_understood_properties(understood: list[str], properties: dict) → None

Validate that all properties are understood. This function primarily ensures that properties not understood by Cheetah are not ignored silently.

Raises an AssertionError if a property is found that is not understood.

Parameters:

• understood – List of properties understood (or purpusefully ignored) by Cheetah.

• properties – Dictionary of properties to validate.

Returns:

None

converters.utils.rpn.evaluate_expression(expression: str, context: dict | None = None) → Any

Evaluates an expression in Reverse Polish Notation.

Throws a SyntaxError if the expression is invalid.