BIHC package

Beam Induced Heating Computation package is structured in the following modules:

Beam module

class bihc.beam.Beam(M: int = 1e6, A: int = 1, fillNumber: int = 0, bunchLength: float = 1.2e-9, phi: float = 0, realMachineLength: bool = True, ppbk: int = 250, t0: float | None = None, Np: float | NDArray[numpy.floating[Any]] = 2.3e11, bunchShape: str = 'GAUSSIAN', LPCfile: str | None = None, qvalue: float = 1.2, beamNumber: int = 1, fillMode: str = 'FLATTOP', fillingScheme: list[bool] = [False] * 3564, machine: str = 'LHC', spectrum: str = 'numeric', frev: float | None = None, fmax: float = 2e9, exp: float = 2.5, verbose: bool = False, spark: Any = None)[source]

Bases: Impedance, Power, Plot

Defining the beam characteristics.

Enables to create a beam object with certain characteristics. The beam can be created from an existing fill stored in Timber or from a self defined filling scheme. It is possible to assign the bunch lenght, the bunch profile shape, the total intensity and the number of beams (1 or 2).

Parameters

  • M (int, default 3564) – Maximum number of bucket

  • A (int, default 1) – Normalized amplitude for bunch profiles

  • bunchLength (float, default 1.2e-9) – Beam total longitudinal bunch length in seconds (4*sigma) [s]

  • bunchShape (str, default 'GAUSSIAN') – Beam profile shape : ‘GAUSSIAN’, ‘BINOMIAL’ , ‘COS2’ or ‘q-GAUSSIAN’

  • qvalue (float, default 1.2) – q-Gaussian q-value for the ‘q-GAUSSIAN’ beam profile opt

  • exp (float) – Binomial exponent used for the ‘BINOMIAL’ bunch shape.

  • LPCfile (str) – Base name (without extension) of the LPC filling scheme file, if one was provided.

  • phi (float, default 0) – Offset of the bunch profile distribution in time [s]

  • t0 (float, default 0) – The time length (space) of one bucket

  • Np (float or list, default 2.3e11) – Beam intensity in number of protons per bunch. It can also be passed as a list of length == fillingScheme

  • beamNumber (int, default 1) – Number of beams for the power loss computation (1 or 2)

  • fillNumber (int, default 0) – Fill number relative to a particular beam fill of the machine

  • fillMode (str, default 'FLATTOP') – Timber label to extract data at a certain energy ‘INJ’, ‘FLATTOP’, ‘STABLE’

  • fillingScheme (list of bool, default [False]*3564) – Bool values to define the bunch filling scheme with length the number of buckets

  • machine (str, default 'LHC') – Name of the machine to operate with : ‘PS’, ‘SPS’, ‘SPS-SFTPRO’, ‘LHC’

  • spectrum (str, default 'numeric') – Whether to calculate the spectrum with a numerical FFT ‘numeric’, from the analytical formula ‘analytic’, or from input ‘user’

  • realMachineLength (bool, default True) – Flag to adapt bucket size to real machine length

  • ppbk (int, default 250) – Number of time samples per bucket

  • frev (float, default None) – Revolution frequency in [Hz] to sample the analytic beam spectrum computation

  • fmax (float, default 2e9) – Maximum frequency in [Hz] up to which to compute the beam spectrum

  • verbose (bool, default True) – Flag to control console output

longitudinalProfile

Beam longitudinal distribution in time, normalized. Returns the list of numpy arrays [time, profile]

Type

numpy.ndarray list

spectrum

Beam spectrum in frequency. Returns the list of numpy arrays [frequency, spectrum]

Type

numpy.ndarray list

powerSpectrum

Beam power spectrum in frequency. Returns the list of numpy arrays [frequency, powerspectrum]

Type

numpy.ndarray list

totalBeamCharge

Beam charge computed from intensity and number of filled slots, in Coulombs [C]

Type

float

profile_1_bunch

