LLRFLibsPy Contents#

Architecture#

The LLRFLibsPy library consists of several Python modules as shown in the diagram below. The associations between these modules are also shown in the diagram. Each module is a Python source file implementing routines that can be directly called in the user codes. The list of routines and the example codes to test the routines are summarized in tables below.

Figure 1: LLRFLibsPy library modules and their associations

rf_sysid Functions#

Function

Example

Comments

prbs

example_sysid_prbs_etfe.py

produce the PRBS signal for system identification

etfe

example_sysid_prbs_etfe.py

Empirical Transfer Function Estimation (ETFE)

half_bw_decay

example_calib_for_ref_sc_cavity.py

calculate the cavity half-bandwidth from the RF pulse decay stage

detuning_decay

example_calib_for_ref_sc_cavity.py

calculate the cavity detuning from the RF pulse decay stage

cav_drv_est

example_calib_for_ref_nc_cavity.py

estimate the required cavity drive and reflected signals from probe signal

cav_par_pulse

example_calib_for_ref_sc_cavity.py
example_sysid_caveq.py

calculate the cavity parameters (half-bandwidth and detuning) within the pulse by directly solving the cavity equation

cav_par_pulse_obs

example_calib_for_ref_sc_cavity.py
example_sysid_caveq.py

calculate the cavity parameters (half-bandwidth and detuning) within the pulse using the ADRC observer

cav_beam_pulse_obs

example_sysid_caveq.py

calculate the beam drive voltage within the pulse using the ADRC observer

cav_observer

construct the ADRC observer and estimate the denoised cavity voltage and the general disturbances

iden_impulse

example_aff_ilc.py

identify the impulse response of a real/complex SISO system from data

beta_powers

identify the cavity input coupling factor using steady-state forw/refl powers

rf_calib Functions#

Function

Example

Comments

calib_vprobe

example_calib_virtual_probe.py

calib. cavity virtual probe with forward/reflected signals

calib_dac_offs

example_calib_dac_offs.py

calib. DAC offset with I/Q modulator direct upconversion

calib_iqmod

example_calib_iqm.py

calib. I/Q modulator imbalance with direct upconversion

calib_cav_for

example_calib_for_ref_nc_cavity.py

calib. cavity forward signal using forward and probe

calib_ncav_for_ref

example_calib_for_ref_nc_cavity.py

calib. cavity forward/reflected signals with constant QL and detuning

calib_scav_for_ref

example_calib_for_ref_sc_cavity.py

calib. cavity forward/reflected signals with time-varying QL and detuning

for_ref_volt2power

example_sim_cavity_basic.py

calib. forward/reflected power from forward/reflected voltage

phasing_energy

example_fit_funcs.py (demo fitting)

calib. energy gain and beam phase with phase scan and energy meas.

egain_cav_power

example_power_to_vacc.py

est. steady-state standing-wave cavity voltage from drive power

egain_cgstr_power

example_power_to_vacc.py

est. const gradient traveling-wave structure ACC voltage from drive power

calib_vsum_poor

calib. vector sum by rotating and scaling referring to one channel

calib_sys_gain_pha

example_calib_sys_gain_phase.py

calib. system gain and system phase

rf_control Functions#

Function

Example

Comments

ss_discrete

example_sim_cavity_basic.py

discretize a continous state-space system and compare freq responses

ss_cascade

example_feedback_analysis.py

cascade two state-space systems (either continous or discrete - C/D)

ss_freqresp

example_feedback_analysis.py

calculate and plot freq response of a state-space system (C/D)

basic_rf_controller

example_feedback_basic.py

derive a basic continous RF I/Q controller: P + I + frequency notches

control_step

example_feedback_basic.py

perform one time-step execution of the discretized controller

loop_analysis

example_feedback_analysis.py

analyze the sensitivity/complementary sensitivity of an RF control loop (C/D)

cav_sp_ff

example_sp_ff.py

derive the setpoint and feedforward waveforms for desired cavity voltage and beam loading

ADRC_controller

example_feedback_adrc.py

derive a basic ADRC controller (the observer and gain)

ADRC_control_step

example_feedback_adrc.py

perform one time-step execution of the discretized controller including the ADRC observer

AFF_timerev_lpf

example_aff_timerev_lpf.py

time-reversed low pass filter-based adaptive feedforward

AFF_ilc_design

example_aff_ilc.py

derive the ILC gain matrix from the impulse response and weighting

