rf_calib#

RF calibrations like virtual probe, RF actuator offset/imbalance, forward and reflected, and power calibrations.

Functions

calib_cav_for(vc, vf_m, pul_ids, pul_ide, ...)

Calibrate the cavity forward signal: vf = a * vf_m.

calib_dac_offs(vdac, viqm, sig_ids, sig_ide, ...)

Calibrate the DAC offset to remove carrier leakage for direct upconversion.

calib_iqmod(vdac, viqm)

Calibrate the I/Q modulator imbalance, return inv(M) with [real(viqm) imag(viqm)]' = M * [real(vdac) imag(vdac)]' + [iqm_offs_I iqm_offs_Q]' This method is OK to calibrate the imbalance matrix M (use its inverse to pre-distort the DAC output) but the offset is not accurate to determine the DAC offset calibration.

calib_ncav_for_ref(vc, vf_m, vr_m, pul_ids, ...)

Calibrate the cavity forward and reflected signals for a normal conducting cavity with constant loaded Q and detuning: vf = a * vf_m + b * vr_m, vr = c * vf_m + d * vr_m The resulting vf and vr are the cavity drive/reflected signals at the same reference plane as the cavity probe vc.

calib_scav_for_ref(vc, vf_m, vr_m, pul_ids, ...)

Calibrate the cavity forward and reflected signals for a superconducting cavity with time-varying loaded Q or detuning: vf = a * vf_m + b * vr_m, vr = c * vf_m + d * vr_m The resulting vf and vr are the cavity drive/reflected signals at the same reference plane as the cavity probe vc.

calib_sys_gain_pha(vact, vf[, beta])

Calibrate the system gain and sytem phase.

calib_vprobe(vc, vf_m, vr_m)

Calibrate the virtual probe signal of the cavity with vc = m * vf_m + n * vr_m aiming at reconstructing the probe signal with the forward and reflected signals.

calib_vsum_poor(amp_vec, pha_vec[, ref_ch])

Calibrate the vector sum (poor man's solution by rotating and scaling all other channels refering to the first channel).

egain_cav_power(pfor, roQ_or_RoQ, QL[, ...])

Standing-wave cavity energy gain estimate from RF drive power without beam loading.

egain_cgstr_power(pfor, f0, rs, L, Q, Tf)

Traveling-wave constant gradient structure energy gain estimate from RF drive power without beam loading.

for_ref_volt2power(roQ_or_RoQ, QL[, ...])

Convert the calibrated forward and reflected signals (in physical unit, V) to forward and reflected power (in W).

phasing_energy(phi_vec, E_vec[, machine])

Calibrate the beam phase using the beam energy measured by scanning RF phase.
calib_cav_for(vc, vf_m, pul_ids, pul_ide, half_bw, detuning, Ts, beta=10000.0)[source]#

Calibrate the cavity forward signal: vf = a * vf_m. The resulting vf is the cavity drive signal at the same reference plane as the cavity probe vc.

Refer to LLRF Book section 4.6.1.3.

Parameters:

  • vc – numpy array (complex), cavity probe waveform (reference plane)

  • vf_m – numpy array (complex), cavity forward waveform (meas.)

  • pul_ids – int, starting index for calculation (calculation window should cover the entire pulse for NC cavities; use the part close to pulse end for SC cavities)

  • pul_ide – int, ending index for calculation

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

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

  • 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 calibration is needed)

Returns:

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

  • a – float (complex), calibrate coefficient

Note

The waveforms should have been aligned in time, i.e., the relative delays between them should have been removed.

calib_dac_offs(vdac, viqm, sig_ids, sig_ide, leak_ids, leak_ide, delay=0)[source]#

Calibrate the DAC offset to remove carrier leakage for direct upconversion.

Refer to LLRF Book section 9.2.2.

Parameters:

  • vdac – numpy array (complex), DAC output waveform

  • viqm – numpy array (complex), I/Q modulator output meas. waveform

  • sig_ids – int, starting index of signals

  • sig_ide – int, ending index of signals

  • leak_ids – int, starting index of leakage

  • leak_ide – int, ending index of leakage

  • delay – int, delay in number of points between I/Q out and DAC WFs, it is needed to be set reflecting the actual delay for better results

