at.collective.beam_loading#

Functions

add_beamloading(ring, qfactor, rshunt, ...)

Function to add beam loading to a cavity element, the cavity element is changed to a beam loading element that combines the energy kick from both the cavity and the resonator.

remove_beamloading(ring[, cavpts, copy])

Function to remove beam loading from a cavity element, the beam loading element is changed to a beam loading element that combines the energy kick from both the cavity and the resonator.

Classes

BeamLoadingElement(family_name, length, ...)

Class to generate a beamloading element, inherits from Element additional argument are ring, cavity, qfactor, rshunt, cavitybeta.

CavityMode(*values)

CavityMode.ACTIVE is an active feedback loop, acting on both detuning and generator voltages to compensate the beam induced voltage.

FeedbackMode(*values)

FeedbackMode.PROP means the feedback is only using the most recent turn, and the delta is applied each turn multiplied by Gain[0] (amplitude) or Gain[1] (phase).
class BeamLoadingElement(family_name, length, voltage, frequency, ring, qfactor, rshunt, cavitybeta, detune=0.0, cavitymode=CavityMode.ACTIVE, fbmode=FeedbackMode.PROP, **kwargs)[source]#

Bases: RFCavity, Collective

Class to generate a beamloading element, inherits from Element additional argument are ring, cavity, qfactor, rshunt, cavitybeta.

Parameters:

  • ring (Lattice) – Lattice object

  • length (float) – Length of the cavity

  • voltage (float) – Cavity voltage [V]

  • frequency (float) – Cavity frequency [Hz]

  • qfactor (float) – Unloaded Q factor

  • rshunt (float) – Unloaded Shunt impedance, [\(\Omega\)].

  • cavitybeta (float) – Cavity coupling factor

  • detune (float | None) – Detuning of the cavity from resonance [Hz]

  • cavitymode (CavityMode | None) – Is cavity ACTIVE (default), PASSIVE or PASSIVE_SETVOLTAGE (Passive with a voltage feedback). For PASSIVE_SETVOLTAGE, the voltage setpoint is specified with PassiveVoltage

  • fbmode (FeedbackMode | None) – Feedback mode of an ACTIVE cavity. PROP (default) takes only the proportional component, compared to PROP_INTEGRAL which takes the Proportional and Integral parts.

Keyword Arguments:

  • Nslice (int) – Number of slices per bunch. Default: 101

  • Nturns (int) – Number of turn for the wake field. Default: 1

  • ZCuts – Limits for fixed slicing, default is adaptive

  • NormFact (float) – Normalization factor

  • SystemHarmonic (float) – Used to compute the nominal rf frequency for the given system. e.g. third of fourth harmonic of rf_frequency. If None, then will be computed to the nearest integer multiple of rf_frequency.

  • ts (float) – The timelag of the synchronous particle in the full RF system [m]. If not specified, it will be calculated using get_timelag_fromU0. Defines the expected position of the beam to be used for the beam loading setpoints.

  • buffersize (int) – Size of the history buffer for vbeam, vgen, vbunch (default 0). Not related to feedbacks, only data storage.

  • [V] (PassiveVoltage) – Voltage setpoint for the passive cavity with feedback.

  • TunerGain (float) – Used for detuning of the cavities. States the gain of the correction factor to be applied.

  • TunerOffset (rad) – Fixed detuning from optimal tuning angle. For a negative slope of the RF voltage at the synchronous position, the optimum detuning is negative. Applying a positive TunerOffset will therefore reduce the detuning. The reverse is true for positive RF slope.

  • TunerAveragingPeriod (int) – Detuning is applied in steps of TunerAveragingPeriod with the average difference over this period.

  • Gain ([float, float]) – Used for cavity feedbacks. If FBMode is PROP then Gain[0] is the amplitude gain, and Gain[1] is the phase gain. If FBMode is PROP_INTEGRAL, then Gain[0] is Prop gain and Gain[1] is Integral gain.

  • Delay (int) – Loop delay. If FBMode is PROP, then the units are in turns, if FBMode is PROP_INTEGRAL, then the units are in buckets.

  • SampleNum (int) – Number of bunch over which the mean cavity voltage is computed. Units are in bucket numbers.

  • Every (int) – Sampling and clock period of the feedback controller Time interval between two cavity voltage monitoring and feedback. Units are in bucket numbers.

  • IIRCutoff (float) – Cutoff frequency of the IIR filter in [Hz]. If 0, cutoff frequency is infinity. Default is 0.

  • FF (bool) – Boolean switch to use feedforward constant. True is recommended to prevent a cavity voltage drop in the beginning of the tracking.

  • OpenLoop (bool) – Do you want to apply the changes or just monitor? Only the PROP or PROP_INTEGRAL loop is opened, the tuner is controlled by TunerGain.

Returns:

bl_elem (Element) – beam loading element

static build_from_cav(cav, ring, qfactor, rshunt, cavitybeta, cavitymode=CavityMode.ACTIVE, buffersize=0, **kwargs)[source]#

Function to build the BeamLoadingElement from a cavity the FamName, Length, Voltage, Frequency and HarmNumber are taken from the cavity element.

