Particles¶

class particles.beam.Beam(*args: Any, **kwargs: Any)¶

Parent class to represent a beam of particles. You should not instantiate this class directly, but use one of the subclasses.

Cheetah uses a 7D vector to describe the state of a particle. It contains the 6D phase space vector (x, px, y, yp, tau, p) and an additional dimension (always 1) for convenient calculations.

The phase space vectors contain the canonical variables: - x: Position in x direction in meters. - px: Horizontal momentum normalized over the reference momentum (dimensionless).

$px = \frac{P_x}{P_0}$

y: Position in y direction in meters.
py: Vertical momentum normalized over the reference momentum (dimensionless).
$py = \frac{P_y}{P_0}$
tau: Position in longitudinal direction in meters, relative to the reference
particle. $\tau = ct - \frac{s}{\beta_0}$, where s is the position along the beamline. In this notation, particle ahead of the reference particle will have negative $\tau$.
p: Relative energy deviation from the reference particle (dimensionless).
$p = \frac{\Delta E}{p_0 C}$, where $p_0$ is the reference momentum. $\Delta E = E - E_0$

UNVECTORIZED_NUM_ATTR_DIMS = {'alpha_x': 0, 'alpha_y': 0, 'beta_x': 0, 'beta_y': 0, 'cov_taup': 0, 'cov_xpx': 0, 'cov_ypy': 0, 'emittance_x': 0, 'emittance_y': 0, 'energy': 0, 'mu_p': 0, 'mu_px': 0, 'mu_py': 0, 'mu_tau': 0, 'mu_x': 0, 'mu_y': 0, 'normalized_emittance_x': 0, 'normalized_emittance_y': 0, 'p0c': 0, 'relativistic_beta': 0, 'relativistic_gamma': 0, 's': 0, 'sigma_p': 0, 'sigma_px': 0, 'sigma_py': 0, 'sigma_tau': 0, 'sigma_x': 0, 'sigma_y': 0, 'total_charge': 0}¶

property alpha_x: Tensor¶: Alpha function in x direction, dimensionless.

property alpha_y: Tensor¶: Alpha function in y direction, dimensionless.

property beta_x: Tensor¶: Beta function in x direction in meters.

property beta_y: Tensor¶: Beta function in y direction in meters.

abstractmethod clone() → Beam¶: Return a cloned beam that does not share the underlying memory.

abstract property cov_pxp: Tensor¶: Covariance between px and p.

abstract property cov_pyp: Tensor¶: Covariance between py and p.

abstract property cov_taup: Tensor¶

abstract property cov_xp: Tensor¶: Covariance of between x and p.

abstract property cov_xpx: Tensor¶

abstract property cov_yp: Tensor¶: Covariance between y and p.

abstract property cov_ypy: Tensor¶

property dispersion_px: Tensor¶: Dispersion of the beam in px direction, dimensionless.

property dispersion_py: Tensor¶: Dispersion of the beam in py direction, dimensionless.

property dispersion_x: Tensor¶: Dispersion of the beam in x direction in m.

property dispersion_y: Tensor¶: Dispersion of the beam in y direction in m.

property emittance_x: Tensor¶: Uncoupled betatron emittance of the beam in x direction in m. This is computed with the dispersion correction.

property emittance_y: Tensor¶: Uncoupled betatron emittance of the beam in y direction in m. This is computed with the dispersion correction.

abstractmethod classmethod from_astra(path: str, device: device = None, dtype: dtype = None) → Beam¶: Load an Astra particle distribution as a Cheetah Beam.

abstractmethod classmethod from_ocelot(parray, device: device = None, dtype: dtype = None) → Beam¶: Convert an Ocelot ParticleArray parray to a Cheetah Beam.

Create beam that with given beam parameters.

Parameters:

mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on yp, dimensionless.
mu_tau – Center of the particle distribution on tau in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in yp direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p direction, dimensionless.
cov_xpx – Covariance between x and px.
cov_ypy – Covariance between y and py.
cov_taup – Covariance between tau and p.
cov_xp – Covariance between x and p.
cov_pxp – Covariance between px and p.
cov_yp – Covariance between y and p.
cov_pyp – Covariance between py and p.
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Create a beam from twiss parameters.