Returns:

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

  • offset_I – float, I offset to be added to the actual DAC output

  • offset_Q – float, Q offset to be added to the actual DAC output

calib_iqmod(vdac, viqm)[source]#

Calibrate the I/Q modulator imbalance, return inv(M) with [real(viqm) imag(viqm)]' = M * [real(vdac) imag(vdac)]' + [iqm_offs_I iqm_offs_Q]' This method is OK to calibrate the imbalance matrix M (use its inverse to pre-distort the DAC output) but the offset is not accurate to determine the DAC offset calibration. It is suggested to calibrate the DAC offset first using the routine calib_dac_offs before executing this function.

Refer to paper “Geng Z, Hong B (2016) Design and calibration of an RF actuator for low-level RF systems. IEEE Trans Nucl Sci 63(1):281-287”.

Parameters:

  • vdac – numpy array (complex), DAC actuation points

  • viqm – numpy array (complex), I/Q modulator meas. points

Returns:

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

  • invM – numpy matrix, inversion of M, can be directly used to correct the I/Q modulator imbalance

  • viqm_s – numpy array (complex), scaled I/Q modulator output

  • viqm_c – numpy array (complex), re-constructed I/Q mod. output

calib_ncav_for_ref(vc, vf_m, vr_m, pul_ids, pul_ide, half_bw, detuning, Ts, beta=1.0)[source]#

Calibrate the cavity forward and reflected signals for a normal conducting cavity with constant loaded Q and detuning: vf = a * vf_m + b * vr_m, vr = c * vf_m + d * vr_m The resulting vf and vr are the cavity drive/reflected signals at the same reference plane as the cavity probe vc.

Refer to LLRF Book section 9.3.5.

Parameters:

  • vc – numpy array (complex), cavity probe waveform (reference plane)

  • vf_m – numpy array (complex), cavity forward waveform (meas.)

  • vr_m – numpy array (complex), cavity reflected waveform (meas.)

  • pul_ids – int, starting index for calculation (calculation window should cover entire pulse)

  • pul_ide – int, ending index for calculation

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

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

  • Ts – float, sampling time, s

  • beta – float, input coupling factor (needed for NC cavities)

Returns:

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

  • a,b,c,d – float (complex), calibrate coefficients

Note

The waveforms should have been aligned in time, i.e., the relative delays between them should have been removed.

calib_scav_for_ref(vc, vf_m, vr_m, pul_ids, pul_ide, decay_ids, decay_ide, half_bw, detuning, Ts, beta=10000.0)[source]#

Calibrate the cavity forward and reflected signals for a superconducting cavity with time-varying loaded Q or detuning: vf = a * vf_m + b * vr_m, vr = c * vf_m + d * vr_m The resulting vf and vr are the cavity drive/reflected signals at the same reference plane as the cavity probe vc.

Refer to LLRF Book section 9.3.5.

Parameters:

  • vc – numpy array (complex), cavity probe waveform (reference plane)

  • vf_m – numpy array (complex), cavity forward waveform (meas.)

  • vr_m – numpy array (complex), cavity reflected waveform (meas.)

  • pul_ids – int, starting index for calculation (calculation window should take the pulse end part close to decay)

  • pul_ide – int, ending index for calculation

  • decay_ids – int, starting id of calculation window at decay stage

  • decay_ide – int, ending id of calculation window at decay stage

  • half_bw – float, half bandwidth of the cavity (derived from early part of decay), rad/s

  • detuning – float, detuning of the cavity (derived from early part of decay), rad/s

  • Ts – float, sampling time, s

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

Returns:

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

  • a,b,c,d – float (complex), calibrate coefficients

Note

The waveforms should have been aligned in time, i.e., the relative delays between them should have been removed.

calib_sys_gain_pha(vact, vf, beta=10000.0)[source]#

Calibrate the system gain and sytem phase.

Refer to LLRF Book section 9.4.2.

