API Reference

Input Data Structures

Module with container dataclasses to encompass expected necessary inputs . Various parts of xibs perform calculations based on beam and optics parameters.

The former is encompassed in a BeamParameters dataclass which is initiated from a generated xtrack.Particles object. The latter is encompassed in an OpticsParameters dataclass which is initiated from the result of a TWISS call on the line (if in xsuite) or the sequence (if in MAD-X).

class xibs.inputs.BeamParameters(particles: dataclasses.InitVar['xtrack.Particles'])[source]

Added in version 0.2.0.

Container dataclass for necessary beam parameters. It is initiated from the xtrack.Particles object to track in your line with xsuite.

Parameters:

particles (xtrack.Particles) -- the generated particles to be tracked or used in the line. This is an init-only parameter used for instanciation and it will not be kept in the instance’s attributes.

Attributes:

  • n_part (int) -- number of simulated particles.

  • particle_charge (int) -- elementary particle charge, in # of Coulomb charges (for instance 1 for electron or proton).

  • particle_mass_eV (float) -- particle mass in [eV].

  • total_energy_eV (float) -- total energy of the simulated particles in [eV].

  • gamma_rel (float) -- relativistic gamma of the simulated particles.

  • beta_rel (float) -- relativistic beta of the simulated particles.

  • particle_classical_radius_m (float) -- the particles’ classical radius in [m].

classmethod from_line(line: xtrack.Line, n_part: int) → OpticsParameters[source]

Added in version 0.3.0.

Constructor to return a BeamParameters object from an Line object. This is a convenience method for the user, which will instantiate the class from the line’s reference particle.

Parameters:

  • line (xtrack.Line) -- an xtrack.Line.

  • n_part (int) -- number of particles to in the bunch. This is a mandatory argument as it is not possible to infer it from line.particle_ref.

Returns:

A BeamParameters object.

classmethod from_madx(madx: cpymad.madx.Madx) → BeamParameters[source]

Added in version 0.3.0.

Constructor to return a BeamParameters object from a Madx object. This is a convenience method for the user, which essentially queries the relevant information from the current sequence’s beam.

Warning

This method will query parameters from the Madx object. It will get parameters from the current active sequence’s beam, and use these to create an xtrack.Particles object from which to instanciate the BeamParameters object. Note that the xpart package is required to use this method.

Parameters:

madx (cpymad.madx.Madx) -- a Madx instance to created an OpticsParameters object from.

Returns:

A BeamParameters object.

class xibs.inputs.OpticsParameters(twiss: dataclasses.InitVar[typing.Union[ForwardRef('xtrack.twiss.TwissTable'), ForwardRef('pandas.DataFrame')]], _slipfactor: dataclasses.InitVar[Optional[float]] = None, _frev_hz: dataclasses.InitVar[Optional[float]] = None)[source]

Added in version 0.2.0.

Container dataclass for necessary optics parameters. It is initiated from the results of a twiss() command with an xtrack.Line, or result of a TWISS call in MAD-X as a dataframe (as given by cpymad by default).

Parameters:

  • twiss (Union["xtrack.twiss.TwissTable", pd.DataFrame]) -- the resulting TwissTable of a twiss() call on the xtrack.Line, or the TWISS table of the MAD-X sequence as a pandas.DataFrame. Lowercase keys are expected. If initiating from a MAD-X twiss, the next two arguments are required. This is an init-only parameter used for instanciation and it will not be kept in the instance’s attributes.

  • _slipfactor (Optional[float]) -- the slip factor for the machine. Only required if the twiss argument is a MAD-X twiss dataframe. See below for the sign convention used.

  • _frev_hz (Optional[float]) -- the revolution frequency for the machine in [Hz]. Only required if the twiss argument is a MAD-X twiss dataframe.

Attributes:

  • s (ArrayLike) -- longitudinal positions of the machine elements in [m].

  • circumference (float) -- machine circumference in [m].

  • slip_factor (float) -- slip factor of the machine. We are using the Xsuite convention, where the slip factor is positive above transition.

  • revolution_frequency (float) -- revolution frequency of the machine in [Hz].

  • betx (ArrayLike) -- horizontal beta functions in [m].

  • bety (ArrayLike) -- vertical beta functions in [m].

  • alfx (ArrayLike) -- horizontal alpha functions.

  • alfy (ArrayLike) -- vertical alpha functions.

  • dx (ArrayLike) -- horizontal dispersion functions in [m].

  • dy (ArrayLike) -- vertical dispersion functions in [m].

  • dpx (ArrayLike) -- horizontal dispersion of px (d px / d delta).

  • dpy (ArrayLike) -- horizontal dispersion of py (d px / d delta).

classmethod from_line(line: xtrack.Line, **kwargs) → OpticsParameters[source]

Added in version 0.3.0.

Constructor to return an OpticsParameters object from an Line object. This is a convenience method for the user, which will perform a twiss call on the provided line and return an OpticsParameters object.

Parameters:

  • line (xtrack.Line) -- an xtrack.Line.

  • **kwargs -- any keyword argument will be transmitted to the line.twiss call. The default method argument is 4d but it can be overriden.

Returns:

An OpticsParameters object.

