LLRFLibsPy库中cav_par_pulse函数解读

Posted on In Views: Disqus:
计算在射频（RF）脉冲期间，带束流关闭（beam off）情况下的驻波腔体的半带宽和失谐频率

source code: Github

这个函数cav_par_pulse的主要作用是计算在射频（RF）脉冲期间，带束流关闭（beam off）情况下的驻波腔体的半带宽和失谐频率。下面对函数的具体实现和参数进行详细解释。

函数签名和参数说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def cav_par_pulse(vc, vf, half_bw, Ts, beta=1e4):
    '''
    Calculate the half-bandwidth and detuning of a standing-wave cavity 
    within an RF pulse with beam off (directly solve the cavity equation).
    
    Refer to LLRF Book section 9.4.3.

    Parameters:
        vc:      numpy array (complex), cavity probe waveform (reference plane)
        vf:      numpy array (complex), cavity forward waveform (calibrated to the
                  same reference plane as the cavity probe signal)
        half_bw: float, half bandwidth of the cavity (derived from early part 
                  of decay), 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)
        wh_pul:  numpy array, half-bandwidth in the pulse, rad/s
        dw_pul:  numpy array, detuning in the pulse, rad/s
    '''

  • 参数：

    • vc: numpy数组（复数），表示腔体探测信号波形（参考平面）。
    • vf: numpy数组（复数），表示腔体前向信号波形（校准到与腔体探测信号相同的参考平面）。
    • half_bw: 浮点数，腔体的半带宽（由衰减的早期部分得出），单位为rad/s。
    • Ts: 浮点数，采样时间，单位为秒。
    • beta: 浮点数，输入耦合因子（非超导腔体需要；对于超导腔体，可以使用默认值，或者如果需要更准确的校准，可以指定）。

  • 返回值：

    • status: 布尔值，表示成功（True）或失败（False）。
    • wh_pul: numpy数组，脉冲期间的半带宽，单位为rad/s。
    • dw_pul: numpy数组，脉冲期间的失谐频率，单位为rad/s。

输入检查

1
2
3
4
# check the input
if (not vc.shape == vf.shape) or (half_bw <= 0.0) or \
   (Ts <= 0.0) or (beta <= 0.0):
    return False, None, None
  • 检查vc和vf的形状是否相同。
  • 检查half_bw是否大于0。
  • 检查Ts是否大于0。
  • 检查beta是否大于0。

如果任何条件不满足，函数返回False和两个None。

使用腔体极坐标方程

1
2
3
4
5
6
# use cavity polar equation
vd = 2 * beta * vf / (beta + 1)
vc_amp = np.abs(vc)
vc_pha = np.angle(vc)
vd_amp = np.abs(vd)
vd_pha = np.angle(vd)
  • 根据输入耦合因子beta计算得到vd。
  • 计算vc和vd的振幅和相位。

计算导数

1
2
3
# derivative 
der_vc_amp = np.gradient(vc_amp, Ts)
der_vc_pha = np.gradient(vc_pha, Ts)
  • 计算vc振幅和相位随时间的导数，使用np.gradient方法计算导数，步长为采样时间Ts。

计算脉冲期间的半带宽和失谐频率

1
2
3
# calculate the half-bandwidth and detuning
wh_pul = (half_bw * vd_amp * np.cos(vc_pha - vd_pha) - der_vc_amp) / vc_amp
dw_pul = der_vc_pha + half_bw * vd_amp / vc_amp * np.sin(vc_pha - vd_pha)
  • 根据腔体的极坐标方程和导数计算脉冲期间的半带宽wh_pul和失谐频率dw_pul。

返回结果

1
return True, wh_pul, dw_pul
  • 返回True，以及计算得到的半带宽和失谐频率。

总结

这个函数通过直接求解腔体方程，计算在射频脉冲期间驻波腔体的半带宽和失谐频率。这对于理解和控制加速器中的射频系统非常重要。通过输入探测信号和前向信号的波形，以及其他必要的参数，可以得到脉冲期间的半带宽和失谐频率，从而有助于对腔体性能的分析和优化。

以下是一个示例，演示如何使用cav_par_pulse函数来计算在射频脉冲期间的驻波腔体的半带宽和失谐频率。

示例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
import numpy as np
import matplotlib.pyplot as plt

