mbtrack2.impedance.impedance_model module

Module where the ImpedanceModel class is defined.

class ImpedanceModel(ring: Synchrotron, average_beta: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)

Bases: object

Define the impedance model of the machine.

The model must be completed with successive add(…) and add_global(…) calls, then compute_sum() must be run.

The transverse impedance and wake functions are beta weighted and divided by the beta at the tracking location (ring.optics.local_beta).

Parameters

ring : Synchrotron object average_beta : array-like of shape (2,), optional

Average beta function used for global wakes normalization in [m]. The global wakes are normalized by average_beta / local_beta. If None and an AT lattice is loaded, average_beta is computed from the lattice. If None and an AT lattice is not loaded, average_beta is taken to be equal to local_beta, i.e. no normalization. The default is None.

Attributes

wakefieldslist of WakeField objects

WakeFields in the model.

positionslist of arrays

Positions corresponding the different WakeField objects in the model.

nameslist of str

Names of the WakeField objects.

sumWakeField

Sum of every WakeField in the model weigthed by beta functions.

sum_”name”WakeField

Sum of the “name” Wakefield weigthed by beta functions.

sum_namesarray

Names of attributes where the WakeFields are summed by name.

globalslist of WakeField objects

Globals WakeFields in the model.

globals_nameslist of str

Names of the global WakeFields objects.

Methods

add(wakefield, positions, name)

Add the same WakeField object at different locations to the model.

add_global(wakefield, name)

Add a “global” WakeField object which will added to the sum WakeField but weighted only by the average beta functions.

sum_beta(wake, beta)

Weight a WakeField object by an array of beta functions.

compute_sum_names()

Compute the weighted WakeField for each WakeField object type.

compute_sum()

Compute the sum of all weighted WakeField into self.sum.

plot_area(Z_type=”Zlong”, component=”real”, sigma=None, attr_list=None)

Plot the contributions of different kind of WakeFields.

save(file)

Save impedance model to file.

load(file)

Load impedance model from file.

__init__(ring: Synchrotron, average_beta: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)

add(wakefield: WakeField, positions: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | float | int, name: str | None = None)

Add the same WakeField object at different locations to the model.

Parameters

wakefieldWakeField

WakeField object to add to the model.

positionsarray, float or int

Array of longitudinal positions where the elements are loacted.

namestr, optional

Name of the element type. If None, the name of the WakeField object is used. The default is None.

Returns

None.

add_global(wakefield: WakeField, name: str | None = None)

Add a “global” WakeField object which will added to the sum WakeField but weighted only by the average beta functions.

To use with “distributed” elements, for example a resistive wall wakefield computed from an effective radius (so which has already been weighted by beta functions).

Parameters

wakefieldWakeField

WakeField object to add to the model.

namestr, optional

Name of the element type. If None, the name of the WakeField object is used. The default is None.

Returns

None.

