trimci.ground_state Tutorial新手教程

1. 30-second quick start 1. 30 秒速通

Have a FCIDUMP file? Three lines: 有 FCIDUMP 文件？三行代码：

Python

import trimci

result = trimci.ground_state("FCIDUMP")
print(result.energy)        # variational energy (Ha)
print(result.energy_pt2)    # + PT2 correction

No FCIDUMP, just h1 and eri arrays? Also three lines: 没有 FCIDUMP，只有 h1、eri 数组？也三行：

Python

result = trimci.ground_state((h1, eri, n_elec))
print(result.summary())

2. The three parameters 2. 三个参数详解

Optional kwargs 可选参数

3. Recipe table 3. 配方表 measured on Fe₄S₄ (54e, 36o)Fe₄S₄ (54e, 36o) 实测

Values below come from a 9-point n_dets sweep on a 32-core x86 node (effort=0.4 fixed). Wall times will scale with your hardware. 下面这张表来自跨 9 个 n_dets 的实测扫描，跑在 32 核 x86 节点上（effort=0.4 固定）。不同硬件 wall 时间会不同。

4. The Result object — how to extract data 4. Result 对象 — 怎么取数据

The returned Result has three layers. The 5 most commonly used fields are at the top: 返回的 Result 分三层。最常用的字段在顶层（5 个）：

Top-level shortcuts

res = trimci.ground_state("FCIDUMP")

res.energy          # float — variational total energy (Ha)
res.energy_pt2      # float | None — variational + PT2
res.n_dets          # int   — final det count
res.wall_time       # float — total wall (seconds)

To judge whether the result is "converged enough" for your purpose, look at: 想判断结果是不是"够收敛"，看：

• res.energies.pt2_correction — small (e.g. < 1 mHa) ⇒ variational space is saturated很小（< 1 mHa）⇒ variational 空间足够
• res.energies.history[-3:] — last few rounds flat ⇒ converged plateau末几轮平 ⇒ 收敛平台
• res.n_dets == res.diagnostics.n_fci — expansion reached the Hilbert dim ⇒ exact (FCI)达到 Hilbert 维度 ⇒ FCI 精确

Sub-objects: .energies / .wavefunction / .diagnostics 子对象：.energies / .wavefunction / .diagnostics

Energies — energy decompositionEnergies — 能量分解

res.energies.var               # variational energy
res.energies.pt2_correction    # ΔE_PT2 (≤ 0)
res.energies.nuclear           # nuclear repulsion
res.energies.electronic        # = var - nuclear
res.energies.history           # energy trajectory across all rounds [list]
res.energies.pt2_history       # per-round ΔPT2 [list]

Wavefunction

wf = res.wavefunction

wf.coeffs          # (N,) ndarray — amplitudes
wf.dets            # (N, 2K) ndarray — α+β bitstrings stacked
wf.alpha_bits      # (N, K) uint64
wf.beta_bits       # (N, K) uint64
wf.n_orb
wf.is_normalized   # normalization check

# advanced extraction
wf.leading(5)    # top-5 dets: [(α_bits, β_bits, c), ...]
wf.occupation_numbers()  # per-orbital occupation (n_orb, 2) [α, β]

# dict-like access (backward compat)
wf["110011|110011"]   # lookup amplitude by bitstring
for bits, c in wf.items():
    ...

Diagnostics — performance / Hilbert dim / configDiagnostics — 性能 / Hilbert 维度 / 配置

d = res.diagnostics

d.wall_phase0       # Phase 0 (orbopt) time
d.wall_expansion    # Phase 1+2 expansion time
d.n_dets_phase0     # det count after Phase 0
d.n_dets_final      # final det count
d.expansion_rounds  # total Phase 1+2 rounds
d.n_fci             # full Hilbert dim = C(n_orb, n_α)·C(n_orb, n_β)
                    # requested n_dets is auto-clamped to this
d.orbopt_dir        # Phase 0 orbopt npz dir (or None)
d.checkpoint_dir    # Phase 1+2 checkpoint dir (or None)
d.config            # the Config dataclass used for this run

Final rotated orbitals (lazy, loaded from disk) 最终旋转后的轨道（lazy 从磁盘加载）

# Integrals in the FINAL basis (after both Phase 0 and Phase 1 orbopt):
res.final_h1            # (n_orb, n_orb)
res.final_eri           # (n_orb, n_orb, n_orb, n_orb)

# Cumulative rotation: C_final = C_input @ U
res.orbital_rotation    # (n_orb, n_orb) orthogonal matrix

# Sanity check: U^T · h1_input · U should equal final_h1
assert np.allclose(
    res.orbital_rotation.T @ h1_input @ res.orbital_rotation,
    res.final_h1,
)

