mbtrack2.tracking package

Subpackages

Submodules

mbtrack2.tracking.aperture module

This module defines aperture elements for tracking.

class mbtrack2.tracking.aperture.CircularAperture(radius)[source]

Bases: Element

Circular aperture element. The particles which are outside of the circle are ‘lost’ and not used in the tracking any more.

radiusfloat

radius of the circle in [m]

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.aperture.ElipticalAperture(X_radius, Y_radius)[source]

Bases: Element

Eliptical aperture element. The particles which are outside of the elipse are ‘lost’ and not used in the tracking any more.

X_radiusfloat

horizontal radius of the elipse in [m]

Y_radiusfloat

vertical radius of the elipse in [m]

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.aperture.LongitudinalAperture(tau_up, tau_low=None)[source]

Bases: Element

Longitudinal aperture element. The particles which are outside of the longitudinal bounds are ‘lost’ and not used in the tracking any more.

ring : Synchrotron object tau_up : float

Upper longitudinal bound in [s].

tau_lowfloat, optional

Lower longitudinal bound in [s].

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.aperture.RectangularAperture(X_right, Y_top, X_left=None, Y_bottom=None)[source]

Bases: Element

Rectangular aperture element. The particles which are outside of the rectangle are ‘lost’ and not used in the tracking any more.

X_rightfloat

right horizontal aperture of the rectangle in [m]

Y_topfloat

top vertical aperture of the rectangle in [m]

X_leftfloat, optional

left horizontal aperture of the rectangle in [m]

Y_bottomfloat, optional

bottom vertical aperture of the rectangle in [m]

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

mbtrack2.tracking.element module

This module defines the most basic elements for tracking, including Element, an abstract base class which is to be used as mother class to every elements included in the tracking.

class mbtrack2.tracking.element.Element[source]

Bases: object

Abstract Element class used for subclass inheritance to define all kinds of objects which intervene in the tracking.

static parallel(track)[source]

Defines the decorator @parallel which handle the embarrassingly parallel case which happens when there is no bunch to bunch interaction in the tracking routine.

Adding @Element.parallel allows to write the track method of the Element subclass for a Bunch object instead of a Beam object.

trackfunction, method of an Element subclass

track method of an Element subclass which takes a Bunch object as input

track_wrapper: function, method of an Element subclass

track method of an Element subclass which takes a Beam object or a Bunch object as input

abstract track(beam)[source]

Track a beam object through this Element. This method needs to be overloaded in each Element subclass.

beam : Beam object

class mbtrack2.tracking.element.LongitudinalMap(ring)[source]

Bases: Element

Longitudinal map for a single turn in the synchrotron.

ring : Synchrotron object

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.element.SkewQuadrupole(strength)[source]

Bases: object

Thin skew quadrupole element used to introduce betatron coupling (the length of the quadrupole is neglected).

strengthfloat

Integrated strength of the skew quadrupole [m].

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.element.SynchrotronRadiation(ring, switch=array([True, True, True]))[source]

Bases: Element

Element to handle synchrotron radiation, radiation damping and quantum excitation, for a single turn in the synchrotron.

ring : Synchrotron object switch : bool array of shape (3,), optional

allow to choose on which plane the synchrotron radiation is active

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.element.TransverseMap(ring)[source]

Bases: Element

Transverse map for a single turn in the synchrotron.

ring : Synchrotron object

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

class mbtrack2.tracking.element.TransverseMapSector(ring, alpha0, beta0, dispersion0, alpha1, beta1, dispersion1, phase_diff, chro_diff, adts=None)[source]

Bases: Element

Transverse map for a sector of the synchrotron, from an initial position s0 to a final position s1.

ringSynchrotron object

Ring parameters.

alpha0array of shape (2,)

Alpha Twiss function at the initial location of the sector.

beta0array of shape (2,)

Beta Twiss function at the initial location of the sector.

dispersion0array of shape (4,)

Dispersion function at the initial location of the sector.

alpha1array of shape (2,)

Alpha Twiss function at the final location of the sector.

beta1array of shape (2,)

Beta Twiss function at the final location of the sector.

dispersion1array of shape (4,)

Dispersion function at the final location of the sector.

phase_diffarray of shape (2,)

Phase difference between the initial and final location of the sector.

chro_diffarray of shape (2,)

Chromaticity difference between the initial and final location of the sector.

adtsarray of shape (4,), optional

Amplitude-dependent tune shift of the sector, see Synchrotron class for details. The default is None.

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

mbtrack2.tracking.element.transverse_map_sector_generator(ring, positions)[source]

Convenience function which generate a list of TransverseMapSector elements from a ring with an AT lattice.

Tracking through all the sectors is equivalent to a full turn (and thus to the TransverseMap object).

ringSynchrotron object

Ring parameters, must .

positionsarray

List of longitudinal positions in [m] to use as starting and end points of the TransverseMapSector elements. The array should contain the initial position (s=0) but not the end position (s=ring.L), so like position = np.array([0, pos1, pos2, …]).

sectorslist

List of TransverseMapSector elements.

mbtrack2.tracking.feedback module

This module defines both exponential and FIR based bunch by bunch damper feedback for tracking.

class mbtrack2.tracking.feedback.ExponentialDamper(ring, plane, damping_time, phase_diff)[source]

Bases: Element

Simple bunch by bunch damper feedback system based on exponential damping.

ringSynchrotron object

Synchrotron to use.

plane{“x”,”y”,”s”}

Allow to choose on which plane the damper is active.

damping_timefloat

Damping time in [s].

phase_diffarray of shape (3,)

Phase difference between the damper and the position monitor in [rad].

track(bunch)[source]

Tracking method for the feedback system No bunch to bunch interaction, so written for Bunch object and @Element.parallel is used to handle Beam object.

bunch : Bunch or Beam object

class mbtrack2.tracking.feedback.FIRDamper(ring, plane, tune, turn_delay, tap_number, gain, phase, bpm_error=None, max_kick=None)[source]

Bases: Element

Bunch by bunch damper feedback system based on FIR filters.

FIR computation is based on [1].

ringSynchrotron object

Synchrotron to use.

plane{“x”,”y”,”s”}

Allow to choose on which plane the damper is active.

tunefloat

Reference (betatron or synchrotron) tune for which the damper system is set.

turn_delayint

Number of turn delay before the kick is applied.

tap_numberint

Number of tap for the FIR filter.

gainfloat

Gain of the FIR filter.

phasefloat

Phase of the FIR filter in [degree].

bpm_errorfloat, optional

RMS measurement error applied to the computed mean position. Unit is [m] if the plane is “x” or “y” and [s] if the plane is “s”. The default is None.

max_kickfloat, optional

Maximum kick strength limitation. Unit is [rad] if the plane is “x” or “y” and no unit (delta) if the plane is “s”. The default is None.

posarray

Stored beam postions.

kickarray

Stored damper kicks.

coefarray

Coefficients of the FIR filter.

get_fir(tap_number, tune, phase, turn_delay, gain)

Initialize the FIR filter and return an array containing the FIR coefficients.

plot_fir()

Plot the gain and the phase of the FIR filter.

track(beam_or_bunch)

Tracking method.

[1] T.Nakamura, S.Daté, K. Kobayashi, T. Ohshima. Proceedings of EPAC 2004. Transverse bunch by bunch feedback system for the Spring-8 storage ring.

