Accelerator

class accelerator.aperture.Aperture(x_max: Tensor | None = None, y_max: Tensor | None = None, shape: Literal['rectangular', 'elliptical'] = 'rectangular', is_active: bool = True, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Physical aperture.

NOTE: The aperture currently only affects beams of type ParticleBeam and only has

an effect when the aperture is active.

Parameters:

• x_max – half size horizontal offset in [m].

• y_max – half size vertical offset in [m].

• shape – Shape of the aperture. Can be “rectangular” or “elliptical”.

• is_active – If the aperture actually blocks particles.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.bpm.BPM(is_active: bool = False, name: str | None = None, misalignment: Tensor | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Beam Position Monitor (BPM) in a particle accelerator.

Parameters:

• is_active – If True the BPM is active and will record the beam’s position. If False the BPM is inactive and will not record the beam’s position.

• name – Unique identifier of the element.

• misalignment – Misalignment vector of the BPM in x- and y-directions.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.cavity.Cavity(length: Tensor, voltage: Tensor | None = None, phase: Tensor | None = None, frequency: Tensor | None = None, cavity_type: Literal['standing_wave', 'traveling_wave'] = 'standing_wave', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Accelerating cavity in a particle accelerator.

NOTE: When computing the gradient on cavities with exactly zero energy gain, it is

possible that some gradient components are lost. This is unlikely to cause (therefore do not hesitate to have cavities with zero voltage in your lattice), but this note is here to make you aware of this possibility.

Parameters:

• length – Length in meters.

• voltage – Voltage of the cavity in volts. NOTE: This assumes the physical voltage. Positive voltage will accelerate electron-like particles. For particle with charge n * e, the energy gain on crest will be n * voltage.

• phase – Phase of the cavity in degrees.

• frequency – Frequency of the cavity in Hz.

• cavity_type – Type of the cavity.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.combined_corrector.CombinedCorrector(length: Tensor, horizontal_angle: Tensor | None = None, vertical_angle: Tensor | None = None, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Combined horizontal and vertical corrector magnet in a particle accelerator.

NOTE: This is modeled as a drift section with thin-kicks in both the horizontal and

vertical planes.

Parameters:

• length – Length in meters.

• horizontal_angle – Particle deflection angle in the horizontal plane in rad.

• vertical_angle – Particle deflection angle in the vertical plane in rad.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

supported_tracking_methods = ['linear']

class accelerator.custom_transfer_map.CustomTransferMap(predefined_transfer_map: Tensor, length: Tensor | None = None, name: Tensor | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

This element can represent any custom transfer map.

Parameters:

• predefined_transfer_map – The transfer map to use for this element.

• length – Length of the element in meters. If None, the length is set to 0.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

classmethod from_merging_elements(elements: list[Element], incoming_beam: Beam) → CustomTransferMap

Combine the transfer maps of multiple successive elements into a single transfer map. This can be used to speed up tracking through a segment, if no changes are made to the elements in the segment or the energy of the beam being tracked through them.

Parameters:

• elements – List of consecutive elements to combine.

• incoming_beam – Beam entering the first element in the segment. NOTE: That this is required because the separate original transfer maps have to be computed before being combined and some of them may depend on the energy of the beam.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

supported_tracking_methods = ['linear']

class accelerator.dipole.Dipole(length: Tensor, angle: Tensor | None = None, k1: Tensor | None = None, dipole_e1: Tensor | None = None, dipole_e2: Tensor | None = None, tilt: Tensor | None = None, gap: Tensor | None = None, gap_exit: Tensor | None = None, fringe_integral: Tensor | None = None, fringe_integral_exit: Tensor | None = None, fringe_at: Literal['neither', 'entrance', 'exit', 'both'] = 'both', fringe_type: Literal['linear_edge'] = 'linear_edge', tracking_method: Literal['linear', 'second_order', 'drift_kick_drift'] = 'linear', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Dipole magnet (by default a sector bending magnet).

Parameters:

• length – Length in meters.

• angle – Deflection angle in rad.

• k1 – Focussing strength in 1/m^-2. Only used with “linear” tracking method.

• dipole_e1 – The angle of inclination of the entrance face in rad.

• dipole_e2 – The angle of inclination of the exit face in rad.

• tilt – Tilt of the magnet in x-y plane [rad].

• gap – The magnet gap in meters. Note that in MAD and ELEGANT: HGAP = gap/2.

• gap_exit – The magnet gap at the exit in meters. Note that in MAD and ELEGANT: HGAP = gap/2. Only set if different from gap. Only used with “drift_kick_drift” tracking method.

• fringe_integral – Fringe field integral (of the enterance face).

• fringe_integral_exit – Fringe field integral of the exit face. Only set if different from fringe_integral. Only used with “drift_kick_drift” tracking method.

• fringe_at – Where to apply the fringe fields for “drift_kick_drift” tracking. The available options are: - “neither”: Do not apply fringe fields. - “entrance”: Apply fringe fields at the entrance end. - “exit”: Apply fringe fields at the exit end. - “both”: Apply fringe fields at both ends.

• fringe_type – Type of fringe field for “drift_kick_drift” tracking. Currently only supports “linear_edge”.

• tracking_method – Method to use for tracking through the element.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

property dipole_e1: Tensor

property dipole_e2: Tensor

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property hx: Tensor

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

second_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s second-order transfer map that describes how the beam and its particles are transformed when traveling through the element.

\(pout_{i} = \sum_{j,k} T_{ijk} pin_{j} pin_{k}\)

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7x7 Tensor T_ijk for further calculations.

supported_tracking_methods = ['linear', 'second_order', 'drift_kick_drift']

to_mesh(cuteness: float | dict = 1.0, asset_version: str = 'v1.2.0', show_download_progress: bool = True) → tuple[trimesh.Trimesh | None, np.ndarray]

Return a 3D mesh representation of the element at position s.

Parameters:

• cuteness – Scaling factor for the mesh. This can be used to adjust the size of the mesh for better visualisation. A value of 1.0 means no scaling, while values less than 1.0 will make the mesh smaller and values greater than 1.0 will make it larger. May be float applied to all elements, or a dictionary mapping element names and types to their respective scaling factors. Names have precedence over types. The “*” key can be used to specify a default scaling factor.

• asset_version – The branch or tag name for the version of the 3D assets repository to use.

• show_download_progress – If True, show a progress bar during the download of the mesh if it is not cached.

Returns:

Tuple of a 3D mesh representation of the element, oriented with the beam’s inbound point in the origin and the s-axis pointing along the longitudinal direction of the element, and the transformation matrix that would have to be applied to a downstream mesh to align it with this mesh’s output.

track(incoming: Beam) → Beam

Track particles through the dipole element.

Parameters:

incoming – Beam entering the element.

Returns:

Beam exiting the element.

class accelerator.drift.Drift(length: Tensor, tracking_method: Literal['linear', 'second_order', 'drift_kick_drift'] = 'linear', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Drift section in a particle accelerator.

Parameters:

• length – Length in meters.

• tracking_method – Method to use for tracking through the element.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

second_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s second-order transfer map that describes how the beam and its particles are transformed when traveling through the element.

\(pout_{i} = \sum_{j,k} T_{ijk} pin_{j} pin_{k}\)

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7x7 Tensor T_ijk for further calculations.

split(resolution: Tensor) → list[Element]

Split the element into slices no longer than resolution. Some elements may not be splittable, in which case a list containing only the element itself is returned.

Parameters:

resolution – Length of the longest allowed split in meters.

Returns:

Ordered sequence of sliced elements.

supported_tracking_methods = ['linear', 'second_order', 'drift_kick_drift']

to_mesh(cuteness: float | dict = 1.0, asset_version: str = 'v1.2.0', show_download_progress: bool = True) → tuple[trimesh.Trimesh | None, np.ndarray]

Return a 3D mesh representation of the element at position s.

Parameters:

• cuteness – Scaling factor for the mesh. This can be used to adjust the size of the mesh for better visualisation. A value of 1.0 means no scaling, while values less than 1.0 will make the mesh smaller and values greater than 1.0 will make it larger. May be float applied to all elements, or a dictionary mapping element names and types to their respective scaling factors. Names have precedence over types. The “*” key can be used to specify a default scaling factor.

• asset_version – The branch or tag name for the version of the 3D assets repository to use.

• show_download_progress – If True, show a progress bar during the download of the mesh if it is not cached.

Returns:

Tuple of a 3D mesh representation of the element, oriented with the beam’s inbound point in the origin and the s-axis pointing along the longitudinal direction of the element, and the transformation matrix that would have to be applied to a downstream mesh to align it with this mesh’s output.

track(incoming: Beam) → Beam

Track particles through the dipole element.

Parameters:

incoming – Beam entering the element.

Returns:

Beam exiting the element.

class accelerator.element.Element(name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Base class for elements of particle accelerators.

Parameters:

• name – Unique identifier of the element.

• 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 on which to create the element’s tensors.

• dtype – Data type of the element’s tensors.

clone() → Element

Create a copy of the element which does not share the underlying memory.

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

property defining_tensors: list[str]

Subset of defining features that are of type torch.Tensor.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

forward(incoming: Beam) → Beam

Forward function required by torch.nn.Module. Simply calls track.

is_name_sanitized() → bool

Check if a name is sanitised, i.e. it contains only alphanumeric characters and underscores.

A clean name can be used as a Python variable name, which is a requirement when using the segment.element_name syntax to access the element in a segment.

abstract property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

abstractmethod plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

register_buffer_or_parameter(name: str, value: Tensor | Parameter, persistent: bool = True) → None

Register a buffer or parameter with the given name and value. Automatically selects the correct method from register_buffer or register_parameter based on the type of value.

Parameters:

• name – Name of the buffer or parameter.

• value – Value of the buffer or parameter.

• default – Default value of the buffer.

• persistent – Whether the buffer or parameter should be persistent. NOTE: This is only relevant for buffers, as parameters are always persistent.

sanitize_name() → None

Sanitise the element’s name to be a valid Python variable name.

Replaces characters that are not alphanumeric or underscores with underscores.

second_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s second-order transfer map that describes how the beam and its particles are transformed when traveling through the element.

\(pout_{i} = \sum_{j,k} T_{ijk} pin_{j} pin_{k}\)

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7x7 Tensor T_ijk for further calculations.

split(resolution: Tensor) → list[Element]

Split the element into slices no longer than resolution. Some elements may not be splittable, in which case a list containing only the element itself is returned.

Parameters:

resolution – Length of the longest allowed split in meters.

Returns:

Ordered sequence of sliced elements.

to_mesh(cuteness: float | dict = 1.0, asset_version: str = 'v1.2.0', show_download_progress: bool = True) → tuple[trimesh.Trimesh | None, np.ndarray]

Return a 3D mesh representation of the element at position s.

Parameters:

• cuteness – Scaling factor for the mesh. This can be used to adjust the size of the mesh for better visualisation. A value of 1.0 means no scaling, while values less than 1.0 will make the mesh smaller and values greater than 1.0 will make it larger. May be float applied to all elements, or a dictionary mapping element names and types to their respective scaling factors. Names have precedence over types. The “*” key can be used to specify a default scaling factor.

• asset_version – The branch or tag name for the version of the 3D assets repository to use.

• show_download_progress – If True, show a progress bar during the download of the mesh if it is not cached.

Returns:

Tuple of a 3D mesh representation of the element, oriented with the beam’s inbound point in the origin and the s-axis pointing along the longitudinal direction of the element, and the transformation matrix that would have to be applied to a downstream mesh to align it with this mesh’s output.

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

property tracking_method: str

The tracking method used by the element. This is used to determine how the element is tracked through the accelerator.

transfer_map(energy: Tensor, species: Species) → Tensor

NOTE: This method is deprecated and will be removed in a future version. Use first_order_transfer_map instead.

Generates the element’s transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

  reference position (usually the center of the pulse)

• p: Relative energy deviation from the reference particle (dimensionless)

  \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

class accelerator.horizontal_corrector.HorizontalCorrector(length: Tensor, angle: Tensor | None = None, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Horizontal corrector magnet in a particle accelerator.

NOTE: This is modeled as a drift section with a thin-kick in the horizontal plane.

Parameters:

• length – Length in meters.

• angle – Particle deflection angle in the horizontal plane in rad.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

supported_tracking_methods = ['linear']

class accelerator.marker.Marker(name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

General Marker / Monitor element

Parameters:

• name – Unique identifier of the element.

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

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.quadrupole.Quadrupole(length: Tensor, k1: Tensor | None = None, misalignment: Tensor | None = None, tilt: Tensor | None = None, num_steps: int = 1, tracking_method: Literal['linear', 'second_order', 'drift_kick_drift'] = 'linear', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Quadrupole magnet in a particle accelerator.

Parameters:

• length – Length in meters.

• k1 – Strength of the quadrupole in 1/m^-2.

• misalignment – Misalignment vector of the quadrupole in x- and y-directions.

• tilt – Tilt angle of the quadrupole in x-y plane in radians. pi/4 for skew-quadrupole.

• num_steps – Number of drift-kick-drift steps to use for tracking through the element when tracking method is set to “drift_kick_drift”.

• tracking_method – Method to use for tracking through the element.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

second_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s second-order transfer map that describes how the beam and its particles are transformed when traveling through the element.

\(pout_{i} = \sum_{j,k} T_{ijk} pin_{j} pin_{k}\)

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7x7 Tensor T_ijk for further calculations.

split(resolution: Tensor) → list[Element]

Split the element into slices no longer than resolution. Some elements may not be splittable, in which case a list containing only the element itself is returned.

Parameters:

resolution – Length of the longest allowed split in meters.

Returns:

Ordered sequence of sliced elements.

supported_tracking_methods = ['linear', 'second_order', 'drift_kick_drift']

to_mesh(cuteness: float | dict = 1.0, asset_version: str = 'v1.2.0', show_download_progress: bool = True) → tuple[trimesh.Trimesh | None, np.ndarray]

Return a 3D mesh representation of the element at position s.

Parameters:

• cuteness – Scaling factor for the mesh. This can be used to adjust the size of the mesh for better visualisation. A value of 1.0 means no scaling, while values less than 1.0 will make the mesh smaller and values greater than 1.0 will make it larger. May be float applied to all elements, or a dictionary mapping element names and types to their respective scaling factors. Names have precedence over types. The “*” key can be used to specify a default scaling factor.

• asset_version – The branch or tag name for the version of the 3D assets repository to use.

• show_download_progress – If True, show a progress bar during the download of the mesh if it is not cached.

Returns:

Tuple of a 3D mesh representation of the element, oriented with the beam’s inbound point in the origin and the s-axis pointing along the longitudinal direction of the element, and the transformation matrix that would have to be applied to a downstream mesh to align it with this mesh’s output.

track(incoming: Beam) → Beam

Track particles through the quadrupole element.

Parameters:

incoming – Beam entering the element.

Returns:

Beam exiting the element.

class accelerator.rbend.RBend(length: Tensor, angle: Tensor | None = None, k1: Tensor | None = None, rbend_e1: Tensor | None = None, rbend_e2: Tensor | None = None, tilt: Tensor | None = None, gap: Tensor | None = None, gap_exit: Tensor | None = None, fringe_integral: Tensor | None = None, fringe_integral_exit: Tensor | None = None, fringe_at: Literal['neither', 'entrance', 'exit', 'both'] = 'both', fringe_type: Literal['linear_edge'] = 'linear_edge', tracking_method: Literal['linear', 'second_order', 'drift_kick_drift'] = 'linear', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Rectangular bending magnet.

Parameters:

• length – Length in meters.

• angle – Deflection angle in rad.

• k1 – Focussing strength in 1/m^-2.

• rbend_e1 – The angle of inclination of the entrance face in rad.

• rbend_e2 – The angle of inclination of the exit face in rad.

• gap – The magnet gap in meters. Note that in MAD and ELEGANT: HGAP = gap/2.

• gap_exit – The magnet gap at the exit in meters. Note that in MAD and ELEGANT: HGAP = gap/2. Only set if different from gap. Only used with “drift_kick_drift” tracking method.

• fringe_integral – Fringe field integral (of the enterance face).

• fringe_integral_exit – Fringe field integral of the exit face. Only set if different from fringe_integral. Only used with “drift_kick_drift” tracking method.

• fringe_at – Where to apply the fringe fields for “drift_kick_drift” tracking. The available options are: - “neither”: Do not apply fringe fields. - “entrance”: Apply fringe fields at the entrance end. - “exit”: Apply fringe fields at the exit end. - “both”: Apply fringe fields at both ends.

• fringe_type – Type of fringe field for “drift_kick_drift” tracking. Currently only supports “linear_edge”.

• name – Unique identifier of the element.

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

property defining_features

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

property rbend_e1

property rbend_e2

class accelerator.screen.Screen(resolution: tuple[int, int] | list[int] = (1024, 1024), pixel_size: Tensor | None = None, binning: int = 1, misalignment: Tensor | None = None, method: Literal['histogram', 'kde'] = 'histogram', kde_bandwidth: Tensor | None = None, is_blocking: bool = False, is_active: bool = False, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Diagnostic screen in a particle accelerator.

Parameters:

• resolution – Resolution of the camera sensor looking at the screen given as tuple or list (width, height) in pixels.

• pixel_size – Size of a pixel on the screen in meters given as a Tensor (width, height).

• binning – Binning used by the camera.

• misalignment – Misalignment of the screen in meters given as a Tensor (x, y).

• method – Method used to generate the screen’s reading. Can be either “histogram” or “kde”, defaults to “histogram”. KDE will be slower but allows backward differentiation.

• kde_bandwidth – Bandwidth used for the kernel density estimation in meters. Controls the smoothness of the distribution.

• is_blocking – If True the screen is blocking and will stop the beam.

• is_active – If True the screen is active and will record the beam’s distribution. If False the screen is inactive and will not record the beam’s distribution.

• name – Unique identifier of the element.

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

NOTE: method=’histogram’ currently does not support vectorisation. Please use

method=’kde’ instead. Similarly, ParameterBeam can also not be vectorised. Please use ParticleBeam instead.

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

property effective_pixel_size: Tensor

property effective_resolution: tuple[int, int]

property extent: Tensor

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

get_read_beam() → Beam

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

property pixel_bin_centers: tuple[Tensor, Tensor]

property pixel_bin_edges: tuple[Tensor, Tensor]

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

property reading: Tensor

set_read_beam(value: Beam) → None

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.segment.Segment(elements: list[Element], name: str | None = None, sanitize_name: bool = False)

Segment of a particle accelerator consisting of several elements.

Parameters:

• cell – List of Cheetah elements that describe an accelerator (section).

• name – Unique identifier of the element.

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

beam_along_segment_generator(incoming: Beam, resolution: float | None = None) → Iterator[Beam]

Generator for beam objects along the segment either at the end of each element or at a given resolution.

Parameters:

• incoming – Beam that is entering the segment from upstream for which the trajectory is computed.

• resolution – Requested resolution of trajectory. Note that not all elements can be split at arbitrary resolutions, which can lead to deviations from the requested resolution. If None is passed, samples are taken at the end of each element.

Returns:

Generator that yields the beam objects along the segment.

clone() → Segment

Create a copy of the element which does not share the underlying memory.

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

element_index(element_name: str) → int

Get the index of the first occurrence of an element in the segment by its name.

Parameters:

element_name – Name of the element to get the index for.

Returns:

Index of the first element in the segment with the passed name.

property element_names: list[str]

Ordered list of names of the elements in the segment.

Returns:

Ordered list of names of the elements in the segment.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

flattened() → Segment

Return a flattened version of the segment, i.e. one where all subsegments are resolved and their elements entered into a top-level segment.

classmethod from_bmad(bmad_lattice_file_path: str, environment_variables: dict | None = None, sanitize_names: bool = False, device: device | None = None, dtype: dtype | None = None) → Segment

Read a Cheetah segment from a Bmad lattice file.

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 place the lattice elements on.

• dtype – Data type to use for the lattice elements.

Returns:

Cheetah Segment representing the Bmad lattice.

classmethod from_elegant(elegant_lattice_file_path: str, name: str, sanitize_names: bool = False, device: device | None = None, dtype: dtype | None = None) → Segment

Read a Cheetah segment from an Elegant lattice file.

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 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 place the lattice elements on.

• dtype – Data type to use for the lattice elements.

Returns:

Cheetah Segment representing the Elegant lattice.

classmethod from_lattice_json(filepath: str, device: device | None = None, dtype: dtype | None = None) → Segment

Load a Cheetah model from a JSON file.

Parameters:

• filepath – Path of the file to load the lattice from.

• device – Device to place the lattice elements on.

• dtype – Data type to use for the lattice elements.

Returns:

Loaded Cheetah Segment.

classmethod from_nx_tables(filepath: Path | str) → Element

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

NOTE: This format is specific to the ARES accelerator at DESY.

Parameters:

filepath – Path to the NX Tables file.

Returns:

Converted Cheetah Segment.

classmethod from_ocelot(cell, name: str | None = None, sanitize_names: bool = False, device: device | None = None, dtype: dtype | None = None, **kwargs) → Segment

Translate an Ocelot cell to a Cheetah Segment.

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:

• cell – Ocelot cell, i.e. a list of Ocelot elements to be converted.

• name – Unique identifier for the entire segment.

• 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 place the lattice elements on.

• dtype – Data type to use for the lattice elements.

Returns:

Cheetah segment closely resembling the Ocelot cell.

get_beam_attrs_along_segment(attr_names: tuple[str, ...] | str, incoming: Beam, resolution: float | None = None) → tuple[Tensor, ...] | Tensor

Get metrics along the segment either at the end of each element or at a given resolution.

Parameters:

• attr_names – Metrics to compute. Can be a single metric or a tuple of metrics. Supported metrics are any property of beam class of incoming.

• incoming – Beam that is entering the segment from upstream for which the trajectory is computed.

• resolution – Requested resolution of trajectory. Note that not all elements can be split at arbitrary resolutions, which can lead to deviations from the requested resolution. If None is passed, samples are taken at the end of each element.

Returns:

Tuple of tensors containing the requested metrics along the segment.

inactive_elements_as_drifts(except_for: list[str] | None = None) → Segment

Return a segment where all inactive elements (that have a length) are replaced by drifts. This can be used to speed up tracking through the segment and is a valid thing to as inactive elements should basically be no different from drift sections.

Parameters:

except_for – List of names of elements that should not be replaced by drifts despite being inactive. Usually these are the elements that are currently inactive but will be activated later.

Returns:

Segment with inactive elements replaced by drifts.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

property length: Tensor

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

plot_beam_attrs(incoming: Beam, attr_names: tuple[str, ...] | str, resolution: float | None = None, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot beam attributes along the segment.

Parameters:

• incoming – Beam that is entering the segment from upstream for which the trajectory is computed.

• attr_names – Metrics to compute. Can be a single metric or a tuple of metrics. Supported metrics are any property of beam class of incoming.

• resolution – Requested resolution of trajectory. Note that not all elements can be split at arbitrary resolutions, which can lead to deviations from the requested resolution. If None is passed, samples are taken at the end of each element.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot into.

Returns:

Axes with the plotted beam attributes.

plot_beam_attrs_over_lattice(incoming: Beam, attr_names: tuple[str, ...] | str, figsize=(8, 4), resolution: float | None = None, vector_idx: tuple | None = None) → None

Plot beam attributes in a plot over a plot of the lattice.

Parameters:

• incoming – Beam that is entering the segment from upstream for which the trajectory is computed.

• attr_names – Metrics to compute. Can be a single metric or a tuple of metrics. Supported metrics are any property of beam class of incoming.

• figsize – Size of the figure.

• resolution – Minimum resolution of the tracking of the beam position and beam size in the plot.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

plot_mean_and_std(axx: Axes, axy: Axes, incoming: Beam, resolution: float | None = None, vector_idx: tuple | None = None) → None

Plot the mean (i.e. beam position) and standard deviation (i.e. beam size) of the beam along the segment view in x- and y-direction.

Parameters:

• axx – Axes to plot the particle traces into viewed in x-direction.

• axy – Axes to plot the particle traces into viewed in y-direction.

• incoming – Entering beam for which the position and size are shown

• resolution – Minimum resolution of the tracking of the beam position and beam size in the plot.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

plot_overview(incoming: Beam, fig: Figure | None = None, resolution: float | None = None, vector_idx: tuple | None = None) → None

Plot an overview of the segment with the lattice along with the beam position and size.

Parameters:

• incoming – Entering beam for which the position and size are shown.

• fig – Figure to plot the overview into.

• resolution – Minimum resolution of the tracking of the beam position and beam size in the plot.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

plot_twiss(incoming: Beam, vector_idx: tuple | None = None, ax: Any | None = None) → Axes

Plot twiss parameters along the segment.

plot_twiss_over_lattice(incoming: Beam, figsize=(8, 4)) → None

Plot twiss parameters in a plot over a plot of the lattice.

reversed() → Segment

Return a reversed version of the segment, i.e. one where the order of the elements is reversed.

set_attrs_on_every_element(filter_type: type[Element] | tuple[type[Element]] | None = None, is_recursive: bool = True, **kwargs: dict[str, Any]) → None

Set attributes on every element of a specific type in the segment.

Parameters:

• filter_type – Type of the elements to set the attributes for.

• is_recursive – If True, the this method is applied to nested Segment`s as well. If `False, only the elements directly in the top-level Segment are considered.

• kwargs – Attributes to set and their values.

split(resolution: Tensor) → list[Element]

Split the element into slices no longer than resolution. Some elements may not be splittable, in which case a list containing only the element itself is returned.

Parameters:

resolution – Length of the longest allowed split in meters.

Returns:

Ordered sequence of sliced elements.

subcell(start: str | None = None, end: str | None = None, include_start: bool = True, include_end: bool = True) → Segment

Extract a subcell from this segment.

If either start or end is None, the subcell starts or ends at the same element as the original segment. If start or end is not part of the segment, a ValueError is raised.

Parameters:

• start – Name of the element at the start of the subcell. If None is passed, the subcell starts at the same element as the original segment.

• end – Name of the element at the end of the subcell. If None is passed, the subcell ends at the same element as the original segment.

• include_start – If True, start is included in the subcell, otherwise not.

• include_end – If True, end is included in the subcell, otherwise not.

Returns:

Subcell of elements from start to end.

to_lattice_json(filepath: str, title: str | None = None, info: str = 'This is a placeholder lattice description') → None

Save a Cheetah model to a JSON file.

Parameters:

• filename – Name/path of the file to save the lattice to.

• title – Title of the lattice. If not provided, defaults to the name of the Segment object. If that also does not have a name, defaults to “Unnamed Lattice”.

• info – Information about the lattice. Defaults to “This is a placeholder lattice description”.

to_mesh(cuteness: float | dict = 1.0, asset_version: str = 'v1.2.0', show_download_progress: bool = True) → tuple[trimesh.Scene | None, np.ndarray]

Return a 3D mesh representation of the element at position s.

Parameters:

• cuteness – Scaling factor for the mesh. This can be used to adjust the size of the mesh for better visualisation. A value of 1.0 means no scaling, while values less than 1.0 will make the mesh smaller and values greater than 1.0 will make it larger. May be float applied to all elements, or a dictionary mapping element names and types to their respective scaling factors. Names have precedence over types. The “*” key can be used to specify a default scaling factor.

• asset_version – The branch or tag name for the version of the 3D assets repository to use.

• show_download_progress – If True, show a progress bar during the download of the mesh if it is not cached.

Returns:

Tuple of a 3D mesh representation of the element, oriented with the beam’s inbound point in the origin and the s-axis pointing along the longitudinal direction of the element, and the transformation matrix that would have to be applied to a downstream mesh to align it with this mesh’s output.

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

transfer_maps_merged(incoming_beam: Beam, except_for: list[str] | None = None) → Segment

Return a segment where the transfer maps of skipable elements are merged into elements of type CustomTransferMap. This can be used to speed up tracking through the segment.

Parameters:

• incoming_beam – Beam that is incoming to the segment. NOTE: This beam is needed to determine the energy of the beam when entering each element, as the transfer maps of merged elements might depend on the beam energy.

• except_for – List of names of elements that should not be merged despite being skippable. Usually these are the elements that are changed from one tracking to another.

Returns:

Segment with merged transfer maps.

without_inactive_markers(except_for: list[str] | None = None) → Segment

Return a segment where all inactive markers are removed. This can be used to speed up tracking through the segment.

NOTE: is_active has not yet been implemented for Markers. Therefore, this function currently removes all markers.

Parameters:

except_for – List of names of elements that should not be removed despite being inactive.

Returns:

Segment without inactive markers.

without_inactive_zero_length_elements(except_for: list[str] | None = None) → Segment

Return a segment where all inactive zero length elements are removed. This can be used to speed up tracking through the segment.

NOTE: If is_active is not implemented for an element, it is assumed to be inactive and will be removed.

Parameters:

except_for – List of names of elements that should not be removed despite being inactive and having a zero length.

Returns:

Segment without inactive zero length elements.

class accelerator.sextupole.Sextupole(length: Tensor, k2: Tensor | None = None, misalignment: Tensor | None = None, tilt: Tensor | None = None, tracking_method: Literal['linear', 'second_order'] = 'second_order', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

A sextupole element in a particle accelerator.

Parameters:

• length – Length in meters.

• k2 – Sextupole strength in 1/m^3.

• misalignment – Transverse misalignment in x and y directions in meters.

• tilt – Tilt angle of the quadrupole in x-y plane in radians.

• tracking_method – Method to use for tracking through the element. Note: By default, the sextupole is created with linear tracking method so it will not have second order effects.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

second_order_transfer_map(energy, species)

Generates the element’s second-order transfer map that describes how the beam and its particles are transformed when traveling through the element.

\(pout_{i} = \sum_{j,k} T_{ijk} pin_{j} pin_{k}\)

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7x7 Tensor T_ijk for further calculations.

supported_tracking_methods = ['linear', 'second_order']

track(incoming: Beam) → Beam

Track particles through the element. The input can be a ParameterBeam or a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.solenoid.Solenoid(length: Tensor, k: Tensor | None = None, misalignment: Tensor | None = None, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Solenoid magnet.

Implemented according to A.W.Chao P74

Parameters:

• length – Length in meters.

• k – Normalised strength of the solenoid magnet B0/(2*Brho). B0 is the field inside the solenoid, Brho is the momentum of central trajectory.

• misalignment – Misalignment vector of the solenoid magnet in x- and y-directions.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

split(resolution: Tensor) → list[Element]

Split the element into slices no longer than resolution. Some elements may not be splittable, in which case a list containing only the element itself is returned.

Parameters:

resolution – Length of the longest allowed split in meters.

Returns:

Ordered sequence of sliced elements.

supported_tracking_methods = ['linear']

class accelerator.space_charge_kick.SpaceChargeKick(effect_length: Tensor, grid_shape: tuple[int, int, int] = (32, 32, 32), grid_extent_x: Tensor | None = None, grid_extent_y: Tensor | None = None, grid_extent_tau: Tensor | None = None, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Applies the effect of space charge over a length effect_length, on the momentum (i.e. divergence and energy spread) of the beam. The positions are unmodified; this is meant to be combined with another lattice element (e.g. Drift) that does modify the positions, but does not take into account space charge. The integrated Green function method (https://journals.aps.org/prab/abstract/10.1103/PhysRevSTAB.9.044204) is used to compute the effect of space charge. This is similar to the method used in Ocelot. The main difference is that it solves the Poisson equation in the beam frame, while here we solve a modified Poisson equation in the laboratory frame (https://pubs.aip.org/aip/pop/article-abstract/15/5/056701/1016636/Simulation-of-beams-or-plasmas-crossing-at). The two methods are in principle equivalent.

Overview of the method:

• Compute the beam charge density on a grid.

• Convolve the charge density with a Green function (the integrated green function) to find the potential phi on the grid. The convolution uses the Hockney method for open boundaries (allocate 2x larger arrays and perform convolution using FFTs).

• Compute the corresponding electromagnetic fields and Lorentz force on the grid.

• Interpolate the Lorentz force to the particles and update their momentum.

Parameters:

• effect_length – Length over which the effect is applied in meters.

• grid_shape – Number of grid points in (x, y, tau) directions.

• grid_extent_x – Dimensions of the grid on which to compute space-charge, as multiples of sigma of the beam in the x direction (dimensionless).

• grid_extent_y – Dimensions of the grid on which to compute space-charge, as multiples of sigma of the beam in the y direction (dimensionless).

• grid_extent_tau – Dimensions of the grid on which to compute space-charge, as multiples of sigma of the beam in the tau direction (dimensionless).

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

track(incoming: ParticleBeam) → ParticleBeam

Tracks particles through the element. The input must be a ParticleBeam.

Parameters:

incoming – Beam of particles entering the element.

Returns:

Beam of particles exiting the element.

class accelerator.transverse_deflecting_cavity.TransverseDeflectingCavity(length: Tensor, voltage: Tensor | None = None, phase: Tensor | None = None, frequency: Tensor | None = None, misalignment: Tensor | None = None, tilt: Tensor | None = None, num_steps: int = 1, tracking_method: Literal['drift_kick_drift'] = 'drift_kick_drift', name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Transverse deflecting cavity element.

Parameters:

• length – Length in meters.

• voltage – Voltage of the cavity in volts. NOTE: This assumes the physical voltage. The sign is default for electron-like particles. For particles with a positive charge, the sign should be flipped.

• phase – Phase of the cavity in (radians / 2 pi).

• frequency – Frequency of the cavity in Hz.

• misalignment – Misalignment vector of the quadrupole in x- and y-directions.

• tilt – Tilt angle of the quadrupole in x-y plane [rad]. pi/4 for skew-quadrupole.

• num_steps – Number of drift-kick-drift steps to use for tracking through the element when tracking method is set to “drift_kick_drift”.

• tracking_method – Method to use for tracking through the element.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

supported_tracking_methods = ['drift_kick_drift']

track(incoming: Beam) → Beam

Track particles through the transverse deflecting cavity.

Parameters:

incoming – Beam entering the element.

Returns:

Beam exiting the element.

class accelerator.undulator.Undulator(length: Tensor, is_active: bool = False, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Element representing an undulator in a particle accelerator.

NOTE Currently behaves like a drift section but is plotted distinctively.

Parameters:

• length – Length in meters.

• is_active – Indicates if the undulator is active or not. Currently has no effect.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

supported_tracking_methods = ['linear']

class accelerator.vertical_corrector.VerticalCorrector(length: Tensor, angle: Tensor | None = None, name: str | None = None, sanitize_name: bool = False, device: device | None = None, dtype: dtype | None = None)

Verticle corrector magnet in a particle accelerator.

NOTE: This is modeled as a drift section with a thin-kick in the vertical plane.

Parameters:

• length – Length in meters.

• angle – Particle deflection angle in the vertical plane in rad.

• name – Unique identifier of the element.

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

property defining_features: list[str]

List of features that define the element. Used to compare elements for equality and to save them.

NOTE: When overriding this property, make sure to call the super method and extend the list it returns.

first_order_transfer_map(energy: Tensor, species: Species) → Tensor

Generates the element’s first order transfer map that describes how the beam and its particles are transformed when traveling through the element. The state vector consists of 6 values with a physical meaning. They represent a particle in the phase space with: - x: Position in x direction (m) relative to the reference particle - px: Horinzontal momentum normalized over the reference momentum

(dimensionless) \(px = P_x / P_0\)

• y: Position in y direction (m) relative to the reference particle

• py: Vertical momentum normalized over the reference momentum

  (dimensionless) \(py = P_y / P_0\)

• tau: Position in longitudinal direction (m) with the zero value set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle (dimensionless) \(p = \frac{\Delta E}{p_0 C}\)

As well as a seventh value used to add constants to some of the previous values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication, i.e. the augmented matrix as in an affine transformation.

Parameters:

• energy – Reference energy of the incoming beam.

• species – Species of the particles in the incoming beam.

Returns:

A 7x7 Matrix for further calculations.

property is_active: bool

property is_skippable: bool

Whether the element can be skipped during tracking. If True, the element’s transfer map is combined with the transfer maps of surrounding skipable elements.

plot(s: float, vector_idx: tuple | None = None, ax: Axes | None = None) → Axes

Plot a representation of this element into a matplotlib Axes at position s.

Parameters:

• s – Position of the object along s in meters.

• vector_idx – Index of the vector dimension to plot. If the model has more than one vector dimension, this can be used to select a specific one. In the case of present vector dimension but no index provided, the first one is used by default.

• ax – Axes to plot the representation into.

supported_tracking_methods = ['linear']