About mbtrack2

mbtrack2

GitLab Release PyPI - Version PyPI - License Read the Docs

mbtrack2 is a coherent object-oriented framework written in python to work on collective effects in synchrotrons.

mbtrack2 is composed of different modules allowing to easily write scripts for single bunch or multi-bunch tracking using MPI parallelization in a transparent way. The base of the tracking model of mbtrack2 is inspired by mbtrack, a C multi-bunch tracking code initially developed at SOLEIL.

Features

Tracking capabilities

Single-particle dynamics

  • Single and multi-bunch 6D (x, xp, y, yp, τ, δ) macro-particle tracking with arbitrary filling patterns

  • Longitudinal and transverse optics maps, including non-linear chromaticity, amplitude-dependent tune shifts and higher-orders of momentum compaction factor

  • Lattice import from AT/pyAT

  • Synchrotron radiation and quantum excitation maps

  • RF cavity (ideal cosine voltage)

  • Bunch-by-bunch feedback (exponential and FIR filter-based models)

  • Physical apertures

  • Skew quadrupole

Collective effects

  • RF cavities with beam loading and feedback loops

  • Short-range wake fields (longitudinal, dipolar, quadrupolar, monopolar)

  • Long-range resistive-wall wake fields

  • Intrabeam scattering

  • Transverse space charge

  • Beam-ion interactions

  • Coherent Synchrotron Radiation

Parallel computation capabilities

  • Multi-process parallelization with MPI: the bunches are distributed across available processes, with no changes required to single-process scripts

  • Each process tracks only its assigned bunches, providing near-linear scaling with the number of processes up to the number of non-empty bunches

  • Synchronization primitives allow processes to exchange bunch statistics and distributions when tracking elements that require global beam knowledge (e.g. long-range wake fields)

Monitoring

  • Turn-by-turn recording of bunch and beam statistics (centroids, emittances, energy spread), longitudinal profiles, phase space snapshots, spectral data, cavity voltages and powers, wake potential, and ion distributions, all written to HDF5 with configurable buffering

  • Built-in plotting helpers for all recorded quantities, including streak plots for time-frequency analysis

  • Parallel-aware: monitors coordinate across MPI processes to produce a single, coherent output file

Impedance and wake models

  • Analytic impedance and wake function for different models: resonator, tapers, inductive and resistive wakes

  • Resistive-wall impedance for circular beam pipes, with support for multi-layer coatings

  • Coherent synchrotron radiation in free space and between parallel conducting plates

  • Framework for combining multiple impedance sources into a single model, weighted by the local optics functions at each source position

  • Import from external electromagnetic codes: CST, IW2D, ABCI, GdfidL, ECHO2D

Analytical computations

  • Coupled-bunch instability growth rates, mode spectra, and stability diagrams for longitudinal and transverse planes

  • Threshold and growth-rate estimates for resistive-wall and micro-bunching instabilities

  • Transverse tune shift from space charge for Gaussian bunches

  • Beam-ion instability: ion oscillation frequencies, ionization cross sections, critical ion mass, and fast beam-ion growth rates

Examples

Jupyter notebooks demonstrating mbtrack2 features are available in the example folder and can be opened online using google colab:

  • mbtrack2 base features Open In Colab

  • Dealing with RF cavities and longitudinal beam dynamics Open In Colab

  • Collective effects Open In Colab

  • Bunch by unch feedback Open In Colab

  • RF loops and feedbacks Open In Colab

  • Coherent Synchrotron Radiation (CSR) Open In Colab

  • Intrabeam Scattering (IBS) Open In Colab

Installation

Using pip (serial HDF5 I/O)

Run:

pip install mbtrack2

To test your installation run:

from mbtrack2 import *

With MPI-enabled h5py (parallel HDF5 I/O)

The standard pip install mbtrack2 wheel for h5py does not support parallel HDF5 I/O. If you need multiple MPI ranks to write monitor files simultaneously, build h5py from source against an MPI-enabled HDF5 library.

On Ubuntu/Debian, first install the required system packages:

sudo apt-get install libopenmpi-dev libhdf5-dev libhdf5-mpi-dev

Then set the following environment variables so h5py’s build system finds the parallel HDF5 library:

export CC=mpicc
export HDF5_MPI=ON
export HDF5_LIBDIR=/usr/lib/x86_64-linux-gnu/hdf5/openmpi/
export HDF5_INCLUDEDIR=/usr/include/hdf5/openmpi/

Install mbtrack2 and its dependencies, then rebuild h5py from source:

pip install mbtrack2
pip install --no-binary=h5py --force-reinstall "h5py>=3.6"

Using docker

A docker (built with parallel HDF5 support enabled) image is available:

docker pull gitlab-registry.synchrotron-soleil.fr/pa/collective-effects/mbtrack2

References

If used in a publication, please cite mbtrack2 paper and the zenodo archive for the corresponding code version (and any other paper in this list for more specific features).

DOI

mbtrack2 general features

A. Gamelin, W. Foosang, and R. Nagaoka, “mbtrack2, a Collective Effect Library in Python”, presented at the 12th Int. Particle Accelerator Conf. (IPAC’21), Campinas, Brazil, May 2021, paper MOPAB070.

RF cavities with beam loading and RF feedbacks

N. Yamamoto, A. Gamelin, and R. Nagaoka. “Investigation of Longitudinal Beam Dynamics With Harmonic Cavities by Using the Code Mbtrack.” Proc. 10th International Partile Accelerator Conference (IPAC’19), Melbourne, Australia, 19-24 May 2019. 2019.

Intrabeam scattering

V. Gubaidulin, S. F. Dellalou, A. Gamelin, S. Habet, L. S. Nadolski, and R. Nagaoka. “Interaction of intrabeam scattering, longitudinal wakefield and a passive harmonic rf cavity in SOLEIL II.” Journal of Physics: Conference Series. Vol. 3094. No. 1. IOP Publishing, 2025.