mbtrack2.instability.instabilities module¶

General calculations about instability thresholds.

mbi_threshold(ring: Synchrotron, sigma: float, R: float, b: float) → float[source]¶

Compute the microbunching instability (MBI) threshold for a bunched beam considering the steady-state parallel plate model [1][2].

Parameters¶

ring : Synchrotron object sigma : float

RMS bunch length in [s]

Rfloat: dipole bending radius in [m]
bfloat: vertical distance between the conducting parallel plates in [m]

Returns¶

Ifloat: MBI current threshold in [A]

[1] : Y. Cai, “Theory of microwave instability and coherent synchrotron radiation in electron storage rings”, SLAC-PUB-14561 [2] : D. Zhou, “Coherent synchrotron radiation and microwave instability in electron storage rings”, PhD thesis, p112

cbi_threshold(ring: Synchrotron, I: float, Vrf: float, f: float, beta: float, Ncav: int = 1) → tuple[float, float, float][source]¶

Compute the longitudinal and transverse coupled bunch instability thresolds driven by HOMs [1].

Approximate formula, does not take into account variation with Q. For better estimate use lcbi_growth_rate.

Parameters¶

ring : Synchrotron object I : float

Total beam current in [A].

Vrffloat: Total RF voltage in [V].
ffloat: Frequency of the HOM in [Hz].
betaarray-like of shape (2,): Horizontal and vertical beta function at the HOM position in [m].
Ncavint, optional: Number of RF cavity.

Returns¶

Zlongfloat: Maximum longitudinal impedance of the HOM in [ohm].
Zxdipfloat: Maximum horizontal dipolar impedance of the HOM in [ohm/m].
Zydipfloat: Maximum vertical dipolar impedance of the HOM in [ohm/m].

References¶

[1] : Ruprecht, Martin, et al. “Calculation of Transverse Coupled Bunch Instabilities in Electron Storage Rings Driven By Quadrupole Higher Order Modes.” 7th Int. Particle Accelerator Conf.(IPAC’16), Busan, Korea.

Compute the longitudinal coupled bunch instability growth rate driven by an impedance for a given coupled bunch mode mu [1-2].

Use either a list of resonators (fr, RL, QL) or an Impedance object (Z).

Parameters¶

ring : Synchrotron object I : float

Total beam current in [A].

Mint: Nomber of bunches in the beam.
muint: Coupled bunch mode number (= 0, …, M-1).
synchrotron_tunefloat, optional: Synchrotron tune.
Vrffloat, optinal: Total RF voltage in [V] used to compute synchrotron tune if not given.
frfloat or list, optional: Frequency of the resonator in [Hz].
RLfloat or list, optional: Loaded shunt impedance of the resonator in [Ohm].
QLfloat or list, optional: Loaded quality factor of the resonator.
ZImpedance, optional: Longitunial impedance to consider.
bunch_lengthfloat, optional: Bunch length in [s]. Used to computed the form factor for a resonator impedance if given. Default is None.

Returns¶

float: Coupled bunch instability growth rate for the mode mu in [s-1].

References¶

[1] : Eq. 51 p139 of Akai, Kazunori. “RF System for Electron Storage Rings.” Physics And Engineering Of High Performance Electron Storage Rings And Application Of Superconducting Technology. 2002. 118-149.

[2] : Tavares, P. F., et al. “Beam-based characterization of higher-order-mode driven coupled-bunch instabilities in a fourth-generation storage ring.” NIM A (2022): 165945.

lcbi_growth_rate(ring: Synchrotron, I: float, M: int, synchrotron_tune: float | None = None, Vrf: float | None = None, fr: float | None = None, RL: float | None = None, QL: float | None = None, Z: float | None = None, bunch_length: float | None = None) → tuple[float, int, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]¶

Compute the maximum growth rate for longitudinal coupled bunch instability driven an impedance [1-2].

Use either a list of resonators (fr, RL, QL) or an Impedance object (Z).

Parameters¶

ring : Synchrotron object I : float

Total beam current in [A].

Mint: Nomber of bunches in the beam.
synchrotron_tunefloat, optional: Synchrotron tune.
Vrffloat, optional: Total RF voltage in [V] used to compute synchrotron tune if not given.
frfloat or list, optional: Frequency of the HOM in [Hz].
RLfloat or list, optional: Loaded shunt impedance of the HOM in [Ohm].
QLfloat or list, optional: Loaded quality factor of the HOM.
ZImpedance, optional: Longitunial impedance to consider.
bunch_lengthfloat, optional: Bunch length in [s]. Used to computed the form factor for a resonator impedance if given. Default is None.

