fabiocampolim-design/rmcprofile-skill

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；兩者皆接受試執行 (dry-run)
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

檢查器會先執行，並在發現錯誤時拒絕啟動。執行的標準輸出會寫入 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。若 G(r) 的低 r 平台不等於 −(Σ c b)²，則表示未以 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 (Keen 的 G(r)，單位為 barn) 與 <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^(−Δ) 接受。從平均結構開始，絕不從隨機扭曲開始；絕不擬合未展寬（δ 函數般尖銳）的目標；期望配對分佈能被重現，而非座標本身（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 射線與布拉格，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 核心上執行；PASS/FAIL 統計記錄在 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、講義、備註（使用 --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/（已加入 .gitignore）。若某個資訊源無回應，則會在報告中產生一行並退出碼 1；在相信某個靜默週之前，請先閱讀報告。首次執行（2026-W36）在 SourceForge 上發現了一個網站下載頁面未列出的 6.8.0-rc.1 候選版本。