Time profile for a single bunch slot. Returns the list of numpy arrays [time, profile]. Available after the first access of longitudinalProfile or spectrum.

Type

numpy.ndarray list

lambdas

Analytic spectrum envelope. Returns the list of numpy arrays [frequency, envelope]. Only available when spectrum='analytic' and after the first access of spectrum.

Type

numpy.ndarray list

property bunchLength: NDArray[floating[Any]]
property bunchShape: str
property fillNumber: int
setBeamFromFillNumber(fillNumber: int, fillMode: str = 'FLATTOP', beamNumber: int = 1, spark: Any = None) → None[source]

Set beam from fill number

Retrieves beam fill information from Timber provided a fill Number It requires to install pytimber python package For more information refer to bihc installation guide

Parameters will override class instantiation

Parameters

  • beamNumber (int, default 1) – Number of beams for the power loss computation (1 or 2)

  • fillNumber (int, default 0) – Fill number relative to a particular beam fill of the machine

  • fillMode (str, default 'FLATTOP') – Timber label to extract data at a certain energy ‘INJ’, ‘RAMP’, ‘FLATTOP’, ‘STABLE’

Raises

Exception – pytimber could not be imported

setBeamFromLPC() → None[source]

Set beam from LPC tool csv output

Sets beam reading the rows of the .csv file specified by the user. This .csv file is the ouput of the graphical tool LPC

For more information check the tool documentation: https://lpc.web.cern.ch/schemeEditor.html

setBeamsFromSumWithShift(beam1: Beam, beam2: Beam, shift: float) → None[source]

Set beam object from the sum of two beam objects

Parameters

  • beam1 (Beam object) – First beam to add

  • beam2 (Beam object) – Second beam to add

  • shift (float) – Time shift between beam 1 and beam 2 in seconds [s]

setBunches(newLongitudinalProfile: list[NDArray[numpy.floating[Any]]], interp: bool = True) → None[source]
setCustomBeam() → None[source]

Set custom beam without a filling scheme

Sets beam with all bunches set to True for all bucket slots with the bunch length, bunch shape and offset defined in class instance

setCustomBeamWithFillingScheme() → None[source]

Set custom beam with a filling scheme

Sets beam with bunches where the filling scheme list is set to true, and empty when False; for every bucket slots, and with the bunch length, bunch shape and offset defined in class instance

setNpFromFillNumber(spark: Any = None) → None[source]

Set Intensity from fill number

Retrieves intensity information from Timber provided a fill Number It requires to install pytimber python package For more information refer to bihc installation guide

Parameters will override class instantiation

Raises

Exception – pytimber could not be imported

setSpectrum(newSpectrum: list[NDArray[numpy.floating[Any]]]) → None[source]

Setter for new spectrum data Needs to be used when using: >>> Beam(specturm=’user’ )

property spectrum: list[NDArray[numpy.floating[Any]]]

Computes spectrum and power spectrum from the longitudinal beam profile using Numpy fft or the analytical fomula (C. Zannini)

Returns

spectrum – Beam spectrum in frequency. Returns the list of numpy arrays [frequency, spectrum]

Return type

numpy.ndarray list

Impedance module

class bihc.impedance.Impedance(f: NDArray[floating[Any]] = np.linspace(0.1, 2e9, int(1e5)), Z: NDArray[numpy.complexfloating[Any, Any]] | None = None, CST_file: str | None = None)[source]

Define a Beam Coupling Impedance curve.

It is possible to define an impedance curve using: (i) the broad-band resonator model, (ii) the resistive wall impedance of a circular beam pipe, and (iii) importing an external impedance text file (like the one that can be exported from CST).

Mixin class for the Beam class.

Parameters

  • f (numpy.ndarray, default np.linspace(0.1,2e9,int(1e5))) –

    Frequency array of the impedance curve.

    This is the numpy array containing the frequency point of the impedance curve. by default it is a linearly spaced vector going from 0.1 Hz to 2 GHz with 10’000 points.

  • CST_file (str, deafult 0) – File name with extension of the txt file containing the impedance curve.

