rf_sim#

Simulate the RF cavity response in the presence of RF drive and beam loading.

Functions

cav_impulse(half_bw, detuning, Ts[, order])

Derive the impulse response from the cavity equation.

cav_ss(half_bw[, detuning, beta, ...])

Derive the continuous state-space equation of the cavity

cav_ss_mech(mech_modes[, lpf_fc])

Derive the continous state-space equation of the cavity mechanical modes.

opt_QL_detuning(f0, vc0, ib0, phib, Q0, ...)

Derived the optimal loaded Q and detuning.

rf_power_req(f0, vc0, ib0, phib, Q0, roQ_or_RoQ)

Plot the steady-state forward and reflected power for given cavity voltage, beam current and beam phase, as function of loaded Q and detuning.

sim_ncav_pulse(Arfc, Brfc, Crfc, Drfc, vf, Ts)

Simulate the cavity response to a pulsed RF drive and beam current.

sim_ncav_step(Arfd, Brfd, Crfd, Drfd, ...[, ...])

Simulate the cavity response for a time step using the discrete cavity state-space function.

sim_ncav_step_simple(half_bw, detuning, ...)

Simulate the cavity response for a time step using the simple discrete cavtiy equation (Euler method for discretization).
cav_impulse(half_bw, detuning, Ts, order=20)[source]#

Derive the impulse response from the cavity equation. We assume that the system gain has been normalized to 1 and the system phase corrected to 0. Therefore, the referred cavity equation is dvc/dt + (half_bw - 1j * detuning)*vc = half_bw * vd, where vc is the vector of cavity voltage and vd is the vector of cavity drive (in principle vd = 2 * beta * vf / (beta + 1)).

Refer to LLRF Book section 4.5.2.

Parameters:

  • half_bw – float, constant half bandwidth of the cavity, rad/s

  • detuning – float, constant detuning of the cavity, rad/s

  • Ts – float, sampling time, s

  • order – int, order of the impulse response

Returns:

  • status – boolean, success (True) or fail (False)

  • h – numpy array (complex), impulse response

cav_ss(half_bw, detuning=0.0, beta=10000.0, passband_modes=None, plot=False, plot_pno=1000)[source]#
Derive the continuous state-space equation of the cavity

  • include pass-band modes.

  • we assume the half-bandwidth and detuning of the fundamental mode are constant.

  • we output two models: one for RF drive, and the other for beam (beam only interacts with the fundamental mode of the cavity).

Refer to LLRF Book section 3.3.7 and 3.4.3.

Parameters:

  • half_bw – float, half bandwidth of the cavity (constant), rad/s

  • detuning – float, detuning of the cavity (constant), rad/s

  • beta – float, input coupling factor (needed for NC cavities; for SC cavities, can use the default value, or you can specify it if more accurate result is needed)

  • passband_modes – dict, with the following items: freq_offs : list, offset frequencies of the modes, Hz; gain_rel : list, relative gain wrt fundamental mode; half_bw : list, half bandwidth of the mode, rad/s

  • plot – boolean, enable the plot of frequency response

  • plot_pno – int, number of point in the plot

Returns:

  • status – boolean, success (True) or fail (False)

  • Arf, Brf, Crf, Drf – numpy matrix (complex), continous cavity model for RF drive

  • Abm, Bbm, Cbm, Dbm – numpy matrix (complex), continous cavity model for beam drive

cav_ss_mech(mech_modes, lpf_fc=None)[source]#

Derive the continous state-space equation of the cavity mechanical modes.

Refer to LLRF book section 3.3.10.

Parameters:

  • mech_modes – dict, with the following items: f : list, frequencies of mech modes, Hz; Q : list, qualify factors; K : list, K values, rad/s/(MV)^2.

  • lpf_fc – float, low-pass cutoff freq (optional), Hz

Returns:

  • status – boolean, success (True) or fail (False)

  • A, B, C, D – numpy matrix (real), continous mechanical model

cav_ss_passband(passband_modes)[source]#

Derive the continuous state-space equation of the cavity, only the passband modes. Refer to LLRF Book section 3.3.7 and 3.4.3.

Parameters:

passband_modes – dict, with the following items: freq_offs : list, offset frequencies of the modes, Hz; gain_rel : list, relative gain wrt fundamental mode; half_bw : list, half bandwidth of the mode, rad/s

Returns:

  • status – boolean, success (True) or fail (False)

  • Arf, Brf, Crf, Drf – numpy matrix (complex), continous passband model for RF drive

opt_QL_detuning(f0, vc0, ib0, phib, Q0, roQ_or_RoQ, machine='linac', cav_type='sc')[source]#