Returns¶

growth_ratefloat: Maximum coupled bunch instability growth rate in [s-1].
muint: Coupled bunch mode number corresponding to the maximum coupled bunch instability growth rate.
growth_ratesarray: Coupled bunch instability growth rates for the different mode numbers in [s-1].

References¶

[2] : Tavares, P. F., et al. “Beam-based characterization of higher-order-mode driven coupled-bunch instabilities in a fourth-generation storage ring.” NIM A (2022): 165945.

lcbi_stability_diagram(ring: Synchrotron, I: float, M: int, modes: list[int], cavity_list: list[Any], detune_range: ndarray[tuple[int, ...], dtype[_ScalarType_co]], synchrotron_tune: float | None = None, Vrf: float | None = None, ax: Axes | None = None) → Axes[source]¶

Plot longitudinal coupled bunch instability stability diagram for a arbitrary list of CavityResonator objects around a detuning range.

Last object in the cavity_list is assumed to be the one with the variable detuning.

Parameters¶

ringSynchrotron object

Ring parameters.

Ifloat

Total beam current in [A].

Mint

Nomber of bunches in the beam.

modeslist

Coupled bunch mode numbers to consider.

cavity_listlist

list of CavityResonator objects to consider, which can be:

active cavities
passive cavities
HOMs
mode dampers

detune_rangearray

Detuning range (list of points) of the last CavityResonator object.

synchrotron_tunefloat, optional

Synchrotron tune.

Vrffloat, optinal

Total RF voltage in [V] used to compute synchrotron tune if not given.

Returns¶

axAxes: Show the shunt impedance threshold for different coupled bunch modes.

rwmbi_growth_rate(ring: Synchrotron, current: float, beff: float, rho_material: float, plane: str = 'x') → float[source]¶

Compute the growth rate of the transverse coupled-bunch instability induced by resistive wall impedance [1].

Parameters¶

ring : Synchrotron object current : float

Total beam current in [A].

befffloat: Effective radius of the vacuum chamber in [m].
rho_materialfloat: Resistivity of the chamber’s wall material in [Ohm.m].
planestr, optional: The plane in which the instability will be computed. Use ‘x’ for the horizontal plane, and ‘y’ for the vertical.

Reference¶

[1] Eq. (31) in R. Nagaoka and K. L. F. Bane, “Collective effects in a diffraction-limited storage ring”, J. Synchrotron Rad. Vol 21, 2014. pp.937-960

rwmbi_threshold(ring: Synchrotron, beff: float, rho_material: float, plane: str = 'x') → float[source]¶

Compute the threshold current of the transverse coupled-bunch instability induced by resistive wall impedance [1].

Parameters¶

ring : Synchrotron object beff : float

Effective radius of the vacuum chamber in [m].

rho_materialfloat: Resistivity of the chamber’s wall material in [Ohm.m].
planestr, optional: The plane in which the instability will be computed. Use ‘x’ for the horizontal plane, and ‘y’ for the vertical.

Reference¶

[1] Eq. (32) in R. Nagaoka and K. L. F. Bane, “Collective effects in a diffraction-limited storage ring”, J. Synchrotron Rad. Vol 21, 2014. pp.937-960

transverse_gaussian_space_charge_tune_shift(ring: Synchrotron, bunch_current: float, **kwargs) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]¶

Return the (maximum) transverse space charge tune shift for a Gaussian bunch in the linear approximation, see Eq.(1) of [1].

Parameters¶

ringSynchrotron object: Ring parameters.
bunch_currentfloat: Bunch current in [A].
sigma_sfloat, optional: RMS bunch length in [s]. Default is ring.sigma_0.
emit_xfloat, optional: Horizontal emittance in [m.rad]. Default is ring.emit[0].
emit_yfloat, optional: Vertical emittance in [m.rad]. Default is ring.emit[1].
use_latticebool, optional: If True, use beta fonctions along the lattice. If False, local values of beta fonctions are used. Default is ring.optics.use_local_values.
n_pointsint, optional: Number of points in the lattice to be considered if use_lattice == True. Default is 1000.
sigma_deltafloat, optional: Relative energy spread. Default is ring.sigma_delta.
gammafloat, optional: Relativistic Lorentz gamma. Default is ring.gamma.

Returns¶

tune_shiftarray of shape (2,): Horizontal and vertical space charge tune shift.

Reference¶

[1] : Antipov, S. A., Gubaidulin, V., Agapov, I., Garcia, E. C., & Gamelin, A. (2024). Space Charge and Future Light Sources. arXiv preprint arXiv:2409.08637.