get_fir(tap_number, tune, phase, turn_delay, gain)[source]

Compute the FIR coefficients.

FIR computation is based on [1].

FIR_coefarray

Array containing the FIR coefficients.

init_beam_no_mpi(beam)[source]

Change array sizes if Beam is used without mpi.

beamBeam

Beam to track.

plot_fir()[source]

Plot the gain and the phase of the FIR filter.

figFigure

Plot of the gain and phase.

track(beam_or_bunch)[source]

Tracking method.

beam_or_bunchBeam or Bunch

Data to track.

track_sb(bunch, bunch_number=0)[source]

Core of the tracking method.

bunchBunch

Bunch to track.

bunch_numberint, optional

Number of bunch in beam.not_empty. The default is 0.

mbtrack2.tracking.parallel module

Module to handle parallel computation

class mbtrack2.tracking.parallel.Mpi(filling_pattern)[source]

Bases: object

Class which handle parallel computation via the mpi4py module [1].

filling_patternbool array of shape (h,)

Filling pattern of the beam, like Beam.filling_pattern

commMPI.Intracomm object

MPI intra-comminicator of the processor group, used to manage communication between processors.

rankint

Rank of the processor which run the program

sizeint

Number of processor within the processor group (in fact in the intra-comminicator group)

tableint array of shape (size, 2)

Table of correspondance between the rank of the processor and its associated bunch number

bunch_numint

Return the bunch number corresponding to the current processor

next_bunchint

Return the rank of the next tracked bunch

previous_bunchint

Return the rank of the previous tracked bunch

write_table(filling_pattern)

Write a table with the rank and the corresponding bunch number for each bunch of the filling pattern

rank_to_bunch(rank)

Return the bunch number corresponding to rank

bunch_to_rank(bunch_num)

Return the rank corresponding to the bunch number bunch_num

share_distributions(beam)

Compute the bunch profiles and share it between the different bunches.

share_means(beam)

Compute the bunch means and share it between the different bunches.

share_stds(beam)

Compute the bunch standard deviations and share it between the different bunches.

[1] L. Dalcin, P. Kler, R. Paz, and A. Cosimo, Parallel Distributed Computing using Python, Advances in Water Resources, 34(9):1124-1139, 2011.

property bunch_num

Return the bunch number corresponding to the current processor

bunch_to_rank(bunch_num)[source]

Return the rank corresponding to the bunch number bunch_num

bunch_numint

Bunch number

rankint

Rank of the processor which tracks the input bunch number

property next_bunch

Return the rank of the next tracked bunch

property previous_bunch

Return the rank of the previous tracked bunch

rank_to_bunch(rank)[source]

Return the bunch number corresponding to rank

rankint

Rank of a processor

bunch_numint

Bunch number corresponding to the input rank

share_distributions(beam, dimensions='tau', n_bin=75)[source]

Compute the bunch profiles and share it between the different bunches.

beam : Beam object dimension : str or list of str, optional

Dimensions in which the binning is done. The default is “tau”.

n_binint or list of int, optional

Number of bins. The default is 75.

share_means(beam)[source]

Compute the bunch means and share it between the different bunches.

beam : Beam object

share_stds(beam)[source]

Compute the bunch standard deviations and share it between the different bunches.

beam : Beam object

write_table(filling_pattern)[source]

Write a table with the rank and the corresponding bunch number for each bunch of the filling pattern

filling_patternbool array of shape (h,)

Filling pattern of the beam, like Beam.filling_pattern

mbtrack2.tracking.particles module

Module where particles, bunches and beams are described as objects.

class mbtrack2.tracking.particles.Beam(ring, bunch_list=None)[source]

Bases: object

Define a Beam object composed of several Bunch objects.

ring : Synchrotron object bunch_list : list of Bunch object, optional

currentfloat

Total beam current in [A]

chargefloat

Total bunch charge in [C]

particle_numberint

Total number of particle in the beam

filling_patternbool array of shape (ring.h,)

Filling pattern of the beam

bunch_currentarray of shape (ring.h,)

Current in each bunch in [A]

bunch_chargearray of shape (ring.h,)

Charge in each bunch in [C]

bunch_particlearray of shape (ring.h,)

Particle number in each bunch

bunch_meanarray of shape (6, ring.h)

Mean position of alive particles for each bunch

bunch_stdarray of shape (6, ring.h)

Standard deviation of the position of alive particles for each bunch

bunch_emitarray of shape (6, ring.h)

Bunch emittance of alive particles for each bunch

mpi : Mpi object mpi_switch : bool

Status of MPI parallelisation, should not be changed directly but with mpi_init() and mpi_close()

bunch_indexarray of shape (len(self,))

Return an array with the positions of the non-empty bunches

init_beam(filling_pattern, current_per_bunch=1e-3, mp_per_bunch=1e3)

Initialize beam with a given filling pattern and marco-particle number per bunch. Then initialize the different bunches with a 6D gaussian phase space.

mpi_init()

Switch on MPI parallelisation and initialise a Mpi object

mpi_gather()

Gather beam, all bunches of the different processors are sent to all processors. Rather slow

mpi_share_distributions()

Compute the bunch profile and share it between the different bunches.

mpi_close()

Call mpi_gather and switch off MPI parallelisation

plot(var, option=None)

Plot variables with respect to bunch number.

save(file_name)

Save beam object data in an HDF5 file format.

load(file_name, mpi)

Load data from a HDF5 file recorded by Beam save method.

property bunch_charge

Return an array with the charge in each bunch in [C]

property bunch_cs

Return an array with the average Courant-Snyder invariant for each bunch

property bunch_current

Return an array with the current in each bunch in [A]

property bunch_emit

Return an array with the bunch emittance of alive particles for each bunches and each plane

property bunch_index

Return an array with the positions of the non-empty bunches.

property bunch_mean

Return an array with the mean position of alive particles for each bunches

property bunch_particle

Return an array with the particle number in each bunch

property bunch_std

Return an array with the standard deviation of the position of alive particles for each bunches

property charge

Total beam charge in [C]

property current

Total beam current in [A]

property distance_between_bunches

Return an array which contains the distance to the next bunch in units of the RF period (ring.T1)

property filling_pattern

Return an array with the filling pattern of the beam as bool

init_beam(filling_pattern, current_per_bunch=0.001, mp_per_bunch=1000.0, track_alive=True, mpi=False)[source]

Initialize beam with a given filling pattern and marco-particle number per bunch. Then initialize the different bunches with a 6D gaussian phase space.

If the filling pattern is an array of bool then the current per bunch is uniform, else the filling pattern can be an array with the current in each bunch.

filling_patternnumpy array or list of length ring.h

Filling pattern of the beam, can be a list or an array of bool, then current_per_bunch is used. Or can be an array with the current in each bunch.

current_per_bunchfloat, optional

Current per bunch in [A]

mp_per_bunchfloat, optional

Macro-particle number per bunch

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase.

mpibool, optional

If True, only a single bunch is fully initialized on each core, the other bunches are initialized with a single marco-particle.

load(file_name, mpi, track_alive=True)[source]

Load data from a HDF5 file recorded by Beam save method.

file_namestr

Path to the HDF5 file where the Beam data is stored.

mpibool