def cav_par_pulse(vc, vf, half_bw, Ts, beta=1e4):
    '''
    Calculate the half-bandwidth and detuning of a standing-wave cavity 
    within an RF pulse with beam off (directly solve the cavity equation).
    
    Refer to LLRF Book section 9.4.3.

    Parameters:
        vc:      numpy array (complex), cavity probe waveform (reference plane)
        vf:      numpy array (complex), cavity forward waveform (calibrated to the
                  same reference plane as the cavity probe signal)
        half_bw: float, half bandwidth of the cavity (derived from early part 
                  of decay), 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)
        wh_pul:  numpy array, half-bandwidth in the pulse, rad/s
        dw_pul:  numpy array, detuning in the pulse, rad/s
    '''
    # check the input
    if (not vc.shape == vf.shape) or (half_bw <= 0.0) or \
       (Ts <= 0.0) or (beta <= 0.0):
        return False, None, None

    # use cavity polar equation
    vd = 2 * beta * vf / (beta + 1)
    vc_amp = np.abs(vc)
    vc_pha = np.angle(vc)
    vd_amp = np.abs(vd)
    vd_pha = np.angle(vd)

    # derivative 
    der_vc_amp = np.gradient(vc_amp, Ts)
    der_vc_pha = np.gradient(vc_pha, Ts)

    # calculate the half-bandwidth and detuning
    wh_pul = (half_bw * vd_amp * np.cos(vc_pha - vd_pha) - der_vc_amp) / vc_amp
    dw_pul = der_vc_pha + half_bw * vd_amp / vc_amp * np.sin(vc_pha - vd_pha)

    return True, wh_pul, dw_pul

# 示例参数设置
sampling_time = 1e-6  # 采样时间，单位为秒
half_bandwidth = 2 * np.pi * 100  # 半带宽，单位为rad/s
beta = 1e4  # 输入耦合因子

# 生成示例波形
time = np.arange(0, 0.01, sampling_time)  # 时间数组
vc = np.exp(1j * 2 * np.pi * 50 * time) * np.exp(-time / 0.002)  # 腔体探测信号
vf = np.exp(1j * 2 * np.pi * 50 * time)  # 腔体前向信号

# 调用函数计算
success, wh_pul, dw_pul = cav_par_pulse(vc, vf, half_bandwidth, sampling_time, beta)

# 打印结果
if success:
    print("Calculation successful!")
    print("Half-bandwidth in pulse:", wh_pul)
    print("Detuning in pulse:", dw_pul)

    # 绘制结果
    plt.figure(figsize=(12, 6))
    
    plt.subplot(2, 1, 1)
    plt.plot(time, wh_pul, label='Half-bandwidth (rad/s)')
    plt.xlabel('Time (s)')
    plt.ylabel('Half-bandwidth (rad/s)')
    plt.legend()
    plt.grid(True)
    
    plt.subplot(2, 1, 2)
    plt.plot(time, dw_pul, label='Detuning (rad/s)', color='orange')
    plt.xlabel('Time (s)')
    plt.ylabel('Detuning (rad/s)')
    plt.legend()
    plt.grid(True)
    
    plt.tight_layout()
    plt.show()
else:
    print("Calculation failed.")

example-cav-par-pulse.png

示例解释：

  1. 导入必要的库：导入numpy和matplotlib.pyplot用于计算和绘图。
  2. 定义cav_par_pulse函数：直接使用之前解释的函数实现。
  3. 设置示例参数：
    • sampling_time: 采样时间，单位为秒。
    • half_bandwidth: 半带宽，单位为rad/s。
    • beta: 输入耦合因子。
  4. 生成示例波形：
    • time: 时间数组，从0到0.01秒，步长为采样时间。
    • vc: 腔体探测信号，使用复指数函数生成，包含一个频率为50Hz的信号和一个衰减因子。
    • vf: 腔体前向信号，使用复指数函数生成，包含一个频率为50Hz的信号。
  5. 调用函数计算：调用cav_par_pulse函数，传入示例波形和参数，计算半带宽和失谐频率。
  6. 打印和绘制结果：
    • 如果计算成功，打印计算结果并绘制半带宽和失谐频率随时间变化的图像。
    • 如果计算失败，打印失败信息。

运行此示例代码，将会看到脉冲期间的半带宽和失谐频率随时间的变化情况的图表。这有助于分析和理解腔体在射频脉冲期间的性能。