classmethod from_madx(madx: cpymad.madx.Madx, **kwargs) → OpticsParameters[source]

Added in version 0.3.0.

Constructor to return an OpticsParameters object from a Madx object. This is a convenience method for the user, which essentially follows the steps described in the FAQ.

Warning

This method will query parameters from the Madx object. It will get parameters from the current active sequence, and make a TWISS call for said sequence.

Parameters:

  • madx (cpymad.madx.Madx) -- a Madx instance to created an OpticsParameters object from.

  • **kwargs -- any keyword argument will be transmitted to the madx.twiss call. The default centre argument is true (recommended) but it can be overriden.

Returns:

An OpticsParameters object.

Formalism Dispatch

This module provides a single function, ibs, to ease the class instantiation for the user. The function returns an instance of the relevant IBS modelling class based on the desired formalism.

xibs.dispatch.ibs(beam_params: BeamParameters, optics_params: OpticsParameters, formalism: str) → BjorkenMtingwaIBS | NagaitsevIBS | KineticKickIBS | SimpleKickIBS[source]

A dispatch function to return the appropriate IBS modelling class based on the desired formalism.

Parameters:

  • beam_parameters (BeamParameters) -- the beam parameters to use for the calculations. They will be used to initialize the relevant IBS class.

  • optics_params (OpticsParameters) -- the optics parameters to use for the calculations. They will be used to initialize the relevant IBS class.

  • formalism (str) -- the desired IBS modelling formalism. This determines which IBS class will be returned. Valid options are: “bjorken-mtingwa” (or also “b&m”), “nagaitsev”, “kinetic”, and “simple”. This argument is case-insensitive. See the return annotation below for more details.

Returns:

An instance of the relevant IBS modelling class. The chosen class is determined by the formalism argument. Below are the various options and corresponding returned classes:

  • bjorken-mtingwa or b&m: returns a BjorkenMtingwaIBS instance (see IBS: Analytical Calculations), which implements the MAD-X analytical calculations for IBS growth rates that build on Bjorken & Mtingwa’s formalism to take in consideration vertical dispersion.

  • nagaitsev: returns a NagaitsevIBS instance (see IBS: Analytical Calculations), which implements the Nagaitsev analytical calculation for IBS growth rates. It is very fast, but does not take in consideration the vertical dispersion.

  • kinetic: returns a KineticKickIBS instance (see IBS: Applying Kicks), which implements the kinetic kick-based formalism.

  • simple: returns a SimpleKickIBS instance (see IBS: Applying Kicks), which implements the kick formalism from Nagaitsev analytical values.

Example

from xibs import ibs, BeamParameters, OpticsParameters

# Here is where you would define your inputs
beam_params = BeamParameters(...)
optics = OpticsParameters(...)

# Get the proper modelling class based on the demanded formalism
BM_IBS = ibs(beam_params, optics, formalism="b&m")  # a BjorkenMtingwaIBS instance
NAGAITSEV_IBS = ibs(beam_params, optics, formalism="nagaitsev")  # a NagaitsevIBS instance
KINETIC_IBS = ibs(beam_params, optics, formalism="kinetic")  # a KineticKickIBS instance
SIMPLE_IBS = ibs(beam_params, optics, formalism="simple")  # a SimpleKickIBS instance

IBS: Analytical Calculations

Module with functionality to perform analytical IBS calculations, either according to either Nagaitsev’s or Bjorken & Mtingwa’s formalism. User-facing classes are provided which allow to compute the growth rates based on beam parameters and machine optics. The formalism from which formulas and calculations are implemented can be found in [Nag05] and [AZ12], respectively.

Warning

Please note that these analytical implementations make the assumptions. Should your scenario not satisfy the following assumptions, the results might not be accurate:

  • It is assumed that beam profiles are Gaussian,

  • It is assumed that no betatron coupling is present in the machine (or very little, in the order of \(\left| C^{-} \right| \le 10^{-4}\)).

Should these assumptions not be satisfied, the results provided by these calculations are not to be entirely discarded but might not be totally accurate.

class xibs.analytical.AnalyticalIBS(beam_params: BeamParameters, optics: OpticsParameters)[source]

Added in version 0.4.0.

Abstract base class for analytical IBS calculations, from which all implementations inherit.

Attributes:

  • beam_parameters (BeamParameters) -- the beam parameters to use for the calculations.

  • optics (OpticsParameters) -- the optics parameters to use for the calculations.

  • ibs_growth_rates (IBSGrowthRates) -- the computed IBS growth rates. This self-updates when they are computed with the growth_rates method.

coulomb_log(epsx: float, epsy: float, sigma_delta: float, bunch_length: float, bunched: bool = True, normalized_emittances: bool = False) → float[source]

Added in version 0.2.0.

Calculates the Coulomb logarithm based on the beam parameters and optics the class was initiated with. For a good introductory resource on the Coulomb Log, see: https://docs.plasmapy.org/en/stable/notebooks/formulary/coulomb.html.

Note