Parameters:

  • ring (Sequence) – Lattice object

  • qfactor (float) – Q factor

  • rshunt (float) – Shunt impedance, [\(\Omega\)]

  • cavitybeta (float) – Cavity coupling factor

Keyword Arguments:

  • Nslice (int) – Number of slices per bunch. Default: 101

  • Nturns (int) – Number of turn for the wake field. Default: 1

  • ZCuts – Limits for fixed slicing, default is adaptive

  • NormFact (float) – Normalization factor

  • cavitymode (CavityMode) – type of beam loaded cavity ACTIVE (default) for a cavity with active compensation, or PASSIVE to only include the beam induced voltage

  • buffersize (int) – Size of the history buffer for vbeam, vgen, vbunch (default 0)

Returns:

bl_elem (Element) – beam loading element

clear_history(ring=None)[source]#
is_compatible(other)[source]#

Checks if another Element can be merged.

property Buffersize#
property Delay#

Loop delay, in turns (PROP) or buckets (PROP_INTEGRAL).

property Every#

Sampling and clock period of the PI loop [buckets].

property Nslice#

Number of slices per bunch.

property Nturns#

Number of turn for the wake field.

property PhaseDelay#

Delayed cavity phase measurements of the PROP loop.

property RecordSize#

Length of the PI loop delay record.

property ResFrequency#

Resonator frequency.

property SampleNum#

Number of buckets for the mean cavity voltage of the PI loop.

property TurnHistory#

Turn history of the slices center of mass.

property Vbeam#

Beam phasor (amplitude, phase).

property Vbeam_buffer#

Stored beam induced voltage data.

property Vbunch#

Bunch phasor (amplitude, phase).

property Vbunch_buffer#

Stored bunch induced voltage data.

property Vcav#

Cavity phasor (amplitude, phase).

property Vgen#

Generator phasor (amplitude, phase).

property Vgen_buffer#

Stored generator voltage data.

property VoltDelay#

Delayed cavity voltage measurements of the PROP loop.

default_pass = {False: 'DriftPass', True: 'BeamLoadingCavityPass'}#
class CavityMode(*values)[source]#

Bases: IntEnum

CavityMode.ACTIVE is an active feedback loop, acting on both detuning and generator voltages to compensate the beam induced voltage.

CavityMode.PASSIVE takes a fixed cavity frequency and assumes zero generator voltage.

CavityMode.PASSIVE_SETVOLTAGE is a feedback loop for a passive harmonic cavity. The frequency of the cavity is varied in order to maintain a voltage setpoint.

ACTIVE = 1#
PASSIVE = 2#
PASSIVE_SETVOLTAGE = 3#
class FeedbackMode(*values)[source]#

Bases: IntEnum

FeedbackMode.PROP means the feedback is only using the most recent turn, and the delta is applied each turn multiplied by Gain[0] (amplitude) or Gain[1] (phase).

FeedbackMode.PROP_INTEGRAL is a proportional-integral loop acting on the generator current. The cavity voltage averaged over SampleNum buckets is sampled every Every buckets, filtered with IIRCutoff and the error is corrected with Gain[0] (proportional) and Gain[1] (integral) after Delay buckets.

PROP = 1#
PROP_INTEGRAL = 2#
add_beamloading(ring, qfactor, rshunt, cavitybeta, cavpts=None, copy=False, **kwargs)[source]#

Function to add beam loading to a cavity element, the cavity element is changed to a beam loading element that combines the energy kick from both the cavity and the resonator.

Parameters:

  • ring (Lattice) – Lattice object

  • qfactor (float | Sequence[float]) – Unloaded Q. Scalar or array of float are accepted

  • rshunt (float | Sequence[float]) – Unloaded Shunt impedance, [\(\Omega\)] for longitudinal Scalar or array of float are accepted

  • cavitybeta (float | Sequence[float]) – Cavity coupling factor.

Keyword Arguments:

  • cavpts (Refpts) – refpts of the cavity. If None (default) apply to all cavity in the ring

  • Nslice (int) – Number of slices per bunch. Default: 101

  • Nturns (int) – Number of turn for the wake field. Default: 1

  • ZCuts – Limits for fixed slicing, default is adaptive

  • NormFact (float) – Normalization factor

  • copy – If True, returns a shallow copy of ring with new beam loading elements. Otherwise, modify ring in-place

  • cavitymode (CavityMode) – Define PASSIVE or ACTIVE cavity

  • fbmode (FeedbackMode) – Feedback mode of an ACTIVE cavity, PROP (default) or PROP_INTEGRAL

  • buffersize (int) – Size of the history buffer for vbeam, vgen, vbunch (default 0)

  • arguments (Other keyword)

:keyword passed to BeamLoadingElement.:

remove_beamloading(ring, cavpts=None, copy=False)[source]#

Function to remove beam loading from a cavity element, the beam loading element is changed to a beam loading element that combines the energy kick from both the cavity and the resonator.

Parameters:

ring – Lattice object

Keyword Arguments:

  • cavpts (Refpts) – refpts of the beam loading Elements. If None (default) apply to all elements

  • copy – If True, returns a shallow copy of ring with new cavity elements. Otherwise, modify ring in-place