Parameters:

beta_x – Beta function in x direction in meters.
alpha_x – Alpha function in x direction in rad.
emittance_x – Emittance in x direction in m*rad.
beta_y – Beta function in y direction in meters.
alpha_y – Alpha function in y direction in rad.
emittance_y – Emittance in y direction in m*rad.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p direction, dimensionless.
cov_taup – Covariance between tau and p.
dispersion_x – Dispersion in x direction in meters.
dispersion_px – Dispersion in px direction, dimensionless.
dispersion_y – Dispersion in y direction in meters.
dispersion_py – Dispersion in py direction, dimensionless.
energy – Energy of the beam in eV.
total_charge – Total charge of the beam in C.
species – Particle species of the beam. Defaults to electron.
s – Position along the beamline of the reference particle in meters.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

abstract property mu_p: Tensor¶

abstract property mu_px: Tensor¶

abstract property mu_py: Tensor¶

abstract property mu_tau: Tensor¶

abstract property mu_x: Tensor¶

abstract property mu_y: Tensor¶

property normalized_emittance_x: Tensor¶: Normalized emittance of the beam in x direction in m.

property normalized_emittance_y: Tensor¶: Normalized emittance of the beam in y direction in m.

property p0c: Tensor¶: Reference momentum * speed of light in eV.

property projected_emittance_x: Tensor¶: Projected emittance of the beam in x direction in m. This is determined from the beam sizes without dispersion correction.

property projected_emittance_y: Tensor¶: Projected emittance of the beam in y direction in m. This is determined from the beam sizes without dispersion correction.

register_buffer_or_parameter(name: str, value: Tensor | Parameter) → 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.

property relativistic_beta: Tensor¶: Reference relativistic beta of the beam.

property relativistic_gamma: Tensor¶: Reference relativistic gamma of the beam.

abstract property sigma_p: Tensor¶

abstract property sigma_px: Tensor¶

abstract property sigma_py: Tensor¶

abstract property sigma_tau: Tensor¶

abstract property sigma_x: Tensor¶

abstract property sigma_y: Tensor¶

Create version of this beam that is transformed to new beam parameters.

Parameters:

mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on yp, dimensionless.
mu_tau – Center of the particle distribution on tau in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in yp direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p direction, dimensionless.
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
species – Particle species of the beam.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Beam of charged particles, where each particle is simulated.

Parameters:

mu – Mu vector of the beam with shape (…, 7).
cov – Covariance matrix of the beam with shape (…, 7, 7).
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

UNVECTORIZED_NUM_ATTR_DIMS = {'alpha_x': 0, 'alpha_y': 0, 'beta_x': 0, 'beta_y': 0, 'cov': 2, 'cov_taup': 0, 'cov_xpx': 0, 'cov_ypy': 0, 'emittance_x': 0, 'emittance_y': 0, 'energy': 0, 'mu': 1, 'mu_p': 0, 'mu_px': 0, 'mu_py': 0, 'mu_tau': 0, 'mu_x': 0, 'mu_y': 0, 'normalized_emittance_x': 0, 'normalized_emittance_y': 0, 'p0c': 0, 'relativistic_beta': 0, 'relativistic_gamma': 0, 's': 0, 'sigma_p': 0, 'sigma_px': 0, 'sigma_py': 0, 'sigma_tau': 0, 'sigma_x': 0, 'sigma_y': 0, 'total_charge': 0}¶

as_particle_beam(num_particles: int) → ParticleBeam¶

Convert this beam to a ParticleBeam beam with num_particles particles.

Parameters:: num_particles – Number of macro particles to create.
Returns:: ParticleBeam with num_particles particles and the same parameters as this beam.

clone() → ParameterBeam¶: Return a cloned beam that does not share the underlying memory.

property cov_pxp: Tensor¶: Covariance between px and p.