This function follows the formulae in [HLAnderson81]. The Coulomb log is computed as \(\ln \left( \Lambda \right) = \ln(r_{max} / r_{min})\). Here \(r_{max}\) denotes the smaller of \(\sigma_x\) and the Debye length; while \(r_{min}\) is the larger of the classical distance of closest approach and the quantum diffraction limit from the nuclear radius. It is the calculation that is done by MAD-X (see the twclog subroutine in the MAD-X/src/ibsdb.f90 source file).

Note

Both geometric or normalized emittances can be given as input to this function, and it is assumed the user provides geomettric emittances. If normalized ones are given the normalized_emittances parameter should be set to True (it defaults to False). Internally, a conversion is done to geometric emittances, which are used in the computations.

Parameters:

  • epsx (float) -- horizontal geometric or normalized emittance in [m].

  • epsy (float) -- vertical geometric or normalized emittance in [m].

  • sigma_delta (float) -- momentum spread.

  • bunch_length (float) -- bunch length in [m].

  • bunched (bool) -- whether the beam is bunched or not (coasting). Defaults to True.

  • normalized_emittances (bool) -- whether the provided emittances are normalized or not. Defaults to False (assume geometric emittances).

Returns:

The dimensionless Coulomb logarithm \(\ln \left( \Lambda \right)\).

emittance_evolution(epsx: float, epsy: float, sigma_delta: float, bunch_length: float, dt: float = None, normalized_emittances: bool = False, auto_recompute_rates_percent: float = None, **kwargs) → Tuple[float, float, float, float][source]

Added in version 0.2.0.

Analytically computes the new emittances after a given time step dt has ellapsed, from initial values, based on the IBS growth rates.

Warning

This calculation is done by building on the IBS growth rates. If the latter have not been computed yet, this method will raise an error. Please remember to call the instance’s growth_rates method first.

Hint

The calculation is an exponential growth based on the rates \(T_{x,y,z}\). It goes according to the following, where \(N\) represents the time step:

\[ \begin{align}\begin{aligned}T_{x,y,z} &= 1 / \tau_{x,y,z}\\\varepsilon_{x,y}^{N+1} &= \varepsilon_{x,y}^{N} * e^{t / \tau_{x,y}}\\\sigma_{\delta, z}^{N+1} &= \sigma_{\delta, z}^{N} * e^{t / 2 \tau_{z}}\end{aligned}\end{align} \]

Note

Both geometric or normalized emittances can be given as input to this function, and it is assumed the user provides geomettric emittances. If normalized ones are given the normalized_emittances parameter should be set to True (it defaults to False). Internally, a conversion is done to geometric emittances, which are used in the computations. The returned emittances correspond to the type of those provided: if given normalized emittances this function will return values that correspond to the new normalized emittances.

Synchrotron Radiation

Synchrotron Radiation can play a significant role in the evolution of the emittances in certain scenarios, particularly for leptons. One can include the contribution of SR to this calculation by providing several keyword arguments corresponding to the equilibrium emittances and damping times from SR and quantum excitation. See the list of expected kwargs below. A dedicated section in the FAQ provides information on how to obtain these values from Xsuite or MAD-X.

In case this contribution is included, then the calculation is modified from the one shown above, and goes according to [Wol14] (Eq (13.64)) or [Mar15] (Eq (135)):

\[ \begin{align}\begin{aligned}T_{x,y,z} &= 1 / \tau_{x,y,z}^{\mathrm{IBS}}\\\varepsilon_{x,y}^{N+1} &= \left[ - \varepsilon_{x,y}^{\mathrm{SR}eq} + \left( \varepsilon_{x,y}^{\mathrm{SR}eq} + \frac{\varepsilon_{x,y}^{N}}{2 \tau_{x,y}^{\mathrm{IBS}}} \tau_{x,y}^{\mathrm{SR}} - 1 \right) * e^{2 t \left( \frac{1}{2 \tau_{x,y}^{\mathrm{IBS}}} - \frac{1}{\tau_{x,y}^{\mathrm{SR}}} \right)} \right] / \left( \frac{\tau_{x,y}^{\mathrm{SR}}}{2 \tau_{x,y}^{\mathrm{IBS}}} - 1 \right)\\{\sigma_{\delta, z}^{N+1}}^2 &= \left[ - {\sigma_{\delta, z}^{\mathrm{SR}eq}}^2 + \left( {\sigma_{\delta, z}^{\mathrm{SR}eq}}^2 + \frac{{\sigma_{\delta, z}^{N}}^2}{2 \tau_{z}^{\mathrm{IBS}}} \tau_{z}^{\mathrm{SR}} - 1 \right) * e^{2 t \left( \frac{1}{2 \tau_{z}^{\mathrm{IBS}}} - \frac{1}{\tau_{z}^{\mathrm{SR}}} \right)} \right] / \left( \frac{\tau_{z}^{\mathrm{SR}}}{2 \tau_{z}^{\mathrm{IBS}}} - 1 \right)\end{aligned}\end{align} \]
Parameters:

  • epsx (float) -- horizontal geometric or normalized emittance in [m].

  • epsy (float) -- vertical geometric or normalized emittance in [m].

  • sigma_delta (float) -- momentum spread.

  • dt (float, optional) -- the time interval to use, in [s]. Default to the inverse of the revolution frequency, \(1 / f_{rev}\).

  • bunch_length (float) -- the bunch length in [m].

  • normalized_emittances (bool) -- whether the provided emittances are normalized or not. Defaults to False (assume geometric emittances).

  • auto_recompute_rates_percent (float) -- Optional. If given, a check is performed to determine if an update of the growth rates is necessary, in which case it will be done before computing the emittance evolutions. Please provide a value as a percentage of the emittance change since the last update of the growth rates. For instance, if one provides 12, a check is made to see if any quantity would have changed by more than 12% compared to reference values stored at the last growth rates update, and if so the growth rates are automatically recomputed to be as up-to-date as possible before returning the new values. Defaults to None (no checks done, no auto-recomputing).

  • **kwargs --

    If keyword arguments are provided, they are considered inputs for the inclusion of synchrotron radiation in the calculation, and the following are expected, case-insensitively:

    • sr_equilibrium_epsx (float)

      the horizontal equilibrium emittance from synchrotron radiation and quantum excitation, in [m]. Should be the same type (geometric or normalized) as epsx and epsy.

    • sr_equilibrium_epsy (float)

      the vertical equilibrium emittance from synchrotron radiation and quantum excitation, in [m]. Should be the same type (geometric or normalized) as epsx and epsy.

    • sr_equilibrium_sigma_delta (float)

      the equilibrium momentum spread from synchrotron radiation and quantum excitation.

    • sr_tau_x (float)

      the horizontal damping time from synchrotron radiation, in [s] (should be the same unit as dt).

    • sr_tau_y (float)

      the vertical damping time from synchrotron radiation, in [s] (should be the same unit as dt).

    • sr_tau_z (float)

      the longitudinal damping time from synchrotron radiation, in [s] (should be the same unit as dt).