Human-readable summary人类可读 summary

print(res.summary())

# Output (example):
# TrimCI Calculation Summary
#   Energy (var):     -327.1937 Ha
#   Energy (PT2):     -327.1957 Ha  (ΔPT2 = -0.002)
#   Determinants:     800  (Phase 0: 100)
#   Wall (Phase 0):   3.1 min
#   Wall (Expansion): 0.7 min  (12 rounds)
#   Wall (total):     3.8 min

5. Three input modes 5. 三种输入方式

Mode A: FCIDUMP file (most common)方式 A: FCIDUMP 文件（最常用）

res = trimci.ground_state("path/to/FCIDUMP", n_dets=100000)

Mode B: (h1, eri, n_elec) tuple方式 B: (h1, eri, n_elec) 元组

import numpy as np

# 4-site Hubbard ring, U=4, t=1
n = 4
h1 = np.zeros((n, n))
eri = np.zeros((n, n, n, n))
for i in range(n):
    j = (i + 1) % n
    h1[i, j] = h1[j, i] = -1.0
    eri[i, i, i, i] = 4.0

res = trimci.ground_state((h1, eri, 4), n_dets=30)
# E_var = -2.1027484 Ha — matches exact FCI

# Open-shell: pass ms2 = 2·S_z = n_alpha - n_beta
res = trimci.ground_state((h1, eri, 3), ms2=1)   # doublet
res = trimci.ground_state((h1, eri, 4), ms2=2)   # triplet

The 4-tuple form (h1, eri, n_elec, e_nuc) lets you specify nuclear repulsion explicitly. 四元组形式 (h1, eri, n_elec, e_nuc) 让你显式指定核排斥。

Mode C: PySCF mean-field (a converged mf object)方式 C: PySCF mean-field（已收敛的 mf 对象）

from pyscf import gto, scf

mol = gto.M(atom="N 0 0 0; N 0 0 1.1", basis="sto-3g")
mf = scf.RHF(mol).run()

# Unified entry — same as Mode A/B
res = trimci.ground_state(mf, n_dets=10000)

# For an active space: pass active=(n_e, n_o)
# res = trimci.ground_state(mf, n_dets=10000, active=(8, 8))

6. Save / load results 6. 保存 / 读取结果

For large-n_dets calculations, save your results. Default is NPZ (compressed binary): 大 n_dets 跑出来的结果，务必存盘。默认 NPZ 格式（压缩二进制）：

res.save("my_calc.npz")         # NPZ — recommended
res.save("my_calc")             # auto-appends .npz
res.save("my_calc.json")        # JSON — only for small n_dets / debug

# load back
res2 = trimci.Result.load("my_calc.npz")
print(res2.energy)               # exact round-trip across processes

7. Decision tree: tune for your scenario 7. 决策树：我的场景该怎么调

trimci.ground_state(p, n_dets=100, effort=0.05)
# ~2 min, absolute value off by ~100 mHa, but you'll know if import + workflow are healthy

trimci.ground_state(p, n_dets=10_000)
# Usually nails FCI. Cross-check with pyscf FCI: diff < 0.1 mHa

trimci.ground_state(p, n_dets=100_000)
# Fe4S4: -327.224 Ha in 5 min, ~7 mHa above theoretical limit

trimci.ground_state(p, n_dets=1_000_000)
# Fe4S4 single run: ~-327.23 Ha in ~10 min
# For tighter bounds, run multiple seeds and take the best/mean.

trimci.ground_state(p, n_dets=3_000_000)
# Measured: N2 r=2.5 Å (823 mHa correlation) → FCI at n=2000
# Fe4S4-scale clusters: 1M-3M recommended

8. Advanced — full Config control 8. 高级 — Config 全量控制 advanced

When 3 parameters aren't enough, construct a Config and pass it via the config= kwarg of ground_state: 当三参数不够用时，构造 Config 对象，通过 ground_state 的 config= 关键字传入：

from trimci import Config

cfg = Config(
    # Phase 0
    num_runs=128,
    orbopt_cycles=8,
    orbopt=True,
    max_dets_phase0=500,
    tracking_dets=True,
    loaded_dets_randomness=0.1,
    # Phase 1 (orbopt + expansion)
    max_dets_phase1=100_000,
    growth_factor_phase1=1.1,
    orbopt_phase1=True,
    use_connection_cache_phase1=True,
    # Phase 2 (final expansion)
    max_dets_phase2=1_000_000,
    growth_factor_phase2=2.0,
    pt2_correction=True,
    pt2_only_last=True,   # PT2 only at the final round; saves time
    # Reproducibility (None = fresh entropy per call; int = deterministic)
    seed=42,
    # Performance
    n_cpu_workers=8,           # Phase 0 parallel subprocesses
    n_gpu_workers=0,
    backend_phase1="cpu",     # or "gpu", "auto"
    # Advanced PT2 override
    phase2_overrides={"pt2": {"sketch_width": 500_000}},
)

