simba.Modules.Beams.Particles package

Submodules

simba.Modules.Beams.Particles.centroids module

SIMBA Centroids Module

This module calculates the beam centroids of a particle distribution.

Classes:

centroids: Centroid calculations.

class centroids(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class for calculating centroids of a particle distribution.

property CEn: UnitValue

Mean beam energy in eV

Returns:: Mean energy
Return type:: UnitValue

property Ccp: UnitValue

Mean of total momentum in eV/c

Returns:: Mean of x
Return type:: UnitValue

property Cgamma: UnitValue

Mean of relativistic Lorentz factor

Returns:: Mean of gamma
Return type:: UnitValue

property Cp: UnitValue

Mean of total momentum in eV/c

Returns:: Mean of cp
Return type:: UnitValue

property Cpx: UnitValue

Mean of horizontal momentum in eV/c

Returns:: Mean of cpx
Return type:: UnitValue

property Cpy: UnitValue

Mean of vertical momentum in eV/c

Returns:: Mean of cpy
Return type:: UnitValue

property Cpz: UnitValue

Mean of longitudinal momentum in eV/c

Returns:: Mean of cpz
Return type:: UnitValue

property Ct: UnitValue

Mean of temporal distribution

Returns:: Mean of t
Return type:: UnitValue

property Cx: UnitValue

Mean of horizontal distribution

Returns:: Mean of x
Return type:: UnitValue

property Cxp: UnitValue

Mean of horizontal angle in rad

Returns:: Mean of xp
Return type:: UnitValue

property Cy: UnitValue

Mean of vertical distribution

Returns:: Mean of y
Return type:: UnitValue

property Cyp: UnitValue

Mean of vertical angle in rad

Returns:: Mean of yp
Return type:: UnitValue

property Cz: UnitValue

Mean of longitudinal distribution

Returns:: Mean of z
Return type:: UnitValue

property mean_cp: UnitValue

Mean of total momentum in eV/c

Returns:: Mean of cp
Return type:: UnitValue

property mean_cpx: UnitValue

Mean of horizontal momentum in eV/c

Returns:: Mean of cpx
Return type:: UnitValue

property mean_cpy: UnitValue

Mean of vertical momentum in eV/c

Returns:: Mean of cpy
Return type:: UnitValue

property mean_cpz: UnitValue

Mean of longitudinal momentum in eV/c

Returns:: Mean of cpz
Return type:: UnitValue

property mean_energy: UnitValue

Mean of beam energy in eV

Returns:: Mean of E
Return type:: UnitValue

property mean_gamma: UnitValue

Mean relativistic Lorentz factor

Returns:: Mean of gamma
Return type:: UnitValue

property mean_px: UnitValue

Mean of horizontal momentum in kg*m/s

Returns:: Mean of px
Return type:: UnitValue

property mean_py: UnitValue

Mean of vertical momentum in kg*m/s

Returns:: Mean of py
Return type:: UnitValue

property mean_pz: UnitValue

Mean of longitudinal momentum in kg*m/s

Returns:: Mean of pz
Return type:: UnitValue

property mean_t: UnitValue

Mean of temporal distribution

Returns:: Mean of t
Return type:: UnitValue

property mean_x: UnitValue

Mean of horizontal distribution

Returns:: Mean of x
Return type:: UnitValue

property mean_y: UnitValue

Mean of vertical distribution

Returns:: Mean of y
Return type:: UnitValue

property mean_z: UnitValue

Mean of longitudinal distribution

Returns:: Mean of t
Return type:: UnitValue

simba.Modules.Beams.Particles.emittance module

SIMBA Emittance Module

This module calculates the beam emittances of a particle distribution. Multiple emittance definitions are provided.

For slice emittance calculations, see slice

Classes:

emittance: Emittance calculations.

class emittance(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class for calculating emittances of a particle distribution.

property ecnx: UnitValue

Normalised horizontal emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: x-emittance corrected and normalised
Return type:: UnitValue

property ecny: UnitValue

Normalised vertical emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: y-emittance corrected and normalised
Return type:: UnitValue

property ecx: UnitValue

Horizontal emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: x-emittance corrected
Return type:: UnitValue

property ecy: UnitValue

Vertical emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: y-emittance corrected
Return type:: UnitValue

emittance(plane='x', corrected=False)[source]

Calculate the emittance for the plane provided; see emittance_calc().

Parameters:

plane (str) – Name of the plane to calculate; must be one of [x, y, z]
corrected (bool) – If true, correct with respect to dispersion

Returns:

The emittance

Return type:

UnitValue

Raises:

ValueError – If the plane provided is not one of [x, y, z]

emittance_calc(x, xp, p=None, units='m-rad')[source]

Calculate the emittance from two arrays using covariance()

Parameters:

x (UnitValue | np.ndarray) – Spatial column
xp (UnitValue | np.ndarray) – Angle column
p (UnitValue | np.ndarray, optional) – Momentum column; if provided, normalise the emittance with respect to this
units (str) – Unit value (deprecated?)

Returns:

Calculated emittance

Return type:

UnitValue

property enx: UnitValue

Normalised horizontal emittance of the beam in m-rad; see emittance_calc().

Returns:: x-emittance normalised
Return type:: UnitValue

property eny: UnitValue

Normalised vertical emittance of the beam in m-rad; see emittance_calc().

Returns:: y-emittance normalised
Return type:: UnitValue

property ex: UnitValue

Horizontal emittance of the beam in m-rad; see emittance_calc().

Returns:: x-emittance
Return type:: UnitValue

property ey: UnitValue

Vertical emittance of the beam in m-rad; see emittance_calc().

Returns:: y-emittance
Return type:: UnitValue

property horizontal_emittance: UnitValue

Horizontal emittance of the beam in m-rad; see emittance_calc().

Returns:: x-emittance
Return type:: UnitValue

property horizontal_emittance_90: UnitValue

Horizontal emittance of 90% of the beam in m-rad; see emittance_calc().

Returns:: 90% x-emittance
Return type:: UnitValue

property horizontal_emittance_corrected: UnitValue

Horizontal emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: x-emittance corrected
Return type:: UnitValue

property normalised_horizontal_emittance_corrected: UnitValue

Normalised horizontal emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: x-emittance corrected and normalised
Return type:: UnitValue

property normalised_vertical_emittance_corrected: UnitValue

Normalised vertical emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: y-emittance corrected and normalised
Return type:: UnitValue

normalized_emittance(plane='x', corrected=False)[source]

Calculate the normalised emittance for the plane provided; see emittance_calc().

Parameters:

plane (str) – Name of the plane to calculate; must be one of [x, y, z]
corrected (bool) – If true, correct with respect to dispersion

Returns:

The normalised emittance

Return type:

UnitValue

Raises:

ValueError – If the plane provided is not one of [x, y, z]

property normalized_horizontal_emittance: UnitValue

Normalised horizontal emittance of the beam in m-rad; see emittance_calc().

Returns:: x-emittance normalised
Return type:: UnitValue

property normalized_horizontal_emittance_90: UnitValue

Normalised horizontal emittance of 90% of the beam in m-rad; see emittance_calc().

Returns:: 90% x-emittance normalised
Return type:: UnitValue

property normalized_vertical_emittance: UnitValue

Normalised vertical emittance of the beam in m-rad; see emittance_calc().

Returns:: y-emittance normalised
Return type:: UnitValue

property normalized_vertical_emittance_90: UnitValue

Normalised vertical emittance of 90% of the beam in m-rad; see emittance_calc().

Returns:: 90% y-emittance normalised
Return type:: UnitValue

property vertical_emittance: UnitValue

Vertical emittance of the beam in m-rad; see emittance_calc().

Returns:: y-emittance
Return type:: UnitValue

property vertical_emittance_90: UnitValue

Vertical emittance of 90% of the beam in m-rad; see emittance_calc().

Returns:: 90% y-emittance
Return type:: UnitValue

property vertical_emittance_corrected: UnitValue

Vertical emittance of the beam in m-rad corrected for dispersion; see emittance_calc().

Returns:: y-emittance corrected
Return type:: UnitValue

simba.Modules.Beams.Particles.kde module

class kde(beam)[source]

Bases: object

get_vals_6d(beam)[source]

resample(npart, bandwidth=0.2, **kwargs)[source]

simba.Modules.Beams.Particles.minimumVolumeEllipse module

ellipse(center, radii, rotation, color='b')[source]

gaussian_fraction(s, n)[source]

getEllipsoidVolume(radii)[source]: Calculate the volume of the blob

getMinVolEllipse(P=None, tolerance=0.01)[source]

Find the minimum volume ellipsoid which holds all the points

Based on work by Nima Moshtagh

Here, P is a numpy array of N dimensional points like this: P = [[x,y,z,…], <– one point per line

[x,y,z,…], [x,y,z,…]]

Returns:: (center, radii, rotation)
Return type:: tuple

plotEllipsoid(center, radii, rotation, ax=None, plotAxes=False, cageColor='b', cageAlpha=0.2)[source]: Plot an ellipsoid

remove_Hull(P, desired_len)[source]

simba.Modules.Beams.Particles.mve module

class MVE(beam)[source]

Bases: object

CDF(x, x_grid, bandwidth=0.2, **kwargs)[source]

FWHM(X, Y, frac=0.5)[source]

PDF(x, x_grid, bandwidth=0.2, **kwargs)[source]

PDFI(x, x_grid, bandwidth=0.2, **kwargs)[source]

property density

property horizontal_mve_emittance

kde_bw_func(bandwidth, x, *args, **kwargs)[source]

kde_function(x, bandwidth=0.2, **kwargs)[source]: Kernel Density Estimation with Scipy

mve_emittance(x, xp, p=None)[source]

mvesliceAnalysis()[source]

property normalized_mve_horizontal_emittance

property normalized_mve_vertical_emittance

property slice_6D_Volume

property slice_density

property slice_normalized_mve_horizontal_emittance

property slice_normalized_mve_vertical_emittance

property vertical_mve_emittance

property volume

volume6D(x, y, t, xp, yp, cp)[source]

simba.Modules.Beams.Particles.sigmas module

SIMBA Sigmas Module

This module calculates the sigmas of a particle distribution.

Classes:

sigmas: Sigma calculations.

class sigmas(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class for calculating sigmas of a particle distribution.

property St: UnitValue

Temporal beam sigma <x^2>.

Returns:: sigma-t
Return type:: UnitValue

property Sx: UnitValue

Horizontal beam sigma <x^2>.

Returns:: sigma-x
Return type:: UnitValue

property Sy: UnitValue

Vertical beam sigma <x^2>.

Returns:: sigma-y
Return type:: UnitValue

property Sz: UnitValue

Longitudinal beam sigma <x^2>.

Returns:: sigma-z
Return type:: UnitValue

property linear_chirp_t_cpz: UnitValue

Linear chirp of the beam as std(t) / (max(cpz) - min(cpz))

Returns:: Linear chirp t/cpz
Return type:: UnitValue

property linear_chirp_t_pz: UnitValue

Linear chirp of the beam as std(t) / (max(pz) - min(pz))

Returns:: Linear chirp t/pz
Return type:: UnitValue

property linear_chirp_z: UnitValue

Linear chirp of the beam as v_z * t / momentum_spread

Returns:: Linear chirp in z
Return type:: UnitValue

property momentum_spread: UnitValue

Beam momentum spread

Returns:: sigma-x
Return type:: UnitValue

property sigma_cp: UnitValue

Beam momentum spread.

Returns:: Momentum spread
Return type:: UnitValue

property sigma_cp_eV: UnitValue

Beam momentum spread.

Returns:: Momentum spread
Return type:: UnitValue

property sigma_px: UnitValue

Horizontal momentum signa <px^2>

Returns:: sigma-px
Return type:: UnitValue

property sigma_py: UnitValue

Vertical momentum signa <px^2>

Returns:: sigma-py
Return type:: UnitValue

property sigma_pz: UnitValue

Longitudinal momentum signa <py^2>

Returns:: sigma-pz
Return type:: UnitValue

property sigma_t: UnitValue

Temporal beam sigma <t^2>.

Returns:: sigma-t
Return type:: UnitValue

property sigma_x: UnitValue

Horizontal beam sigma <x^2>.

Returns:: sigma-x
Return type:: UnitValue

property sigma_y: UnitValue

Vertical beam sigma <y^2>.

Returns:: sigma-y
Return type:: UnitValue

property sigma_z: UnitValue

Longitudinal beam sigma <x^2>.

Returns:: sigma-z
Return type:: UnitValue

simba.Modules.Beams.Particles.slice module

SIMBA Slice Module

This module calculates the slice properties of a particle distribution.

Classes:

slice: Slice calculations.

class slice(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class for calculating slice properties of a particle distribution.

property alpha_x: UnitValue

Get the slice Twiss horizontal alpha.

Returns:: Slice alpha
Return type:: UnitValue

property alpha_y: UnitValue

Get the slice Twiss vertical alpha.

Returns:: Slice alpha
Return type:: UnitValue

property beta_x: UnitValue

Get the slice Twiss horizontal beta.

Returns:: Slice beta
Return type:: UnitValue

property beta_y: UnitValue

Get the slice Twiss vertical beta.

Returns:: Slice beta
Return type:: UnitValue

bin_momentum(width=1000000)[source]

Bin the momentum distribution depending on the width provided. The histogram is calculated and various internal parameters relating to the temporal and momentum slices in the bunch are set.

Parameters:: width (float) – Width of momentum distribution
Return type:: None

bin_time()[source]

Bin the temporal distribution depending on slice_length. The temporal histogram is calculated and various internal parameters relating to the temporal slices in the bunch are set. The time_binned dictionary is then updated.

Return type:: None

property chirp: UnitValue

Get the longitudinal momentum chirp based on slice_current and slice_momentum in eV/s

Returns:: Longitudinal momentum chirp
Return type:: UnitValue

property chirp_m1: UnitValue

Get the longitudinal momentum chirp based on slice_current and slice_momentum in 1/m

Returns:: Longitudinal momentum chirp
Return type:: UnitValue

emitbins(x, y)[source]

Calculate the slice data for two arrays and transpose these with the slice momenta

Parameters:

x (UnitValue or np.ndarray) – First array
y (UnitValue or np.ndarray) – Second array

Returns:

Transpose of binned arrays with slice momenta

Return type:

np.ndarray

property enx: UnitValue

Get the normalised slice horizontal emittance.

Returns UnitValue

Normalised slice horizontal emittance

property eny: UnitValue

Get the slice vertical emittance.

Returns UnitValue

Normalised slice vertical emittance

property ex: UnitValue

Get the slice horizontal emittance.

Returns UnitValue

Slice horizontal emittance

property ey: UnitValue

Get the slice vertical emittance.

Returns UnitValue

Slice vertical emittance

property gamma_x: UnitValue

Get the slice Twiss horizontal gamma.

Returns:: Slice gamma
Return type:: UnitValue

property gamma_y: UnitValue

Get the slice Twiss vertical gamma.

Returns:: Slice gamma
Return type:: UnitValue

get_chirp_coeffs(order=3)[source]

Get the momentum chirps up to order-th order based on slice_current and slice_momentum

Returns:: Longitudinal momentum chirps
Return type:: Dict

have_we_already_been_binned()[source]

Check if time and momentum have already been binned by checking the values in time_binned

Returns:: True if beam has already been binned
Return type:: bool

property peak_current: UnitValue

Get the peak current (i.e. max of slice_current)

Returns:: Peak current
Return type:: UnitValue

set_slices(slices)[source]

Set the slices in the bunch based on the range of time values and the number of slices provided; calls bin_time().

Parameters:: slices (int) – Number of slices
Return type:: None

sliceAnalysis(density=False)[source]

Get various slice properties of the bunch.

Parameters:: density (bool) – If True, calculate the slice density from MVE
Returns:: The following slice parameters are returned: - slice_current at slice_max_peak_current_slice - standard deviation of slice_current - slice_relative_momentum_spread at slice_max_peak_current_slice - slice_normalized_horizontal_emittance at slice_max_peak_current_slice - slice_normalized_vertical_emittance at slice_max_peak_current_slice - slice_momentum at slice_max_peak_current_slice - slice_density if density is True
Return type:: tuple

property slice_alpha_x: UnitValue

Get the slice Twiss horizontal alpha.

Returns:: Slice alpha
Return type:: UnitValue

property slice_alpha_y: UnitValue

Get the slice Twiss vertical alpha.

Returns:: Slice alpha
Return type:: UnitValue

property slice_beta_x: UnitValue

Get the slice Twiss horizontal beta.

Returns:: Slice beta
Return type:: UnitValue

property slice_beta_y: UnitValue

Get the slice Twiss vertical beta.

Returns:: Slice beta
Return type:: UnitValue

property slice_bins: UnitValue

Get the slice temporal bins

Returns:: Slice temporal bins
Return type:: UnitValue

property slice_cpbins: UnitValue

Get the slice momentum bins

Returns:: Slice momentum bins
Return type:: UnitValue

property slice_current: UnitValue

Get the slice current based on the bunch charge and temporal binning.

Returns:: Slice current
Return type:: UnitValue

slice_data(data)[source]

Get the temporal slice data for a given axis

Parameters:: data (UnitValue | np.ndarray) – Array for which to calculate the slice data
Returns:: Slice data
Return type:: UnitValue

property slice_enx: UnitValue

Get the normalised slice horizontal emittance.

Returns UnitValue

Normalised slice horizontal emittance

property slice_eny: UnitValue

Get the slice vertical emittance.

Returns UnitValue

Normalised slice vertical emittance

property slice_ex: UnitValue

Get the slice horizontal emittance.

Returns UnitValue

Slice horizontal emittance

property slice_ey: UnitValue

Get the slice vertical emittance.

Returns UnitValue

Slice vertical emittance

property slice_gamma_x: UnitValue

Get the slice Twiss horizontal gamma.

Returns:: Slice gamma
Return type:: UnitValue

property slice_gamma_y: UnitValue

Get the slice Twiss vertical gamma.

Returns:: Slice gamma
Return type:: UnitValue

property slice_horizontal_emittance: UnitValue

Get the slice horizontal emittance.

Returns:: Slice horizontal emittance
Return type:: UnitValue

slice_length(slicelength)

Set the slice length in seconds; sets _slicelength and calls bin_time().

Parameters:: slicelength (UnitValue or float) – Slice length to set.
Return type:: None

property slice_max_peak_current_slice: int

Get the peak slice current slice from slice_current.

Returns:: Peak current slice
Return type:: UnitValue

property slice_momentum: UnitValue

Get the slice momentum.

Returns:: Slice momentum
Return type:: UnitValue

property slice_momentum_spread: UnitValue

Get the slice momentum spread (eV/c).

Returns:: Slice momentum spread
Return type:: UnitValue

property slice_normalized_horizontal_emittance: UnitValue

Get the normalised slice horizontal emittance.

Returns:: Normalised slice horizontal emittance
Return type:: UnitValue

property slice_normalized_vertical_emittance: UnitValue

Get the normalised slice vertical emittance.

Returns:: Normalised slice vertical emittance
Return type:: UnitValue

property slice_relative_momentum_spread: UnitValue

Get the slice momentum spread (relative)

Returns:: Slice momentum spread
Return type:: UnitValue

property slice_t: ndarray

Get the slice temporal bins

Returns:: Slice temporal bins
Return type:: np.ndarray

property slice_vertical_emittance: UnitValue

Get the slice vertical emittance.

Returns:: Slice vertical emittance
Return type:: UnitValue

property slice_z: ndarray

Get the slice longitudinal bins

Returns:: Slice longitudinal bins
Return type:: np.ndarray

slices(slices)

Set the number of slices; calls set_slices()

Parameters:: slices (int) – Number of slices

time_binned: Dict = {'beam': None, 'slice_length': None, 'slices': None}: Dictionary representing whether the beam has been binned

update_binned_parameters()[source]

Update the binned parameters in time_binned.

Return type:: None

simba.Modules.Beams.Particles.twiss module

SIMBA Twiss Module

This module calculates the Twiss properties of a particle distribution.

Classes:

twiss: Twiss calculations.

class twiss(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class for calculating Twiss properties of a particle distribution.

property alpha_x: UnitValue

Get the horizontal Twiss alpha function as -covariance(x, xp) / horizontal_emittance.

Returns:: Horizontal Twiss alpha
Return type:: UnitValue

property alpha_x_corrected: UnitValue

Get the horizontal Twiss beta corrected for dispersion as -covariance(xc, xpc) / horizontal_emittance_corrected.

Returns:: Corrected horizontal Twiss alpha
Return type:: UnitValue

property alpha_y: UnitValue

Get the vertical Twiss beta function as -covariance(y, yp) / horizontal_emittance.

Returns:: Vertical Twiss alpha
Return type:: UnitValue

property alpha_y_corrected: UnitValue

Get the vertical Twiss alpha corrected for dispersion as -covariance(yc, ypc) / vertical_emittance_corrected.

Returns:: Corrected vertical Twiss alpha
Return type:: UnitValue

property beta_x: UnitValue

Get the horizontal Twiss beta function as covariance(x, x) / horizontal_emittance.

Returns:: Horizontal Twiss beta
Return type:: UnitValue

property beta_x_corrected: UnitValue

Get the horizontal Twiss beta corrected for dispersion as covariance(xc, xc) / horizontal_emittance_corrected.

Returns:: Corrected horizontal Twiss beta
Return type:: UnitValue

property beta_y: UnitValue

Get the vertical Twiss beta function as covariance(y, y) / horizontal_emittance.

Returns:: Vertical Twiss beta
Return type:: UnitValue

property beta_y_corrected: UnitValue

Get the vertical Twiss beta corrected for dispersion as covariance(yc, yc) / vertical_emittance_corrected.

Returns:: Corrected vertical Twiss beta
Return type:: UnitValue

calculate_etax()[source]

Get the horizontal dispersion and its derivative.

Returns:

Horizontal dispersion
Derviative of horizontal dispersion
Mean of temporal distribution

Return type:

tuple

calculate_etay()[source]

Get the vertical dispersion and its derivative.

Returns:

Vertical dispersion
Derviative of vertical dispersion
Mean of temporal distribution

Return type:

tuple

property corrected: Dict

Get the following Twiss parameters (corrected for dispersion) as a dictionary keyed by name: - normalized_horizontal_emittance - horizontal_emittance - alpha_x - beta_x - normalized_vertical_emittance - vertical_emittance - alpha_y - beta_y

Returns:: Dictionary of corrected Twiss parameters
Return type:: Dict

property eta_x: UnitValue

Get the horizontal dispersion; see calculate_etax().

Returns:: Horizontal dispersion
Return type:: UnitValue

property eta_xp: UnitValue

Get the derivative of horizontal dispersion; see calculate_etax().

Returns:: Horizontal dispersion derivative
Return type:: UnitValue

property eta_y: UnitValue

Get the vertical dispersion; see calculate_etay().

Returns:: Vertical dispersion
Return type:: UnitValue

property eta_yp: UnitValue

Get the derivative of vertical dispersion; see calculate_etay().

Returns:: Vertical dispersion derivative
Return type:: UnitValue

property gamma_x: UnitValue

Get the horizontal Twiss alpha function as covariance(xp, xp) / horizontal_emittance.

Returns:: Horizontal Twiss gamma
Return type:: UnitValue

property gamma_x_corrected: UnitValue

Get the horizontal Twiss gamma corrected for dispersion as covariance(xpc, xpc) / horizontal_emittance_corrected.

Returns:: Corrected horizontal Twiss gamma
Return type:: UnitValue

property gamma_y: UnitValue

Get the vertical Twiss gamma function as covariance(yp, yp) / horizontal_emittance.

Returns:: Vertical Twiss gamma
Return type:: UnitValue

property gamma_y_corrected: UnitValue

Get the vertical Twiss gamma corrected for dispersion as covariance(ypc, ypc) / vertical_emittance_corrected.

Returns:: Corrected vertical Twiss gamma
Return type:: UnitValue

property horizontal_emittance: UnitValue

Get the horizontal emittance; see horizontal_emittance.

Returns:: Horizontal emittance
Return type:: UnitValue

property horizontal_emittance_corrected: UnitValue

Get the horizontal emittance corrected for dispersion; see horizontal_emittance_corrected.

Returns:: Corrected horizontal emittance
Return type:: UnitValue

property normal: Dict

Get the following Twiss parameters as a dictionary keyed by name: - normalized_horizontal_emittance - horizontal_emittance - alpha_x - beta_x - normalized_vertical_emittance - vertical_emittance - alpha_y - beta_y

Returns:: Dictionary of Twiss parameters
Return type:: Dict

property normalized_horizontal_emittance: UnitValue

Get the normalized horizontal emittance; see normalized_horizontal_emittance.

Returns:: Normalized horizontal emittance
Return type:: UnitValue

property normalized_vertical_emittance: UnitValue

Get the normalized vertical emittance; see normalized_vertical_emittance.

Returns:: Normalized vertical emittance
Return type:: UnitValue

property twiss_analysis: tuple

Get the calculated Twiss parameters as a tuple.

Returns:: Calculated Twiss parameters in the following order: - horizontal_emittance - alpha_x - beta_x - gamma_x - vertical_emittance - alpha_y - beta_y - gamma_y
Return type:: tuple

property twiss_analysis_corrected: tuple

Get the calculated Twiss parameters corrected for dispersion as a tuple.

Returns:: Calculated Twiss parameters in the following order: - horizontal_emittance_corrected - alpha_x_corrected - beta_x_corrected - gamma_x_corrected - vertical_emittance_corrected - alpha_y_corrected - beta_y_corrected - gamma_y_corrected
Return type:: tuple

property vertical_emittance: UnitValue

Get the vertical emittance; see vertical_emittance.

Returns:: Vertical emittance
Return type:: UnitValue

property vertical_emittance_corrected: UnitValue

Get the vertical emittance corrected for dispersion; see vertical_emittance_corrected.

Returns:: Corrected vertical emittance
Return type:: UnitValue

Module contents

SIMBA Particles Module

This module defines the class and utilities for storing a particle distribution.

Each beam consists of particles represented in 6-dimensional phase space (x, cpx, y, cpy, z, cpz), and appropriate transformations of these coordinates are also accessible as properties.

Functions are also available for rematching the beam based on Twiss parameters.

Classes:

Particles: Container for a particle distribution.

class Particles(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Class describing particles in 6D phase space [x (m), y (m), z (m) / t (s), px (kg*m/s), py (kg*m/s), pz (kg*m/s)].

The following objects are created based on this distribution:

centroids – see centroids
emittance – see emittance
kde – see kde
mve – see MVE
sigmas – see sigmas
slice – see slice
twiss – see twiss

The following properties are derived from these arrays:

fullbeam – the transpose of the 6D array.
[xp, yp] – horizontal and vertical angular distributions.
[xc, xpc, yc, ypc] – horizontal and vertical positions and

angular distributions, corrected for dispersion.

[cpx, cpy, cpz] – the beam momenta in eV/c.
deltap – fractional momentum deviation from the mean.
[p, cp] – total beam momentum in kg*m/s and eV/c, respectively.
[Ex, Ey, Ez] – beam energies in eV.
[Bx, By, Bz] – relativistic betas.
gamma – relativistic Lorentz factor.
Brho – magnetic rigidity.
BetaGamma – beam momentum as beta*gamma.
[kinetic_energy, mean_energy] – kinetic energy in J and its mean.
E0_eV – rest energy of the particles in eV.
Q – total charge of the bunch in C.

property BetaGamma: UnitValue

Get the beam momentum as beta*gamma

Returns:: Beam momentum
Return type:: UnitValue

property Brho: UnitValue

Get the magnetic rigidity in the longitudinal direction

Returns:: Magnetic rigidity
Return type:: UnitValue

property Bx: UnitValue

Get the horizontal relativistic beta

Returns:: The horizontal relativistic beta
Return type:: UnitValue

property By: UnitValue

Get the vertical relativistic beta

Returns:: The vertical relativistic beta
Return type:: UnitValue

property Bz: UnitValue

Get the longitudinal relativistic beta

Returns:: The longitudinal relativistic beta
Return type:: UnitValue

property E0_eV: UnitValue

Get the particle rest energy in eV; see particle_rest_energy_eV

Returns:: Particle rest energy
Return type:: UnitValue

property Ex: UnitValue

Get the horizontal beam energy in eV

Returns:: The horizontal beam energy
Return type:: UnitValue

property Ey: UnitValue

Get the longitudinal beam energy in eV

Returns:: The longitudinal beam energy
Return type:: UnitValue

property Ez: UnitValue

Get the longitudinal beam energy in eV

Returns:: The longitudinal beam energy
Return type:: UnitValue

property Q: UnitValue

Get the total charge of the bunch in C

Returns:: The total charge
Return type:: UnitValue

apply_mask(mask)[source]

Cut the beam with respect to a mask, removing some particles

Parameters:: mask (int | np.ndarray | list) – Mask to apply
Return type:: None

property centroids: centroids

Get the centroids from the distribution.

Returns:: Beam centroids
Return type:: centroids

charge: UnitValue | list | ndarray = None: Charge of the particle [C] – can be all the same, or variable

charge_sign_index: Dict = {1: -1, 2: 1, 3: 1, 4: 1}: Dictionary representing the index and charge of supported particles

property chargesign: list

Get the sign of charge all particles

Returns:: The charge signs of all particles
Return type:: list

clock: UnitValue | list | ndarray = None: Time unit of particles (ASTRA-type)

computeCorrelations(x, y)[source]

Get the covariances (cov(x,x), cov(x,y), cov(y,y)), see covariance()

Returns:

Covariances between the arrays provided

Return type:

tuple

Parameters:

x (UnitValue | ndarray)
y (UnitValue | ndarray)

covariance(u, up)[source]

Get the covariance from two arrays

Parameters:

u (np.ndarray or UnitValue) – First column
up (np.ndarray or UnitValue) – Second column

Returns:

Covariance (returns zero if arrays are not of same length)

Return type:

UnitValue or int

property cp: UnitValue

Get the total beam momentum in eV/C

Returns:: The beam momentum
Return type:: UnitValue

property cpx: UnitValue

Get the horizontal momentum in eV/c

Returns:: The horizontal momentum
Return type:: UnitValue

property cpy: UnitValue

Get the vertical momentum in eV/c

Returns:: The vertical momentum
Return type:: UnitValue

property cpz: UnitValue

Get the longitudinal momentum in eV/c

Returns:: The longitudinal momentum
Return type:: UnitValue

property deltap: UnitValue

Get the fractional beam momentum

Returns:: The fractional momentum
Return type:: UnitValue

property emittance: emittance

Get the emittance calculations from the distribution.

Returns:: Beam emittance
Return type:: emittance

property energy: UnitValue

Get the energy of the particles in eV

Returns:: The beam energy
Return type:: UnitValue

eta_corrected(u)[source]

Correct a column with respect to the beam momentum, subtracting eta_correlation() from u multiplied with p

Parameters:: u (np.ndarray or UnitValue) – Column to correct with respect to p
Returns:: Corrected column
Return type:: UnitValue or int

eta_correlation(u)[source]

Get the covariance between an array and the beam momentum p

Parameters:: u (np.ndarray or UnitValue) – Column to correlate with p
Returns:: Covariance
Return type:: UnitValue or int

property fullbeam: ndarray

Get the full beam as a transpose of all six columns.

Returns:: The beam object as [x,y,z,px,py,pz]
Return type:: np.ndarray

property gamma: UnitValue

Get the relativistic Lorentz factor of the beam distribution

Returns:: Lorentz factor
Return type:: UnitValue

get_particle_index(m, q)[source]

Get the index of a particle from mass and charge index.

Parameters:

m (float) – Mass of particle
q (int) – Charge of particle

Returns:

Particle index (see mass_index and charge_sign_index.

Return type:

int

property kde: kde

Get the kernel density estimator from the distribution.

Returns:: KDE
Return type:: kde

property kinetic_energy: UnitValue

Get the kinetic energy of the particles in J

Returns:: Kinetic energy of particles
Return type:: UnitValue

mass: UnitValue | list | ndarray = None: Mass of particles [kg] – can be all the same, or variable #TODO deprecated?

mass_index: Dict = {1: 9.1093837015e-31, 2: 9.1093837015e-31, 3: 1.67262192595e-27, 4: 1.67262192595e-27}: Dictionary representing the index and mass of supported particles

property mean_energy: UnitValue

Get the mean energy of the particles in J (the mean of kinetic_energy)

Returns:: Mean energy of particles
Return type:: UnitValue

property mve: Any

Get the minimum volume ellipse from the distribution.

Returns:: The MVE
Return type:: MVE

nmacro: int | ndarray | UnitValue = None: Number of macroparticles in this object

offset: UnitValue | list | ndarray = [0, 0, 0]: Beam positional offset in Cartesian coordinates

property p: UnitValue

Get the total beam momentum in kg*m/s

Returns:: The beam momentum
Return type:: UnitValue

particle_charge: UnitValue | list | ndarray = None: Charge of the particle [C] – can be all the same, or variable #TODO deprecated?

property particle_index: list

Get the particle index from the mass and charge of all particles.

Returns:: The particle index for all particle_mass and charge.
Return type:: list

particle_mass: UnitValue | list | ndarray = None: Mass of particles [kg] – can be all the same, or variable

particle_rest_energy: UnitValue | list | ndarray = None: Rest mass energy of the particle in kg

particle_rest_energy_eV: UnitValue | list | ndarray = None: Rest mass energy of the particle in eV

performTransformation(x, xp, beta=False, alpha=False, nEmit=False)[source]

Transform the arrays provided with respect to the Twiss and emittance functions given.

Parameters:

x (UnitValue or np.ndarray) – The first array
xp (UnitValue or np.ndarray) – The second array
beta (UnitValue or float or bool) – The beta function to transform the arrays; if False, use computeCorrelations()
alpha (UnitValue or float or bool) – The alpha function to transform the arrays; if False, use computeCorrelations()
nEmit (UnitValue or float or bool) – The emittance to transform the arrays; if False, use computeCorrelations()

Returns:

The transformed arrays

Return type:

tuple

performTransformationPeakISlice(xslice, xpslice, x, xp, beta=None, alpha=None, nEmit=None)[source]

Transform the arrays provided with respect to the Twiss and emittance functions given, or match the arrays with respect to their values at a given slice.

Parameters:

xslice (UnitValue or np.ndarray) – The first array at a given slice
xpslice (UnitValue or np.ndarray) – The second array at a given slice
x (UnitValue or np.ndarray) – The first array
xp (UnitValue or np.ndarray) – The second array
beta (UnitValue or float or bool) – The beta function to transform the arrays; if False, use computeCorrelations()
alpha (UnitValue or float or bool) – The alpha function to transform the arrays; if False, use computeCorrelations()
nEmit (UnitValue or float or bool) – The emittance to transform the arrays; if False, use computeCorrelations()

Returns:

The transformed arrays

Return type:

tuple

px: UnitValue | list | ndarray = None: Horizontal momentum of particles [kg*m/s]

py: UnitValue | list | ndarray = None: Vertical momentum of particles [kg*m/s]

pz: UnitValue | list | ndarray = None: Longitudinal momentum of particles [kg*m/s]

q_over_c: UnitValue = 5.344285992678308e-28 C/c: Elementary charge divided by speed of light

rematchXPlane(beta=None, alpha=None, nEmit=None)[source]

Rematch x and xp with respect to the Twiss and emittance functions given.

Parameters:

beta (UnitValue or float or bool) – The beta function to transform the arrays; if False, raise a warning
alpha (UnitValue or float or bool) – The alpha function to transform the arrays; if False, raise a warning
nEmit (UnitValue or float or bool) – The emittance to transform the arrays.

Return type:

None

rematchXPlanePeakISlice(beta=False, alpha=False, nEmit=False)[source]

Rematch x and xp with respect to the Twiss and emittance functions given, or their values at the peak current slice; see performTransformationPeakISlice().

Parameters:

beta (UnitValue or float or bool) – The beta function to transform the arrays; if False, raise a warning
alpha (UnitValue or float or bool) – The alpha function to transform the arrays; if False, raise a warning
nEmit (UnitValue or float or bool) – The emittance to transform the arrays.

Return type:

None

rematchYPlane(beta=False, alpha=False, nEmit=False)[source]

Rematch y and yp with respect to the Twiss and emittance functions given.

Parameters:

beta (UnitValue or float or bool) – The beta function to transform the arrays; if False, raise a warning
alpha (UnitValue or float or bool) – The alpha function to transform the arrays; if False, raise a warning
nEmit (UnitValue or float or bool) – The emittance to transform the arrays.

Return type:

None

rematchYPlanePeakISlice(beta=False, alpha=False, nEmit=False)[source]

Rematch y and yp with respect to the Twiss and emittance functions given, or their values at the peak current slice; see performTransformationPeakISlice().

Parameters:

beta (UnitValue or float or bool) – The beta function to transform the arrays; if False, raise a warning
alpha (UnitValue or float or bool) – The alpha function to transform the arrays; if False, raise a warning
nEmit (UnitValue or float or bool) – The emittance to transform the arrays.

Return type:

None

s: UnitValue | list | ndarray | float = None: s-position coordinates of particles [m]

set_total_charge(q)[source]

Set the total charge of the bunch in C.

This will also update the charge of the individual particles.

Parameters:: q (float) – The total charge
Return type:: None

property sigmas: sigmas

Get the beam sigmas from the distribution.

Returns:: Beam sigmas
Return type:: sigmas

sign(x)[source]

property slice: slice

Get the slice properties from the distribution.

Returns:: The slice properties
Return type:: slices

species_name: Dict = {1: 'electron', 2: 'positron', 3: 'proton', 4: 'hydrogen'}

speed_of_light: UnitValue = 299.792458 Mm/s: Speed of light

status: UnitValue | list | ndarray = None: Status of particles for OpenPMD-type distributions

t: UnitValue | list | ndarray = None: Time coordinates of particles [s]

theta: UnitValue | float = 0.0: Horizontal rotation of particle distribution with respect to the nominal axis [rad]

toffset: float | UnitValue = None: Temporal offset [s]

total_charge: UnitValue | float = None: Total charge of particle bunch [C]

property twiss: twiss

Get the Twiss parameters from the distribution.

Returns:: Twiss parameters
Return type:: twiss

x: UnitValue | list | ndarray = None: Horizontal coordinates of particles [m]

property xc: UnitValue

Get the horizontal distribution corrected with respect to dispersion

Returns:: The corrected horizontal distribution
Return type:: UnitValue

property xp: UnitValue

Get the horizontal momentum angle in rad

Returns:: The horizontal angle
Return type:: UnitValue

property xpc: UnitValue

Get the horizontal angle corrected with respect to dispersion

Returns:: The corrected horizontal angle
Return type:: UnitValue

y: UnitValue | list | ndarray = None: Vertical coordinates of particles [m]

property yc: UnitValue

Get the vertical distribution corrected with respect to dispersion

Returns:: The corrected vertical distribution
Return type:: UnitValue

property yp: UnitValue

Get the vertical momentum angle in rad

Returns:: The vertical angle
Return type:: UnitValue

property ypc: UnitValue

Get the vertical angle corrected with respect to dispersion

Returns:: The corrected vertical angle
Return type:: UnitValue

z: UnitValue | list | ndarray = None: Longitudinal coordinates of particles [m]