If True, only a single bunch is fully initialized on each core, the other bunches are initialized with a single marco-particle.

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase. The default is True.

mpi_close()[source]

Call mpi_gather and switch off MPI parallelisation

mpi_gather()[source]

Gather beam, all bunches of the different processors are sent to all processors. Rather slow

mpi_init()[source]

Switch on MPI parallelisation and initialise a Mpi object

property not_empty

Return a generator to iterate over not empty bunches.

property particle_number

Total number of particles in the beam

plot(var, option=None)[source]

Plot variables with respect to bunch number.

varstr {“bunch_current”, “bunch_charge”, “bunch_particle”,

“bunch_mean”, “bunch_std”, “bunch_emit”}

Variable to be plotted.

optionstr, optional

If var is “bunch_mean”, “bunch_std”, or “bunch_emit, option needs to be specified. For “bunch_mean” and “bunch_std”,

option = {“x”,”xp”,”y”,”yp”,”tau”,”delta”}.

For “bunch_emit”, option = {“x”,”y”,”s”}. The default is None.

figFigure

Figure object with the plot on it.

save(file_name)[source]

Save beam object data in an HDF5 file format.

The output file is named as “<file_name>.hdf5”.

file_namestr

Name of the output file.

update_distance_between_bunches()[source]

Update the distance_between_bunches array

update_filling_pattern()[source]

Update the beam filling pattern.

class mbtrack2.tracking.particles.Bunch(ring, mp_number=1000.0, current=0.001, track_alive=True, alive=True, load_from_file=None, load_suffix=None)[source]

Bases: object

Define a bunch object.

ring : Synchrotron object mp_number : float, optional

Macro-particle number.

currentfloat, optional

Bunch current in [A].

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase.

alivebool, optional

If False, the bunch is defined as empty.

load_from_filestr, optional

Name of bunch save file generated by save method. If None, the bunch is initialized using the input parameters. Otherwise, the bunch from the file is loaded and the other inputs are ignored. Default is None.

load_suffixstr or int, optional

Suffix to the group name used to load the data from the HDF5 file. Default is None.

mp_numberint

Macro-particle number.

alivearray of bool of shape (mp_number,)

Array used to monitor which particle is dead or alive.

chargefloat

Bunch charge in [C].

charge_per_mpfloat

Charge per macro-particle in [C].

particle_numberint

Number of particles in the bunch.

currentfloat

Bunch current in [A].

is_emptybool

Return True if the bunch is empty.

meanarray of shape (6,)

Mean position of alive particles for each coordinates.

stdarray of shape (6,)

Standard deviation of the position of alive particles for each coordinates.

emitarray of shape (3,)

Bunch emittance for each plane [1]. !!! -> Correct for long ?

init_gaussian(cov=None, mean=None, **kwargs)

Initialize bunch particles with 6D gaussian phase space.

plot_phasespace(x_var=”tau”, y_var=”delta”, plot_type=”j”)

Plot phase space.

save(file_name)

Save bunch object data (6D phase space, current, and state) in an HDF5 file format.

load(file_name)

Load data from a HDF5 file recorded by Bunch save method.

[1] Wiedemann, H. (2015). Particle accelerator physics. 4th edition. Springer, Eq.(8.39) of p224.

binning(dimension='tau', n_bin=75)[source]

Bin macro-particles.

dimensionstr, optional

Dimension in which the binning is done. The default is “tau”.

n_binint, optional

Number of bins. The default is 75.

binsarray of shape (n_bin,)

Bins where the particles are sorted.

sorted_indexarray of shape (self.mp_number,)

Bin number of each macro-particles.

profilearray of shape (n_bin - 1,)

Number of marco-particles in each bin.

centerarray of shape (n_bin - 1,)

Center of each bin.

property charge

Bunch charge in [C]

property charge_per_mp

Charge per macro-particle [C]

property cs_invariant

Return the average Courant-Snyder invariant of each plane.

property current

Bunch current [A]

property emit

Return the bunch emittance for each plane.

init_gaussian(cov=None, mean=None, **kwargs)[source]

Initialize bunch particles with 6D gaussian phase space. Covariance matrix is taken from [1] and dispersion is added following the method explained in [2].

cov(6,6) array, optional

Covariance matrix of the bunch distribution

mean(6,) array, optional

Mean of the bunch distribution

[1] Wiedemann, H. (2015). Particle accelerator physics. 4th edition. Springer, Eq.(8.38) of p223. [2] http://www.pp.rhul.ac.uk/bdsim/manual-develop/dev_beamgeneration.html

property is_empty

Return True if the bunch is empty.

load(file_name, suffix=None, track_alive=True)[source]

Load data from a HDF5 file recorded by Bunch save method.

file_namestr

Path to the HDF5 file where the Bunch data is stored.

suffixstr or int, optional

Suffix to the group name used to load the data from the HDF5 file. If None, it is not used.

track_alivebool, optional

If False, the code no longer take into account alive/dead particles. Should be set to True if element such as apertures are used. Can be set to False to gain a speed increase.

property mean

Return the mean position of alive particles for each coordinates.

property mp_number

Macro-particle number

property particle_number

Particle number

plot_phasespace(x_var='tau', y_var='delta', kind='scatter')[source]

Plot phase space.

x_varstr

Dimension to plot on horizontal axis.

y_varstr

Dimension to plot on vertical axis.

kindstr, {“scatter”, “kde”, “hist”, “hex”, “reg”, “resid”}

Kind of plot to draw. See seeborn documentation. The defualt value is “scatter”.

figFigure

Figure object with the plot on it.

plot_profile(dimension='tau', n_bin=75)[source]

Plot bunch profile.

dimensionstr, optional

Dimension to plot. The default is “tau”.

n_binint, optional

Number of bins. The default is 75.

save(file_name, suffix=None, mpi_comm=None)[source]

Save bunch object data (6D phase space, current, and state) in an HDF5 file format.

The output file is named as “<file_name>.hdf5”.

file_namestr

Name of the output file.

suffixstr or int, optional

Suffix to the group name used to save the data into the HDF5 file. If None, it is not used.

mpi_commMPI communicator, optional

For internal use if mpi is used in Beam objects. Default is None.

property std

Return the standard deviation of the position of alive particles for each coordinates.

class mbtrack2.tracking.particles.Electron[source]

Bases: Particle

Define an electron

class mbtrack2.tracking.particles.Particle(mass, charge)[source]

Bases: object

Define a particle object.

massfloat

total particle mass in [kg]

chargefloat

electrical charge in [C]

E_restfloat

particle rest energy in [eV]

property E_rest
class mbtrack2.tracking.particles.Proton[source]

Bases: Particle

Define a proton

mbtrack2.tracking.rf module

This module handles radio-frequency (RF) cavitiy elements.

class mbtrack2.tracking.rf.CavityResonator(ring, m, Rs, Q, QL, detune, Ncav=1, Vc=0, theta=0, n_bin=75)[source]

Bases: object

Cavity resonator class for active or passive RF cavity with beam loading or HOM, based on [1,2].

Use cosine definition.

If used with mpi, beam.mpi.share_distributions must be called before the track method call.

Different kind of RF feeback and loops can be added using:

cavity_resonator.feedback.append(loop)

ring : Synchrotron object m : int or float

Harmonic number of the cavity.

Rsfloat