f

Frequency array of the impedance curve [Hz].

Type

numpy.ndarray, default np.linspace(0.1,2e9,int(1e5))

Zr

Real part of the impedance in the speciefied frequency points [Ohm].

Type

numpy.ndarray

Zi

Imaginary part of the impedance in the speciefied frequency points [Ohm].

Type

numpy.ndarray

copy() → Impedance[source]
getFrequencyRegions(vlines: NDArray[numpy.floating[Any]] | None = None, figsize: list[float] = [12, 6], dpi: int = 200) → NDArray[floating[Any]][source]

Interactively select frequency points of the impedance curve.

The picked frequencies are stored in self.freqregions and returned. Behaviour depends on the active Matplotlib backend:

  • Interactive / script (e.g. Qt5Agg, TkAgg): Spacebar –> pick | Delete –> unpick | Enter –> Finish

  • Jupyter notebook with %matplotlib widget (ipympl): Left click –> pick | Right click –> undo last pick. A Done button is displayed below the figure; click it to finish.

    Note

    The function returns immediately with an empty array. Results are stored in self.freqregions when Done is pressed.

  • Jupyter notebook with %matplotlib inline: A static plot is shown and you are prompted to type the frequencies (in GHz) as a space- or comma-separated list.

Parameters

  • vlines (numpy.ndarray, optional) – Frequencies [Hz] at which to draw dashed reference lines.

  • figsize (list, default [12, 6]) – Figure size [width, height] in inches.

  • dpi (int, default 200) – Figure resolution.

Returns

freqregions – Selected frequencies [Hz]. In %matplotlib widget mode the array is empty on return and is populated once Done is clicked.

Return type

numpy.ndarray

getImpedanceFromCST(path: str, unit: str = 'GHz', skip_header: int = 2, skip_footer: int = 0) → list[NDArray[numpy.floating[Any]]][source]

Creating the impedance curve from CST file.

This methods creates an impedance curve using a txt file, usually exported from CST.

Parameters

  • path (str) – File name with extension.

  • unit (str, default "GHz") – Units of the frquency array from the simulation. Either GHz or MHz.

  • skip_header (int, default 2) – Line index to skip to at the beginning of the txt file.

  • skip_footer (int, default 0) – Line index from which to skip to at the end of the txt file.

Returns

[f, Z] – Impedance curve. Returns the list of numpy arrays [frequency, complex impedance].

Return type

numpy.ndarray list

getImpedanceFromFunc(func: Callable[[NDArray[floating[Any]]], NDArray[complexfloating[Any, Any]]], f: NDArray[numpy.floating[Any]] | None = None) → list[NDArray[numpy.floating[Any]]][source]

Gets impedance from a python function in the form of Z = func(f)

Ensures compatibility to Xwakes wake objects https://github.com/xsuite/xwakes/

>>> import xwakes as xw
>>> wake = xw.WakeResonator(r=1e8, q=10, f_r=1e9,
                            kind='longitudinal')
>>> import bihc
>>> Z = bihc.Impedance(f=np.linspace(0,1e9,10000))
>>> Z.getImpedanceFromFunc(wake.components[0].impedance)
getImpedanceFromPandas(path: str, unit: str = 'GHz') → Any[source]
getRWImpedance(L: float, b: float, sigma: float) → list[NDArray[numpy.floating[Any]]][source]

Creating the impedance curve from the resistive wall impedance model.

This methods creates an impedance curve using the resistive wall impedance model for a resistive pipe of circular section with. It considers the thick wall regime.

Parameters

  • L (float) – Length of the pipe in the resistive wall impedance model [m].

  • b (float) – Pipe radius in the resisitve wall impedance model [m].

  • sigma (float) – Electrical conductivity of the pipe in the resistive wall impedance model [Siemens/m].

Returns

[f, Z] – Impedance curve. Returns the list of numpy arrays [frequency, complex impedance].

Return type

numpy.ndarray list