property cov_pyp: Tensor¶: Covariance between py and p.

property cov_taup: Tensor¶

property cov_xp: Tensor¶: Covariance of between x and p.

property cov_xpx: Tensor¶

property cov_yp: Tensor¶: Covariance between y and p.

property cov_ypy: Tensor¶

classmethod from_astra(path: str, device: device = None, dtype: dtype = None) → ParameterBeam¶: Load an Astra particle distribution as a Cheetah Beam.

classmethod from_ocelot(parray, device: device = None, dtype: dtype = None) → ParameterBeam¶: Load an Ocelot ParticleArray parray as a Cheetah Beam.

Create beam that with given beam parameters.

Parameters:

mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on yp, dimensionless.
mu_tau – Center of the particle distribution on tau in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in yp direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p direction, dimensionless.
cov_xpx – Covariance between x and px.
cov_ypy – Covariance between y and py.
cov_taup – Covariance between tau and p.
cov_xp – Covariance between x and p.
cov_pxp – Covariance between px and p.
cov_yp – Covariance between y and p.
cov_pyp – Covariance between py and p.
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Create a beam from twiss parameters.

Parameters:

beta_x – Beta function in x direction in meters.
alpha_x – Alpha function in x direction in rad.
emittance_x – Emittance in x direction in m*rad.
beta_y – Beta function in y direction in meters.
alpha_y – Alpha function in y direction in rad.
emittance_y – Emittance in y direction in m*rad.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p direction, dimensionless.
cov_taup – Covariance between tau and p.
dispersion_x – Dispersion in x direction in meters.
dispersion_px – Dispersion in px direction, dimensionless.
dispersion_y – Dispersion in y direction in meters.
dispersion_py – Dispersion in py direction, dimensionless.
energy – Energy of the beam in eV.
total_charge – Total charge of the beam in C.
species – Particle species of the beam. Defaults to electron.
s – Position along the beamline of the reference particle in meters.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

linspaced(num_particles: int) → ParticleBeam¶

Create a ParticleBeam beam with the same parameters as this beam and num_particles particles evenly distributed in the beam.

Parameters:: num_particles – Number of particles to create.
Returns:: ParticleBeam with num_particles particles.

property mu_p: Tensor¶

property mu_px: Tensor¶

property mu_py: Tensor¶

property mu_tau: Tensor¶

property mu_x: Tensor¶

property mu_y: Tensor¶

property sigma_p: Tensor¶

property sigma_px: Tensor¶

property sigma_py: Tensor¶

property sigma_tau: Tensor¶

property sigma_x: Tensor¶

property sigma_y: Tensor¶

Create version of this beam that is transformed to new beam parameters.

Parameters:

mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on yp, dimensionless.
mu_tau – Center of the particle distribution on tau in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in py direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p, dimensionless.
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
species – Particle species of the beam.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Beam of charged particles, where each particle is simulated.

Parameters:

particles – List of 7-dimensional particle vectors.
energy – Reference energy of the beam in eV.
particle_charges – Charges of the macroparticles in the beam in C.
survival_probabilities – Vector of probabilities that each particle has survived (i.e. not been lost), where 1.0 means the particle has survived and 0.0 means the particle has been lost. Defaults to ones.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

PRETTY_DIMENSION_LABELS = {'p': '$\\delta$', 'px': '$p_x$', 'py': '$p_y$', 'tau': '$\\tau$', 'x': '$x$', 'y': '$y$'}¶

UNVECTORIZED_NUM_ATTR_DIMS = {'alpha_x': 0, 'alpha_y': 0, 'beta_x': 0, 'beta_y': 0, 'cov_taup': 0, 'cov_xpx': 0, 'cov_ypy': 0, 'emittance_x': 0, 'emittance_y': 0, 'energy': 0, 'mu_p': 0, 'mu_px': 0, 'mu_py': 0, 'mu_tau': 0, 'mu_x': 0, 'mu_y': 0, 'normalized_emittance_x': 0, 'normalized_emittance_y': 0, 'p': 1, 'p0c': 0, 'particle_charges': 1, 'particles': 2, 'px': 1, 'py': 1, 'relativistic_beta': 0, 'relativistic_gamma': 0, 's': 0, 'sigma_p': 0, 'sigma_px': 0, 'sigma_py': 0, 'sigma_tau': 0, 'sigma_x': 0, 'sigma_y': 0, 'survival_probabilities': 1, 'tau': 1, 'total_charge': 0, 'x': 1, 'y': 1}¶