Shunt impedance of the cavities in [Ohm], defined as 0.5*Vc*Vc/Pc. If Ncav = 1, used for the total shunt impedance. If Ncav > 1, used for the shunt impedance per cavity.

Qfloat

Quality factor of the cavity.

QLfloat

Loaded quality factor of the cavity.

detunefloat

Detuing of the cavity in [Hz], defined as (fr - m*ring.f1).

Ncavint, optional

Number of cavities.

Vcfloat, optinal

Total cavity voltage objective value in [V].

thetafloat, optional

Total cavity phase objective value in [rad].

n_binint, optional

Number of bins used for the beam loading computation. Only used if MPI is not used, otherwise n_bin must be specified in the beam.mpi.share_distributions method. The default is 75.

beam_phasorcomplex

Beam phasor in [V].

beam_phasor_recordarray of complex

Last beam phasor value of each bunch in [V].

generator_phasorcomplex

Generator phasor in [V].

generator_phasor_recordarray of complex

Last generator phasor value of each bunch in [V].

cavity_phasorcomplex

Cavity phasor in [V].

cavity_phasor_recordarray of complex

Last cavity phasor value of each bunch in [V].

ig_phasor_recordarray of complex

Last current generator phasor of each bunch in [A]. Only used for some feedback types.

cavity_voltagefloat

Cavity total voltage in [V].

cavity_phasefloat

Cavity total phase in [rad].

loss_factorfloat

Cavity loss factor in [V/C].

Rs_per_cavityfloat

Shunt impedance of a single cavity in [Ohm], defined as 0.5*Vc*Vc/Pc.

betafloat

Coupling coefficient of the cavity.

frfloat

Resonance frequency of the cavity in [Hz].

wrfloat

Angular resonance frequency in [Hz.rad].

psifloat

Tuning angle in [rad].

filling_timefloat

Cavity filling time in [s].

Pcfloat

Power dissipated in the cavity walls in [W].

Pgfloat

Generator power in [W].

Vgrfloat

Generator voltage at resonance in [V].

theta_grfloat

Generator phase at resonance in [rad].

Vgfloat

Generator voltage in [V].

theta_gfloat

Generator phase in [rad].

trackingbool

True if the tracking has been initialized.

bunch_indexint

Number of the tracked bunch in the current core.

distancearray

Distance between bunches.

valid_bunch_index : array

Vbr(I0)

Return beam voltage at resonance in [V].

Vb(I0)

Return beam voltage in [V].

Pb(I0)

Return power transmitted to the beam in [W].

Pr(I0)

Return power reflected back to the generator in [W].

Z(f)

Cavity impedance in [Ohm] for a given frequency f in [Hz].

set_optimal_coupling(I0)

Set coupling to optimal value.

set_optimal_detune(I0)

Set detuning to optimal conditions.

set_generator(I0)

Set generator parameters.

plot_phasor(I0)

Plot phasor diagram.

is_DC_Robinson_stable(I0)

Check DC Robinson stability.

plot_DC_Robinson_stability()

Plot DC Robinson stability limit.

init_tracking(beam)

Initialization of the tracking.

track(beam)

Tracking method.

phasor_decay(time)

Compute the beam phasor decay during a given time span.

phasor_evol(profile, bin_length, charge_per_mp)

Compute the beam phasor evolution during the crossing of a bunch.

VRF(z, I0)

Return the total RF voltage.

dVRF(z, I0)

Return derivative of total RF voltage.

ddVRF(z, I0)

Return the second derivative of total RF voltage.

deltaVRF(z, I0)

Return the generator voltage minus beam loading voltage.

update_feedback()

Force feedback update from current CavityResonator parameters.

sample_voltage()

Sample the voltage seen by a zero charge particle during an RF period.

[1] Wilson, P. B. (1994). Fundamental-mode rf design in e+ e− storage ring factories. In Frontiers of Particle Beams: Factories with e+ e-Rings (pp. 293-311). Springer, Berlin, Heidelberg.

[2] Naoto Yamamoto, Alexis Gamelin, and Ryutaro Nagaoka. “Investigation of Longitudinal Beam Dynamics With Harmonic Cavities by Using the Code Mbtrack.” IPAC’19, Melbourne, Australia, 2019.

property DFB_ig_phasor

Last direct feedback current generator phasor of each bunch in [A]

property Ncav

Number of cavities

Pb(I0)[source]

Return power transmitted to the beam in [W] - near Eq. (4.2.3) in [1].

I0float

Beam current in [A].

float

Power transmitted to the beam in [W].

property Pc

Power dissipated in the cavity walls in [W]

Pr(I0)[source]

Power reflected back to the generator in [W].

I0float

Beam current in [A].

float

Power reflected back to the generator in [W].

property Q

Quality factor

property QL

Loaded quality factor

property RL

Loaded shunt impedance [ohm]

property Rs

Shunt impedance [ohm]

property Rs_per_cavity

Shunt impedance of a single cavity in [Ohm], defined as 0.5*Vc*Vc/Pc.

VRF(z, I0, F=1, PHI=0)[source]

Total RF voltage taking into account form factor amplitude F and form factor phase PHI

Vb(I0)[source]

Return beam voltage in [V].

I0float

Beam current in [A].

float

Beam voltage in [V].

Vbr(I0)[source]

Return beam voltage at resonance in [V].

I0float

Beam current in [A].

float

Beam voltage at resonance in [V].

Z(f)[source]

Cavity impedance in [Ohm] for a given frequency f in [Hz]

property beam_phase

Beam loading phase in [rad]

property beam_voltage

Beam loading voltage in [V]

property beta

Coupling coefficient

property cavity_phase

Cavity total phase in [rad]

property cavity_phasor

Cavity total phasor in [V]

property cavity_phasor_record

Last cavity phasor value of each bunch in [V]

property cavity_voltage

Cavity total voltage in [V]

dVRF(z, I0, F=1, PHI=0)[source]

Return derivative of total RF voltage taking into account form factor amplitude F and form factor phase PHI

ddVRF(z, I0, F=1, PHI=0)[source]

Return the second derivative of total RF voltage taking into account form factor amplitude F and form factor phase PHI

deltaVRF(z, I0, F=1, PHI=0)[source]

Return the generator voltage minus beam loading voltage taking into account form factor amplitude F and form factor phase PHI

property detune

Cavity detuning [Hz] - defined as (fr - m*f1)

property filling_time

Cavity filling time in [s]

property fr

Resonance frequency of the cavity in [Hz]

property generator_phasor

Generator phasor in [V]

property ig_phasor_record

Last current generator phasor of each bunch in [A]

init_phasor(beam)[source]

Initialize the beam phasor for a given beam distribution using an analytic formula [1].

No modifications on the Beam object.

beam : Beam object

[1] mbtrack2 manual.

init_phasor_track(beam)[source]

Initialize the beam phasor for a given beam distribution using a tracking like method.

Follow the same steps as the track method but in the “rf” reference frame and without any modifications on the beam.

beam : Beam object

init_tracking(beam)[source]

Initialization of the tracking.

beam : Beam object

is_CBI_stable(I0, synchrotron_tune=None, modes=None, bool_return=False)[source]

Check Coupled-Bunch-Instability stability, Effect of Direct RF feedback is not included.

This method is a wraper around lcbi_growth_rate to caluclate the CBI growth rate from the CavityResonator own impedance.

