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

center_of_mass()[source]

Return center of mass position in [s]

dV(z)[source]

Return derivative of the RF system total voltage at position z

ddV(z)[source]

Return the second derivative of the RF system total voltage at position z

deltaVRF(z)[source]

Return the generator voltage minus beam loading voltage of the total RF system at position z

du_dz(z)[source]

Partial derivative of the scaled potential u(z) by z

energy_balance()[source]

Return energy balance for the synchronous particle (z = 0 ,delta = 0).

integrate_func(f, g)[source]

Return Integral[f*g]/Integral[f] between B1 and B2

plot_dV(z1=None, z2=None)[source]

Plot the derivative of RF system total voltage between z1 and z2

plot_rho(z1=None, z2=None)[source]

Plot the bunch equilibrium profile between z1 and z2

plot_voltage(z1=None, z2=None)[source]

Plot the RF system total voltage between z1 and z2

rho(z)[source]

Return bunch equilibrium profile at postion z

std_rho(z1=None, z2=None)[source]

Return the rms bunch equilibrium size in [m]

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.

u(z)[source]

Scaled potential u(z)

uexp(z)[source]
update_potentials()[source]

Update potentials with cavity and ring data.

voltage(z)[source]

Return the RF system total voltage at position z

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.tune_shift_from_effective_impedance(Zeff)[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.

setup_interpolation()[source]

Setup interpolation of the optic functions.

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.

get_aperture(s)[source]
plot_aperture()[source]

Plot horizontal and vertical apertures.

plot_resistivity()[source]

Plot resistivity along the ring.

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

Module contents