Returns:

A tuple with the new horizontal & vertical geometric emittances, the new momentum spread and the new bunch length, after the time step has ellapsed.

abstract growth_rates(epsx: float, epsy: float, sigma_delta: float, bunch_length: float, bunched: bool = True, normalized_emittances: bool = False) → IBSGrowthRates[source]

Method to compute the IBS growth rates.

Parameters:

  • epsx (float) -- horizontal geometric or normalized emittance in [m].

  • epsy (float) -- vertical geometric or normalized emittance in [m].

  • sigma_delta (float) -- momentum spread.

  • bunch_length (float) -- the bunch length in [m].

  • bunched (bool) -- whether the beam is bunched or not (coasting). Defaults to True.

  • normalized_emittances (bool) -- whether the provided emittances are normalized or not. Defaults to False (assume geometric emittances).

Returns:

An IBSGrowthRates object with the computed growth rates for each plane.

class xibs.analytical.BjorkenMtingwaIBS(beam_params: BeamParameters, optics: OpticsParameters)[source]

Added in version 0.3.0.

A single class to compute the IBS growth rates according to the Bjorken & Mtingwa formalism. The exact approach follows the MAD-X implementation, which has corrected B&M in order to take in consideration the vertical dispersion values (see the relevant note about the changes at [AZ12]). It initiates from a BeamParameters and an OpticsParameters objects.

See the Bjorken-Mtingwa example for detailed usage, and the Nagaitsev example for a comparison to the Nagaitsev formalism.

Note

If possible, when creating the OpticsParameters to initiate this class, please do so by providing the TWISS values calculated at the center of elements. This is done by giving the flag centre=true to the TWISS command in MAD-X, for instance. If this isn’t done, a warning will be issued that one might observe some slight discrepancies against MAD-X result values.

Attributes:

  • beam_parameters (BeamParameters) -- the beam parameters to use for the calculations.

  • optics (OpticsParameters) -- the optics parameters to use for the calculations.

  • ibs_growth_rates (IBSGrowthRates) -- the computed IBS growth rates. This self-updates when they are computed with the growth_rates method.

growth_rates(epsx: float, epsy: float, sigma_delta: float, bunch_length: float, bunched: bool = True, normalized_emittances: bool = False, integration_intervals: int = 17) → IBSGrowthRates[source]

Added in version 0.3.0.

Computes the IBS growth rates, named \(T_x, T_y\) and \(T_z\) in this code base. These correspond to the \(1 / \tau\) term, for each plane \(x, y\) and \(z\), respectively. The instance attribute self.ibs_growth_rates is automatically updated with the results of this method when it is called.

Warning

When creating the OpticsParameters to initiate this class, please do so by providing the TWISS values calculated at the center of elements. This is done by giving the flag centre=true to the TWISS command in MAD-X for instance. If not, one might observe some slight discrepancies with the MAD-X values.

Hint

The calculation is done according to the following steps, which are related to different equations in [AZ12]:

  • Adjusts the \(D_x, D_y, D^{\prime}_{x}, D^{\prime}_{y}\) terms (multiply by \(\beta_{rel}\)) to be in the \(pt\) frame.

  • Computes the various terms from Table 1 of the MAD-X note.

  • Computes the Coulomb logarithm and the common constant term (first fraction) of Eq (8).

  • Defines the integrands of integrals in Eq (8) of the MAD-X note.

  • Defines sub-intervals and integrates the above over all of them, getting growth rates at each element in the lattice.

  • Averages the results over the full circumference of the machine.

