工具 API

输入输出辅助函数

分子数据与结果的输入输出工具。

q2m3.utils.io.load_xyz(filepath)

从 XYZ 文件加载分子结构。

参数:

filepath (str) -- XYZ 文件路径

返回:

Atom 对象列表

抛出:

• FileNotFoundError -- 文件不存在时

• ValueError -- 文件格式无效时

返回类型:

list[Atom]

q2m3.utils.io.save_json_results(results, filepath, indent=2)

将计算结果保存为严格 JSON，支持不可变数据类。

参数:

• results (Any) -- 结果映射或数据类实例。递归转换嵌套的数据类、映射、numpy 值和元组。复数使用包含 real 和 imag 字段的字典表示。

• filepath (str | Path) -- 输出文件路径

• indent (int) -- JSON 缩进级别

抛出:

• ValueError -- 数值为 NaN 或无穷大。

• TypeError -- 值无法用 JSON 表示。

返回类型:

None

q2m3.utils.io.load_config(filepath)

从 YAML 或 JSON 文件加载配置。

参数:

filepath (str) -- 配置文件路径

返回:

配置字典

抛出:

• FileNotFoundError -- 文件不存在时

• ValueError -- 文件格式不受支持时

返回类型:

dict[str, Any]

绘图辅助函数

用于能量分析的通用绘图工具。

提供跨模块可视化工具，例如 HF 能量与量子能量的比较。

q2m3.utils.plotting.plot_energy_comparison(hf_energies, quantum_energies, title='HF vs Quantum Energy Comparison', output_path=None, show=True)

绘制 HF 能量与量子能量的相关关系。

创建双面板图：(1) HF 能量与量子能量的散点图，含 y=x 参考线；(2) 能量差的直方图。

参数:

• hf_energies (Sequence[float]) -- 量子计算步骤对应的 HF 能量

• quantum_energies (Sequence[float]) -- 量子算法估计的能量

• title (str) -- 图标题

• output_path (str | Path | None) -- 图的保存路径

• show (bool) -- 是否显示图

返回:

Matplotlib Figure 对象

返回类型:

Figure