工具函数

概述

quatm.utils 包提供 Quatm 框架中跨模块使用的通用工具函数。

变密度采样 — quatm.utils.vds

变密度采样（Variable Density Sampling, VDS）允许在参数空间中高效探索，将采样点集中在感兴趣的区域（如量子系统中的共振或相变附近）。

核心思想

在物理实验中，某些参数区域比其他区域更有意义。例如：

• Feshbach 共振附近的磁场扫描
• 光谱线中心附近的频率扫描
• 相变临界点附近的参数探索

VDS 通过在感兴趣区域自动加密采样点，在平坦区域稀疏采样，实现以最少的数据点获取最多信息。

gauss_prime_norm — 归一化高斯导数

高斯函数的导数，归一化到最大值为 1：

$$f(x) = \sqrt{e} \cdot \frac{x - \mu}{\sigma} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)$$

from quatm.utils.vds import gauss_prime_norm

# 计算 x=5.0 处的高斯导数值
val = gauss_prime_norm(5.0, mu=5.0, sigma=1.0)

gauss_prime_norm_abs — 绝对值归一化高斯导数

高斯导数绝对值的归一化形式，适合用作对称峰检测的兴趣函数。

create_support_points_stochastic — 随机支持点生成

从精细等距网格开始，随机移除低兴趣区域的点，保留高兴趣区域的点。

from quatm.utils.vds import (
    create_support_points_stochastic,
    gauss_prime_norm_abs
)

# 定义兴趣函数：在 x=5.0 附近集中采样
def interest(x, center, width):
    return gauss_prime_norm_abs(x, center, width)

points = create_support_points_stochastic(
    start=0.0,      # 扫描起点
    stop=10.0,      # 扫描终点
    steps=50,       # 最终支持点数量
    interest_fn=interest,
    max_stepsize=0.5,   # 最大允许步长
    enhancement=0.8,    # 0-1，1 表示强增强
    center=5.0,         # 传递给 interest_fn
    width=1.0           # 传递给 interest_fn
)

应用场景

变密度采样特别适用于：

• Feshbach 共振谱扫描：在共振峰附近加密采样
• 光谱线扫描：在线心附近提高分辨率
• 相变参数扫描：在临界区域精细探索
• 阱频率测量：在预期共振频率附近集中采样