mbtrack2.tracking.monitors.monitors module

This module defines the different monitor class which are used to save data during tracking.

class Monitor

Bases: Element

Abstract Monitor class used for subclass inheritance to define all the different kind of monitors objects.

The Monitor class is based on h5py module to be able to write data on structured binary files. The class provides a common file where the different Monitor subclass can write.

Attributes

fileHDF5 file

Common file where all monitors, Monitor subclass elements, write the saved data. Based on class attribute _file_storage.

file_namestring

Name of the HDF5 file where the data is stored. Based on class attribute _file_name_storage.

Methods

monitor_init(group_name, save_every, buffer_size, total_size,

dict_buffer, dict_file, file_name=None, mpi_mode=True)

Method called to initialize Monitor subclass.

write()

Write data from buffer to the HDF5 file.

to_buffer(object_to_save)

Save data to buffer.

close()

Close the HDF5 file shared by all Monitor subclass, must be called by at least an instance of a Montior subclass at the end of the tracking.

track_bunch_data(object_to_save)

Track method to use when saving bunch data.

_file_name_storage = []

_file_storage = []

property file_name: str

Common file where all monitors, Monitor subclass elements, write the saved data.

property file: File

HDF5 file where the data is stored.

monitor_init(group_name: str, save_every: int | float, buffer_size: int | float, total_size: int | float, dict_buffer: dict, dict_file: dict, file_name: str | None = None, mpi_mode: bool = False, dict_dtype: dict | None = None)

Method called to initialize Monitor subclass.

Parameters

group_namestring

Name of the HDF5 group in which the data for the current monitor will be saved.

save_everyint or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

dict_bufferdict

dictionary with keys as the attribute name to save and values as the shape of the buffer to create to hold the attribute, like (key.shape, buffer_size)

dict_filedict

dictionary with keys as the attribute name to save and values as the shape of the dataset to create to hold the attribute, like (key.shape, total_size)

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

dict_dtypedict, optional

dictionary with keys as the attribute name to save and values as the dtype to use to save the values. If None, float is used for all attributes.

write()

Write data from buffer to the HDF5 file.

to_buffer(object_to_save: Any)

Save data to buffer.

Parameters

object_to_savepython object

Depends on the Monitor subclass, typically a Beam or Bunch object.

close()

Close the HDF5 file shared by all Monitor subclass, must be called by at least an instance of a Montior subclass at the end of the tracking.

track_bunch_data(object_to_save: Bunch | Beam, check_empty: bool = False)

Track method to use when saving bunch data.

Parameters

object_to_save : Beam or Bunch check_emptiness: bool

If True, check if the bunch is empty. If it is, then do nothing.

_abc_impl = <_abc._abc_data object>