Geometric or Normalized Emittances

Both geometric or normalized emittances can be given as input to this function, and it is assumed the user provides geomettric emittances. If normalized ones are given the normalized_emittances parameter should be set to True (it defaults to False). Internally, a conversion is done to geometric emittances, which are used in the computations. For more information please see the following section of the FAQ.

Parameters:

  • epsx (float) -- horizontal geometric or normalized emittance in [m].

  • epsy (float) -- vertical geometric or normalized emittance in [m].

  • sigma_delta (float) -- momentum spread.

  • bunch_length (float) -- the bunch length in [m].

  • bunched (bool) -- whether the beam is bunched or not (coasting). Defaults to True.

  • normalized_emittances (bool) -- whether the provided emittances are normalized or not. Defaults to False (assume geometric emittances).

  • integration_intervals (int) -- the number of sub-intervals to use when integrating the integrands of Eq (8) of the MAD-X note. Please DO NOT change this parameter unless you know exactly what you are doing, as you might affect convergence. Defaults to 17.

Returns:

An IBSGrowthRates object with the computed growth rates for each plane.

class xibs.analytical.IBSGrowthRates(Tx: float, Ty: float, Tz: float)[source]

Added in version 0.2.0.

Container dataclass for IBS growth rates results.

Parameters:

  • Tx (float) -- horizontal IBS growth rate.

  • Ty (float) -- vertical IBS growth rate.

  • Tz (float) -- longitudinal IBS growth rate.

class xibs.analytical.NagaitsevIBS(beam_params: BeamParameters, optics: OpticsParameters)[source]

Added in version 0.2.0.

A single class to compute Nagaitsev integrals (see [Nag05]) and IBS growth rates. It initiates from a BeamParameters and an OpticsParameters objects.

See the Nagaitsev example for detailed usage, and the Bjorken-Mtingwa example for a comparison to the Bjorken-Mtingwa formalism.

Attributes:

  • beam_parameters (BeamParameters) -- the beam parameters to use for the calculations.

  • optics (OpticsParameters) -- the optics parameters to use for the calculations.

  • elliptic_integrals (NagaitsevIntegrals) -- the computed elliptic integrals. This self-updates when they are computed with the integrals method.

  • ibs_growth_rates (IBSGrowthRates) -- the computed IBS growth rates. This self-updates when they are computed with the growth_rates method.

growth_rates(epsx: float, epsy: float, sigma_delta: float, bunch_length: float, bunched: bool = True, normalized_emittances: bool = False, compute_integrals: bool = True) → IBSGrowthRates[source]

Added in version 0.2.0.

Computes the IBS growth rates, named \(T_x, T_y\) and \(T_z\) in this code base, from Nagaitsev integrals. These correspond to the \(1 / \tau\) term, for each plane, of Eq (28) in [Nag05], respectively. The instance attribute self.ibs_growth_rates is automatically updated with the results of this method when it is called.

Warning

Currently this calculation does not take into account vertical dispersion. Should you have any in your lattice, please use the BjorkenMtingwaIBS class instead, which supports it fully. Supporting vertical dispersion in NagaitsevIBS might be implemented in a future version.

Hint

The calculation is done according to the following steps, which are related to different equations in [Nag05]:

  • Get the Nagaitsev integrals from the instance attributes (integrals of Eq (30-32)).

  • Computes the Coulomb logarithm for the defined beam and optics parameters.

  • Compute the rest of the constant term of Eq (30-32).

  • Compute for each plane the full result of Eq (30-32), respectively.

  • Plug these into Eq (28) and divide by either \(\varepsilon_x, \varepsilon_y\) or \(\sigma_{\delta}^{2}\) (as relevant) to get \(1 / \tau\).

Note: As one can see above, this calculation is done by building on the Nagaitsev integrals. If these have not been computed yet, this method will first log a message and compute them, then compute the growth rates.

Geometric or Normalized Emittances

Both geometric or normalized emittances can be given as input to this function, and it is assumed the user provides geomettric emittances. If normalized ones are given the normalized_emittances parameter should be set to True (it defaults to False). Internally, a conversion is done to geometric emittances, which are used in the computations. For more information please see the following section of the FAQ.

Coasting Beams

It is possible in this formalism to get an approximation in the case of coasting beams by providing bunched=False. This will as a bunch length \(C / 2 \pi\) with C the circumference (or length) of the machine, and a warning will be logged for the user. Additionally the appropriate adjustement will be made in the Coulomb logarithm calculation, and the resulting growth rates will be divided by a factor 2 before being returned (see [ICH74]). For fully accurate results in the case of coasting beams, please use the BjorkenMtingwaIBS class instead.

Parameters:

  • epsx (float) -- horizontal geometric or normalized emittance in [m].

  • epsy (float) -- vertical geometric or normalized emittance in [m].

  • sigma_delta (float) -- momentum spread.

  • bunch_length (float) -- the bunch length in [m].

  • bunched (bool) -- whether the beam is bunched or not (coasting). Defaults to True. Please note that this will do an approximation using bunch_length=C/(2*pi). For fully accurate results in the case of coasting beams, please use the BjorkenMtingwaIBS class instead.

  • normalized_emittances (bool) -- whether the provided emittances are normalized or not. Defaults to False (assume geometric emittances).

  • compute_integrals (bool) -- if True, the Nagaitsev elliptic integrals will be computed before the growth rates. Defaults to True. New in version 0.3.0.