Derived the optimal loaded Q and detuning.

Refer to LLRF Book section 3.3.9.

Parameters:

  • f0 – float, RF operating frequency, Hz

  • vc0 – float, desired cavity voltage, V

  • ib0 – float, desired average beam current, A

  • phib – float, desired beam phase, degree

  • Q0 – float, unloaded quality factor (for SC cavity, give it a very high value like 1e10)

  • roQ_or_RoQ – float, cavity r/Q of Linac or R/Q of circular accelerator, Ohm (see the note below)

  • machine – string, linac or circular, used to select r/Q or R/Q

  • cav_type – string, sc for superconducting or nc for normal conducting

Returns:

  • status – boolean, success (True) or fail (False)

  • QL_opt – float, optimal loaded quality factor

  • dw_opt – float, optimal detuning, rad/s

  • beta_opt – float, optimal input coupling factor

Note

Linacs define the r/Q = Vacc**2 / (w0 * U) while circular machines define R/Q = Vacc**2 / (2 * w0 * U), where Vacc is the accelerating voltage, w0 is the angular cavity resonance frequency and U is the cavity energy storage. Therefore, to use this function, one needs to specify the machine to be linac or circular. Generally, we have R/Q = 1/2 * r/Q.

rf_power_req(f0, vc0, ib0, phib, Q0, roQ_or_RoQ, QL_vec=None, detuning_vec=None, machine='linac', plot=False)[source]#

Plot the steady-state forward and reflected power for given cavity voltage, beam current and beam phase, as function of loaded Q and detuning. The beam phase is defined to be zero for on-crest acceleration.

Refer to LLRF Book section 3.3.9.

Parameters:

  • f0 – float, RF operating frequency, Hz

  • vc0 – float, desired cavity voltage, V

  • ib0 – float, desired average beam current, A

  • phib – float, desired beam phase, degree

  • Q0 – float, unloaded quality factor (for SC cavity, give it a very high value like 1e10)

  • roQ_or_RoQ – float, cavity r/Q of Linac or R/Q of circular accelerator, Ohm (see the note below)

  • QL_vec – numpy array, QL vector for power calculation

  • detuning_vec – numpy array, detuning at which to evaluated the powers

  • machine – string, linac or circular, used to select r/Q or R/Q

  • plot – boolean, enable/disable the plotting

Returns:

  • status – boolean, success (True) or fail (False)

  • Pfor – dictionary, keyed by detuning, forward power at different QL

  • Pref – dictionary, keyed by detuning, reflected power at different QL

Note

Linacs define the r/Q = Vacc**2 / (w0 * U) while circular machines define R/Q = Vacc**2 / (2 * w0 * U), where Vacc is the accelerating voltage, w0 is the angular cavity resonance frequency and U is the cavity energy storage. Therefore, to use this function, one needs to specify the machine to be linac or circular. Generally, we have R/Q = 1/2 * r/Q.

sim_ncav_pulse(Arfc, Brfc, Crfc, Drfc, vf, Ts, Abmc=None, Bbmc=None, Cbmc=None, Dbmc=None, vb=None)[source]#

Simulate the cavity response to a pulsed RF drive and beam current. This function is for normal conducting cavties with constant QL and detuning.

Parameters:

  • Arfc – numpy matrix (complex), continous cavity model for RF drive

  • Brfc – numpy matrix (complex), continous cavity model for RF drive

  • Crfc – numpy matrix (complex), continous cavity model for RF drive

  • Drfc – numpy matrix (complex), continous cavity model for RF drive

  • vf – numpy array (complex), cavity forward voltage (calibrated to the cavity probe signal reference plane)

  • Ts – float, sampling frequency, Hz

  • Abmc – numpy matrix (complex), continous cavity model for beam drive

  • Bbmc – numpy matrix (complex), continous cavity model for beam drive

  • Cbmc – numpy matrix (complex), continous cavity model for beam drive

  • Dbmc – numpy matrix (complex), continous cavity model for beam drive

  • vb – numpy array (complex), beam drive voltage (calibrated to the cavity probe signal reference plane)

Returns:

  • status – boolean, success (True) or fail (False)

  • T – numpy array, time waveform, s

  • vc – numpy array (complex), cavity voltage waveform

  • vr – numpy array (complex), cavity reflected voltage waveform

sim_ncav_step(Arfd, Brfd, Crfd, Drfd, vf_step, state_rf0, Abmd=None, Bbmd=None, Cbmd=None, Dbmd=None, vb_step=None, state_bm0=None)[source]#

