albums package

Submodules

albums.mbtrack2_to_pycolleff module

Module with conversion function to go from mbtrack2 to pycolleff.

synchrotron_to_pycolleff(synchrotron, I0, Vrf, bunch_number)

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)

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)

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

Module where the optimization functions are defined.

evaluate_R(B, method, is_equilibrium=False)

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)

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)

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

__get_vals(ring, MC, HC, I0, psi0_HC, tau_boundary, method, bounds, **kwargs)

__get_vals_equilibrium(ring, MC, HC, I0, psi0_HC, tau_boundary, method, bounds, **kwargs)

maximize_R(ring, MC, HC, I0, psi0_HC, tau_boundary, method, bounds, **kwargs)

maximize_R_equilibrium(ring, MC, HC, I0, psi0_HC, tau_boundary, method, bounds, **kwargs)

albums.plot_func module

Module with the core plotting functions.

configure_plot(ax=None, title=None, xlabel=None, ylabel=None, grid=True, legend=True)

Helper function to configure plot appearance.

save_plot(name, method, plot_2D, tau_boundary=None)

Helper function to save plots with consistent naming.

create_grid(var1, var2, var1_unit, var2_unit)

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={})

Helper function to handle 2D data visualization.

__plot(out, var1, var2, var1_unit, var2_unit, var1_label, var2_label, plot_2D, save, **kwargs)

Primary plotting function for 2D data.

__plot_modes(out, psi_HC_vals, mode_coupling)

Plots mode coupling dynamics.

__plot_opti(out, var1, var2, var1_unit, var2_unit, var1_label, var2_label, plot_2D, save, **kwargs)

Optimized plotting for specific optimization outputs.

albums.robinson module

Module to compute longitudinal instabilities in a double RF system.

class RobinsonModes(ring, cavity_list, I0, tau_boundary=None)

Bases: object

Class 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.

__init__(ring, cavity_list, I0, tau_boundary=None)

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)

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)

R_factor(method)

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].

_potential_decomposition()

_bunch_length(a, b, c)

_form_factors(f, m, bunch_length)

_robinson_frequency()

_dipole_coupled_bunch_growth_rate(f_HOM, Z_HOM, bunch_length, omega_r)

_dipole_coupled_bunch(f_HOM, Z_HOM, bunch_length, omega_r, landau)

_zero_frequency_no_coupling(mu, bunch_length)

_zero_frequency_instability(omega_r, bunch_length, mode_coupling)

_landau_threshold(omega_r, c, b)

_robinson_damping_rate(Omega, mu, bunch_length)

_coupled_bunch_mode1_damping_rate(Omega, mu, bunch_length)

_robinson_no_coupling(omega_r, bunch_length, landau_threshold)

_coupled_bunch_mode1(omega_r, bunch_length, landau_threshold)

_robinson_coupling(omega_r, bunch_length, landau_threshold, abs_val=True)

_converge_form_factors(passive_harmonic_cavity=True, auto_set_MC_theta=True, optimal_tunning=True, method='Venturini', **kwargs)

_conv_ff_passive_bosch(auto_set_MC_theta=True, optimal_tunning=True, **kwargs)

_conv_ff_active_bosch(optimal_tunning=True, **kwargs)

_conv_ff_venturini(passive_harmonic_cavity=True, auto_set_MC_theta=True, optimal_tunning=True, **kwargs)

_conv_ff_alves(passive_harmonic_cavity=True, auto_set_MC_theta=True, optimal_tunning=True, **kwargs)

_solve_core(bunch_length, a, b, c, mode_coupling, f_HOM, Z_HOM, method, **kwargs)

_omega_n(cavity)

_phi_pm(cavity, Omega, sign)

_A_tilde(Omega)

_B_tilde(Omega, bunch_length)

_D_tilde(Omega, bunch_length)

_a_tilde(Omega)

_b_tilde(Omega, bunch_length)