as_parameter_beam() → ParameterBeam¶

Convert the the beam to a ParameterBeam.

Returns:: ParameterBeam having the same parameters as this beam.

clone() → ParticleBeam¶: Return a cloned beam that does not share the underlying memory.

property cov_pxp: Tensor¶: Returns the covariance between px and p. $\sigma_{px, p}^2$. It is weighted by the survival probability of the particles.

property cov_pyp: Tensor¶: Returns the covariance between py and p. $\sigma_{py, p}^2$. It is weighted by the survival probability of the particles.

property cov_taup: Tensor¶: Returns the covariance between tau and p. $\sigma_{\tau, p}^2$. It is weighted by the survival probability of the particles.

property cov_xp: Tensor¶: Returns the covariance between x and p. $\sigma_{x, p}^2$. It is weighted by the survival probability of the particles.

property cov_xpx: Tensor¶: Returns the covariance between x and px. $\sigma_{x, px}^2$. It is weighted by the survival probability of the particles.

property cov_yp: Tensor¶: Returns the covariance between y and p. $\sigma_{y, p}^2$. It is weighted by the survival probability of the particles.

property cov_ypy: Tensor¶: Returns the covariance between y and py. $\sigma_{y, py}^2$. It is weighted by the survival probability of the particles.

property energies: Tensor¶: Energies of the individual particles.

classmethod from_astra(path: str, device: device = None, dtype: dtype = None) → ParticleBeam¶: Load an Astra particle distribution as a Cheetah Beam.

Generate Cheetah Beam of random particles from a multivariate normal distribution.

Parameters:

num_particles – Number of particles to generate.
mu – Mean of the multivariate normal distribution.
cov – Covariance matrix of the multivariate normal distribution.
energy – Energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Returns:

ParticleBeam with random particles.

classmethod from_elegant(file_path: Path | str, device: device = None, dtype: dtype = None) → ParticleBeam¶

Load an Elegant particle distribution as a Cheetah ParticleBeam.

Parameters:

file_path – Path to the SDDS file from which to load the Elegant beam.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

classmethod from_ocelot(parray, device: device = None, dtype: dtype = None) → ParticleBeam¶: Convert an Ocelot ParticleArray parray to a Cheetah Beam.

classmethod from_openpmd_file(path: str, energy: Tensor, device: device | None = None, dtype: dtype | None = None) → ParticleBeam¶: Load an openPMD particle group HDF5 file as a Cheetah ParticleBeam.

classmethod from_openpmd_particlegroup(particle_group: openpmd.ParticleGroup, energy: Tensor, device: device | None = None, dtype: dtype | None = None) → ParticleBeam¶

Create a Cheetah ParticleBeam from an openPMD ParticleGroup object.

Parameters:

particle_group – openPMD ParticleGroup object.
energy – Reference energy of the beam in eV.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Generate Cheetah Beam of random particles.

Parameters:

num_particles – Number of particles to generate.
mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on py , dimensionless.
mu_tau – Center of the particle distribution on tau (longitudinal) in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in py direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in longitudinal momentum, dimensionless.
cov_xpx – Correlation between x and px.
cov_ypy – Correlation between y and py.
cov_taup – Correlation between s and p.
cov_xp – Correlation between x and p.
cov_pxp – Correlation between px and p.
cov_yp – Correlation between y and p.
cov_pyp – Correlation between py and p.
energy – Energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Returns:

ParticleBeam with random particles.

Create a beam from twiss parameters.

Parameters:

beta_x – Beta function in x direction in meters.
alpha_x – Alpha function in x direction in rad.
emittance_x – Emittance in x direction in m*rad.
beta_y – Beta function in y direction in meters.
alpha_y – Alpha function in y direction in rad.
emittance_y – Emittance in y direction in m*rad.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p direction, dimensionless.
cov_taup – Covariance between tau and p.
dispersion_x – Dispersion in x direction in meters.
dispersion_px – Dispersion in px direction, dimensionless.
dispersion_y – Dispersion in y direction in meters.
dispersion_py – Dispersion in py direction, dimensionless.
energy – Energy of the beam in eV.
total_charge – Total charge of the beam in C.
species – Particle species of the beam. Defaults to electron.
s – Position along the beamline of the reference particle in meters.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

classmethod from_xyz_pxpypz(xp_coordinates: Tensor, energy: Tensor, particle_charges: Tensor | None = None, survival_probabilities: Tensor | None = None, s: Tensor | None = None, species: Species | None = None, device: device | None = None, dtype: dtype | None = None) → Tensor¶: Create a beam from a tensor of position and momentum coordinates in SI units. This tensor should have shape (…, num_particles, 7), where the last dimension is the moment vector $(x, p_x, y, p_y, z, p_z, 1)$.

linspaced(num_particles: int) → ParticleBeam¶

Create a new beam with the same parameters as this beam, but with num_particles particles evenly distributed in the beam.

Parameters:: num_particles – Number of particles to create.
Returns:: New beam with num_particles particles.

Generate Cheetah Beam of n linspaced particles.

Parameters:

n – Number of particles to generate.
mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on py , dimensionless.
mu_tau – Center of the particle distribution on tau (longitudinal) in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in py direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p, dimensionless.
energy – Energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Returns:

ParticleBeam with n linspaced particles.

property momenta: Tensor¶: Momenta of the individual particles.

property mu_p: Tensor | None¶

property mu_px: Tensor | None¶: Mean of the $px$ coordinates of the particles, weighted by their survival probability.

property mu_py: Tensor | None¶

property mu_tau: Tensor | None¶

property mu_x: Tensor | None¶: Mean of the $x$ coordinates of the particles, weighted by their survival probability.

property mu_y: float | None¶

property num_particles: int¶

Length of the macroparticle array.

NOTE: This does not account for lost particles.

property num_particles_survived: Tensor¶: Number of macroparticles that have survived.

property p: Tensor | None¶

plot_1d_distribution(dimension: Literal['x', 'px', 'y', 'py', 'tau', 'p'], bins: int = 100, bin_range: tuple[float] | None = None, smoothing: float = 0.0, plot_kws: dict | None = None, ax: Axes | None = None) → Axes¶

Plot a 1D histogram of the given dimension of the particle distribution.

Parameters:

dimension – Name of the dimension to plot. Should be one of (‘x’, ‘px’, ‘y’, ‘py’, ‘tau’, ‘p’).
bins – Number of bins to use for the histogram.
bin_range – Range of the bins to use for the histogram.
smoothing – Standard deviation of the Gaussian kernel used to smooth the histogram.
plot_kws – Additional keyword arguments to be passed to plot function of matplotlib used to plot the histogram data.
ax – Matplotlib axes object to use for plotting.

Returns:

Matplotlib axes object with the plot.

plot_2d_distribution(x_dimension: Literal['x', 'px', 'y', 'py', 'tau', 'p'], y_dimension: Literal['x', 'px', 'y', 'py', 'tau', 'p'], style: Literal['histogram', 'contour'] = 'histogram', bins: int = 100, bin_ranges: tuple[tuple[float]] | None = None, histogram_smoothing: float = 0.0, contour_smoothing: float = 3.0, pcolormesh_kws: dict | None = None, contour_kws: dict | None = None, ax: Axes | None = None) → Axes¶

Plot a 2D histogram of the given dimensions of the particle distribution.

Parameters:

x_dimension – Name of the x dimension to plot. Should be one of (‘x’, ‘px’, ‘y’, ‘py’, ‘tau’, ‘p’).
y_dimension – Name of the y dimension to plot. Should be one of (‘x’, ‘px’, ‘y’, ‘py’, ‘tau’, ‘p’).
style – Style of the plot. Should be one of (‘histogram’, ‘contour’).
bins – Number of bins to use for the histogram in both dimensions.
bin_ranges – Ranges of the bins to use for the histogram in each dimension.
smoothing – Standard deviation of the Gaussian kernel used to smooth the histogram.
pcolormesh_kws – Additional keyword arguments to be passed to pcolormesh function of matplotlib used to plot the histogram data.
contour_kws – Additional keyword arguments to be passed to contour function of matplotlib used to plot the histogram data.
ax – Matplotlib axes object to use for plotting.

Returns:

Matplotlib axes object with the plot.

plot_distribution(dimensions: tuple[str, ...] = ('x', 'px', 'y', 'py', 'tau', 'p'), bins: int = 100, bin_ranges: Literal['same'] | tuple[float] | list[tuple[float]] | None = None, plot_1d_kws: dict | None = None, plot_2d_kws: dict | None = None, axs: list[Axes] | None = None) → tuple[Figure, ndarray]¶

Plot of coordinates projected into 2D planes.

Parameters:

dimensions – Tuple of dimensions to plot. Should be a subset of (‘x’, ‘px’, ‘y’, ‘py’, ‘tau’, ‘p’).
contour – If True, overlay contour lines on the 2D histogram plots.
bins – Number of bins to use for the histograms.
bin_ranges – Ranges of the bins to use for the histograms. If set to “unit_same”, the same range is used for all dimensions that share the same unit. If set to None, ranges are determined automatically.
smoothing – Standard deviation of the Gaussian kernel used to smooth the histograms.
plot_1d_kws – Additional keyword arguments to be passed to ParticleBeam.plot_1d_distribution for plotting 1D histograms.
plot_2d_kws – Additional keyword arguments to be passed to ParticleBeam.plot_2d_distribution for plotting 2D histograms.
axs – List of Matplotlib axes objects to use for plotting. If set to None, a new figure is created. Must have the shape (len(dimensions), len(dimensions)).

Returns:

Matplotlib figure and axes objects with the plot.

plot_point_cloud(scatter_kws: dict | None = None, ax: Axes | None = None) → Axes¶

Plot a 3D point cloud of the spatial coordinates of the particles.

Parameters:

scatter_kws – Additional keyword arguments to be passed to the scatter plotting function of matplotlib.
ax – Matplotlib axes object to use for plotting.

Returns:

Matplotlib axes object with the plot.

property px: Tensor | None¶

property py: Tensor | None¶

randomly_subsampled(num_particles: int, adjust_particle_charges: bool = True, random_state: Generator | None = None) → ParticleBeam¶

Create a new beam with the same parameters as this beam, but with num_particles particles randomly sampled from the original beam.

Parameters:

num_particles – Number of particles to sample.
adjust_particle_charges – If True, the particle charges are adjusted to match the total charge of the old beam.
random_state – Random state to use for thinning. If None, a new random state is created.

Returns:

New beam with num_particles particles.

save_as_openpmd_h5(path: str) → None¶

Save the ParticleBeam as an openPMD particle group HDF5 file.

Parameters:: path – Path to the file where the beam should be saved.

property sigma_p: Tensor | None¶

property sigma_px: Tensor | None¶: Standard deviation of the $px$ coordinates of the particles, weighted by their survival probability.

property sigma_py: Tensor | None¶

property sigma_tau: Tensor | None¶

property sigma_x: Tensor | None¶: Standard deviation of the $x$ coordinates of the particles, weighted by their survival probability.

property sigma_y: Tensor | None¶

property tau: Tensor | None¶

to_openpmd_particlegroup() → openpmd.ParticleGroup¶

Convert the ParticleBeam to an openPMD ParticleGroup object.

NOTE: openPMD uses boolean particle status flags, i.e. alive or dead. Cheetah’s: survival probabilities are converted to status flags by thresholding at 0.5.
NOTE: At the moment this method only supports non-vectorised particle: distributions.