Simulate the cavity response for a time step using the discrete cavity state-space function.

Parameters:

  • Arfd – numpy matrix (complex), discrete cavity model for RF drive

  • Brfd – numpy matrix (complex), discrete cavity model for RF drive

  • Crfd – numpy matrix (complex), discrete cavity model for RF drive

  • Drfd – numpy matrix (complex), discrete cavity model for RF drive

  • vf_step – complex, cavity forward voltage of this step

  • state_rf0 – numpy matrix (complex), state of RF response model of last step

  • Abmd – numpy matrix (complex), discrete cavity model for beam drive

  • Bbmd – numpy matrix (complex), discrete cavity model for beam drive

  • Cbmd – numpy matrix (complex), discrete cavity model for beam drive

  • Dbmd – numpy matrix (complex), discrete cavity model for beam drive

  • vb_step – complex, beam drive voltage of this step

  • state_bm0 – numpy matrix (complex), state of beam response model of last step

Returns:

  • status – boolean, success (True) or fail (False)

  • vc_step – complex, cavity voltage of this step

  • vr_step – complex, cavity reflected voltage of this step

  • state_rf – numpy matrix (complex), state of RF response model of this step (should input to next execution)

  • state_bm – numpy matrix (complex), state of beam response model of this step (should input to next execution)

sim_ncav_step_simple(half_bw, detuning, vf_step, vb_step, vc_step0, Ts, beta=10000.0)[source]#

Simulate the cavity response for a time step using the simple discrete cavtiy equation (Euler method for discretization).

Parameters:

  • half_bw – float, half bandwidth of the cavity (constant), rad/s

  • detuning – float, detuning of the cavity (constant), rad/s

  • vf_step – complex, cavity forward voltage of this step

  • vb_step – complex, beam drive voltage of this step

  • vc_step0 – complex, cavity voltage of the last step

  • Ts – float, sampling time, s

  • beta – float, input coupling factor (needed for NC cavities; for SC cavities, can use the default value, or you can specify it if more accurate result is needed)

Returns:

  • status – boolean, success (True) or fail (False)

  • vc_step – complex, cavity voltage of this step

  • vr_step – complex, cavity reflected voltage of this step

sim_scav_step(half_bw, dw_step0, detuning0, vf_step, vb_step, vc_step0, Ts, beta=10000.0, state_m0=0, Am=None, Bm=None, Cm=None, Dm=None, mech_exe=False)[source]#

Simulate the cavity response for a time step using the simple discrete cavtiy equation (Euler method for discretization) including the mechanical modes. We first simulate one step of the mechanical mode and determine the detuning value, then use the sim_ncav_step_simple function to simulate one step of the electrical model.

Parameters:

  • half_bw – float, half bandwidth of the cavity (constant), rad/s

  • dw_step0 – float, detuning of the last step, rad/s

  • detuning0 – float, external detuning (tuner + microphonics), rad/s

  • vf_step – complex, cavity forward voltage of this step, V

  • vb_step – complex, beam drive voltage of this step, V

  • vc_step0 – complex, cavity voltage of the last step, V

  • Ts – float, sampling time, s

  • beta – float, input coupling factor (needed for NC cavities; for SC cavities, can use the default value, or you can specify it if more accurate result is needed)

  • state_m0 – numpy matrix (real), last state of the mechanical equation

  • Am – numpy matrix (real), state-space matrix of mech modes

  • Bm – numpy matrix (real), state-space matrix of mech modes

  • Cm – numpy matrix (real), state-space matrix of mech modes

  • Dm – numpy matrix (real), state-space matrix of mech modes

  • mech_exe – boolean, if exe mech sim one step or not (for down sampling)

Returns:

  • status – boolean, success (True) or fail (False)

  • vc_step – complex, cavity voltage of this step

  • vr_step – complex, cavity reflected voltage of this step

  • dw – float, detuning of this step, rad/s

  • state_m – numpy matrix (real), updated state of the mechanical equation

sim_ss_step(Ad, Bd, Cd, Dd, vin_step, state0)[source]#

A generic state-space solver to execute for one step. :param Ad: numpy matrix (float/complex), discrete state-space matrices :param Bd: numpy matrix (float/complex), discrete state-space matrices :param Cd: numpy matrix (float/complex), discrete state-space matrices :param Dd: numpy matrix (float/complex), discrete state-space matrices :param vin_step: float/complex, input of this step :param state0: numpy matrix (float/complex), state of last step

Returns:

  • status – boolean, success (True) or fail (False)

  • vout_step – float/complex, output of this step

  • state – numpy matrix (float/complex), state of this step (input to next exe)