_d_tilde(Omega, bunch_length)

_ar_B11(Omega, bunch_length, omega_r)

_Omega_B13(Omega, alpha_r, bunch_length, omega_r, sign, abs_val=True, return_root=False)

_PTBL_alves(**kwargs)

_FMCI_alves(**kwargs)

_PTBL_He()

albums.saveload module

Module for save/load and utility functions.

save_hdf5(filename, data_dict)

Saves data dictionary to an HDF5 file.

load_hdf5(filename, keys)

Loads data from an HDF5 file given a list of keys.

save_out(name, out)

Save output data to an HDF5 file.

load_out(file)

Load output data from an HDF5 file.

save_out_opti(name, out)

Save optimization results to an HDF5 file.

load_out_opti(file)

Load optimization results from an HDF5 file.

albums.scan module

Module where parameter scans and optimization scans are defined.

initialize_arrays(var1, var2, mode_coupling)

__scan(func, var1, var2, **kwargs)

__scan_1D(MC, HC, ring, psi_HC_vals, current, mode_coupling, tau_boundary, method, **kwargs)

scan_modes(MC, HC, ring, psi_HC_vals, current, mode_coupling, tau_boundary, method, **kwargs)

__scan_opti(func, var1, var2, **kwargs)

__scan_after_opti(func, psi, var1, var2, psi_add, **kwargs)

__psi_I0(psi, I0, **kwargs)

scan_psi_I0(name, MC, HC, ring, psi_HC_vals, currents, method, tau_boundary=None, save=True, **other_kwargs)

__psi_RoQ(psi, RoQ, **kwargs)

scan_psi_RoQ(name, MC, HC, ring, psi_HC_vals, RoQ_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)

__opti_I0_RoQ(I0, RoQ, **kwargs)

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)

__opti_I0_RoQ_equilirium(I0, RoQ, **kwargs)

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)

__opti_Q0_RoQ(Q0, RoQ, **kwargs)

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)

__opti_Q0_RoQ_equilirium(Q0, RoQ, **kwargs)

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)

__psi_I0_RoQ(psi, I0, RoQ, **kwargs)

__psi_Q0_RoQ(psi, Q0, RoQ, **kwargs)

__psi_QL(psi, QL, **kwargs)

scan_psi_QL(name, MC, HC, ring, psi_HC_vals, QL_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)

__psi_MCdet(psi, det, **kwargs)

scan_psi_MCdet(name, MC, HC, ring, psi_HC_vals, MCdet_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)

__psi_MCRs(psi, Rs, **kwargs)

scan_psi_MC_Rs(name, MC, HC, ring, psi_HC_vals, MC_Rs_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)

__psi_MC_beta(psi, beta, **kwargs)

scan_psi_MC_beta(name, MC, HC, ring, psi_HC_vals, MC_beta_vals, I0, method, tau_boundary=None, save=True, **other_kwargs)

__psi_HC_Q0(psi, Q0, **kwargs)

scan_psi_HC_Q0(name, MC, HC, ring, psi_HC_vals, HC_Q0_vals, RoQ, I0, method, tau_boundary=None, save=True, **other_kwargs)

__MC_Vc_HC_Vc_active(MC_Vc, HC_Vc, **kwargs)

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)

__MC_Vc_MC_psi_active(MC_Vc, MC_psi, **kwargs)

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)

__MC_psi_HC_psi_active(MC_psi, HC_psi, **kwargs)

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)

__HC_beta_I0_active(HC_beta, I0, **kwargs)

scan_HC_beta_I0_active(name, MC, HC, ring, HC_beta_vals, I0_vals, method, tau_boundary=None, save=True, **other_kwargs)

__MC_psi_I0(psi, I0, **kwargs)

scan_MC_psi_I0(name, MC, HC, ring, psi_MC_vals, I0_vals, method, tau_boundary=None, save=True, **other_kwargs)