sum_beta(wake: WakeField, beta: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → WakeField

Weight a WakeField object by an array of beta functions.

Parameters

wakeWakeField

WakeField element object.

betaarray of shape (2, N)

Beta function at the locations of the elements.

Returns

wake_sumWakeField

WakeField object weighted by beta functions.

compute_sum_names()

Compute the weighted WakeField for each WakeField object type. The new summed WakeField object are set to into self.sum_name.

compute_sum()

Compute the sum of all weighted WakeField into self.sum.

group_attributes(string_in_name: str, names_to_group: list[str] | None = None)

Group attributes in the ImpedanceModel based on a string pattern or explicit list.

Parameters

string_in_namestr

The string pattern used to match attribute names for grouping. If names_to_group is provided, this is the name of the new grouped attribute.

names_to_grouplist of str, optional

list of attribute names to be explicitly grouped. If not provided, attributes matching string_in_name are automatically selected. Defaults to None.

rename_attribute(old_name: str, new_name: str)

Rename an attribute in the ImpedanceModel.

Parameters

old_namestr

The current name of the attribute to be renamed.

new_namestr

The new name for the attribute.

plot_area(Z_type: str = 'Zlong', component: str = 'real', sigma: float | None = None, attr_list: list[str] | None = None, zoom: bool = False, ax: Axes | None = None) → Axes

Plot the contributions of different kind of WakeFields.

Parameters

Z_typestr, optional

Type of impedance to plot.

componentstr, optional

Component to plot, can be “real” or “imag”.

sigmafloat, optional

RMS bunch length in [s] to use for the spectral density. If equal to None, the spectral density is not plotted.

attr_listlist or array of str, optional

Attributes to plot.

zoombool

If True, add a zoomed plot on top right corner.

axAxes, optional

Axes where the plot is displayed. If None, a new figure is created.

Return

axAxes

Axes with the plot on it.

effective_impedance(m: int, mu: int, sigma: float, M: int, tuneS: float, xi: float | None = None, mode: str = 'Hermite') → DataFrame

Compute the longitudinal and transverse effective impedance.

Parameters

muint

coupled bunch mode number, goes from 0 to (M-1) where M is the number of bunches

mint

head-tail (or azimutal/synchrotron) mode number

sigmafloat

RMS bunch length in [s]

Mint

Number of bunches.

tuneSfloat

Synchrotron tune.

xifloat, optional

(non-normalized) chromaticity

mode: str, optional

type of the mode taken into account for the computation: -“Hermite” modes for Gaussian bunches

Returns

summaryDataFrame

Longitudinal and transverse effective impedance.

energy_loss(M: int, bunch_spacing: float, I: float, sigma: float | None = None, bunch_spectrum: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, freq_spectrum: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, n_points: float = 10000000.0) → DataFrame

Compute the beam and bunch loss factor and energy losses for each type of element in the model.

Assumtions:

• Constant spacing between bunches.

• All bunches have the same bunch distribution.

• Gaussian bunches if sigma is given.

Parameters

Mint

Number of bunches in the beam.

bunch_spacingfloat

Time between two bunches in [s].

Ifloat

Total beam current in [A].

sigmafloat, optional

RMS bunch length in [s]. If None, freq_spectrum and bunch_spectrum must be given. Default is None.

bunch_spectrumarray, optional

Bunch spectrum to consider (i.e. FT of bunch profile). Not used if sigma is not None. Default is None.

freq_spectrumarray, optional

Frequency points corresponding to bunch_spectrum in [Hz]. Not used if sigma is not None. Default is None.

n_pointsfloat, optional

Number of points used in the frequency spectrums. Default is 10e6.

Returns

summaryDataframe

Contains the beam and bunch loss factor and energy loss for the full model and for each type of different component.

power_loss_spectrum(M: int, bunch_spacing: float, I: float, sigma: float | None = None, bunch_spectrum: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, freq_spectrum: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, n_points: float = 10000000.0, max_overlap: bool = False, plot: bool = False) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Compute the power loss spectrum of the summed longitudinal impedance as in Eq. (4) of [1].

Assumtions:

• Constant spacing between bunches.

• All bunches have the same bunch distribution.

• Gaussian bunches if sigma is given.

Parameters

Mint

Number of bunches in the beam.

bunch_spacingfloat

Time between two bunches in [s].

Ifloat

Total beam current in [A].

sigmafloat, optional

RMS bunch length in [s]. If None, freq_spectrum and bunch_spectrum must be given. Default is None.

bunch_spectrumarray

Bunch spectrum to consider (i.e. FT of bunch profile). Not used if sigma is not None. Default is None.

freq_spectrumarray

Frequency points corresponding to bunch_spectrum in [Hz]. Not used if sigma is not None. Default is None.

n_pointsfloat, optional

Number of points used in the frequency spectrum. Default is 10e6.

max_overlapbool, optional

If True, the bunch spectrum (scaled to the number of bunches) is used instead of the beam spectrum to compute the maximum value of the power loss spectrum at each frequency. Should only be used to maximise the power loss at a given frequency (e.g. for HOMs) and not for the full spectrum. Default is False.

plotbool, optional

If True, plots:

• the overlap between the real part of the longitudinal impedance

and the beam spectrum. - the power loss spectrum.

Default is False.

Returns

pf0array

Frequency points.

power_lossarray

Power loss spectrum in [W].

References

[1] : L. Teofili, et al. “A Multi-Physics Approach to Simulate the RF Heating 3D Power Map Induced by the Proton Beam in a Beam Intercepting Device”, in IPAC’18, 2018, doi:10.18429/JACoW-IPAC2018-THPAK093

save(file: str)

Save impedance model to file.

The same pandas version is needed on both saving and loading computer for the pickle to work.

Parameters

filestr

File where the impedance model is saved.

Returns

None.

load(file: str)

Load impedance model from file.

The same pandas version is needed on both saving and loading computer for the pickle to work.

Parameters

filestr

File where the impedance model is saved.

Returns

None.