mbtrack2.utilities package¶
Submodules¶
mbtrack2.utilities.beamloading module¶
Module where the BeamLoadingEquilibrium class is defined.
- class mbtrack2.utilities.beamloading.BeamLoadingEquilibrium(ring, cavity_list, I0, auto_set_MC_theta=False, F=None, PHI=None, B1=- 0.2, B2=0.2)[source]¶
Bases:
object
Class used to compute beam equilibrium profile for a given storage ring and a list of RF cavities of any harmonic. The class assumes an uniform filling of the storage ring. Based on an extension of [1].
[1] 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.
ring : Synchrotron object cavity_list : list of CavityResonator objects I0 : beam current in [A]. auto_set_MC_theta : if True, allow class to change cavity phase for
CavityResonator objetcs with m = 1 (i.e. main cavities)
F : list of form factor amplitude PHI : list of form factor phase B1 : lower intergration boundary B2 : upper intergration boundary
- PTBL_threshold(I0, m=None, MC_index=0, HC_index=1)[source]¶
Compute the periodic transient beam loading (PTBL) instability threshold based on [1].
The beam_equilibrium method should be called before the PTBL_threshold one.
Eq. (22) and (23) have been modified for cosine voltage convention for the main cavity.
- I0float
Beam total current in [A].
- mint, optional
Number of bunches in the beam. The default is None. If None, uniform filling is assumed.
- MC_indexint, optional
Index of the main cavity in cavity_list. The default is 0.
- HC_indexint, optional
Index of the harmonic cavity in cavity_list. The default is 1.
- etafloat
Amplification factor, if bigger than 1 then the beam is possibly in the PTBL regime, Eq. (22) of [1].
- RQthfloat
R/Q threshold, Eq. (24) of [1].
- ffloat
f function, Eq. (23) of [1].
[1] : He, T. (2022). 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), 094402.
- beam_equilibrium(x0=None, tol=0.0001, method='hybr', options=None, plot=False, CM=True, verbiose=False)[source]¶
Solve system of non-linear equation to find the form factors F and PHI at equilibrum. Can be used to compute the equilibrium bunch profile.
x0 : initial guess tol : tolerance for termination of the algorithm method : method used by scipy.optimize.root to solve the system options : options given to scipy.optimize.root plot : if True, plot the equilibrium bunch profile CM : if True, the system imposes zero center of mass offset, if False, the system imposes energy balance. verbiose : if True, print out informations about convergence.
sol : OptimizeResult object representing the solution
- deltaVRF(z)[source]¶
Return the generator voltage minus beam loading voltage of the total RF system at position z
- to_solve(x, CM=True)[source]¶
System of non-linear equation to solve to find the form factors F and PHI at equilibrum. The system is composed of Eq. (B6) and (B7) of [1] for each cavity. If auto_set_MC_theta == True, the system also find the main cavity phase to impose energy balance or cancel center of mass offset. If CM is True, the system imposes zero center of mass offset, if False, the system imposes energy balance.
mbtrack2.utilities.misc module¶
This module defines miscellaneous utilities functions.
- mbtrack2.utilities.misc.beam_loss_factor(impedance, frequency, spectrum, ring)[source]¶
Compute “beam” loss factor using the beam spectrum, uses a sum instead of integral compared to loss_factor [1].
impedance : Impedance of type “long” frequency : array
Sample points of spectrum.
- spectrumarray
Beam spectrum to consider.
ring : Synchrotron object
- kloss_beamfloat
Beam loss factor in [V/C].
- [1]Handbook of accelerator physics and engineering, 3rd printing.
Eq (3) p239.
- mbtrack2.utilities.misc.double_sided_impedance(impedance)[source]¶
Add negative frequency points to single sided impedance spectrum following symetries depending on impedance type.
- impedanceImpedance object
Single sided impedance.
- mbtrack2.utilities.misc.effective_impedance(ring, imp, m, mu, sigma, M, tuneS, xi=None, mode='Hermite')[source]¶
Compute the effective (longitudinal or transverse) impedance. Formulas from Eq. (1) and (2) p238 of [1].
ring : Synchrotron object imp : Impedance object mu : int
coupled bunch mode number, goes from 0 to (M-1) where M is the number of bunches
- mint
head-tail (or azimutal/synchrotron) mode number
- sigmafloat
RMS bunch length in [s]
- Mint
Number of bunches.
- tuneSfloat
Synchrotron tune.
- xifloat, optional
(non-normalized) chromaticity
- mode: str, optional
type of the mode taken into account for the computation: -“Hermite” modes for Gaussian bunches
- Zefffloat
effective impedance in [ohm] or in [ohm/m] depanding on the impedance type.
[1] : Handbook of accelerator physics and engineering, 3rd printing.
- mbtrack2.utilities.misc.head_tail_form_factor(ring, imp, m, sigma, tuneS, xi=None, mode='Hermite', mu=0)[source]¶
- mbtrack2.utilities.misc.yokoya_elliptic(x_radius, y_radius)[source]¶
Compute Yokoya factors for an elliptic beam pipe. Function adapted from N. Mounet IW2D.
- x_radiusfloat
Horizontal semi-axis of the ellipse in [m].
- y_radiusfloat
Vertical semi-axis of the ellipse in [m].
- yoklongfloat
Yokoya factor for the longitudinal impedance.
- yokxdipfloat
Yokoya factor for the dipolar horizontal impedance.
- yokydipfloat
Yokoya factor for the dipolar vertical impedance.
- yokxquadfloat
Yokoya factor for the quadrupolar horizontal impedance.
- yokyquadfloat
Yokoya factor for the quadrupolar vertical impedance.
mbtrack2.utilities.optics module¶
Module where the class to store the optic functions and the lattice physical parameters are defined.
- class mbtrack2.utilities.optics.Optics(lattice_file=None, local_beta=None, local_alpha=None, local_dispersion=None, **kwargs)[source]¶
Bases:
object
Class used to handle optic functions.
- lattice_filestr, optional if local_beta, local_alpha and
local_dispersion are specified. AT lattice file path.
- local_betaarray of shape (2,), optional if lattice_file is specified.
Beta function at the location of the tracking. Default is mean beta if lattice has been loaded.
- local_alphaarray of shape (2,), optional if lattice_file is specified.
Alpha function at the location of the tracking. Default is mean alpha if lattice has been loaded.
- local_dispersionarray of shape (4,), optional if lattice_file is
specified. Dispersion function and derivative at the location of the tracking. Default is zero if lattice has been loaded.
- use_local_valuesbool
True if no lattice has been loaded.
- local_gammaarray of shape (2,)
Gamma function at the location of the tracking.
lattice : AT lattice
- load_from_AT(lattice_file, **kwargs)
Load a lattice from accelerator toolbox (AT).
- setup_interpolation()
Setup interpolation of the optic functions.
- beta(position)
Return beta functions at specific locations given by position.
- alpha(position)
Return alpha functions at specific locations given by position.
- gamma(position)
Return gamma functions at specific locations given by position.
- dispersion(position)
Return dispersion functions at specific locations given by position.
- plot(self, var, option, n_points=1000)
Plot optical variables.
- alpha(position)[source]¶
Return alpha functions at specific locations given by position. If no lattice has been loaded, local values are returned.
- positionarray or float
Longitudinal position at which the alpha functions are returned.
- alphaarray
Alpha functions.
- beta(position)[source]¶
Return beta functions at specific locations given by position. If no lattice has been loaded, local values are returned.
- positionarray or float
Longitudinal position at which the beta functions are returned.
- betaarray
Beta functions.
- dispersion(position)[source]¶
Return dispersion functions at specific locations given by position. If no lattice has been loaded, local values are returned.
- positionarray or float
Longitudinal position at which the dispersion functions are returned.
- dispersionarray
Dispersion functions.
- gamma(position)[source]¶
Return gamma functions at specific locations given by position. If no lattice has been loaded, local values are returned.
- positionarray or float
Longitudinal position at which the gamma functions are returned.
- gammaarray
Gamma functions.
- load_from_AT(lattice_file, **kwargs)[source]¶
Load a lattice from accelerator toolbox (AT).
- lattice_filestr
AT lattice file path.
- n_pointsint or float, optional
Minimum number of points to use for the optic function arrays.
- periodicityint, optional
Lattice periodicity, if not specified the AT lattice periodicity is used.
- property local_alpha¶
Return alpha function at the location defined by the lattice file.
- property local_beta¶
Return beta function at the location defined by the lattice file.
- property local_gamma¶
Return beta function at the location defined by the lattice file.
- mu(position)[source]¶
Return phase advances at specific locations given by position. If no lattice has been loaded, None is returned.
- positionarray or float
Longitudinal position at which the phase advances are returned.
- muarray
Phase advances.
- plot(var, option, n_points=1000)[source]¶
Plot optical variables.
- var{“beta”, “alpha”, “gamma”, “dispersion”, “mu”}
Optical variable to be plotted.
- optionstr
If var = “beta”, “alpha” and “gamma”, option = {“x”,”y”} specifying the axis of interest. If var = “dispersion”, option = {“x”,”px”,”y”,”py”} specifying the axis of interest for the dispersion function or its derivative.
- n_pointsint
Number of points on the plot. The default value is 1000.
- class mbtrack2.utilities.optics.PhysicalModel(ring, x_right, y_top, shape, rho, x_left=None, y_bottom=None, n_points=10000.0)[source]¶
Bases:
object
Store the lattice physical parameters such as apperture and resistivity.
ring : Synchrotron object x_right : float
Default value for the right horizontal aperture in [m].
- y_topfloat
Default value for the top vertical aperture in [m].
- shapestr
Default value for the shape of the chamber cross section (elli/circ/rect).
- rhofloat
Default value for the resistivity of the chamber material [ohm.m].
- x_leftfloat, optional
Default value for the left horizontal aperture in [m].
- y_bottomfloat, optional
Default value for the bottom vertical aperture in [m].
- n_pointsint or float, optional
Number of points to use in class arrays
- positionarray of shape (n_points,)
Longitudinal position in [m].
- x_rightarray of shape (n_points,)
Right horizontal aperture in [m].
- y_toparray of shape (n_points,)
Top vertical aperture in [m].
- shapearray of shape (n_points - 1,)
Shape of the chamber cross section (elli/circ/rect).
- rhoarray of shape (n_points - 1,)
Resistivity of the chamber material in [ohm.m].
- x_leftarray of shape (n_points,)
Left horizontal aperture in [m].
- y_bottomarray of shape (n_points,)
Bottom vertical aperture in [m].
- lengtharray of shape (n_points - 1,)
Length of each segments between two longitudinal positions in [m].
- centerarray of shape (n_points - 1,)
Center of each segments between two longitudinal positions in [m].
- change_values(start_position, end_position, x_right, y_top, shape, rho)
Change the physical parameters between start_position and end_position.
- taper(start_position, end_position, x_right_start, x_right_end,
y_top_start, y_top_end, shape, rho)
Change the physical parameters to have a tapered transition between start_position and end_position.
- plot_aperture()
Plot horizontal and vertical apertures.
- resistive_wall_effective_radius(optics)
Return the effective radius of the chamber for resistive wall calculations.
- change_values(start_position, end_position, x_right=None, y_top=None, shape=None, rho=None, x_left=None, y_bottom=None, sym=True)[source]¶
Change the physical parameters between start_position and end_position.
start_position : float end_position : float x_right : float, optional
Right horizontal aperture in [m].
- y_topfloat, optional
Top vertical aperture in [m].
- shapestr, optional
Shape of the chamber cross section (elli/circ/rect).
- rhofloat, optional
Resistivity of the chamber material [ohm.m].
- x_leftfloat, optional
Left horizontal aperture in [m].
- y_bottomfloat, optional
Bottom vertical aperture in [m].
- symbool, optional
If True, right/left and top/bottum symmetry is applied.
- resistive_wall_effective_radius(optics, x_right=True, y_top=True)[source]¶
Return the effective radius of the chamber for resistive wall calculations as defined in Eq. 27 of [1].
Section with rho = 0 ohm.m are not considered in this calculation.
optics : Optics object x_right : bool, optional
If True, x_right is used, if Fasle, x_left is used.
- y_topbool, optional
If True, y_top is used, if Fasle, y_bottom is used.
- Lfloat
Total length considered in [m].
- rho_starfloat
Effective resistivity of the chamber material in [ohm.m].
- a1_Lfloat
Effective longitudinal radius of the chamber of the first power in [m].
- a2_Lfloat
Effective longitudinal radius of the chamber of the second power in [m].
- a3_Hfloat
Effective horizontal radius of the chamber of the third power in [m].
- a4_Hfloat
Effective horizontal radius of the chamber of the fourth power in [m].
- a3_Vfloat
Effective vertical radius of the chamber of the third power in [m].
- a4_Vfloat
Effective vertical radius of the chamber of the fourth power in [m].
[1] Skripka, Galina, et al. “Simultaneous computation of intrabunch and interbunch collective beam motions in storage rings.” Nuclear Instruments and Methods in Physics Research Section A: Accelerators, Spectrometers, Detectors and Associated Equipment 806 (2016): 221-230.
- taper(start_position, end_position, x_right_start=None, x_right_end=None, y_top_start=None, y_top_end=None, shape=None, rho=None, x_left_start=None, x_left_end=None, y_bottom_start=None, y_bottom_end=None, sym=True)[source]¶
Change the physical parameters to have a tapered transition between start_position and end_position.
start_position : float end_position : float x_right_start : float
Right horizontal aperture at the start of the taper in [m].
- x_right_endfloat
Right horizontal aperture at the end of the taper in [m].
- y_top_startfloat
Top vertical aperture at the start of the taper in [m].
- y_top_endfloat
Top vertical aperture at the end of the taper in [m].
- shapestr
Shape of the chamber cross section (elli/circ/rect).
- rhofloat
Resistivity of the chamber material [ohm.m].
- x_left_startfloat, optional
Left horizontal aperture at the start of the taper in [m].
- x_left_endfloat, optional
Left horizontal aperture at the end of the taper in [m].
- y_bottom_startfloat, optional
Bottom vertical aperture at the start of the taper in [m].
- y_bottom_endfloat, optional
Bottom vertical aperture at the end of the taper in [m].
- symbool, optional
If True, right/left and top/bottum symmetry is applied.
mbtrack2.utilities.read_impedance module¶
Module where function used to import impedance and wakes from other codes are defined.
- mbtrack2.utilities.read_impedance.read_ABCI(file, azimuthal=False, output=False)[source]¶
Read ABCI output files [1].
- filestr
Path to ABCI .pot file.
- azimuthalbool, optional
If True, the transverse wake potential and impedance is loaded from the “AZIMUTHAL” data. If False, it is loaded from the “TRANSVERSE” data. In that case, a -1 factor is applied on the wake to agree with mbtrack2 sign convention. The default is False.
- outputbool, optional
If True, print out the loaded components header. Default is False.
- wakeWakeField
Object where the ABCI computed impedance and wake are stored.
[1] : ABCI - https://abci.kek.jp/abci.htm
- mbtrack2.utilities.read_impedance.read_CST(file, component_type='long', divide_by=None, imp=True)[source]¶
Read CST text file format into an Impedance or WakeFunction object.
- filestr
Path to the text file to read.
- component_typestr, optional
Type of the Impedance or WakeFunction object to load. Default is ‘long’.
- divide_byfloat, optional
Divide the impedance by a value. Mainly used to normalize transverse impedance by displacement. Default is None.
- impbool, optional.
If True a Impedance object is loaded, if False a WakeFunction object is loaded. Default is True.
- resultImpedance or WakeFunction object.
Data from file.
- mbtrack2.utilities.read_impedance.read_ECHO2D(file, component_type='long')[source]¶
Read ECHO2D text file format (after matlab post-processing) into a WakeFunction object.
- filestr
Path to the text file to read.
- component_typestr, optional
Type of the WakeFunction object to load. Default is ‘long’.
- resultWakeFunction object.
Data from file.
- mbtrack2.utilities.read_impedance.read_IW2D(file, file_type='Zlong', output=False)[source]¶
Read IW2D file format into an Impedance object or a WakeField object.
- filestr
Path to the file to read.
- file_typestr, optional
Type of the Impedance or WakeField object.
- outputbool, optional
If True, print out the interpolated values. Default is False.
- resultImpedance or WakeField object
Data from file.
- mbtrack2.utilities.read_impedance.read_IW2D_folder(folder, suffix, select='WZ', output=False)[source]¶
Read IW2D results into a WakeField object.
- folderstr
Path to the folder to read.
- suffixstr
End of the name of each files. For example, in “Zlong_test.dat” the suffix should be “_test.dat”.
- selectstr, optional
Select which object to load. “W” for WakeFunction, “Z” for Impedance and “WZ” or “ZW” for both.
- outputbool, optional
If True, print out the interpolated values. Default is False.
- resultWakeField object
WakeField object with Impedance and WakeFunction objects from the different files.
mbtrack2.utilities.spectrum module¶
Module where bunch and beam spectrums and profile are defined.
- mbtrack2.utilities.spectrum.beam_spectrum(frequency, M, bunch_spacing, sigma=None, bunch_spectrum=None)[source]¶
Compute the beam spectrum assuming constant spacing between bunches [1].
- frequencylist or numpy array
sample points of the beam spectrum in [Hz].
- Mint
Number of bunches.
- bunch_spacingfloat
Time between two bunches in [s].
- sigmafloat, optional
If bunch_spectrum is None then a Gaussian bunch with sigma RMS bunch length in [s] is assumed.
- bunch_spectrumarray, optional
Bunch spectrum sampled at points given in frequency.
beam_spectrum : array
- [1] Rumolo, G - Beam Instabilities - CAS - CERN Accelerator School:
Advanced Accelerator Physics Course - 2014, Eq. 9
- mbtrack2.utilities.spectrum.gaussian_bunch(time, sigma)[source]¶
Compute a Gaussian bunch profile.
- timearray
sample points of the bunch profile in [s].
- sigmafloat
RMS bunch length in [s].
- bunch_profilearray
Bunch profile in [s**-1] sampled at points given in time.
- mbtrack2.utilities.spectrum.gaussian_bunch_spectrum(frequency, sigma)[source]¶
Compute a Gaussian bunch spectrum [1].
- frequencyarray
sample points of the beam spectrum in [Hz].
- sigmafloat
RMS bunch length in [s].
- bunch_spectrumarray
Bunch spectrum sampled at points given in frequency.
[1] : Gamelin, A. (2018). Collective effects in a transient microbunching regime and ion cloud mitigation in ThomX. p86, Eq. 4.19
- mbtrack2.utilities.spectrum.spectral_density(frequency, sigma, m=1, k=0, mode='Hermite')[source]¶
Compute the spectral density of different modes for various values of the head-tail mode number, based on Table 1 p238 of [1].
- frequencylist or numpy array
sample points of the spectral density in [Hz]
- sigmafloat
RMS bunch length in [s]
- mint, optional
head-tail (or azimutal/synchrotron) mode number
- kint, optional
radial mode number (such that |q|=m+2k, where |q| is the head-tail mode number)
- mode: str, optional
type of the mode taken into account for the computation: -“Hermite” modes for Gaussian bunches (typical for electrons) -“Chebyshev” for airbag bunches -“Legendre” for parabolic bunches (typical for protons) -“Sacherer” or “Sinusoidal” simplifying approximation of Legendre modes from [3]
numpy array
[1] : Handbook of accelerator physics and engineering, 3rd printing. [2] : Ng, K. Y. (2005). Physics of intensity dependent beam instabilities. WORLD SCIENTIFIC. https://doi.org/10.1142/5835 [3] : Sacherer, F. J. (1972). Methods for computing bunched beam instabilities. CERN Tech. rep. CERN/SI-BR/72-5 https://cds.cern.ch/record/2291670?ln=en