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
Installation
Using docker
A docker image is available:
docker pull gitlab-registry.synchrotron-soleil.fr/pa/collective-effects/albums:latest
References
If used in a publication, please cite both:
Gamelin, A., Gubaidulin, V., Alves, M. B., & Olsson, T. (2024). Semi-analytical algorithms to study longitudinal beam instabilities in double rf systems. arXiv preprint arXiv:2412.06539.
ALBuMS Documentation
Submodules
albums.mbtrack2_to_pycolleff
Module with conversion function to go from mbtrack2 to pycolleff.
- synchrotron_to_pycolleff(synchrotron, I0, Vrf, bunch_number)[source]
Return a pycolleff Ring element from the synchrotron element data.
Parameters
- synchrotronmbtrack2.tracking.synchrotron.Synchrotron
Parameters description.
- I0float
Beam current in [A].
- Vrffloat
RF voltage in [V].
- bunch_numberint
Total number of bunches filled.
Returns
- ringpycolleff.colleff.Ring
pycolleff Ring object.
- cavityresonator_to_pycolleff(cavres, Impedance=True)[source]
Convenience method to export a CavityResonator to pycolleff.
Parameters
- cavresmbtrack2.tracking.rf.CavityResonator
CavityResonator object.
- Impedancebool, optional
If True, export as impedance (i.e. ImpedanceSource.Methods.ImpedanceDFT). If False, export as wake (i.e. ImpedanceSource.Methods.Wake). Default is True.
Returns
cav : pycolleff ImpedanceSource object
- impedance_to_pycolleff(impedance)[source]
Convenience method to export impedance to pycolleff. Only implemented for longitudinal impedance.
Parameters
- impedancembtrack2.impedance.wakefield.Impedance
Impedance object.
Returns
- imppycolleff.longitudinal_equilibrium.ImpedanceSource
pycolleff ImpedanceSource object
albums.optimiser
Module where the optimization functions are defined.
- evaluate_R(B, method, is_equilibrium=False)[source]
Evaluate the R-factor or equilibrium solution.
Parameters: - B: RobinsonModes instance - method: The method used for solving - is_equilibrium: Boolean indicating if equilibrium-only evaluation is performed
Returns: - Evaluation score (negative R-factor if successful, penalized score otherwise)
- optimize_R(ring, MC, HC, I0, psi0_HC, tau_boundary, bounds, is_equilibrium=False, **kwargs)[source]
General optimization for the R-factor or equilibrium.
Parameters: - ring: Ring configuration - MC: Main cavity parameters - HC: Harmonic cavity parameters - I0: Beam current - psi0_HC: Initial guess for psi_HC - tau_boundary: Boundary for tau - bounds: Bounds for psi_HC - is_equilibrium: Boolean flag for equilibrium-only optimization - kwargs: Additional configuration for the optimizer
Returns: - Optimal value of psi_HC or a fallback value (90 on failure)
- minimize_psi(ring, MC, HC, I0, psi0_HC, tau_boundary, bounds, **kwargs)[source]
Minimize the psi parameter for stability.
Parameters: - ring: Ring configuration - MC: Main cavity parameters - HC: Harmonic cavity parameters - I0: Beam current - psi0_HC: Initial guess for psi_HC - tau_boundary: Boundary for tau - bounds: Bounds for psi_HC - kwargs: Additional configuration for the optimizer
Returns: - Optimal value of psi_HC or np.nan on failure
albums.plot_func
Module with the core plotting functions.
- configure_plot(ax=None, title=None, xlabel=None, ylabel=None, grid=True, legend=True)[source]
Helper function to configure plot appearance.
- save_plot(name, method, plot_2D, tau_boundary=None)[source]
Helper function to save plots with consistent naming.
- create_grid(var1, var2, var1_unit, var2_unit)[source]
Helper function to create grids and scaled variables.
- plot_image(ax, data, extent, clabel, var1_grid, var2_grid, cmap='viridis', vmin=None, vmax=None, colorbar=True, contour=False, colorplot=True, contour_dict={})[source]
Helper function to handle 2D data visualization.
albums.robinson
Module to compute longitudinal instabilities in a double RF system.
- class RobinsonModes(ring, cavity_list, I0, tau_boundary=None)[source]
Bases:
objectClass to compute instabilities in a double RF system mainly based on the theory and algorithm developped in [1].
The original algorithm has been adapted to work with other methods to solve the self-consistent problem (i.e. Haissinski equation) [3,4,5,6] and to give an estimate of the threshold of l=1/PTBL instability [7].
See the solve method for details.
Parameters
- ringSynchrotron object
Ring parameters.
- cavity_listlist of CavityResonator objects
- A list which contains:
a CavityResonator for the main cavity in 1st position.
a CavityResonator for the harmonic cavity in 2nd position.
- I0float
Beam current in [A].
- tau_boundaryfloat, optinal
Integration boundary in [s]. If None, 0.1 * RF period is used. The default is None.
Attributes
xi : float
Methods
- solve()
Solve for a given settings of the double RF system.
- R_factor(method)
Touschek lifetime ratio.
References
[1] : Bosch, R. A., K. J. Kleman, and J. J. Bisognano. “Robinson instabilities with a higher-harmonic cavity.” Physical Review Special Topics-Accelerators and Beams 4.7 (2001): 074401.
[2] : Bosch, R. A., and C. S. Hsue. “Suppression of longitudinal coupled-bunch instabilities by a passive higher harmonic cavity.” Proceedings of International Conference on Particle Accelerators. IEEE, 1993.
[3] : Gamelin, A., Yamamoto, N. (2021). Equilibrium bunch density distribution with multiple active and passive RF cavities. IPAC’21 (MOPAB069).
[4] : Venturini, M. (2018). Passive higher-harmonic rf cavities with general settings and multibunch instabilities in electron storage rings. Physical Review Accelerators and Beams, 21(11), 114404.
[5] : Alves, Murilo B., and Fernando H. de Sá. “Equilibrium of longitudinal bunch distributions in electron storage rings with arbitrary impedance sources and generic filling patterns.” Physical Review Accelerators and Beams 26.9 (2023): 094402.
[6] : de Sá, F., & Alves, M. (2023). pycolleff and cppcolleff: modules for impedance analysis and wake-field induced instabilities evaluation. (Version 0.1.0) [Computer software]. https://doi.org/10.5281/zenodo.7974571
[7] : He, Tianlong. “Novel perturbation method for judging the stability of the equilibrium solution in the presence of passive harmonic cavities.” Physical Review Accelerators and Beams 25.9 (2022): 094402.
- solve(passive_harmonic_cavity=True, mode_coupling=True, auto_set_MC_theta=True, optimal_tunning=True, f_HOM=0, Z_HOM=0, method='Venturini', **kwargs)[source]
Solve for a given settings of the double RF system.
Parameters
- passive_harmonic_cavitybool, optional
If True, solve for a passive harmonic cavity. If False, solve for an active harmonic cavity. The default is True.
- mode_couplingbool, optional
If True, compute Robinson instabilities taking into account dipole-quadrupole mode coupling (only dipole and quadrupole modes). If False, compute Robinson instabilities without taking into account mode coupling (modes from dipole to octupole). The default is True.
- auto_set_MC_thetabool, optional
- For passive harmonic cavity only:
-if True, set the main cavity phase to cancel the losses in the harmonic cavity. -if False, keep input main cavity phase setting.
The default is True.
- optimal_tunningbool, optional
- For passive harmonic cavity:
-if True, set main cavity tuning to optimal. -if False, keep input main cavity tuning setting.
- For active harmonic cavity:
-if True, set main and harmonic cavity tuning to optimal. -if False, keep input main and harmonic cavity tuning setting. The default is True.
- f_HOMfloat or list of float, optional
Frequencies of the HOMs to evaluate in [Hz]. The default is 0.
- Z_HOMfloat or list of float, optional
Impedances of the HOMs at f_HOM in [ohm]. The default is 0.
- method{“Bosch”,”Venturini”, “Alves”}, optional
Choose the method used to solve the self-consistent problem (i.e. Haissinski equation):
“Bosch” corresponds to an implementation of the original
algorithm in [1]. It computes only the amplitude form factor and bunch length. The result can depend heavily on tau_boundary. - “Venturini” corresponds to the method described in [3-4]. It can deal with passive and active HC. - “Alves” corresponds to the method described in [5]. It can deal with arbitrary filling pattern and broad band impedance. The pycolleff package is needed for this method [6]. Only for passive HC.
For both “Venturini” and “Alves”, the bunch profile is computed which gives both amplitude and phase form factors. The default is “Venturini”.
Kwargs for method “Bosch”
- Passive harmonic cavity:
- max_counterint
Maximum number of iteration for the computation of form factors. Default is 200.
- Active harmonic cavity:
- auto_set_for_xibool
If True, set harmonic cavity setting to achive xi value. specified as in [1]. If False, keep input main and harmonic cavity setting. Default is False.
- xifloat
Value to achive if auto_set_for_xi is True. Default is None.
Kwargs for method “Venturini”
- F_initarray-like of float of shape (2,)
Initial form factors (MC, HC) to consider for synchronous phase calculation if auto_set_MC_theta is True. Default is [1,1].
- set_MC_phase_HCpassivebool
If True, set the main cavity phase to cancel the losses in the harmonic cavity using approxmiate relation. Default is False.
Kwargs for method “Alves”
- fillingarray-like of float of shape (ring.h,)
Filling pattern of the beam. Sum must be equal to one. Default is None, corresponding to uniform filling.
- impedanceImpedance object
Additional (broad band) longitudinal impedance to consider for the Haissiski equation. Default is None.
- F_initarray-like of float of shape (2,)
Initial form factors (MC, HC) to consider for synchronous phase calculation if auto_set_MC_theta is True. Default is [1,1].
- set_MC_phase_HCpassivebool
If True, set the main cavity phase to cancel the losses in the harmonic cavity using approximate relation. Default is False.
- use_GaussLMCIbool
If True, the Gaussian LMCI method is used to compute Robinson instabilities instead of Bosch’s equations. Default is False.
- use_PTBL_Hebool
If True, the He criteria is used to compute PTBL instability instead of Gaussian LMCI method. Default is False.
- **kwargs passed to LongitudinalEquilibrium.calc_longitudinal_equilibrium:
niter
tol
beta
m
print_flag
- **kwargs passed to LongitudinalEquilibrium.calc_mode_coupling:
max_azi
max_rad
Returns
- bunch_lengthfloat or None
RMS bunch length in [s].
- zero_frequencybool or None
True if zero frequency instability is predicted.
- robinsonarray of bool of shape (4,) or None
Bool of the arrays are True if the following instability is predicted: If mode_coupling:
Coupled dipole mode
Coupled quadrupole mode
Fast mode coupling by dipole mode
Fast mode coupling by quadrupole mode
- else:
Dipole mode
Quadrupole mode
Sextupole mode
Octupole mode
- HOMbool
True if HOM instability is predicted.
- Omegaarray of float or None
- If mode_coupling:
Coupled dipole angular frequency in unit of 2*pi*[Hz]
Coupled quadrupole angular frequency in unit of 2*pi*[Hz]
- else:
Dipole angular frequency in unit of 2*pi*[Hz]
Quadrupole angular frequency in unit of 2*pi*[Hz]
Sextupole angular frequency in unit of 2*pi*[Hz]
Octupole angular frequency in unit of 2*pi*[Hz]
- PTBLbool
True if PTBL instability is predicted. None is returned if method is “Bosch”.
- convergedbool or array of bool
Return True values if calculation has converged. In details: If form factor calculation or Haissinski equation resolution fails:
return False and other results are None
- If zero_frequency is True:
return True and other instability results than zero_frequency are None
- If mode_coupling is True:
return array of bool of shape (2,) for coupled dipole and quadrupole modes.
- If mode_coupling is False:
return array of bool of shape (4,) for dipole to octupole modes.
- solve_equilibrium_only(passive_harmonic_cavity=True, auto_set_MC_theta=True, optimal_tunning=True, method='Venturini', **kwargs)[source]
- R_factor(method)[source]
Touschek lifetime ratio as defined in [1].
Parameters
- method{“Bosch”,”Venturini”, “Alves”}
Method used in self.solve.
Returns
- Rfloat
Touschek lifetime ratio for methods “Veturini” or “Alves”. 1 if method is “Bosch” or solve has not converged.
Reference
[1] : Byrd, J. M., and M. Georgsson. “Lifetime increase using passive harmonic cavities in synchrotron light sources.” Physical Review Special Topics-Accelerators and Beams 4.3 (2001): 030701.
- property xi
Ratio of the harmonic cavity ‘force’ over the main cavity one. Near Eq. (7) in [1].
- _converge_form_factors(passive_harmonic_cavity=True, auto_set_MC_theta=True, optimal_tunning=True, method='Venturini', **kwargs)[source]
- _conv_ff_venturini(passive_harmonic_cavity=True, auto_set_MC_theta=True, optimal_tunning=True, **kwargs)[source]
albums.saveload
Module for save/load and utility functions.
albums.scan
Module where parameter scans and optimization scans are defined.
- __scan_1D(MC, HC, ring, psi_HC_vals, current, mode_coupling, tau_boundary, method, **kwargs)[source]
- scan_modes(MC, HC, ring, psi_HC_vals, current, mode_coupling, tau_boundary, method, **kwargs)[source]
- scan_psi_I0(name, MC, HC, ring, psi_HC_vals, currents, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_psi_RoQ(name, MC, HC, ring, psi_HC_vals, RoQ_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_RoQ_I0(name, MC, HC, ring, current_vals, RoQ_vals, psi0_HC, bounds, tau_boundary, method, plot_2D=None, save=True, scan_after_opti=True, psi_add_after_opti=-0.1, **other_kwargs)[source]
- scan_RoQ_I0_equilirium(name, MC, HC, ring, current_vals, RoQ_vals, psi0_HC, bounds, tau_boundary, method, plot_2D=None, save=True, **other_kwargs)[source]
- scan_RoQ_Q0(name, MC, HC, ring, Q0_vals, RoQ_vals, I0, psi0_HC, bounds, tau_boundary, method, plot_2D=None, save=True, scan_after_opti=True, psi_add_after_opti=-0.1, **other_kwargs)[source]
- scan_RoQ_Q0_equilirium(name, MC, HC, ring, Q0_vals, RoQ_vals, I0, psi0_HC, bounds, tau_boundary, method, plot_2D=None, save=True, **other_kwargs)[source]
- scan_psi_QL(name, MC, HC, ring, psi_HC_vals, QL_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_psi_MCdet(name, MC, HC, ring, psi_HC_vals, MCdet_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_psi_MC_Rs(name, MC, HC, ring, psi_HC_vals, MC_Rs_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_psi_MC_beta(name, MC, HC, ring, psi_HC_vals, MC_beta_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_psi_HC_Q0(name, MC, HC, ring, psi_HC_vals, HC_Q0_vals, RoQ, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_MC_Vc_HC_Vc_active(name, MC, HC, ring, MC_Vc_vals, HC_Vc_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_MC_Vc_MC_psi_active(name, MC, HC, ring, MC_Vc_vals, MC_psi_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]
- scan_MC_psi_HC_psi_active(name, MC, HC, ring, MC_psi_vals, HC_psi_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)[source]