About ALBuMS

ALBuMS

ALBuMS (Algorithms for Longitudinal Multibunch Beam Stability) is an open-source Python package for double rf system stability analysis.

Double rf systems are critical for achieving the parameters of 4th-generation light sources. These systems, comprising both main and harmonic rf cavities, relax statistical collective effects but also introduce instabilities, such as Robinson and periodic transient beam loading (PTBL) instabilities.

ALBuMS semi-analytical algorithms are designed to predict and analyze these instabilities.

The algorithms leverage recent advancements in the field, offering a computationally efficient and accurate complement to multibunch tracking simulations.

These algorithms can optimize rf cavity parameters in high-dimensional parameter spaces, thereby maximizing the Touschek lifetime.

Usage

A few examples of how to use ALBuMS are provided in the examples and benchmark_aladdin folders:

benchmark_aladdin

• Passive harmonic cavity case w/ standard Aladdin lattice

• Active harmonic cavity case w/ standard Aladdin lattice

• Active harmonic cavity case w/ LF20 Aladin lattice

• Passive harmonic cavity case w/ LF20 Aladdin lattice

examples

• SOLEIL II instability map

• SOLEIL II optimize RoQ/Q0

• Instabilities in single RF systems

The flow API (equilibrium → theories → result)

A computation is a flow: one beam-equilibrium method plus a subset of instability theories. Build an SystemState from the ring and cavity list, then call .run(flow, eq_opts). The beam current and every solver option live in an EquilibriumOptions; the shared theory inputs (HOM parameters, mode coupling) live in a TheoryOptions:

from albums import SystemState, DEFAULT_FLOWS, Flow
from albums import EquilibriumOptions, TheoryOptions
from albums import VenturiniEquilibrium, RobinsonCoupling, PTBLHe

system = SystemState(ring, [MC, HC])
eq_opts = EquilibriumOptions(I0=0.5)  # beam current [A] (+ optional solver options)

# a built-in default flow (equivalent to the former method="Venturini")
result = system.run(DEFAULT_FLOWS["Venturini"], eq_opts)

# or a custom flow: pick the equilibrium method + the theories you want
flow = Flow(VenturiniEquilibrium(), [RobinsonCoupling(), PTBLHe()])
result = system.run(flow, eq_opts, TheoryOptions(f_HOM=1e9, Z_HOM=10e3))

print(result.equilibrium.bunch_length, result.Touschek)
print(result.theories["robinson_coupling"].unstable)

result is a structured Result; result.theories[name] holds each theory’s TheoryResult (unstable, growth_rate, mode_frequency, converged). The solved Equilibrium (only) can be obtained with system.run_equilibrium(flow, eq_opts).

Not every theory is compatible with every equilibrium method (e.g. Bosch does not compute the phase form factor needed by the PTBL criteria). flow.validate() — called automatically by run() — rejects an invalid combination before any computation, naming the missing capability. The compatibility matrix below is generated from the code (albums.compatibility_matrix()), so it cannot drift:

Theory	Bosch	Venturini	Alves
zero_frequency	✅	✅	✅
robinson_coupling	✅	✅	✅
robinson_no_coupling	✅	✅	✅
hom_coupled_bunch	✅	✅	✅
bosch_mode1	✅	✅	✅
ptbl_he	❌	✅	✅
ptbl_alves	❌	❌	✅
robinson_glmci	❌	❌	✅

Regenerate with:

python -c "from albums.flow import compatibility_matrix; print(compatibility_matrix())"

Installation

Using docker

A docker image is available:

docker pull gitlab-registry.synchrotron-soleil.fr/pa/collective-effects/albums:latest

How to run a jupyter notebook from the docker image

Start the ALBuMS docker container:

sudo docker run -p 8888:8888 -it gitlab-registry.synchrotron-soleil.fr/pa/collective-effects/albums:latest

To save data computed with ALBuMS, share a folder using the -v option when starting the container i.e use:

sudo docker run -p 8888:8888 -v path_to_local_shared_folder:/home/dockeruser/shared -it gitlab-registry.synchrotron-soleil.fr/pa/collective-effects/albums:latest

Inside the container, run:

jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root

References

If used in a publication, please cite both:

• ALBuMS (using the Zenodo archive and DOI)

• The following article:

Gamelin, A., Gubaidulin, V., Alves, M. B., & Olsson, T. (2025). Semianalytical algorithms to study longitudinal beam instabilities in double rf systems. Physical Review Accelerators and Beams, 28(5), 054401.