mbtrack2.tracking.particles module

Module where particles, bunches, beams and particles of trapped ions are described as objects

class Particle(mass: float, charge: float)

Bases: object

Define a particle object.

Attributes

massfloat

Total particle mass in [kg].

chargefloat

Electrical charge in [C].

mass: float

charge: float

property E_rest: float

Particle rest energy in [eV].

__init__(mass: float, charge: float) → None

class Electron

Bases: Particle

Define an electron.

__init__()

class Proton

Bases: Particle

Define a proton.

__init__()

class Ion(ion_mass: float, ion_charge: float)

Bases: Particle

Define an ion.

__init__(ion_mass: float, ion_charge: float)

class Bunch(ring: Synchrotron, mp_number: int | float = 1000, current: float = 0.001, track_alive: bool = True, alive: bool = True, load_from_file: str | None = None, load_suffix: str | None = None)

Bases: object

Define a bunch object.

Parameters

ring : Synchrotron object mp_number : float, optional

Macro-particle number.

currentfloat, optional

Bunch current in [A].

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase.

alivebool, optional

If False, the bunch is defined as empty.

load_from_filestr, optional

Name of bunch save file generated by save method. If None, the bunch is initialized using the input parameters. Otherwise, the bunch from the file is loaded and the other inputs are ignored. Default is None.

load_suffixstr or int, optional

Suffix to the group name used to load the data from the HDF5 file. Default is None.

Attributes

mp_numberint

Macro-particle number.

alivearray of bool of shape (mp_number,)

Array used to monitor which particle is dead or alive.

chargefloat

Bunch charge in [C].

charge_per_mpfloat

Charge per macro-particle in [C].

particle_numberint

Number of particles in the bunch.

currentfloat

Bunch current in [A].

is_emptybool

Return True if the bunch is empty.

meanarray of shape (6,)

Mean position of alive particles for each coordinates.

stdarray of shape (6,)

Standard deviation of the position of alive particles for each coordinates.

emitarray of shape (3,)

Bunch emittance for each plane [1].

skewarray of shape (6,)

Skew (3rd moment) of the position of alive particles for each coordinates.

kurtosisarray of shape (6,)

Kurtosis (4th moment) of the position of alive particles for each coordinates.

Methods

init_gaussian(cov=None, mean=None, **kwargs)

Initialize bunch particles with 6D gaussian phase space.

plot_phasespace(x_var=”tau”, y_var=”delta”, plot_type=”j”)

Plot phase space.

save(file_name)

Save bunch object data (6D phase space, current, and state) in an HDF5 file format.

load(file_name)

Load data from a HDF5 file recorded by Bunch save method.

References

[1] Wiedemann, H. (2015). Particle accelerator physics. 4th edition. Springer, Eq.(8.39) of p224.

__init__(ring: Synchrotron, mp_number: int | float = 1000, current: float = 0.001, track_alive: bool = True, alive: bool = True, load_from_file: str | None = None, load_suffix: str | None = None)

property mp_number: int

Macro-particle number

property charge_per_mp: float

Charge per macro-particle [C]

property charge: float

Bunch charge in [C]

property particle_number: int

Particle number

property current: float

Bunch current [A]

property is_empty: bool

Return True if the bunch is empty.

property mean: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the mean position of alive particles for each coordinates.

property std: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the standard deviation of the position of alive particles for each coordinates.

property skew: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the skew (3rd moment) of the position of alive particles for each coordinates.

property kurtosis: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the kurtosis (4th moment) of the position of alive particles for each coordinates.

property emit: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the bunch emittance for each plane.

property cs_invariant: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the average Courant-Snyder invariant of each plane.

To get non-zero longitudinal Courant-Snyder invariant, the longitudinal Twiss parameters need to be computed using the ring.get_longitudinal_twiss method.

init_gaussian(cov: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, mean: ndarray[tuple[int, ...], dtype[_ScalarType_co]] = array([0., 0., 0., 0., 0., 0.]), **kwargs)

Initialize bunch particles with 6D gaussian phase space. Covariance matrix is taken from [1] and dispersion is added following the method explained in [2].

Parameters

cov(6,6) array, optional

Covariance matrix of the bunch distribution

mean(6,) array, optional

Mean of the bunch distribution

References

[1] Wiedemann, H. (2015). Particle accelerator physics. 4th edition. Springer, Eq.(8.38) of p223. [2] http://www.pp.rhul.ac.uk/bdsim/manual-develop/dev_beamgeneration.html

binning(dimension: str = 'tau', n_bin: int = 75, return_full_length: bool = False) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Bin macro-particles.

Parameters

dimensionstr, optional

Dimension in which the binning is done. The default is “tau”.

n_binint, optional

Number of bins. The default is 75.

return_full_lengthbool, optional

If True (and self.track_alive), also assign bins to untracked macro-particles. The returned sorted_index has shape (self.mp_number,). Default is False.

Returns

binsarray of shape (n_bin + 1,)

Bins where the particles are sorted.

sorted_indexarray of shape (len(self),) or (self.mp_number,)

Bin number of each macro-particles.

