rmcprofile-skill 0.5.5
围绕RMCProfile的Python工具包，RMCProfile是全散射的反向蒙特卡罗程序 (rmcprofile.ornl.gov)。它读取和写入版本6.7.9的每种输入和输出格式 (references/formats.md)，检查输入集是否存在手册警告的错误，运行用户安装的二进制文件，并独立分析配置 (references/method.md)，通过与已安装的包 (scripts/upstream_adapter.py) 交叉验证自身，并携带一个用于教学的小型洁净室RMC引擎 (scripts/rmclite.py, references/rmclite.md)。RMCProfile是闭源的，并根据其自身的“非营利目的”条款分发；此技能从未提供或复制它——它通过RMCPROFILE_HOME (references/package.md) 找到它。在接触运行目录之前，请阅读references/pitfalls.md。使用rmcprofile conda环境和PYTHONIOENCODING=utf-8从产品根目录运行所有内容；每个标志都列在AGENTS.md中。
1. 设置与验证
scripts/install_rmcprofile_windows.ps1 # 或 scripts/install_rmcprofile.sh；两者都支持试运行
export RMCPROFILE_HOME=/path/to/RMCProfile_package # 包含 exe/ 和 tutorial/ 的目录
python scripts/verify_rmcprofile.py # 导入、格式、Keen恒等式、岩盐壳层、包冒烟测试
该包由用户从 rmcprofile.ornl.gov/download/ (SourceForge) 下载并解压；没有RMCPROFILE_HOME，所有绑定包的检查和测试将被跳过，而不是失败。verify_rmcprofile.py 仅在所有检查通过时退出码为 0；其冒烟测试将 tutorial/ex_1 复制到临时目录并运行它（几秒钟，两个版本的 χ²/dof 均为 0.4201）。
2. 运行前检查输入集
python scripts/rmcprofile_tools.py check STEM --dir RUNDIR
每发现一个问题打印一行，格式为 LEVEL code: message，遇到任何ERROR时退出码为 1。代码：no-dat, dat-parse, no-configuration, rmc6f-parse, atom-order (ATOMS :: 与配置不一致)，minimum-distances-count, maximum-moves-count, data-file-missing, data-file-parse, data-block-no-filename, bragg-file-missing, bragg-inst-missing, bragg-back-missing, bragg-parse, poly-file-missing (程序将永远等待)，bulk-rho-missing (PARTICLE_RADIUS :: 缺少 BULK_RHO ::，程序停止)；警告 end-point-beyond-data, filename-case (Linux/macOS 无法找到文件)，no-weight，hkl-range-unspecified, stale-neighbour-files, history-file (来自零移动传递的 .his6f 会毒害下次运行)；信息 potential-lists-regenerated, summary。
3. 运行RMCProfile并读取结果
python scripts/rmcprofile_tools.py run STEM --dir RUNDIR --timeout 10 # 分钟；--home 覆盖 RMCPROFILE_HOME
检查器首先运行，并在出现错误时拒绝启动。运行的 stdout 进入 RUNDIR/run.log；摘要行给出返回码、挂钟时间和输出文件数量；final: 回显 <stem>.chi2 的最后一行。在Python中：res = run_rmcprofile(stem, rundir, find_package()) → res.returncode, res.seconds, res.outputs, res.final_chi2。使用 read_csv_pair("<stem>_PDF1.csv") (r, calc, expt)、read_partials_csv("<stem>_PDFpartials.csv")、read_chi2_history("<stem>.chi2") 读取拟合结果。缺少配置会使 RMCProfile 以退出码 0 停止——请信任 outputs 和 final_chi2，而不是退出码。
4. 准备数据文件
from rmcprofile_tools import write_data_file, read_data_file
write_data_file("sample_gr.dat", r, G, "sample 300 K", style="two-line") # 或 style="stog"
DATA_TYPE/FIT_TYPE 在实空间为 G(r), D(r), T(r)，在倒易空间为 F(Q), S(Q), i(Q)；定义、r → 0 恒等式 G(0) = −(Σ c_i b_i)² 以及权重在 references/method.md 中。低 r 平台不是 −(Σ c b)² 的 G(r) 没有按照 RMCProfile 期望的方式进行归一化。
5. 构建或编辑 .dat 文件
from rmcprofile_tools import read_dat
d = read_dat("sample.dat")
d.set("NEUTRON_REAL_SPACE_DATA", "WEIGHT", "0.02")
d.scalars["TIME_LIMIT"] = "30.00 MINUTES"
d.write("sample.dat")
DatFile 按文件顺序保存标量、ATOMS :: 行以及每个块，并逐字节稳定地写回；d.get(block, key), d.data_blocks(), d.filenames()。块与标量的规则以及包中见过的每个关键字都在 references/formats.md 中。保持 NUMBER_DENSITY 等于配置的头部密度。
6. 无需二进制文件分析配置
python scripts/rmcprofile_tools.py pdf FILE.rmc6f --rmax 8 --dr 0.02 --qmax 30 --dq 0.02 --radiation neutron --outdir out
python scripts/rmcprofile_tools.py coord FILE.rmc6f --pair Na Cl --rmax 3.0
python scripts/rmcprofile_tools.py angles FILE.rmc6f --triplet Na Cl Cl --rmax 3.0 --dangle 2 --outdir out
pdf 写入 <stem>_PDFpartials.csv (g_ij)、<stem>_GofR.csv (以 barn 为单位的 Keen G(r)) 和 <stem>_FofQ.csv；coord 打印配位直方图；angles 写入 B-A-C 角度直方图。合理性检查：G(r) 的第一个值必须为 −(Σ c_i b_i)² (SF6 为 −0.2759 barn)。在Python中：read_rmc6f, partial_gr, total_gr, fq_from_gr, coordination, bond_angles, average_cell, NEUTRON_B。--rmax 必须保持低于最短超胞边缘的一半。
7. 陷阱
references/pitfalls.md：.poly 等待、致命错误退出码 0、.his6f 优先级、过时的邻居文件、CUDA 与 CPU 移动速率、WSL 下 /mnt/* 缓慢、两种 .rmc6f 原子行布局、CRLF、r 网格约定、自然丰度权重、cp1252 控制台。
8. 与已安装的包进行交叉检查
python scripts/upstream_adapter.py list # 八个附带的练习及其暂存配方
python scripts/upstream_adapter.py crosscheck ex_1 --timeout 3
crosscheck 将练习的原始输入暂存到临时目录中（移除输出，保留 .poly/.fs/.sf，将 ex_7 的 TIME_LIMIT 缩短为 5 分钟），运行该包，然后将我们针对结果 .rmc6f 计算的部分对分布函数和 Keen G(r) 与该包自身的 _PDFpartials.csv 和 _PDF1.csv 进行比较。"within tolerance: True" 意味着每对都在 tolerance_partials (1e-3；该包以单精度计算，在 g = 20 峰值处测量为 2.8e-4) 和 G(r) 在 tolerance_gofr (1e-4 barn，测量为 3e-5) 之内，与 tests/records/crosscheck_v1.json 比较。--update-records 重写测量的最大值和出处——只有在故意重新测量之后才进行。在Python中：crosscheck_partials(rmc6f, partials_csv), crosscheck_gofr(rmc6f, pdf_csv), stage_exercise, run_and_crosscheck。
9. 使用 rmclite 教学
python scripts/rmclite.py synth truth.rmc6f --displace 0.05 --rmax 5 --outdir out # 真实目标 + 一个位移副本
python scripts/rmclite.py fit average.rmc6f --target out/truth_target_PDFpartials.csv --moves 3000 --sigma 0.2 --min-dist "Na-Na:3.0,Na-Cl:2.2,Cl-Cl:3.0" --outdir out
fit 写入 <stem>_fit.rmc6f、<stem>_fit.chi2 (RMCProfile 的头部 m_accepted m_generated m_tested chi2)、<stem>_fit_PDFpartials.csv 和 <stem>_fit_GofR.csv——使用与读取 RMCProfile 输出相同的读取器读取它们。接受规则是 Δ = Δχ²/2 + ΔU/k_BT，如果 Δ ≤ 0 则接受，否则以概率 e^(−Δ) 接受。从平均结构开始，切勿从随机畸变开始；切勿拟合未展宽（delta 尖锐）的目标；期望再现的是对分布，而不是坐标 (references/rmclite.md §5)。在Python中：Box.from_rmc6f, Histogram, PartialTarget, TotalGTarget, FqTarget, ClosestApproach, DistanceWindow, BondPotential, RmcLite(...).run(n), synth_targets。
10. 阅读或重建书籍
chapters/RMCProfile_NN_*.ipynb — 十一个已执行的笔记本（§1–40，索引在 chapters/README.md 中）：1 总散射和PDF，2 RMC算法，3 起始配置，4 使用RMCProfile拟合中子数据，5 X射线和Bragg，6 约束和势，7 校正（RESOLUTION_CORRECTION 和 PARTICLE_RADIUS 的测量形式），8 EXAFS / 磁性 / 漫散射，9 分析配置，10 基准测试和生态系统。将用户指向章节，而不是转述：其中的每个数字都是在笔记本中计算出来的。要在编辑 build/part*.py 后重建：
python build/assemble.py --which 07 # 重新生成一个章节（未更改的笔记本保留其输出）
RMCPROFILE_HOME=... python build/execute.py --which 07 # 在 rmcprofile-mc 内核上执行它；通过/失败统计在 logs/execute.log 中
python build/gallery.py # docs/figures + README 图库
python -m pytest tests/test_notebooks.py -q # 源代码、输出、总计、泄漏
11. 教授课程
course/deck/index.html — 十一讲（L0 为什么局部结构 … L10 贡献），扁平且线性，每个章节图在其笔记本标题下方；course/slides.pdf 是无需浏览器的相同幻灯片组；course/handout/handout.html 是A4配套资料；course/notes/LECTURER_NOTES.md 包含每张幻灯片的笔记及其预期问题。将讲师指向 course/README.md（教学大纲、密钥、重建）。在重新执行一个章节后：
python course/tools/extract_figures.py # 图形 + 出处（--check 用于测试）
python course/tools/build_deck.py # index.html, handout, notes（--check 用于测试）
python course/tools/make_slides_pdf.py # slides.pdf (Playwright；已提交)
python -m pytest tests/test_course.py -q
12. 每周关注上游
python scripts/watch_upstream.py --weekly # SourceForge 列表、站点页面/帖子、conda 工具、GitHub 邻居、跟踪器状态
python scripts/watch_upstream.py --snapshot # 记录状态而不生成报告
powershell -File scripts/register_watch_task.ps1 # Windows 任务计划程序，周一 08:00 (-DryRun, -Remove)
报告进入 <study>/docs/watch/YYYY-WW.md，快照和审计日志进入 <study>/forum/upstream-watch/ (已忽略 git)。没有应答的 feed 会在报告中形成一行并退出码为 1；在相信静默周之前请阅读报告。首次运行 (2026-W36) 在 SourceForge 上发现了一个站点下载页面未列出的 6.8.0-rc.1 候选版本。