正确性验证清单

每次改动教学版 NNQS 后，建议按从小到大的顺序验证。前面的检查便宜，后面的检查更接近真实训练。

单元测试

在远端仓库根目录运行：

source ~/miniforge3/etc/profile.d/conda.sh
conda activate nnqs
python -m pytest nnqs_tutorial/tests -q

重点覆盖：

• bitstring 与 token 的往返转换。
• restricted electron mask。
• model forward 的 shape 与 \(\psi\) 公式。
• autoregressive sampling 的 counts 和电子数约束。
• ExactHamiltonian 的 local energy。
• 配置字段严格校验。
• trainer 单轮 smoke。

CPU CLI Smoke

用临时小 Hamiltonian 跑 2 个 epoch。检查：

• train_log.csv 生成。
• checkpoints/epoch-2.pt 生成。
• energy_real、energy_imag、loss_proxy 都是有限数。

这个阶段主要验证命令行、配置、采样、Hamiltonian 和 trainer 是否能完整串起来。

Slurm GPU Smoke

提交：

cd /home/tnx/code/vqe2nnqs2afqmc2nnqs/nnqs_learn/nnqs
mkdir -p nnqs_tutorial/slurm/logs
sbatch nnqs_tutorial/slurm/gpu_smoke.sbatch

查看：

squeue -u tnx
tail -n 120 nnqs_tutorial/slurm/logs/gpu_smoke-<jobid>.out

日志中应出现：

cuda_available: True
epoch=1 ...
epoch=2 ...
GPU smoke test finished successfully.

这一步验证 Slurm、GPU、conda 环境和教学版 CLI 的整条链路。

FCI 对比能量曲线

提交：

sbatch nnqs_tutorial/slurm/gpu_fci_curve.sbatch

脚本会在 GPU 节点上：

1. 生成一个 4-qubit projector Hamiltonian。
2. 用 exact diagonalization 得到 FCI 能量。
3. 用教学版 NNQS/VMC 训练 80 epoch。
4. 画出 energy_vs_epoch_fci.png。

成功日志应包含：

FCI_ENERGY=-1.0000000000000000
FCI curve GPU demo finished successfully.

这个测试可以粗略确认能量曲线朝正确方向运动。

C++ 后端注意事项

如果当前 local_energy/libeloc.so 是 CUDA 版，但当前 Python 环境没有 GPU，教学版会提前报错，提示切换 CPU 版 C++ 后端或使用：

hamiltonian_backend: exact

这类提前失败比动态库直接 abort Python 进程更容易定位问题。

文档站构建

本笔记站复用 MonteCarlo 的 MkDocs 环境：

../MonteCarlo/.venv/bin/mkdocs build --strict

如果公式、导航或链接有问题，先让严格构建通过，再考虑发布到个人网站目录。