Accelerator¶

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

Physical aperture.

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.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

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_map(energy: Tensor) → Tensor¶

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: (in the trace space notation)

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.BPM(is_active: bool = False, name: str | 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.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

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_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

Accelerating cavity in a particle accelerator.

Parameters:

length – Length in meters.
voltage – Voltage of the cavity in volts.
phase – Phase of the cavity in degrees.
frequency – Frequency of the cavity in Hz.
name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

track(incoming: Beam) → Beam¶

Track particles through the cavity. The input can be a ParameterBeam or a ParticleBeam. For a cavity, this does a little more than just the transfer map multiplication done by most elements.

Parameters:: incoming – Beam of particles entering the element.
Returns:: Beam of particles exiting the element.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.CustomTransferMap(transfer_map: Tensor | Parameter, length: Tensor | None = None, name: str | None = None, device=None, dtype=torch.float32)¶

This element can represent any custom transfer map.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

Dipole magnet (by default a sector bending magnet).

Parameters:

length – Length in meters.
angle – Deflection angle in rad.
e1 – The angle of inclination of the entrance face [rad].
e2 – The angle of inclination of the exit face [rad].
tilt – Tilt of the magnet in x-y plane [rad].
fringe_integral – Fringe field integral (of the enterance face).
fringe_integral_exit – (only set if different from fint) Fringe field integral of the exit face.
gap – The magnet gap [m], NOTE in MAD and ELEGANT: HGAP = gap/2
name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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 hx: Tensor¶

property is_active¶

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.Drift(length: Tensor | Parameter, name: str | None = None, device=None, dtype=torch.float32)¶

Drift section in a particle accelerator.

Note: the transfer map now uses the linear approximation. Including the R_56 = L / (beta**2 * gamma **2)

Parameters:

length – Length in meters.
name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.Element(name: str | None = None)¶

Base class for elements of particle accelerators.

Parameters:: name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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

forward(incoming: Beam) → Beam¶: Forward function required by torch.nn.Module. Simply calls track.

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.

length: Tensor = tensor([0.])¶

abstract plot(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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

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_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.HorizontalCorrector(length: Tensor | Parameter, angle: Tensor | Parameter | None = None, name: str | None = None, device=None, dtype=torch.float32)¶

Horizontal corrector magnet in a particle accelerator. Note: This is modeled as a drift section with

Parameters:

length – Length in meters.
angle – Particle deflection angle in the horizontal plane in rad.
name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.Marker(name: str | None = None)¶

General Marker / Monitor element

Parameters:: name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

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_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

Quadrupole magnet in a particle accelerator.

Parameters:

length – Length in meters.
k1 – Strength of the quadrupole in rad/m.
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.
name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

Rectangular bending magnet.

Parameters:

length – Length in meters.
angle – Deflection angle in rad.
e1 – The angle of inclination of the entrance face [rad].
e2 – The angle of inclination of the exit face [rad].
tilt – Tilt of the magnet in x-y plane [rad].
fringe_integral – Fringe field integral (of the enterance face).
fringe_integral_exit – (only set if different from fint) Fringe field integral of the exit face.
gap – The magnet gap [m], NOTE in MAD and ELEGANT: HGAP = gap/2
name – Unique identifier of the element.

Diagnostic screen in a particle accelerator.

Parameters:

resolution – Resolution of the camera sensor looking at the screen given as Tensor (width, height).
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).
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.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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: Tensor¶

property extent: Tensor¶

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_edges: tuple[Tensor, Tensor]¶

plot(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

property reading: Tensor¶

set_read_beam(value: Beam) → None¶

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.

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_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.Segment(elements: list[Element], name: str | None = None)¶

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.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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.

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

Returns:

Cheetah Segment representing the Bmad lattice.

classmethod from_lattice_json(filepath: str) → Segment¶

Load a Cheetah model from a JSON file.

Parameters:: filename – Name/path of the file to load the lattice from.
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, warnings: bool = True, device=None, dtype=torch.float32, **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.
warnings – Whether to print warnings when objects are not supported by Cheetah or converted with potentially unexpected behavior.

Returns:

Cheetah segment closely resembling the Ocelot cell.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

plot_overview(fig: Figure | None = None, beam: Beam | None = None, n: int = 10, resolution: float = 0.01) → None¶

Plot an overview of the segment with the lattice and traced reference particles.

Parameters:

fig – Figure to plot the overview into.
beam – Entering beam from which the reference particles are sampled.
n – Number of reference particles to plot. Must not be larger than number of particles passed in beam.
resolution – Minimum resolution of the tracking of the reference particles in the plot.

plot_reference_particle_traces(axx: Axes, axy: Axes, beam: Beam | None = None, num_particles: int = 10, resolution: float = 0.01) → None¶

Plot n reference particles 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.
beam – Entering beam from which the reference particles are sampled.
num_particles – Number of reference particles to plot. Must not be larger than number of particles passed in beam.
resolution – Minimum resolution of the tracking of the reference particles in the plot.

plot_twiss(beam: Beam, ax: Any | None = None) → None¶: Plot twiss parameters along the segment.

plot_twiss_over_lattice(beam: Beam, figsize=(8, 4)) → None¶: Plot twiss parameters in a plot over a plot of the lattice.

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, end: str) → Segment¶: Extract a subcell [start, end] from an this segment.

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

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_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

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.

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.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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¶

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.Undulator(length: Tensor | Parameter, is_active: bool = False, name: str | None = None, device=None, dtype=torch.float32)¶

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.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.

class accelerator.VerticalCorrector(length: Tensor | Parameter, angle: Tensor | Parameter | None = None, name: str | None = None, device=None, dtype=torch.float32)¶

Verticle corrector magnet in a particle accelerator. Note: This is modeled as a drift section with

Parameters:

length – Length in meters.
angle – Particle deflection angle in the vertical plane in rad.
name – Unique identifier of the element.

broadcast(shape: Size) → Element¶: Broadcast the element to higher batch dimensions.

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(ax: Axes, s: float) → None¶

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

Parameters:

ax – Axes to plot the representation into.
s – Position of the object along s in meters.

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.

transfer_map(energy: Tensor) → Tensor¶

x: Position in x direction
xp: Angle in x direction
y: Position in y direction
yp: Angle in y direction
s: Position in longitudinal direction, the zero value is set to the

reference position (usually the center of the pulse) - p: Relative energy deviation from the reference particle

As well as a seventh value used to add constants to some of the prior values if necessary. Through this seventh state, the addition of constants can be represented using a matrix multiplication.

Parameters:: energy – Reference energy of the Beam. Read from the fed-in Cheetah Beam.
Returns:: A 7x7 Matrix for further calculations.