See lcbi_growth_rate for details.

I0float

Beam current in [A].

synchrotron_tunefloat, optinal

Fractional number of longitudinal tune. If None, synchrotron_tune is computed using self.Vc as total voltage. Default is None.

modesfloat or list of float, optional

Coupled Bunch Instability mode numbers to consider. If not None, return growth_rates of the input coupled bunch modes. Default is None.

bool_returnbool, optional
If True:
  • return True if the most unstable mode is stronger than

longitudinal damping time. - return False if it is not the case.

Default is False.

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.

is_DC_Robinson_stable(I0)[source]

Check DC Robinson stability - Eq. (6.1.1) [1]

I0float

Beam current in [A].

bool

property loss_factor

Cavity loss factor in [V/C]

property m

Harmonic number of the cavity

phasor_decay(time, ref_frame='beam')[source]

Compute the beam phasor decay during a given time span, assuming that no particles are crossing the cavity during the time span.

timefloat

Time span in [s], can be positive or negative.

ref_framestring, optional

Reference frame to be used, can be “beam” or “rf”.

phasor_evol(profile, bin_length, charge_per_mp, ref_frame='beam')[source]

Compute the beam phasor evolution during the crossing of a bunch using an analytic formula [1].

Assume that the phasor decay happens before the beam loading.

profilearray

Longitudinal profile of the bunch in [number of macro-particle].

bin_lengthfloat

Length of a bin in [s].

charge_per_mpfloat

Charge per macro-particle in [C].

ref_framestring, optional

Reference frame to be used, can be “beam” or “rf”.

[1] mbtrack2 manual.

plot_DC_Robinson_stability(detune_range=[- 100000.0, 100000.0])[source]

Plot DC Robinson stability limit.

detune_rangelist or array, optional

Range of tuning to plot in [Hz].

Figure.

plot_phasor(I0)[source]

Plot phasor diagram showing the vector addition of generator and beam loading voltage.

I0float

Beam current in [A].

Figure.

property psi

Tuning angle in [rad]

sample_voltage(n_points=10000.0, index=0)[source]

Sample the voltage seen by a zero charge particle during an RF period.

n_pointsint or float, optional

Number of sample points. The default is 1e4.

indexint, optional

RF bucket number to sample. Be carful if index > 0 as no new beam loading is not taken into account here. The default is 0.

posarray of float

Array of position from -T1/2 to T1/2.

voltage_recarray of float

Recoring of the voltage.

set_generator(I0)[source]

Set generator parameters (Pg, Vgr, theta_gr, Vg and theta_g) for a given current and set of parameters.

I0float

Beam current in [A].

set_optimal_coupling(I0)[source]

Set coupling to optimal value - Eq. (4.2.3) in [1].

I0float

Beam current in [A].

set_optimal_detune(I0, F=1)[source]

Set detuning to optimal conditions - second Eq. (4.2.1) in [1].

I0float

Beam current in [A].

track(beam)[source]

Track a Beam object through the CavityResonator object.

Can be used with or without mpi. If used with mpi, beam.mpi.share_distributions must be called before.

The beam phasor is given at t=0 (synchronous particle) of the first non empty bunch.

beam : Beam object

update_feedback()[source]

Force feedback update from current CavityResonator parameters.

property wr

Angular resonance frequency in [Hz.rad]

class mbtrack2.tracking.rf.DirectFeedback(DFB_gain, DFB_phase_shift, DFB_sample_num=None, DFB_every=None, DFB_delay=None, **kwargs)[source]

Bases: ProportionalIntegralLoop

Direct RF FB (DFB) via generator current (ig) using PI controller [1,2].

The DirectFeedback inherits from ProportionalIntegralLoop so all mandatory parameters from ProportionalIntegralLoop should be passed as kwargs when initializing a DirectFeedback object.

To avoid cavity-beam unmatching (large synchrotron oscilation of beam), the CavityResonator generator parameters should be set before initialization.

The loop must be added to the CavityResonator object using:

cav_res.feedback.append(loop)

DFB_gainfloat

Gain of the DFB.

DFB_phase_shiftfloat

Phase shift of the DFB.

DFB_sample_numint, optional

Sample number to monitor Vc for the DFB. The averaged Vc value in DFB_sample_num is monitored. Units are in bucket numbers. If None, value from the ProportionalIntegralLoop is used. Default is None.

DFB_everyint, optional

Interval to monitor and change Vc for the DFB. Units are in bucket numbers. If None, value from the ProportionalIntegralLoop is used. Default is None.

DFB_delayint, optional

Loop delay of the DFB. Units are in bucket numbers. If None, value from the ProportionalIntegralLoop is used. Default is None.

phase_shiftfloat

Phase shift applied to DFB, defined as psi - DFB_phase_shift.

DFB_psi: float

Return detuning angle value with Direct RF feedback in [rad].

DFB_alphafloat

Return the amplitude ratio alpha of the DFB.

DFB_gammafloat

Return the gain gamma of the DFB.

DFB_Rsfloat

Return the shunt impedance of the DFB in [ohm].

DFB_parameter_set(DFB_gain, DFB_phase_shift)

Set DFB gain and phase shift parameters.

track()

Tracking method for the Direct RF feedback.

DFB_Vg()

Return the generator voltage main and DFB components in [V].

DFB_fs()

Return the modified synchrotron frequency in [Hz].

[1] : Akai, K. (2022). Stability analysis of rf accelerating mode with feedback loops under heavy beam loading in SuperKEKB. PRAB, 25(10), 102002. [2] : N. Yamamoto et al. (2023). Stability survey of a double RF system with RF feedback loops for bunch lengthening in a low-emittance synchrotron ring. In Proc. IPAC’23. doi:10.18429/JACoW-IPAC2023-WEPL161

property DFB_Rs

Return the shunt impedance of the DFB in [ohm].

Eq. (15) of [1].

DFB_Vg(vc=- 1)[source]

Return the generator voltage main and DFB components in [V].

property DFB_alpha

Return the amplitude ratio alpha of the DFB.

Near Eq. (13) of [1].

DFB_fs(vg_main=- 1, vg_drf=- 1)[source]

Return the modified synchrotron frequency in [Hz].

property DFB_gamma

Return the gain gamma of the DFB.

Near Eq. (13) of [1].

DFB_parameter_set(DFB_gain, DFB_phase_shift)[source]

Set DFB gain and phase shift parameters.

DFB_gainfloat

Gain of the DFB.

DFB_phase_shiftfloat

Phase shift of the DFB.

property DFB_phase_shift

Return DFB phase shift.

property DFB_psi

Return detuning angle value with Direct RF feedback in [rad].

Fig.4 of ref [1].

property phase_shift

Return phase shift applied to DFB. Defined as self.cav_res.psi - self.DFB_phase_shift.

track()[source]

Tracking method for the Direct RF feedback.

None.

class mbtrack2.tracking.rf.ProportionalIntegralLoop(ring, cav_res, gain, sample_num, every, delay, IIR_cutoff=0, FF=True)[source]

Bases: object

Proportional Integral (PI) loop to control a CavityResonator amplitude and phase via generator current (ig) [1,2].

Feedback reference targets (setpoints) are cav_res.Vc and cav_res.theta.

The ProportionalIntegralLoop should be initialized only after generator parameters are set.

The loop must be added to the CavityResonator object using:

cav_res.feedback.append(loop)

When the reference target is changed, it might be needed to re-initialize the feedforward constant by calling init_FFconst().

ring : Synchrotron object cav_res : CavityResonator object

CavityResonator in which the loop will be added.

gainfloat list

Proportional gain (Pgain) and integral gain (Igain) of the feedback system in the form of a list [Pgain, Igain]. In case of normal conducting cavity (QL~1e4), the Pgain of ~1.0 and Igain of ~1e4(5) are usually used. In case of super conducting cavity (QL > 1e6), the Pgain of ~100 can be used. In a “bad” parameter set, unstable oscillation of the cavity voltage can be caused. So, a parameter scan of the gain should be made. Igain * ring.T1 / dtau is Ki defined as a the coefficients for integral part in of [1], where dtau is a clock period of the PI controller.

sample_numint

Number of bunch over which the mean cavity voltage is computed. Units are in bucket numbers.

everyint

Sampling and clock period of the feedback controller Time interval between two cavity voltage monitoring and feedback. Units are in bucket numbers.

delayint

Loop delay of the PI feedback system. Units are in bucket numbers.

IIR_cutofffloat, optinal

Cutoff frequency of the IIR filter in [Hz]. If 0, cutoff frequency is infinity. Default is 0.

FFbool, optional

Boolean switch to use feedforward constant. True is recommended to prevent a cavity voltage drop in the beginning of the tracking. In case of small Pgain (QL ~ 1e4), cavity voltage drop may cause beam loss due to static Robinson. Default is True.

track()

Tracking method for the Cavity PI control feedback.

init_Ig2Vg_matrix()

Initialize matrix for Ig2Vg_matrix.

init_FFconst()

Initialize feedforward constant.

Ig2Vg_matrix()

Return Vg from Ig using matrix formalism.

Ig2Vg()

Go from Ig to Vg and apply values.

Vg2Ig(Vg)

Return Ig from Vg (assuming constant Vg).

IIR_init(cutoff)

Initialization for the IIR filter.

IIR(input)

Return IIR filter output.

IIRcutoff()

Return IIR cutoff frequency in [Hz].

Assumption : delay >> every ~ sample_num

Adjusting ig(Vg) parameter to keep the cavity voltage constant (to target values). The “track” method is

1) Monitoring the cavity voltage phasor Mean cavity voltage value between specified bunch number (sample_num) is monitored with specified interval period (every). 2) Changing the ig phasor The ig phasor is changed according the difference of the specified reference values with specified gain (gain). By using ig instead of Vg, the cavity response can be taken account. 3) ig changes are reflected to Vg after the specifed delay (delay) of the system

Vc–>(rot)–>IIR–>(-)–>(V->I,fac)–>PI–>Ig –> Vg

Ref

PF; E0=2.5GeV, C=187m, frf=500MHz

QL=11800, fs0=23kHz ==> gain=[0.5,1e4], sample_num=8, every=7(13ns), delay=500(1us)

is one reasonable parameter set.

The practical clock period is 13ns.

==> Igain_PF = Igain_mbtrack * Trf / 13ns = Igain_mbtrack * 0.153

[1] : https://en.wikipedia.org/wiki/PID_controller [2] : Yamamoto, N., Takahashi, T., & Sakanaka, S. (2018). Reduction and compensation of the transient beam loading effect in a double rf system of synchrotron light sources. PRAB, 21(1), 012001.

IIR(input)[source]

Return IIR filter output.

IIR_init(cutoff)[source]

Initialization for the IIR filter.

cutofffloat

Cutoff frequency of the IIR filter in [Hz]. If 0, cutoff frequency is infinity.

property IIRcutoff

Return IIR cutoff frequency in [Hz].

Ig2Vg()[source]

Go from Ig to Vg.

Apply new values to cav_res.generator_phasor_record, cav_res.Vg and cav_res.theta_g from ig_phasor_record.

Ig2Vg_matrix()[source]

Return Vg from Ig using matrix formalism. Warning: self.init_Ig2Vg should be called after each CavityResonator parameter change.

Vg2Ig(Vg)[source]

Return Ig from Vg (assuming constant Vg).

Eq.25 of ref [2] assuming the dVg/dt = 0.

init_FFconst()[source]

Initialize feedforward constant.

init_Ig2Vg_matrix()[source]

Initialize matrix for Ig2Vg_matrix.

Shoud be called before first use of Ig2Vg_matrix and after each cavity parameter change.

track(apply_changes=True)[source]

Tracking method for the Cavity PI control feedback.

None.

class mbtrack2.tracking.rf.ProportionalLoop(ring, cav_res, gain_A, gain_P, delay)[source]

Bases: object

Proportional feedback loop to control a CavityResonator amplitude and phase.

Feedback setpoints are cav_res.Vc and cav_res.theta.

The loop must be added to the CavityResonator object using:

cav_res.feedback.append(loop)

ring : Synchrotron object cav_res : CavityResonator

The CavityResonator which is to be controlled.

gain_Afloat

Amplitude (voltage) gain of the feedback.

gain_Pfloat

Phase gain of the feedback.

delayint

Feedback delay in unit of turns. Must be supperior or equal to 1.

track()[source]

Tracking method for the amplitude and phase loop.

None.

class mbtrack2.tracking.rf.RFCavity(ring, m, Vc, theta)[source]

Bases: Element

Perfect RF cavity class for main and harmonic RF cavities. Use cosine definition.

ring : Synchrotron object m : int

Harmonic number of the cavity

Vcfloat

Amplitude of cavity voltage [V]

thetafloat

Phase of Cavity voltage

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object

value(val)[source]
class mbtrack2.tracking.rf.TunerLoop(ring, cav_res, gain=0.01, avering_period=0, offset=0)[source]

Bases: object

Cavity tuner loop used to control a CavityResonator tuning (psi or detune) in order to keep the phase between cavity and generator current constant.

Only a proportional controller is assumed.

The loop must be added to the CavityResonator object using:

cav_res.feedback.append(loop)

ring : Synchrotron object cav_res : CavityResonator

The CavityResonator which is to be controlled.

gainfloat

Proportional gain of the tuner loop. If not specified, 0.01 is used.

avering_period:

Period during which the phase difference is monitored and averaged. Then the feedback correction is applied every avering_period turn. Unit is turn number. A value longer than one synchrotron period (1/fs) is recommended. If not specified, 2-synchrotron period (2/fs) is used, although it is too fast compared to the actual situation.

offsetfloat

Tuning offset in [rad].

track()[source]

Tracking method for the tuner loop.

None.

mbtrack2.tracking.synchrotron module

Module where the Synchrotron class is defined.

class mbtrack2.tracking.synchrotron.Synchrotron(h, optics, particle, **kwargs)[source]

Bases: object

Synchrotron class to store main properties.

Optional parameters are optional only if the Optics object passed to the class uses a loaded lattice.

hint

Harmonic number of the accelerator.

opticsOptics object

Object where the optic functions are stored.

particleParticle object

Particle which is accelerated.

tauarray of shape (3,)

Horizontal, vertical and longitudinal damping times in [s].

sigma_deltafloat

Equilibrium energy spread.

sigma_0float

Natural bunch length in [s].

emitarray of shape (2,)

Horizontal and vertical equilibrium emittance in [m.rad].