profilearray of shape (n_bin,)

Number of marco-particles in each bin.

centerarray of shape (n_bin,)

Center of each bin.

plot_profile(ax: Axes | None = None, dimension: str = 'tau', n_bin: int = 75) → Axes

Plot bunch profile.

Parameters

axplt.Axes, optional

Axe where the plot is displayed.

dimensionstr, optional

Dimension to plot. The default is “tau”.

n_binint, optional

Number of bins. The default is 75.

Return

axAxes

Axes with the plot on it.

plot_phasespace(ax: Axes | None = None, x_var: str = 'tau', y_var: str = 'delta') → Axes

Plot phase space.

Parameters

axplt.Axes, optional

Axe where the plot is displayed.

x_varstr

Dimension to plot on horizontal axis.

y_varstr

Dimension to plot on vertical axis.

kindstr, {“scatter”, “kde”, “hist”, “hex”, “reg”, “resid”}

Kind of plot to draw. See seeborn documentation. The defualt value is “scatter”.

Return

axAxes

Axes with the plot on it.

save(file_name: str, suffix: str | None = None, mpi_comm: Any | None = None)

Save bunch object data (6D phase space, current, and state) in an HDF5 file format.

The output file is named as “<file_name>.hdf5”.

Parameters

file_namestr

Name of the output file.

suffixstr or int, optional

Suffix to the group name used to save the data into the HDF5 file. If None, it is not used.

mpi_commMPI communicator, optional

For internal use if mpi is used in Beam objects. Default is None.

load(file_name: str, suffix: str | int | None = None, track_alive: bool = True)

Load data from a HDF5 file recorded by Bunch save method.

Parameters

file_namestr

Path to the HDF5 file where the Bunch data is stored.

suffixstr or int, optional

Suffix to the group name used to load the data from the HDF5 file. If None, it is not used.

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase.

class Beam(ring: Synchrotron, bunch_list: list[Bunch] | None = None)

Bases: object

Define a Beam object composed of several Bunch objects.

Parameters

ring : Synchrotron object bunch_list : list of Bunch object, optional

Attributes

currentfloat

Total beam current in [A]

chargefloat

Total bunch charge in [C]

particle_numberint

Total number of particle in the beam

filling_patternbool array of shape (ring.h,)

Filling pattern of the beam

bunch_currentarray of shape (ring.h,)

Current in each bunch in [A]

bunch_chargearray of shape (ring.h,)

Charge in each bunch in [C]

bunch_particlearray of shape (ring.h,)

Particle number in each bunch

bunch_meanarray of shape (6, ring.h)

Mean position of alive particles for each bunch

bunch_stdarray of shape (6, ring.h)

Standard deviation of the position of alive particles for each bunch

bunch_emitarray of shape (6, ring.h)

Bunch emittance of alive particles for each bunch

mpi : Mpi object mpi_switch : bool

Status of MPI parallelisation, should not be changed directly but with mpi_init() and mpi_close()

bunch_indexarray of shape (len(self,))

Return an array with the positions of the non-empty bunches

Methods

init_beam(filling_pattern, current_per_bunch=1e-3, mp_per_bunch=1e3)

Initialize beam with a given filling pattern and marco-particle number per bunch. Then initialize the different bunches with a 6D gaussian phase space.

init_bunch_list_mpi(bunch, filling_pattern)

Initialize a beam using MPI parallelisation with a Bunch per core.

mpi_init()

Switch on MPI parallelisation and initialise a Mpi object

mpi_gather()

Gather beam, all bunches of the different processors are sent to all processors. Rather slow

mpi_share_distributions()

Compute the bunch profile and share it between the different bunches.

mpi_close()

Call mpi_gather and switch off MPI parallelisation

plot(var, option=None)

Plot variables with respect to bunch number.

save(file_name)

Save beam object data in an HDF5 file format.

load(file_name, mpi)

Load data from a HDF5 file recorded by Beam save method.

__init__(ring: Synchrotron, bunch_list: list[Bunch] | None = None)

property not_empty: Iterator

Return a generator to iterate over not empty bunches.

property distance_between_bunches: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array which contains the distance to the next bunch in units of the RF period (ring.T1)

update_distance_between_bunches()

Update the distance_between_bunches array

init_beam(filling_pattern: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[bool], current_per_bunch: float = 0.001, mp_per_bunch: int = 1000, track_alive: bool = True, mpi: bool = False)

Initialize beam with a given filling pattern and marco-particle number per bunch. Then initialize the different bunches with a 6D gaussian phase space.

If the filling pattern is an array of bool then the current per bunch is uniform, else the filling pattern can be an array with the current in each bunch.

Parameters

filling_patternnumpy array or list of length ring.h

Filling pattern of the beam, can be a list or an array of bool, then current_per_bunch is used. Or can be an array with the current in each bunch.

current_per_bunchfloat, optional

Current per bunch in [A]

mp_per_bunchfloat, optional

Macro-particle number per bunch

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase.

mpibool, optional

If True, only a single bunch is fully initialized on each core, the other bunches are initialized with a single marco-particle.