class BunchMonitor(bunch_number: int, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

Bases: Monitor

Monitor a single bunch and save attributes (mean, std, emit, current, and cs_invariant).

Parameters

bunch_numberint

Bunch to monitor

save_everyint or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

Methods

track(object_to_save)

Save data

__init__(bunch_number: int, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

track(object_to_save: Bunch | Beam)

Save data

Parameters

object_to_save : Bunch or Beam object

_abc_impl = <_abc._abc_data object>

class PhaseSpaceMonitor(bunch_number: int, sample_number: int | float, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False, mp_number: int | float | None = None)

Bases: Monitor

Monitor a single bunch and save the full phase space.

Parameters

bunch_numberint

Bunch to monitor

sample_numberint or float

Number of macroparticle in the phase space to save. If less than the total number of macroparticles, the total number must be specified in optinal parameter mp_number and a random fraction of the bunch is saved.

save_everyint or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

mp_numberint or float, optional

Total number of macroparticle of the tracked bunch. Mandatory if sample_number != mp_number. Default is None.

Methods

track(object_to_save)

Save data

__init__(bunch_number: int, sample_number: int | float, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False, mp_number: int | float | None = None)

track(object_to_save: Beam | Bunch)

Save data

Parameters

object_to_save : Bunch or Beam object

to_buffer(bunch: Bunch)

Save data to buffer.

Parameters

bunch : Bunch object

_abc_impl = <_abc._abc_data object>

class BeamMonitor(h: int, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

Bases: Monitor

Monitor the full beam and save each bunch attributes (mean, std, emit and current).

Parameters

hint

Harmonic number of the ring.

save_everyint or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

Methods

track(beam)

Save data

__init__(h: int, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

track(beam: Beam)

Save data

Parameters

beam : Beam object

to_buffer(bunch: Bunch, bunch_num: int)

Save data to buffer, if mpi is being used.

Parameters

bunch : Bunch object bunch_num : int

to_buffer_no_mpi(beam: Beam)

Save data to buffer, if mpi is not being used.

Parameters

beam : Beam object

write(bunch_num: int)

Write data from buffer to the HDF5 file, if mpi is being used.

Parameters

bunch_num : int

write_no_mpi()

Write data from buffer to the HDF5 file, if mpi is not being used.

_abc_impl = <_abc._abc_data object>

class ProfileMonitor(bunch_number: int, save_every: int | float, buffer_size: int | float, total_size: int | float, dimensions: str | list[str] = 'tau', n_bin: int | list[int] = 75, file_name: str | None = None, mpi_mode: bool = False)

Bases: Monitor

Monitor a single bunch and save bunch profiles.

Parameters

bunch_numberint

Bunch to monitor.

save_everyint or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

dimensionsstr or list of str, optional

Dimensions to save.

n_binint or list of int, optional

Number of bin to use in each dimension.

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

Methods

track(object_to_save)

Save data.

__init__(bunch_number: int, save_every: int | float, buffer_size: int | float, total_size: int | float, dimensions: str | list[str] = 'tau', n_bin: int | list[int] = 75, file_name: str | None = None, mpi_mode: bool = False)

to_buffer(bunch: Bunch)

Save data to buffer.

Parameters

bunch : Bunch object

write()

Write data from buffer to the HDF5 file.

track(object_to_save: Bunch | Beam)

Save data.

Parameters

object_to_save : Bunch or Beam object

_abc_impl = <_abc._abc_data object>

class WakePotentialMonitor(bunch_number: int, wake_types: str | list[str], n_bin: int, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

Bases: Monitor

Monitor the wake potential from a single bunch and save attributes (tau, …).

Parameters

bunch_numberint

Bunch to monitor.

wake_typesstr or list of str

Wake types to save: “Wlong”, “Wxdip”, …

n_binint

Number of bin to be used to interpolate the wake potential on a fixed grid.

save_everyint or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

Methods

track(object_to_save, wake_potential_to_save)

Save data.

__init__(bunch_number: int, wake_types: str | list[str], n_bin: int, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

to_buffer(wp: WakePotential)

Save data to buffer.

Parameters

wp : WakePotential object

write()

Write data from buffer to the HDF5 file.

track(object_to_save: Bunch | Beam, wake_potential_to_save: WakePotential)

Save data.

Parameters

object_to_save : Bunch or Beam object wake_potential_to_save : WakePotential object

_abc_impl = <_abc._abc_data object>

class BunchSpectrumMonitor(ring: Synchrotron, bunch_number: int, mp_number: int | float, sample_size: int | float, save_every: int | float, total_size: int | float, buffer_size: int | float = 1, dim: str = 'all', n_fft: int | None = None, file_name: str | None = None, mpi_mode: bool = False, higher_orders: bool = False)

Bases: Monitor

Monitor the coherent and incoherent bunch spectrums.

Parameters

ring : Synchrotron object bunch_number : int

Bunch to monitor

mp_numberint or float

Total number of macro-particles in the bunch.

sample_sizeint or float

Number of macro-particles to be used for tune and FFT computation. This number cannot exceed mp_number.

save_everyint or float

Set the frequency of the save. The spectrums are computed every save_every call of the montior.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

buffer_sizeint or float, optional

Size of the save buffer. Default is 1.

dimstr, optional

Dimensions in which the spectrums have to be computed. Can be:

• “all”

• “tau”

• “x”

• “y”

• “xy” or “yx”

• “xtau” or “taux”

• “ytau” or “tauy”

n_fftint or float, optional

The number of points used for FFT computation, if n_fft is bigger than save_every zero-padding is applied. If None, save_every is used.

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

higher_ordersbool, optional

If True, save coherent spectrums for higher order moments (FFT of the std, skew and kurtosis components). Default is False.

Attributes

fft_resolutionfloat

Return the fft resolution in [Hz].

signal_resolutionfloat

Return the signal resolution in [Hz].

frequency_samplesarray of float

Return the fft frequency samples in [Hz].

Methods

track(bunch):

Save spectrum data.

__init__(ring: Synchrotron, bunch_number: int, mp_number: int | float, sample_size: int | float, save_every: int | float, total_size: int | float, buffer_size: int | float = 1, dim: str = 'all', n_fft: int | None = None, file_name: str | None = None, mpi_mode: bool = False, higher_orders: bool = False)

property fft_resolution: float

Return the fft resolution in [Hz].

It is defined as the sampling frequency over the number of samples.

property signal_resolution: float

Return the signal resolution in [Hz].

It is defined as the inverse of the signal length.

property frequency_samples: float

Return the fft frequency samples in [Hz].

track(object_to_save: Bunch | Beam)

Save spectrum data.

Parameters

object_to_save : Beam or Bunch object

to_buffer(bunch: Bunch)

A method to hold saved data before writing it to the output file.

write()

Write data from buffer to output file.

get_incoherent_spectrum(positions: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], float, float]

Compute the incoherent spectrum i.e. the average of the absolute value of the FT of the position of every particule of the bunch.

Returns

incoherentarray

Bunch incoherent spectrum.

mean_incoherentfloat

Mean frequency of the maximum of each individual particle spectrum in [Hz].

std_incoherentfloat

Standard deviation of the frequency of the maximum of each individual particle spectrum in [Hz].

get_coherent_spectrum(mean: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Compute the coherent spectrum i.e. the absolute value of the FT of the mean position of the bunch.

Returns

coherentarray

Bunch coherent spectrum.

_abc_impl = <_abc._abc_data object>

class BeamSpectrumMonitor(ring: Synchrotron, save_every: int | float, total_size: int | float, buffer_size: int | float = 1, dim: str = 'all', n_fft: int | None = None, file_name: str | None = None, mpi_mode: bool = False)

Bases: Monitor

Monitor coherent beam spectrum.

Parameters

ring : Synchrotron object save_every : int or float

Set the frequency of the save. The spectrums are computed every save_every call of the montior.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

buffer_sizeint or float, optional

Size of the save buffer. Default is 1.

dimstr, optional

Dimensions in which the spectrums have to be computed. Can be:

• “all”

• “tau”

• “x”

• “y”

• “xy” or “yx”

• “xtau” or “taux”

• “ytau” or “tauy”

n_fftint or float, optional

The number of points used for FFT computation, if n_fft is bigger than save_every zero-padding is applied. If None, save_every is used.

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

Attributes

fft_resolutionfloat

Return the fft resolution in [Hz].

signal_resolutionfloat

Return the signal resolution in [Hz].

frequency_samplesarray of float

Return the fft frequency samples in [Hz].

Methods

track(bunch):

Save spectrum data.

__init__(ring: Synchrotron, save_every: int | float, total_size: int | float, buffer_size: int | float = 1, dim: str = 'all', n_fft: int | None = None, file_name: str | None = None, mpi_mode: bool = False)

_abc_impl = <_abc._abc_data object>

property fft_resolution: float

Return the fft resolution in [Hz].

It is defined as the sampling frequency over the number of samples.

property signal_resolution: float

Return the signal resolution in [Hz].

It is defined as the inverse of the signal length.

property frequency_samples: float

Return the fft frequency samples in [Hz].

track(beam: Beam)

Save mean data.

Parameters

beam : Beam object

to_buffer(beam: Beam)

A method to hold saved data before writing it to the output file.

write()

Write data from buffer to output file.

get_beam_spectrum(mean: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Compute the beam coherent spectrum i.e. the absolute value of the FT of the mean position of every bunch.

Returns

coherentarray

The beam coherent spectrum.

class CavityMonitor(cavity_name: str, ring: Synchrotron, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

Bases: Monitor

Monitor a CavityResonator object and save attributes.

Parameters

cavity_namestr

Name of the CavityResonator object to monitor.

ring : Synchrotron object save_every : int or float

Set the frequency of the save. The data is saved every save_every call of the montior.

buffer_sizeint or float

Size of the save buffer.

total_sizeint or float

Total size of the save. The following relationships between the parameters must exist:

total_size % buffer_size == 0 number of call to track / save_every == total_size

file_namestring, optional

Name of the HDF5 where the data will be stored. Must be specified the first time a subclass of Monitor is instancied and must be None the following times.

mpi_modebool, optional

If True, open the HDF5 file in parallel mode, which is needed to allow several cores to write in the same file at the same time. If False, open the HDF5 file in standard mode.

Methods

track(beam, cavity)

Save data

_abc_impl = <_abc._abc_data object>

__init__(cavity_name: str, ring: Synchrotron, save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None, mpi_mode: bool = False)

track(beam: Beam, cavity: CavityResonator)

Save data

Parameters

beam : Beam object cavity : CavityResonator object

class IonMonitor(save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None)

Bases: Monitor

A class representing an ion monitor.

Parameters

save_everyint

The number of steps between each save operation.

buffer_sizeint

The size of the buffer to store intermediate data.

total_sizeint

The total number of steps to be simulated.

file_namestr, optional

The name of the HDF5 file to store the data. If not provided, a new file will be created. Defaults to None.

Methods

monitor_init(group_name, save_every, buffer_size, total_size, dict_buffer,

dict_file, file_name=None, dict_dtype=None)

Initialize the monitor object.

track(bunch)

Tracking method for the element.

Raises

ValueError

If total_size is not divisible by buffer_size.

_abc_impl = <_abc._abc_data object>

_n_monitors = count(0)

file = None

__init__(save_every: int | float, buffer_size: int | float, total_size: int | float, file_name: str | None = None)

monitor_init(group_name: str, save_every: int | float, buffer_size: int | float, total_size: int | float, dict_buffer: dict, dict_file: dict, file_name: str | None = None, dict_dtype: dict | None = None)

Initialize the monitor object.

Parameters

group_namestr

The name of the HDF5 group to store the data.

save_everyint

The number of steps between each save operation.

buffer_sizeint

The size of the buffer to store intermediate data.

total_sizeint

The total number of steps to be simulated.

dict_bufferdict

A dictionary containing the names and sizes of the attribute buffers.

dict_filedict

A dictionary containing the names and shapes of the datasets to be created.

file_namestr, optional

The name of the HDF5 file to store the data. If not provided, a new file will be created. Defaults to None.

dict_dtypedict, optional

A dictionary containing the names and data types of the datasets. Defaults to None.

Raises

ValueError

If total_size is not divisible by buffer_size.

track(object_to_save)

Track a Beam or Bunch object through this Element. This method needs to be overloaded in each Element subclass.

Parameters

beam : Beam or Bunch object