mbtrack2.tracking.beam_ion_effects module

Module implementing necessary functionalities for beam-ion interactions. Classes: BeamIonElement IonMonitor

class BeamIonElement(ion_mass: float, ion_charge: float, ionization_cross_section: float, residual_gas_density: float, ring: Synchrotron, ion_field_model: str, electron_field_model: str, ion_element_length: float, n_ion_macroparticles_per_bunch: int = 30, generate_method: str = 'distribution', generate_ions: bool = True, beam_ion_interaction: bool = True, ion_drift: bool = True)

Bases: Element

Represents an element for simulating beam-ion interactions.

Apertures and monitors for the ion beam (instances of IonAperture and IonMonitor) can be added to tracking after the BeamIonElement object has been initialized by using:

beam_ion.apertures.append(aperture) beam_ion.monitors.append(monitor)

If the a IonMonitor object is used to record the ion beam, at the end of tracking the user should close the monitor, for example by calling:

beam_ion.monitors[0].close()

Parameters

ion_massfloat

The mass of the ions in [kg].

ion_chargefloat

The charge of the ions in [C].

ionization_cross_sectionfloat

The cross section of ionization in [m^2].

residual_gas_densityfloat

The residual gas density in [m^-3].

ringinstance of Synchrotron()

The ring.

ion_field_model{‘weak’, ‘strong’, ‘PIC’}

The ion field model used to update electron beam coordinates:

• ‘weak’: ion field acts on each macroparticle.

• ‘strong’: ion field acts on electron bunch c.m.

• ‘PIC’: a PIC solver is used to get the ion electric field and the

result is interpolated on the electron bunch coordinates.

For both ‘weak’ and ‘strong’ models, the electric field is computed using the Bassetti-Erskine formula [1], so assuming a Gaussian beam distribution. For ‘PIC’ the PyPIC package is required.

electron_field_model{‘weak’, ‘strong’, ‘PIC’}

The electron field model, defined in the same way as ion_field_model.

ion_element_lengthfloat

The length of the beam-ion interaction region. For example, if only a single interaction point is used this should be equal to ring.L.

n_ion_macroparticles_per_bunchint, optional

The number of ion macroparticles generated per electron bunch passage. Defaults to 30.

generate_method{‘distribution’, ‘samples’}, optional

The method to generate the ion macroparticles:

• ‘distribution’ generates a distribution statistically equivalent

to the distribution of electrons. - ‘samples’ generates ions from random samples of electron positions.

Defaults to ‘distribution’.

generate_ionsbool, optional

If True, generate ions during BeamIonElement.track calls. Default is True.

beam_ion_interactionbool, optional

If True, update both beam and ion beam coordinate due to beam-ion interaction during BeamIonElement.track calls. Default is True.

ion_driftbool, optional

If True, update ion beam coordinate due to drift time between bunches. Default is True.

Methods

__init__(ion_mass, ion_charge, ionization_cross_section,

residual_gas_density, ring, ion_field_model, electron_field_model, ion_element_length, n_ion_macroparticles_per_bunch=30, generate_method=’distribution’)

Initializes the BeamIonElement object.

parallel(track)

Defines the decorator @parallel to handle tracking of Beam() objects.

clear_ions()

Clear the ion particles in the ion beam.

track_ions_in_a_drift(drift_length)

Tracks the ions in a drift.

generate_new_ions(electron_bunch)

Generate new ions based on the given electron bunch.

track(electron_bunch)

Beam-ion interaction kicks.

Raises

UserWarning

If the BeamIonMonitor object is used, the user should call the close() method at the end of tracking.

References

[1] : Bassetti, M., & Erskine, G. A. (1980). Closed expression for the electrical field of a two-dimensional Gaussian charge (No. ISR-TH-80-06).

__init__(ion_mass: float, ion_charge: float, ionization_cross_section: float, residual_gas_density: float, ring: Synchrotron, ion_field_model: str, electron_field_model: str, ion_element_length: float, n_ion_macroparticles_per_bunch: int = 30, generate_method: str = 'distribution', generate_ions: bool = True, beam_ion_interaction: bool = True, ion_drift: bool = True)

static parallel(track: Callable) → Callable

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.

Parameters

trackfunction, method of an Element subclass

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

Returns

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

clear_ions()

Clear the ion particles in the ion beam.

track_ions_in_a_drift(drift_length: float)

Tracks the ions in a drift.

Parameters

drift_lengthfloat

The drift length in meters.

_get_efields(first_beam: Bunch | IonParticles, second_beam: Bunch | IonParticles, field_model: str) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Calculates the electromagnetic field of the second beam acting on the first beam for a given field model.

Parameters

first_beamIonParticles or Bunch

The first beam, which is being acted on.

second_beamIonParticles or Bunch

The second beam, which is generating an electric field.

field_model{‘weak’, ‘strong’, ‘PIC’}

The field model used for the interaction.

Returns

en_xnumpy.ndarray

The x component of the electric field.

en_ynumpy.ndarray

The y component of the electric field.

_get_new_beam_momentum(first_beam: Bunch | IonParticles, second_beam: Bunch | IonParticles, prefactor: float, field_model: str = 'strong') → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Calculates the new momentum of the first beam due to the interaction with the second beam.

Parameters

first_beamIonParticles or Bunch

The first beam, which is being acted on.

second_beamIonParticles or Bunch

The second beam, which is generating an electric field.

prefactorfloat

A scaling factor applied to the calculation of the new momentum.

field_model{‘weak’, ‘strong’, ‘PIC’}

The field model used for the interaction. Default is “strong”.

Returns

new_xpnumpy.ndarray

The new x momentum of the first beam.

new_ypnumpy.ndarray

The new y momentum of the first beam.

_update_beam_momentum(beam: Bunch, new_xp: ndarray[tuple[int, ...], dtype[_ScalarType_co]], new_yp: ndarray[tuple[int, ...], dtype[_ScalarType_co]])

generate_new_ions(electron_bunch: Bunch)

Generate new ions based on the given electron bunch.

Parameters

electron_bunchBunch

The electron bunch used to generate new ions.

Returns

None

track(electron_bunch: Bunch)

Beam-ion interaction kicks.

Parameters

electron_bunchBunch() or Beam() class object

An electron bunch to be interacted with.

_abc_impl = <_abc._abc_data object>