工具函数

Quatm 通用工具函数：变密度采样等辅助功能

概述

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)

参数	说明
`x`	输入值，可以是标量或 `numpy.ndarray`
`mu`	高斯中心
`sigma`	高斯标准差

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

参数	说明
`start`	扫描起点，始终包含在最终支持点中
`stop`	扫描终点，始终包含在最终支持点中
`steps`	最终支持点数量
`interest_fn`	兴趣函数 `f(x, **kwargs)`，返回 0（低兴趣）到 1（高兴趣）
`max_stepsize`	相邻支持点最大间距
`enhancement`	0-1，1 表示强增强感兴趣区域，0 表示均匀随机采样
`**kwargs`	传递给 `interest_fn` 的额外参数

应用场景

变密度采样特别适用于：

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

变密度采样

变密度采样：按兴趣函数在参数空间加密采样的支撑点生成器。

工具函数

概述

变密度采样 — quatm.utils.vds