Parameters:

  • vact – numpy array (complex), RF actuation waveform (usually DAC output)

  • vf – numpy array (complex), cavity forward signal (calibrated to the reference plane of the cavity voltage or vector-sum voltage)

  • 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)

  • sys_gain – numpy array, waveform of system gain

  • sys_phase – numpy array, waveform of system phase, deg

calib_vprobe(vc, vf_m, vr_m)[source]#

Calibrate the virtual probe signal of the cavity with vc = m * vf_m + n * vr_m aiming at reconstructing the probe signal with the forward and reflected signals. This is useful when the probe is temperally not available.

Parameters:

  • vc – numpy array (complex), cavity probe waveform (as reference plane)

  • vf_m – numpy array (complex), cavity forward waveform (meas.)

  • vr_m – numpy array (complex), cavity reflected waveform (meas.)

Returns:

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

  • m, n – float (complex), calibration coefficients

Note

The waveforms should have been aligned in time, i.e., the relative delays between them should have been removed.

calib_vsum_poor(amp_vec, pha_vec, ref_ch=0)[source]#

Calibrate the vector sum (poor man’s solution by rotating and scaling all other channels refering to the first channel).

Parameters:

  • amp_vec – numpy array, amplitude of all channels

  • pha_vec – numpy array, phase of all channels, deg

  • ref_ch – int, reference channel, between 0 and (num of channels - 1)

Returns:

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

  • scale – numpy array, scale factor for all channels

  • phase – numpy array, phase offset adding to all channels, deg

egain_cav_power(pfor, roQ_or_RoQ, QL, beta=10000.0, machine='linac')[source]#

Standing-wave cavity energy gain estimate from RF drive power without beam loading.

Refer to LLRF Book section 9.3.2.1, equation (9.13).

Parameters:

  • pfor – float, cavity drive power, W

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

  • QL – float, loaded quality factor of the cavity

  • 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)

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

Returns:

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

  • vc0 – float, desired cavity voltage for the given drive power

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.

egain_cgstr_power(pfor, f0, rs, L, Q, Tf)[source]#

Traveling-wave constant gradient structure energy gain estimate from RF drive power without beam loading.

Refer to LLRF Book section 9.3.2.1, equation (9.14).

Parameters:

  • pfor – float, structure input RF power, W

  • f0 – float, RF operating frequency, Hz

  • rs – float, shunt impedance per unit length, Ohm/m

  • L – float, length of the traveling-wave structure, m

  • Q – float, quality factor of the TW strcuture

  • Tf – float, filling time of the TW structure, s

Returns:

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

  • vc0 – float, desired accelerating voltage for the given drive power

for_ref_volt2power(roQ_or_RoQ, QL, vf_pcal=None, vr_pcal=None, beta=10000.0, machine='linac')[source]#

Convert the calibrated forward and reflected signals (in physical unit, V) to forward and reflected power (in W).

Refer to LLRF Book section 3.3.9.

Parameters:

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

  • QL – float, loaded quality factor of the cavity

  • vf_pcal – numpy array (complex), forward waveform (calibrated to physical unit)

  • vf_pcal – numpy array (complex), reflected waveform (calibrated to physical unit)

  • 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)

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

Returns:

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

  • for_power – numpy array, waveform of forward power (if input is not None), W

  • ref_power – numpy array, waveform of reflected power (if input is not None), W

  • C – float (complex), calibration coefficient: power_W = C * Volt_V^2

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.

phasing_energy(phi_vec, E_vec, machine='linac')[source]#

Calibrate the beam phase using the beam energy measured by scanning RF phase.

Refer to LLRF Book section 9.3.2.3.

Parameters:

  • phi_vec – numpy array, phase measurement, degree

  • E_vec – numpy array, beam energy measurement

  • machine – string, ‘linac’ or ‘circular’, see the note below

Returns:

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

  • Egain – float, maximum energy gain of the RF station

  • phi_off – float, phase offset that should be added to the phase meas, deg

Note

Circular accelerator use sine as convention of beam phase definition, resulting in 90 degree for on-crest acceleration; while for Linacs, the consine convention is used with 0 degree for on-crest acceleration.