# config= works with any input type:
res = trimci.ground_state("FCIDUMP", config=cfg)
res = trimci.ground_state((h1, eri, 14, 0.0), config=cfg)
res = trimci.ground_state(mf, config=cfg)

Default values (auto-applied by ground_state) 默认参数（ground_state 自动用）

9. Common questions and pitfalls 9. 常见问题与陷阱

Q: Energy isn't monotonic; higher effort gives worse results 问题：能量没收敛单调，effort 越高反而越差

The variance of a single stochastic realization can exceed the expected gap between different effort levels. Pass config=Config(seed=42, ...) to ground_state to make a run reproducible, then sweep seeds to estimate variance. Or just scale up n_dets instead of pushing effort. 原因：单次 stochastic 实现的方差大于不同 effort 之间的期望差。给 ground_state 传 config=Config(seed=42, ...) 可复现一次运行；扫多个 seed 可估方差。或者直接扩 n_dets 而不是堆 effort。

Q: I bumped n_dets but the wall barely grew 问题：n_dets 设很大但 wall 没怎么涨

This is expected. Phase 0 (orbital optimization) dominates wall time and barely scales with n_dets; Phase 1+2 expansion is relatively cheap under the default settings. 这是正常现象。Phase 0（轨道优化）是主要 wall 来源，几乎不随 n_dets 变化；Phase 1+2 expansion 在默认配置下成本相对较低。

Q: res.energy_pt2 is None 问题：res.energy_pt2 is None

Either pt2_correction is disabled, or n_dets has covered the full Hilbert space (FCI-saturated — no external dets for PT2 to add). Read res.energy directly. 说明 pt2_correction 被关了，或者 n_dets 已经覆盖了完整 Hilbert 空间（FCI saturated，PT2 没有外部 det 可加）。看 res.energy。

Q: Does n_orb > 64 cause problems? 问题：n_orb > 64 是不是有问题

No. Wavefunction.alpha_bits has shape (N, K) where K = ceil(n_orb / 64) uint64 segments. All API surfaces (leading(), to_dict(), save/load) handle multi-segment dets correctly. 没问题。Wavefunction.alpha_bits 是 (N, K) 形状，K = ceil(n_orb / 64) 个 uint64 segments。所有 API（leading()、to_dict()、save/load）都正确处理多 segment。

Q: Error PySCF is required to write FCIDUMP 问题：报错 PySCF is required to write FCIDUMP

The (h1, eri) tuple path calls pyscf.tools.fcidump.from_integrals under the hood. Either install PySCF or pre-write the FCIDUMP file yourself and pass the path. 用 (h1, eri) 元组路径会调用 pyscf.tools.fcidump.from_integrals。装 PySCF 或者自己用 FCIDUMP 文件路径替代。

Q: How do I run open-shell (spin ≠ 0)? 问题：开壳层（spin ≠ 0）怎么跑

Three options, depending on input form: 视输入形式，三种方式：

• FCIDUMP path — spin is read from the file's MS2 header (just make sure your FCIDUMP writer set it correctly).FCIDUMP 路径 — 自旋从文件 MS2 字段读取（确保 FCIDUMP 写出时设对了）。
• Integrals tuple — pass the ms2 kwarg: ground_state((h1, eri, n_elec), n_dets=..., ms2=2) for a triplet, ms2=1 for a doublet, etc.积分元组 — 传 ms2 关键字：三态 ground_state((h1, eri, n_elec), n_dets=..., ms2=2)，二态 ms2=1，依此类推。
• PySCF mf — spin is taken from mf.mol.spin automatically (e.g. gto.M(..., spin=2) + scf.ROHF/UHF).PySCF mf — 自旋自动取自 mf.mol.spin（用 gto.M(..., spin=2) + scf.ROHF/UHF）。

Q: Five minutes in and no energy printed 问题：跑了 5 分钟还没出能量

Check stdout for Phase 0 progress before res.diagnostics — Phase 0 prints continuously. If stuck in Cycle 1, orbopt_max_iter may be too high or the system is hard to converge. Try effort=0.05 first to confirm the workflow runs. 查 res.diagnostics 之前先看 stdout — Phase 0 会 print progress。若卡在 Phase 0 cycle 1，可能是 orbopt_max_iter 太大 / 体系难收敛。试 effort=0.05 先验证 workflow 通。