Returns:

An IBSGrowthRates object with the computed growth rates for each plane.

integrals(epsx: float, epsy: float, sigma_delta: float, normalized_emittances: bool = False) → NagaitsevIntegrals[source]

Added in version 0.2.0.

Computes the Nagaitsev integrals, named \(I_x, I_y\) and \(I_z\) in this code base.

These correspond to the integrals inside of Eq (32), (31) and (30) in [Nag05], respectively. The instance attribute self.elliptic_integrals is automatically updated with the results of this method. It is used for other calculations.

Hint

The calculation is done according to the following steps, which are related to different equations in [Nag05]:

  • Computes various intermediate terms and then \(a_x, a_y, a_s, a_1\) and \(a_2\) constants from Eq (18-21).

  • Computes the eigenvalues \(\lambda_1, \lambda_2\) of the \(\bf{A}\) matrix (\(\bf{L}\) matrix in B&M) from Eq (22-24).

  • Computes the \(R_1, R_2\) and \(R_3\) terms from Eq (25-27) with the forms of Eq (5-6).

  • Computes the \(S_p, S_x\) and \(S_{xp}\) terms from Eq (33-35).

  • Computes and returns the integrals terms in Eq (30-32).

Note

Both geometric or normalized emittances can be given as input to this function, and it is assumed the user provides geomettric emittances. If normalized ones are given the normalized_emittances parameter should be set to True (it defaults to False). Internally, a conversion is done to geometric emittances, which are used in the computations.

Parameters:

  • epsx (float) -- horizontal geometric or normalized emittance in [m].

  • epsy (float) -- vertical geometric or normalized emittance in [m].

  • sigma_delta (float) -- momentum spread. Defaults to None.

  • normalized_emittances (bool) -- whether the provided emittances are normalized or not. Defaults to False (assume geometric emittances).

Returns:

A NagaitsevIntegrals object with the computed integrals for each plane.

class xibs.analytical.NagaitsevIntegrals(Ix: float, Iy: float, Iz: float)[source]

Added in version 0.2.0.

Container dataclass for Nagaitsev integrals results.

Parameters:

  • Ix (float) -- horizontal Nagaitsev integral.

  • Iy (float) -- vertical Nagaitsev integral.

  • Iz (float) -- longitudinal Nagaitsev integral.

IBS: Applying Kicks

Module with user-facing API to compute relevant terms to IBS kicks according to different formalism: simple and kinetic kicks.

In the simple formalism, the applied IBS kicks are determined from analytical IBS growth rates, which are computed internally (see IBS: Analytical Calculations). In the kinetic formalism, which adapts the kinetic theory of gases, the applied IBS kicks are determined from computed diffusion and friction terms.

class xibs.kicks.DiffusionCoefficients(Dx: float, Dy: float, Dz: float)[source]

Container dataclass for kinetic IBS diffusion coefficients.

Parameters:

  • Dx (float) -- horizontal diffusion coefficient.

  • Dy (float) -- vertical diffusion coefficient.

  • Dz (float) -- longitudinal diffusion coefficient.

class xibs.kicks.FrictionCoefficients(Fx: float, Fy: float, Fz: float)[source]

Container dataclass for kinetic IBS friction coefficients.

Parameters:

  • Fx (float) -- horizontal friction coefficient.

  • Fy (float) -- vertical friction coefficient.

  • Fz (float) -- longitudinal friction coefficient.

class xibs.kicks.IBSKickCoefficients(Kx: float, Ky: float, Kz: float)[source]

Container dataclass for all IBS kick coefficients. These can be the coeffients from simple kicks, computed from analytical growth rates, or kinetic coefficients computed from the diffusion and friction ones according to [POA06].

Parameters:

  • Kx (float) -- horizontal kick coefficient.

  • Ky (float) -- vertical kick coefficient.

  • Kz (float) -- longitudinal kick coefficient.

class xibs.kicks.KickBasedIBS(beam_params: BeamParameters, optics: OpticsParameters, auto_recompute_coefficients_percent: float = None)[source]

Added in version 0.5.0.

Abstract base class for kick-based IBS effects, from which all implementations inherit.

Attributes:

  • beam_parameters (BeamParameters) -- the beam parameters to use for IBS computations.

  • optics (OpticsParameters) -- the optics parameters to use for the IBS computations.

  • auto_recompute_coefficients_percent (float) -- Optional. If given, a check is performed after kicking the particles to determine if recomputing the kick coefficients is necessary, in which case it will be done before the next kick. Please provide a value as a percentage of the emittance change. For instance, if one provides 12 after kicking a check is done to see if the emittance changed by more than 12% in any plane, and if so the coefficients will be automatically recomputed before the next kick. Defaults to None (no checks done, no auto-recomputing).

  • kick_coefficients (IBSKickCoefficients) -- the computed IBS kick coefficients. This attribute self-updates when they are computed with the compute_kick_coefficients method. It can also be set manually.