Lfloat, optional

Ring circumference in [m].

E0float, optional

Nominal (total) energy of the ring in [eV].

acfloat, optional

Momentum compaction factor.

tunearray of shape (2,), optional

Horizontal and vertical tunes.

chroarray of shape (2,), optional

Horizontal and vertical (non-normalized) chromaticities.

U0float, optional

Energy loss per turn in [eV].

adtslist of arrays or None, optional

List that contains arrays of polynomial’s coefficients, in decreasing powers, used to determine Amplitude-Dependent Tune Shifts (ADTS). The order of the elements strictly needs to be [coef_xx, coef_yx, coef_xy, coef_yy], where x and y denote the horizontal and the vertical plane, respectively, and coef_PQ means the polynomial’s coefficients of the ADTS in plane P due to the amplitude in plane Q.

For example, if the tune shift in y due to the Courant-Snyder invariant Jx is characterized by the equation dQy(x) = 3*Jx**2 + 2*Jx + 1, then coef_yx takes the form np.array([3, 2, 1]).

Use None, to exclude the ADTS from calculation.

mcf_orderarray, optional

Higher-orders momentum compaction factor in decreasing powers. Input here the coefficients considering only the derivatives and which do not include any factorial factor. The 1st order should be included in the array and be at the last position.

T0float

Revolution time in [s].

f0float

Revolution frequency in [Hz].

omega0float

Angular revolution frequency in [Hz.rad]

T1flaot

Fundamental RF period in [s].

f1float

Fundamental RF frequency in [Hz].

omega1float

Fundamental RF angular frequency in [Hz.rad].

k1float

Fundamental RF wave number in [m**-1].

gammafloat

Relativistic Lorentz gamma.

betafloat

Relativistic Lorentz beta.

long_alphafloat

Longitudinal alpha Twiss parameter at the tracking location. Initialized at zero.

long_betafloat

Longitudinal beta Twiss parameter at the tracking location in [s]. Initialized at zero.

long_gammafloat

Longitudinal gamma Twiss parameter at the tracking location in [s-1]. Initialized at zero.

synchrotron_tune(V)

Compute the (unperturbed) synchrotron tune from main RF voltage.

sigma(position)

Return the RMS beam size at equilibrium in [m].

eta(delta)

Momentum compaction taking into account higher orders if provided in mcf_order.

mcf(delta)

Momentum compaction factor taking into account higher orders if provided in mcf_order.

get_adts()

Compute and add Amplitude-Dependent Tune Shifts (ADTS) sextupolar componenet from AT lattice.

get_mcf_order()

Compute momentum compaction factor up to 3rd order from AT lattice.

get_longitudinal_twiss(V)

Compute the longitudinal Twiss parameters and the synchrotron tune for single or multi-harmonic RF systems.

to_pyat(Vrf)

Return a pyAT simple_ring element from the Synchrotron element data.

property E0

Nominal (total) energy of the ring [eV]

property L

Ring circumference [m]

property T0

Revolution time [s]

property T1

“Fundamental RF period [s]

property beta

Relativistic beta

eta(delta=0)[source]

Momentum compaction taking into account higher orders if provided in mcf_order.

deltafloat or array like bunch[“delta”], optional

Relative energy deviation. The default is 0.

float or array

Momentum compaction.

property f0

Revolution frequency [Hz]

property f1

Fundamental RF frequency [Hz]

property gamma

Relativistic gamma

get_adts()[source]

Compute and add Amplitude-Dependent Tune Shifts (ADTS) sextupolar componenet from AT lattice.

get_longitudinal_twiss(V, phase=None, harmonics=None, add=True)[source]

Compute the longitudinal Twiss parameters and the synchrotron tune for single or multi-harmonic RF systems.

Hypthesis: - Use the linear approximation (tau ~ 0). - For higher haromics only, cos(phi) ~ 0 must be true.

Vfloat or array-like of float

RF voltage in [V].

phasefloat or array-like of float, optional

RF phase using cosine convention in [rad]. Default is None.

harmonicsint or array-like of int, optional

Harmonics of the cavities to consider. Default is None.

addbool, optional

If True,

  • If a single voltage value is given, assume a single RF system set at

the synchronous phase. - If a single pair of voltage/phase value is given, assume a single RF system at this setting. - Otherwise, compute the synchrotron tune for a multi-harmonic RF system.

tuneSfloat

Synchrotron tune in the linear approximation.

long_alphafloat

Longitudinal alpha Twiss parameter at the tracking location.

long_betafloat

Longitudinal beta Twiss parameter at the tracking location in [s].

long_gammafloat

Longitudinal gamma Twiss parameter at the tracking location in [s-1].

get_mcf_order(add=True, show_fit=False)[source]

Compute momentum compaction factor up to 3rd order from AT lattice.

addbool, optional

If True, add the computed coefficient to the Synchrotron object. If False, the result is returned. The default is True.

show_fitbool, optional

If True, show a plot with the data and fit. The default is False.

pvaluearray, optional

Momentum compaction factor up to 3rd order

property h

Harmonic number

property k1

Fundamental RF wave number [m**-1]

property mcf_order

Higher-orders momentum compaction factor

property omega0

Angular revolution frequency [Hz rad]

property omega1

Fundamental RF angular frequency[Hz rad]

sigma(position=None)[source]

Return the RMS beam size at equilibrium in [m].

positionfloat or array, optional

Longitudinal position in [m] where the beam size is computed. If None, the local values are used.

sigmaarray

RMS beam size in [m] at position location or at local positon if position is None.

synchrotron_tune(V)[source]

Compute the (unperturbed) synchrotron tune from main RF voltage.

Vfloat

Main RF voltage in [V].

tuneSfloat

Synchrotron tune.

to_pyat(Vrf, harmonic_number=None, TimeLag=False)[source]

Return a pyAT simple_ring element from the Synchrotron element data.

See pyAT documentation for informations about simple_ring.

Vrffloat or array-like of float

RF Voltage in [V]. If sevral cavities are provided, harmonic_number and TimeLag should be provided.

harmonic_numberfloat or array-like of float, optional

Harmonic numbers of the RF cavities. The default is None.

TimeLagfloat or array-like of float, optional

Set the timelag of the cavities in pyAT definition. The default is False.

at_simple_ringat.physics.fastring.simple_ring

A pyAT simple_ring element.

mbtrack2.tracking.wakepotential module

This module defines the WakePotential and LongRangeResistiveWall classes which deal with the single bunch and multi-bunch wakes.

class mbtrack2.tracking.wakepotential.LongRangeResistiveWall(ring, beam, length, rho, radius, types=['Wlong', 'Wxdip', 'Wydip'], nt=50, x3=None, y3=None)[source]

Bases: Element

Element to deal with multi-bunch and multi-turn wakes from resistive wall using the algorithm defined in [1].

Main approximations:
  • Bunches are treated as point charge.

  • Assymptotic expression for the resistive wall wake functions are

used. - Multi-turn wakes are limited to nt turns.

Self-bunch interaction is not included in this element and should be dealed with the WakePotential class.

ring : Synchrotron object beam : Beam object length : float

Length of the resistive pipe to consider in [m].

rhofloat

Effective resistivity to consider in [ohm.m] as in [1].

radiusfloat

Beam pipe radius to consider in [m].

typesstr or list, optional