Returns:: openPMD ParticleGroup object with the ParticleBeam’s particles.

to_xyz_pxpypz() → Tensor¶: Extracts the position and momentum coordinates in SI units, from the beam’s particles, and returns it as a tensor with shape (…, num_particles, 7). For each particle, the obtained vector is $(x, p_x, y, p_y, z, p_z, 1)$.

property total_charge: Tensor¶: Total charge of the beam in C, taking into account particle losses.

Create version of this beam that is transformed to new beam parameters.

Parameters:

mu_x – Center of the particle distribution on x in meters.
mu_px – Center of the particle distribution on px, dimensionless.
mu_y – Center of the particle distribution on y in meters.
mu_py – Center of the particle distribution on py , dimensionless.
mu_tau – Center of the particle distribution on tau (longitudinal) in meters.
mu_p – Center of the particle distribution on p, dimensionless.
sigma_x – Sigma of the particle distribution in x direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless.
sigma_y – Sigma of the particle distribution in y direction in meters.
sigma_py – Sigma of the particle distribution in py direction, dimensionless.
sigma_tau – Sigma of the particle distribution in longitudinal direction, in meters.
sigma_p – Sigma of the particle distribution in p, dimensionless.
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
species – Species of the particles in the beam.

Returns:

ParticleBeam with transformed parameters.

Generate a particle beam with spatially uniformly distributed particles inside an ellipsoid, i.e. a waterbag distribution.

Note that:

The generated particles do not have correlation in the momentum directions, and by default a cold beam with no divergence is generated.

Parameters:

num_particles – Number of particles to generate.
radius_x – Radius of the ellipsoid in x direction in meters.
radius_y – Radius of the ellipsoid in y direction in meters.
radius_tau – Radius of the ellipsoid in tau (longitudinal) direction in meters.
sigma_px – Sigma of the particle distribution in px direction, dimensionless, default is 0.
sigma_py – Sigma of the particle distribution in py direction, dimensionless, default is 0.
sigma_p – Sigma of the particle distribution in p, dimensionless.
energy – Reference energy of the beam in eV.
total_charge – Total charge of the beam in C.
s – Position along the beamline of the reference particle in meters.
species – Particle species of the beam. Defaults to electron.
device – Device that the beam creates its tensors on.
dtype – Data type of the tensors created by the beam.

Returns:

ParticleBeam with uniformly distributed particles inside an ellipsoid.

property x: Tensor | None¶

property y: Tensor | None¶

Named particle species defined by charge and mass.

Parameters:

name – Name of the particle species. For species in Species.known, charge and mass are populated automatically. Custom particle species like ions can be defined by providing charge and mass.
num_elementary_charges – Charge of the particle species in units of elementary charge e. NOTE: Only one of num_elementary_charges and charge_coulomb should be provided.
charge_coulomb – Charge of the particle species in Coulombs. NOTE: Only one of num_elementary_charges and charge_coulomb should be provided.
mass_eV – Mass of the particle species in eV. NOTE: Only one of mass_eV and mass_kg should be provided.
mass_kg – Mass of the particle species in kg. NOTE: Only one of mass_eV and mass_kg should be provided.

property charge_coulomb: Tensor¶: Charge of the particle species in Coulombs.

clone() → Species¶: Return a copy of the species.

known = {'antiproton': {'mass_eV': 938272089.4300001, 'num_elementary_charges': -1}, 'deuteron': {'mass_eV': 1875612945.0, 'num_elementary_charges': 1}, 'electron': {'mass_eV': 510998.95069, 'num_elementary_charges': -1}, 'positron': {'mass_eV': 510998.95069, 'num_elementary_charges': 1}, 'proton': {'mass_eV': 938272089.4300001, 'num_elementary_charges': 1}}¶

property mass_kg: Tensor¶: Mass of the particle species in kg.

register_buffer_or_parameter(name: str, value: Tensor | Parameter) → 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.