apply_ibs_kick(particles: xtrack.Particles, n_slices: int = 40) → None[source]

Added in version 0.5.0.

Compute and apply momenta kicks based on the provided xtrack.Particles object and the chosen IBS formalism. See the _apply_formalism_ibs_kick method for implementation details of the currently selected formalism.

Parameters:

  • particles (xtrack.Particles) -- the xtrack.Particles object to apply IBS kicks to.

  • n_slices (int) -- the number of slices to use for the computation of the line density. Defaults to 40.

abstract compute_kick_coefficients(particles: xtrack.Particles, **kwargs) → IBSKickCoefficients[source]

Added in version 0.5.0.

Abstract method to determine the kick coefficients used in the determination of the IBS to be applied. It returns an IBSKickCoefficients object with the computed coefficients.

Parameters:

particles (xtrack.Particles) -- the particles to apply the IBS kicks to.

line_density(particles: xtrack.Particles, n_slices: int) → ArrayLike[source]

Added in version 0.5.0.

Returns the “line density” of the Particles object, along its longitudinal axis, which corresponds to the \(\rho_t(t)\) term in Eq (8) of [RJMMW10]. The density is used as a weight factor for the application of IBS kicks: particles in the denser parts of the bunch will receive a larger kick, and vice versa. See section III.C of the above reference details.

Hint

The calculation is done according to the following steps:

  • Gets the longitudinal coordinates of the active particles (state > 0) in the Particles object.

  • Determines coordinate cuts at front and back of the bunch, as well as slice width.

  • Determines bin edges and bin centers for the distribution for the chosen number of slices.

  • Computes a (normalized) histogram of the longitudinal coordinates, with the determined bins.

  • Computes and returns the line density \(\rho_t(t)\).

Parameters:

  • particles (xtrack.Particles) -- the xtrack.Particles object to compute the line density for.

  • n_slices (int) -- the number of slices to use for the computation of the bins.

Returns:

An array with the density values for each slice / bin of the Particles object.

class xibs.kicks.KineticKickIBS(beam_params: BeamParameters, optics: OpticsParameters, auto_recompute_coefficients_percent: float = None)[source]

Added in version 0.7.0.

A single class to compute the IBS diffusion and friction coefficients according to the kinetic IBS formalism of [POA06]. The class initiates from a BeamParameters and an OpticsParameters objects.

See the kinetic kicks example for detailed usage.

Attributes:

  • beam_parameters (BeamParameters) -- the beam parameters to use for IBS computations.

  • optics (OpticsParameters) -- the optics parameters to use for the IBS computations.

  • diffusion_coefficients (DiffusionCoefficients) -- the computed diffusion coefficients from the kinetic theory. This attribute self-updates when coefficients are computed with the compute_kick_coefficients method. It can also be set manually.

  • friction_coefficients (FrictionCoefficients) -- the computed friction coefficients from the kinetic theory. This attribute self-updates when coefficients are computed with the compute_kick_coefficients method. It can also be set manually.

  • auto_recompute_coefficients_percent (float) -- Optional. If given, a check is performed after kicking the particles to determine if recomputing the kick coefficients is necessary, in which case it will be done before the next kick. Please provide a value as a percentage of the emittance increase. For instance, if one provides 12 after kicking a check is done to see if the emittance grew by more than 12% in any plane, and if so the coefficients will be automatically recomputed before the next kick. Defaults to None (no checks done, no auto-recomputing).

  • kick_coefficients (IBSKickCoefficients) -- the computed IBS kick coefficients from the kinetic theory, determined from the diffusion and friction coefficients. This attribute self-updates when coefficients are computed with the compute_kick_coefficients method. It can also be set manually.

compute_kick_coefficients(particles: xtrack.Particles, **kwargs) → IBSKickCoefficients[source]

Added in version 0.7.0.

Computes the IBS kick coefficients, named \(K_x, K_y\) and \(K_z\) in this code base, from the friction and diffusion terms of the kinetic theory as expressed in [POA06], and using terms from Nagaitsev’s formalism ([Nag05]) as determined by M. Zampetakis ([Zam12]). This will compute both diffusion and friction coefficients from this formalism, which will be stored and updated internally into the diffusion_coefficients and friction_coefficients attributes. It returns an IBSKickCoefficients object with the computed coefficients (diffusion - friction).

Note

This functionality is separate from the kick application because it internally triggers the computation of the analytical growth rates, and we don’t necessarily want to recompute these at every turn. Meanwhile, the kicks should be applied at every turn.

Hint

The calculation is done according to the following steps:

  • Computes various terms from [Nag05] as well as elliptic integrals.

  • Computes the \(D_{xx}, D_{xz}, D_{yy}, D_{zz}, K_x, K_y\) and \(K_z\) terms.

  • Computes diffusion and friction coefficients from the above, following [Zam12].

  • Computes and returns kick coefficients (as the difference between diffusion and friction).

Parameters:

  • particles (xtrack.Particles) -- the particles to apply the IBS kicks to.

  • **kwargs -- if bunched is found in keyword arguments it will be passed to the coulomb logarithm calculation. A default value of True is used.

Returns:

An IBSKickCoefficients object with the computed coefficients used for the kick application.