init_bunch_list_mpi(bunch: Bunch, filling_pattern: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[bool])

Initialize a beam using MPI parallelisation with a Bunch per core.

Parameters

bunchBunch object

The bunch given should probably depend on the mpi.rank so that each core can track a different bunch. Example: beam.init_bunch_list_mpi(bunch_list[comm.rank], filling_pattern)

filling_patternarray-like of bool of length ring.h

Filling pattern of the beam as a list or an array of bool.

update_filling_pattern()

Update the beam filling pattern.

property filling_pattern: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the filling pattern of the beam as bool

property bunch_index: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the positions of the non-empty bunches.

property bunch_current: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the current in each bunch in [A]

property bunch_charge: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the charge in each bunch in [C]

property bunch_particle: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the particle number in each bunch

property current: float

Total beam current in [A]

property charge: float

Total beam charge in [C]

property particle_number: int

Total number of particles in the beam

property bunch_mean: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the mean position of alive particles for each bunches

property bunch_std: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the standard deviation of the position of alive particles for each bunches

property bunch_emit: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the bunch emittance of alive particles for each bunches and each plane

property bunch_cs: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return an array with the average Courant-Snyder invariant for each bunch

mpi_init()

Switch on MPI parallelisation and initialise a Mpi object

mpi_gather()

Gather beam, all bunches of the different processors are sent to all processors. Rather slow

mpi_close()

Call mpi_gather and switch off MPI parallelisation

plot(var: str, option: str | None = None, ax: Axes | None = None) → Axes

Plot variables with respect to bunch number.

Parameters

varstr {“bunch_current”, “bunch_charge”, “bunch_particle”,

“bunch_mean”, “bunch_std”, “bunch_emit”}

Variable to be plotted.

optionstr, optional

If var is “bunch_mean”, “bunch_std”, or “bunch_emit”, option needs to be specified. For “bunch_mean” and “bunch_std”,

option = {“x”,”xp”,”y”,”yp”,”tau”,”delta”}.

For “bunch_emit”, option = {“x”,”y”,”s”}. The default is None.

axAxes, optional

Axes where the plot is displayed. If None, a new figure is created.

Return

axAxes

Axes with the plot on it.

save(file_name: str)

Save beam object data in an HDF5 file format.

The output file is named as “<file_name>.hdf5”.

Parameters

file_namestr

Name of the output file.

load(file_name: str, mpi: bool, track_alive: bool = True)

Load data from a HDF5 file recorded by Beam save method.

Parameters

file_namestr

Path to the HDF5 file where the Beam data is stored.

mpibool

If True, only a single bunch is fully initialized on each core, the other bunches are initialized with a single marco-particle.

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase. The default is True.

class IonParticles(ring: Synchrotron, mp_number: int, ion_element_length: float, track_alive: bool = False, alive: bool = True)

Bases: Bunch

Class representing a collection of ion particles.

Parameters:

mp_numberint

The number of particles.

ion_element_lengthfloat

The length of the ion segment.

ringSynchrotron class object

The ring object representing the accelerator ring.

track_alivebool, optional

Flag indicating whether to track the alive particles. Default is False.

alivebool, optional

Flag indicating whether the particles are alive. Default is True.

Attributes

chargefloat

Bunch charge in [C].

meanarray of shape (4,)

Charge-weighted mean values for x, xp, y and yp coordinates.

mean_xytuple of 2 float

Charge-weighted mean values for x and y coordinates.

stdarray of shape (4,)

Charge-weighted std values for x, xp, y and yp coordinates.

mean_std_xytuple of 4 float

Charge-weighted mean and std values for x and y coordinates.

Methods:

generate_as_a_distribution(electron_bunch, charge)

Generates the particle positions based on a normal distribution, taking distribution parameters from an electron bunch.

generate_from_random_samples(electron_bunch, charge)

Generates the particle positions and times based on random samples from electron positions.

__init__(ring: Synchrotron, mp_number: int, ion_element_length: float, track_alive: bool = False, alive: bool = True)

property mp_number: int

Macro-particle number

property charge: float

Bunch charge in [C]

_mean_weighted(coord: str) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

_mean_std_weighted(coord: str) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

property mean: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return charge-weighted mean values for x, xp, y and yp coordinates.

property mean_xy: tuple[float, float]

Return charge-weighted mean values for x and y coordinates.

property std: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return charge-weighted std values for x, xp, y and yp coordinates.

property mean_std_xy: tuple[float, float, float, float]

Return charge-weighted mean and std values for x and y coordinates.

generate_as_a_distribution(electron_bunch: Bunch, charge: float)

Generates the particle positions based on a normal distribution, taking distribution parameters from an electron bunch.

Parameters:

electron_bunchBunch

An instance of the Bunch class representing the electron bunch.

chargefloat

Total ion charge generated in [C].

generate_from_random_samples(electron_bunch: Bunch, charge: float)

Generates the particle positions and times based on random samples from electron positions in the bunch.

Parameters:

electron_bunchBunch

An instance of the Bunch class representing the electron bunch.

chargefloat

Total ion charge generated in [C].