Wake types to consider. The default is [“Wlong”,”Wxdip”,”Wydip”].

ntint or float, optional

Number of turns to consider for the long range wakes. The default is 50.

x3float, optional

Horizontal effective radius of the 3rd power in [m], as Eq.27 in [1]. The default is radius.

y3float, optional

Vertical effective radius of the 3rd power in [m], as Eq.27 in [1]. The default is radius.

[1] : Skripka, Galina, et al. “Simultaneous computation of intrabunch and interbunch collective beam motions in storage rings.” NIM.A (2016).

Wdip(t, plane)[source]

Approxmiate expression for the transverse resistive wall wake function - Eq.26 of [1].

tfloat

Time in [s].

planestr

“x” or “y”.

wdipfloat

Wake function in [V/C/m].

Wlong(t)[source]

Approxmiate expression for the longitudinal resistive wall wake function - Eq.24 of [1].

tfloat

Time in [s].

wlfloat

Wake function in [V/C].

get_kick(rank, wake_type)[source]

Compute the wake kick to apply.

rankint

Rank of the bunch, as defined in Mpi class.

wake_typefloat

Type of the wake to compute.

sum_kickfloat

Sum of the kicks from the different bunches at different turns.

track(beam)[source]

Track a beam.

beam : Beam object

None.

track_bunch(bunch, rank)[source]

Track a bunch.

Should only be used within the track method and not standalone.

bunch : Bunch object rank : int

Rank of the bunch, as defined in Mpi class.

None.

update_tables(beam)[source]

Update tables.

Table tau[i,j] is defined as the time difference of the bunch i center of mass with respect to center of the RF bucket number 0 at turn j. Turn 0 corresponds to the tracked turn.

Positive time corresponds to past events and negative time to future events.

beam : Beam object

None.

class mbtrack2.tracking.wakepotential.WakePotential(ring, wakefield, n_bin=80, interp_on_postion=True)[source]

Bases: Element

Compute a wake potential from uniformly sampled wake functions by performing a convolution with a bunch charge profile.

Two different time bases are used. The first one is controled by the n_bin parameter and is used to compute the bunch profile. Then the bunch profile is interpolated on the wake function time base which is used to perform the convolution to get the wake potential.

ring : Synchrotron object wakefield : Wakefield object

Wakefield object which contains the wake functions to be used. The wake functions must be uniformly sampled!

n_binint, optional

Number of bins for constructing the longitudinal bunch profile.

interp_on_postionbool, optional

If True, the computed wake potential is interpolated on the exact particle location. If False, the wake potential is interpolated on the bin center and each particle of the bin get the same value. Default is True.

rhoarray of shape (n_bin, )

Bunch charge density profile in the unit [1/s].

Wparray

Wake potential profile.

Wp_interparray of shape (mp_number, )

Wake potential, obtained from interpolating Wp, exerted on each macro-particle.

charge_density(bunch)

Compute bunch charge density profile in [1/s].

dipole_moment(bunch, plane, tau0)

Return the dipole moment of the bunch computed on the same time array as the wake function.

prepare_wakefunction(wake_type)

Prepare the wake function of a given wake_type to be used for the wake potential computation.

get_wakepotential(bunch, wake_type)

Return the wake potential computed on the wake function time array limited to the bunch profile.

track(bunch)

Tracking method for the element.

plot_last_wake(wake_type)

Plot the last wake potential of a given type computed during the last call of the track method.

reference_loss(bunch)

Calculate the loss factor and kick factor from the wake potential and compare it to a reference value assuming a Gaussian bunch computed in the frequency domain.

check_sampling()

Check if the wake function sampling is uniform.

reduce_sampling(factor)

Reduce wake function samping by an integer factor.

charge_density(bunch)[source]

Compute bunch charge density profile in [1/s].

bunch : Bunch object

check_sampling()[source]

Check if the wake function sampling is uniform.

ValueError

dipole_moment(bunch, plane, tau0)[source]

Return the dipole moment of the bunch computed on the same time array as the wake function.

bunch : Bunch object plane : str

Plane on which the dipole moment is computed, “x” or “y”.

tau0array

Time array on which the dipole moment will be interpolated, in [s].

dipolearray

Dipole moment of the bunch.

get_gaussian_wakepotential(sigma, wake_type, dipole=0.001)[source]

Return the wake potential computed using a perfect gaussian profile.

sigmafloat

RMS bunch length in [s].

wake_typestr

Wake function type: “Wlong”, “Wxdip”, …

dipolefloat, optional

Dipole moment to consider in [m], (uniform dipole moment).

tau0array

Time base in [s].

W0array

Wake function.

Wparray

Wake potential.

profile0array

Gaussian bunch profile.

dipole0array

Dipole moment.

get_wakepotential(bunch, wake_type)[source]

Return the wake potential computed on the wake function time array limited to the bunch profile.

bunch : Bunch object wake_type : str

Wake function type: “Wlong”, “Wxdip”, …

Wparray

Wake potential.

plot_gaussian_wake(sigma, wake_type, dipole=0.001, plot_rho=True, plot_dipole=False, plot_wake_function=True)[source]

Plot the wake potential of a given type for a perfect gaussian bunch.

sigmafloat

RMS bunch length in [s].

wake_typestr

Type of the wake to plot: “Wlong”, “Wxdip”, …

dipolefloat, optional

Dipole moment to consider in [m], (uniform dipole moment).

plot_rhobool, optional

Plot the normalised bunch profile. The default is True.

plot_dipolebool, optional

Plot the normalised dipole moment. The default is False.

plot_wake_functionbool, optional

Plot the normalised wake function. The default is True.

fig : figure

plot_last_wake(wake_type, plot_rho=True, plot_dipole=False, plot_wake_function=True)[source]

Plot the last wake potential of a given type computed during the last call of the track method.

wake_typestr

Type of the wake to plot: “Wlong”, “Wxdip”, …

plot_rhobool, optional

Plot the normalised bunch profile. The default is True.

plot_dipolebool, optional

Plot the normalised dipole moment. The default is False.

plot_wake_functionbool, optional

Plot the normalised wake function. The default is True.

fig : figure

prepare_wakefunction(wake_type, tau, save_data=True)[source]

Prepare the wake function of a given wake_type to be used for the wake potential computation.

The new time array keeps the same sampling time as given in the WakeFunction definition but is restricted to the bunch profile time array.

wake_typestr

Type of the wake function to prepare: “Wlong”, “Wxdip”, …

tauarray

Time domain array of the bunch profile in [s].

save_databool, optional

If True, the results are saved as atributes.

tau0array

Time base of the wake function in [s].

dtau0float

Difference between two points of the wake function time base in [s].

W0array

Wake function array in [V/C] or [V/C/m].

reduce_sampling(factor)[source]

Reduce wake function samping by an integer factor.

Used to reduce computation time for long bunches.

factor : int

reference_loss(bunch)[source]

Calculate the loss factor and kick factor from the wake potential and compare it to a reference value assuming a Gaussian bunch computed in the frequency domain.

bunch : Bunch object

loss_dataDataFrame

An output showing the loss/kick factors compared to the reference values.

track(bunch)[source]

Tracking method for the element. No bunch to bunch interaction, so written for Bunch objects and @Element.parallel is used to handle Beam objects.

bunch : Bunch or Beam object.

Module contents