getResonatorImpedance(Rs: float, Qr: float, fr: float) → list[NDArray[numpy.floating[Any]]][source]

Creating the impedance curve from the broad-band resonator model.

This methods creates an impedance curve using the broad-band resonator model. It requires a shunt impedance value, a quality factor value, and the resonant frequency value.

Parameters

  • Rs (float) – Shunt impedance in the broad-band resonator model [Ohm].

  • Qr (float) – Quality factor in the broad-band resonator model.

  • fr (float) – Resonant frequency in the broad-band resonator model [Hz].

Returns

[f, Z] – Impedance curve. Returns the list of numpy arrays [frequency, complex impedance].

Return type

numpy.ndarray list

Power loss computation module

class bihc.power.Power[source]

Power Mixin class

Class to encapsulate power computation methods It is inherited by Beam class

get2BeamPloss(Z_0: Impedance, tau_s: NDArray[np.floating[Any]] | None = None, s: NDArray[np.floating[Any]] | None = None, offset1: NDArray[np.floating[Any]] | None = None, offset2: NDArray[np.floating[Any]] | None = None, Z_1: Impedance | None = None) → list[float][source]

Computes the power loss for the two beams case given impedance object and the pahse_shift between the two beams

Implemented by Francesco Giordano

Parameters

  • Z_0 (object) – Impedance object returned by Impedance class with the frequency information of the impedance map given by the user

  • tau_s (float list) – Phase shift values between the two beams in seconds [s]

  • s (float list) – Distances from the interaction point in [m]

getPloss(Z: Impedance) → tuple[float, NDArray[np.floating[Any]]][source]

Computes the power loss for a given impedance object Implemented by Francesco Giordano

Parameters

Z (object) – Impedance object returned by Impedance class with the frequency information of the impedance map given by the user

getShiftedPloss(Z: Impedance, shift: float = 20e6) → tuple[NDArray[np.integer[Any]], NDArray[np.floating[Any]]][source]

Computes the power loss, shifting the impedance curve rigidly in steps given by shift, to overlap with the spectral lines, giving a best (away from the line) and worst (on top of the line) case scenario.

Parameters

  • Z (object) – Impedance object returned by Impedance class with the frequency information of the impedance map given by the user

  • shift (float) – Frequency shift to be applied in steps to the impedance curve

getShiftedPowerSpectrum(Z: Impedance, shift: float = 20e6) → tuple[NDArray[np.integer[Any]], NDArray[np.floating[Any]]][source]

Computes the power loss spectrum, shifting the impedance curve rigidly in steps given by shift, to overlap with the spectral lines, giving a best (away from the line) and worst (on top of the line) case scenario.

Parameters

  • Z (object) – Impedance object returned by Impedance class with the frequency information of the impedance map given by the user

  • shift (float) – Frequency shift to be applied in steps to the impedance curve

Built-in plotting module

Plot module to manage built-in plotting functions

It allows to easily plot filling schemes from timber, or user defined beams. It has customized rcParams for scientific plotting.

  • date: 12/12/2022

  • author: Francesco Giordano, Elena de la Fuente, Leonardo Sito

class bihc.plot.Plot[source]
plot2Beam(beam2: Any, shift: float = 0) → None[source]
plotCollide(beam2: Any) → None[source]
plotImpedance(fMin: float = 0, fMax: float = 2e9) → None[source]
plotLongitudinalProfile(tmin: float = - 1, tmax: float = - 1) → None[source]
plotPowerSpectrum(fmin: float = 0, fmax: float = 2, save: bool = True, transparent: bool = True) → None[source]
plotPowerSpectrumFromTimber(beamNumber: int, save: bool = True) → tuple[NDArray[numpy.floating[Any]], NDArray[numpy.floating[Any]], Any][source]
plotSpectrumAndImpedance(Z: Impedance) → None[source]
saveLongitudinalDistribution(path: str, phase_shift: float = 0, normalise: bool = False, plot: bool = False) → None[source]