class xibs.kicks.SimpleKickIBS(beam_params: BeamParameters, optics: OpticsParameters, auto_recompute_coefficients_percent: float = None)[source]

Added in version 0.5.0.

A single class to compute the simple IBS kicks based on the analytical growth rates. The kicks are implemented according to [RJMMW10], and provide a random distribution of momenta changes based on the growth rates, weighted by the line density of the bunch. The class initiates from a BeamParameters and an OpticsParameters objects.

See the simple kicks example for detailed usage.

Warning

Beware: this implementation is only valid above transition energy. Because this formalism implements a weighted random-component kick, it will always lead to emittance growth. Below transition it is common to observe negative growth rates, which would lead to emittance shrinkage and therefore the provided kick would have the wrong effect. It is also possible to obtain negative growth rates above transition in some scenarios, and internally this implementation sets the growth rate to 0 if it is found negative. When this happens, a message is logged to inform the user. For any machine operating below transition energy, the kinetic formalism should be used instead (see the KineticKickIBS class).

Hint

When determining kick coefficients (see the compute_kick_coefficients method), the analytical growth rates are computed. This is done using one of the analytical classes, which is determined internally based on the optics parameters (namely, the presence of vertical dispersion), and set as the self.analytical_ibs attribute. Choices are logged to the user. It is always possible to override this choice by manually setting the self.analytical_ibs attribute to an instance of the desired analytical implementation (to be found in xibs.analytical). It is also possible for the user to provide their own, custom-made analytical implementation, as long as it inherits from the AnalyticalIBS class and implements the API defined therein.

Attributes:

  • beam_parameters (BeamParameters) -- the beam parameters to use for IBS computations.

  • optics (OpticsParameters) -- the optics parameters to use for the IBS computations.

  • analytical_ibs (AnalyticalIBS) -- an internal analytical class for growth rates calculation, which is determined automatically. Can be overridden by the user by setting this attribute manually.

  • auto_recompute_coefficients_percent (float) -- Optional. If given, a check is performed after kicking the particles to determine if recomputing the kick coefficients is necessary, in which case it will be done before the next kick. Please provide a value as a percentage of the emittance increase. For instance, if one provides 12 after kicking a check is done to see if the emittance grew by more than 12% in any plane, and if so the coefficients will be automatically recomputed before the next kick. Defaults to None (no checks done, no auto-recomputing).

  • kick_coefficients (IBSKickCoefficients) -- the computed IBS kick coefficients. This self-updates when they are computed with the compute_kick_coefficients method. It can also be set manually.

property analytical_ibs: AnalyticalIBS

The analytical IBS implementation used for growth rates calculation.

compute_kick_coefficients(particles: xtrack.Particles, **kwargs) → IBSKickCoefficients[source]

Added in version 0.5.0.

Computes the IBS kick coefficients, named \(K_x, K_y\) and \(K_z\) in this code base, from analytical growth rates. The coefficients correspond to the right-hand side of Eq (8) in [RJMMW10] without the line density \(\rho_t(t)\) and random component \(r\).

The kick coefficient corresponds to the scaling of the generated random distribution \(r\) and is expressed as \(K_u = \sigma_{p_u} \sqrt{2 T^{-1}_{IBS_u} T_{rev} \sigma_t \sqrt{\pi}}\).

Note

This functionality is separate from the kick application as it internally triggers the computation of the analytical growth rates. Since this step is computationally intensive and one might not necessarily want to recompute the rates before every kick application.

Hint

The calculation is done according to the following steps, which are related to different terms in Eq (8) of [RJMMW10]:

  • Computes various properties from the non-lost particles in the bunch (\(\sigma_{x,y,\delta,t}\)).

  • Computes the standard deviation of momenta for each plane (\(\sigma_{p_u}\)).

  • Computes the constant term \(\sqrt{2 T_{rev} \sqrt{\pi}}\).

  • Computes the analytical growth rates \(T_{x,y,z}\) (\(T^{-1}_{IBS_u}\) in Eq (8)).

  • Computes, stores and returns the kick coefficients.

Parameters:

  • particles (xtrack.Particles) -- the particles to apply the IBS kicks to.

  • **kwargs -- any keyword arguments will be passed to the growth rates calculation call (self.analytical_ibs.growth_rates). Note that epsx, epsy, sigma_delta, and bunch_length are already provided as positional-only arguments.

Returns:

An IBSKickCoefficients object with the computed coefficients used for the kick application.

Formulary

Module with commonly used formulae to compute quantities of interest needed in the rest of the package.

xibs.formulary.phi(beta: ArrayLike, alpha: ArrayLike, dx: ArrayLike, dpx: ArrayLike) → ArrayLike[source]

Added in version 0.2.0.

Phi parameter of Eq (15) in [Nag05].

Parameters:

  • beta (ArrayLike) -- beta-functions through the machine.

  • alpha (ArrayLike) -- alpha-functions through the machine.

  • dx (ArrayLike) -- dispersion function through the machine.

  • dpx (ArrayLike) -- dpx function through the machine.

Returns:

An array of phi values through the machine.

xibs.version.version_info() → str[source]

Added in version 0.2.0.

Debug convenience function to give version, platform and runtime information.