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]
- 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]
- 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].
- 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]
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
- class mbtrack2.tracking.element.LongitudinalMap(ring)[source]¶
Bases:
Element
Longitudinal map for a single turn in the synchrotron.
ring : Synchrotron 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].
- 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
- class mbtrack2.tracking.element.TransverseMap(ring)[source]¶
Bases:
Element
Transverse map for a single turn in the synchrotron.
ring : Synchrotron 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.
- 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].
- 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.
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
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.
Compute the bunch means and share it between the different bunches.
beam : Beam object
Compute the bunch standard deviations and share it between the different bunches.
beam : Beam object
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_gather()[source]¶
Gather beam, all bunches of the different processors are sent to all processors. Rather slow
- 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.
- 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.
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
- Vbr(I0)[source]¶
Return beam voltage at resonance in [V].
- I0float
Beam current in [A].
- float
Beam voltage at resonance in [V].
- 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
- 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
- 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].
- property DFB_alpha¶
Return the amplitude ratio alpha of the DFB.
Near Eq. (13) of [1].
- 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.
- 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_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.
- 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.
- 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
- 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].
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_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.
- 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.