AFF_ilc

example_aff_ilc.py

apply the ILC algorithm to calculate the feedforward correction signal

resp_inv_svd

example_resp_matrix_inv.py

response matrix inversion with SVD (with singular value filtering)

resp_inv_lsm

example_resp_matrix_inv.py

response matrix inversion with lease-square method (with regularization)

rf_det_act Functions#

Function

Example

Comments

noniq_demod

example_demod.py

perform non-I/Q demodulation of a given raw sampling waveform

twop_demod

example_demod.py

demodulate raw with every two samples

asyn_demod

example_demod.py

demodulate raw sampled by asyn. clock, reference WF needed

self_demod_ap

example_demod.py

demodulate raw with Hilbert transform, return amplitude and phase

iq2ap_wf

example_demod.py

convert I/Q waveforms to amplitude/phase waveforms

ap2iq_wf

convert amplitude/phase waveforms to I/Q waveforms

norm_phase

normalize phase (scalar or WF) to a specific range (default ±180 deg)

pulse_info

derive the pulse info like pulse width, pulse offset, etc.

rf_fit Functions#

Function

Example

Comments

fit_sincos

example_fit_funcs.py

fit the sine or cosine function

fit_circle

example_fit_funcs.py

fit the 2D points to a circle function

fit_ellipse

example_fit_funcs.py

fit the 2D points to an ellipse function

fit_Gaussian

example_fit_funcs.py

fit a 1D Guassian function

rf_noise Functions#

Function

Example

Comments

calc_psd_coherent

example_noise_psd.py

calculate the power spectral density (PSD) of a coherent sampled data series

calc_psd

example_noise_psd.py

calculate the PSD of a general data series

rand_unif

generate uniform distributed random numbers

gen_noise_from_psd

example_noise_time_series.py

generate noise series from a given PSD spectrum

calc_rms_from_psd

example_noise_time_series.py

calculate the RMS jitter from a given PSD spectrum

notch_filt

example_calib_for_ref_sc_cavity.py

apply notch filter to a data series

design_notch_filter

example_feedback_analysis.py

design a notch filter in state-space format

filt_step

example_feedback_basic.py

apply a single time step of state-space filter

moving_avg

moving average without compensating the group delay

rf_sim Functions#

Function

Example

Comments

cav_ss

example_sim_cavity_basic.py

derive a continous state-space equation of a cavity

cav_ss_mech

cavity state-space equation with mechanical modes (to be implemented)

cav_impulse

example_aff_ilc.py

derive the cavity impulse response from the cavity parameters

sim_ncav_pulse

example_sim_cavity_basic.py

simulate cavity (with constant QL and detuning) response to a pulsed input

sim_ncav_step

example_sim_cavity_basic.py

simulate cavity (with constant QL and detuning) response for a time step

sim_ncav_step_simple

example_sim_cavity_basic.py

simulate cavity (with constant QL and detuning) response for a time step (simplified cavity equation only with the fundamental passband mode)

rf_power_req

example_power_req.py
example_power_req2.py

calculate the required RF power for diesired cavity voltage and beam

opt_QL_detuning

example_power_req.py
example_power_req2.py

calcualte the optimal QL and detuning for minimizing the reflection power

rf_misc Functions#

Function

Example

Comments

save_mat

save a dictionary into a Matlab .mat file

load_mat

load a Matlab .mat file into a dictionary

get_curtime_str

get a string of the current date/time

get_bit

get a bit of an integer

add_tf

adding two transfer function in num/den format

plot_ellipse

example_fit_funcs.py

plot an ellipse using its characteristics

plot_Guassian

example_fit_funcs.py

plot a 1D Guassian distribution

rf_plot Functions#

Function

Example

Comments

plot_ss_discrete

make plot for function rf_control.ss_discrete

plot_ss_freqresp

make plot for function rf_control.ss_freqresp

plot_basic_rf_controller

make plot for function rf_control.basic_rf_controller

plot_loop_analysis

make plot for function rf_control.loop_analysis

plot_calc_psd

make plot for function rf_noise.calc_psd and rf_noise.calc_psd_coherent

plot_cav_ss

make plot for function rf_sim.cav_ss

plot_rf_power_req

make plot for function rf_sim.rf_power_req

plot_plot_ellipse

make plot for function rf_misc.plot_ellipse

plot_plot_Guassian

make plot for function rf_misc.plot_Guassian