fabiocampolim-design/rmcprofile-skill

rmcprofile-skill 0.5.5

Une boîte à outils Python autour de RMCProfile, le programme Reverse Monte Carlo pour la diffusion totale (rmcprofile.ornl.gov). Elle lit et écrit tous les formats d'entrée et de sortie de la version 6.7.9 (references/formats.md), vérifie un jeu d'entrées pour les erreurs mentionnées dans le manuel, exécute le binaire installé par l'utilisateur et analyse les configurations de manière autonome (references/method.md), s'auto-vérifie par rapport au package installé (scripts/upstream_adapter.py) et inclut un petit moteur RMC en salle blanche pour l'enseignement (scripts/rmclite.py, references/rmclite.md). RMCProfile est un logiciel propriétaire distribué selon ses propres termes "à but non lucratif" ; cette compétence ne l'expédie ni ne le copie jamais — elle le trouve via RMCPROFILE_HOME (references/package.md). Lisez references/pitfalls.md avant de toucher à un répertoire d'exécution. Exécutez tout depuis la racine du produit avec l'environnement conda rmcprofile et PYTHONIOENCODING=utf-8 ; tous les indicateurs sont listés dans AGENTS.md.

1. Configuration et vérification

scripts/install_rmcprofile_windows.ps1        # ou scripts/install_rmcprofile.sh ; les deux acceptent un dry-run
export RMCPROFILE_HOME=/chemin/vers/RMCProfile_package    # le répertoire contenant exe/ et tutorial/
python scripts/verify_rmcprofile.py           # imports, formats, identité de Keen, couches de sel gemme, test de validation du package

Le package est téléchargé par l'utilisateur depuis rmcprofile.ornl.gov/download/ (SourceForge) et décompressé ; sans RMCPROFILE_HOME, toute vérification et tout test lié au package sont ignorés, pas échoués. verify_rmcprofile.py ne sort avec le code 0 que lorsque chaque vérification réussit ; son test de validation copie tutorial/ex_1 dans un répertoire temporaire et l'exécute (quelques secondes, χ²/ddl 0.4201 sur les deux builds).

2. Vérifier un jeu d'entrées avant l'exécution

python scripts/rmcprofile_tools.py check STEM --dir RUNDIR

Affiche une ligne par constatation, LEVEL code: message, sort avec le code 1 en cas d'ERROR. Codes : no-dat, dat-parse, no-configuration, rmc6f-parse, atom-order (les ATOMS :: et la configuration sont en désaccord), 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 (le programme attendrait indéfiniment), bulk-rho-missing (PARTICLE_RADIUS :: sans BULK_RHO ::, le programme s'arrête) ; avertissements end-point-beyond-data, filename-case (Linux/macOS ne trouverait pas le fichier), no-weight, hkl-range-unspecified, stale-neighbour-files, history-file (un .his6f issu d'un passage à zéro mouvement empoisonne la prochaine exécution) ; informations potential-lists-regenerated, summary.

3. Exécuter RMCProfile et lire le résultat

python scripts/rmcprofile_tools.py run STEM --dir RUNDIR --timeout 10      # minutes ; --home remplace RMCPROFILE_HOME

Le vérificateur s'exécute d'abord et refuse de démarrer en cas d'erreur. La sortie standard de l'exécution va dans RUNDIR/run.log ; la ligne de résumé donne le code de retour, le temps réel et le nombre de fichiers de sortie ; final : répète la dernière ligne de <stem>.chi2. En Python : res = run_rmcprofile(stem, rundir, find_package()) → res.returncode, res.seconds, res.outputs, res.final_chi2. Lisez l'ajustement avec read_csv_pair("<stem>_PDF1.csv") (r, calc, expt), read_partials_csv("<stem>_PDFpartials.csv"), read_chi2_history("<stem>.chi2"). Une configuration manquante fait que RMCProfile s'arrête avec le code de sortie 0 — faites confiance à outputs et final_chi2, pas au code.

4. Préparer les fichiers de données

from rmcprofile_tools import write_data_file, read_data_file
write_data_file("sample_gr.dat", r, G, "sample 300 K", style="two-line")   # ou style="stog"

DATA_TYPE/FIT_TYPE sont G(r), D(r), T(r) dans l'espace réel et F(Q), S(Q), i(Q) dans l'espace réciproque ; les définitions, l'identité r → 0 G(0) = −(Σ c_i b_i)² et les poids sont dans references/method.md. Un G(r) dont le plateau aux faibles r n'est pas −(Σ c b)² n'a pas été normalisé comme RMCProfile l'attend.

5. Construire ou éditer un fichier .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 conserve les scalaires, la ligne ATOMS :: et chaque bloc dans l'ordre du fichier et les réécrit de manière stable au niveau des octets ; d.get(block, key), d.data_blocks(), d.filenames(). La règle bloc-scalaire et chaque mot-clé vu dans le package sont dans references/formats.md. Gardez NUMBER_DENSITY égal à la densité d'en-tête de la configuration.

6. Analyser une configuration sans le binaire

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 écrit <stem>_PDFpartials.csv (g_ij), <stem>_GofR.csv (G(r) de Keen en barn) et <stem>_FofQ.csv ; coord affiche l'histogramme de coordination ; angles écrit l'histogramme des angles B-A-C. Vérification de cohérence : la première valeur de G(r) doit être −(Σ c_i b_i)² (−0.2759 barn pour SF6). En Python : read_rmc6f, partial_gr, total_gr, fq_from_gr, coordination, bond_angles, average_cell, NEUTRON_B. --rmax doit rester inférieur à la moitié du plus petit bord de la supercellule.

7. Pièges

references/pitfalls.md : l'attente .poly, le code de sortie 0 sur une erreur fatale, la précédence de .his6f, les fichiers de voisins obsolètes, le taux de déplacement CUDA contre CPU, la lenteur de /mnt/* sous WSL, les deux dispositions de lignes d'atomes dans .rmc6f, les sauts de ligne CRLF, la convention de la grille r, les poids d'abondance naturelle, les consoles cp1252.

8. Vérification croisée avec le package installé

python scripts/upstream_adapter.py list                      # les huit exercices fournis et leurs recettes de préparation
python scripts/upstream_adapter.py crosscheck ex_1 --timeout 3

crosscheck prépare les entrées vierges de l'exercice dans un répertoire temporaire (sorties supprimées, .poly/.fs/.sf conservés, TIME_LIMIT de ex_7 réduit à 5 min), exécute le package, puis compare nos partielles et notre G(r) de Keen pour le .rmc6f résultant avec les propres _PDFpartials.csv et _PDF1.csv du package. "dans la tolérance : True" signifie que chaque paire se trouve dans tolerance_partials (1e-3 ; le package calcule en simple précision, mesuré à 2.8e-4 sur le pic g = 20) et G(r) dans tolerance_gofr (1e-4 barn, mesuré 3e-5) de tests/records/crosscheck_v1.json. --update-records réécrit les maximums mesurés et la provenance — seulement après une nouvelle mesure délibérée. En Python : crosscheck_partials(rmc6f, partials_csv), crosscheck_gofr(rmc6f, pdf_csv), stage_exercise, run_and_crosscheck.

9. Enseigner avec rmclite

python scripts/rmclite.py synth truth.rmc6f --displace 0.05 --rmax 5 --outdir out     # cibles de la vérité + une copie déplacée
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 écrit <stem>_fit.rmc6f, <stem>_fit.chi2 (l'en-tête de RMCProfile m_accepted m_generated m_tested chi2), <stem>_fit_PDFpartials.csv et <stem>_fit_GofR.csv — lisez-les avec les mêmes lecteurs que la sortie de RMCProfile. La règle d'acceptation est Δ = Δχ²/2 + ΔU/k_BT, accepter si Δ ≤ 0, sinon avec probabilité e^(−Δ). Commencez par la structure moyenne, jamais par une distorsion aléatoire ; n'ajustez jamais des cibles non élargies (delta-sharp) ; attendez-vous à ce que la distribution de paires soit reproduite, pas les coordonnées (references/rmclite.md §5). En Python : Box.from_rmc6f, Histogram, PartialTarget, TotalGTarget, FqTarget, ClosestApproach, DistanceWindow, BondPotential, RmcLite(...).run(n), synth_targets.

10. Lire ou reconstruire le livre

chapters/RMCProfile_NN_*.ipynb — onze cahiers exécutés (§1–40, index dans chapters/README.md) : 1 la diffusion totale et la PDF, 2 l'algorithme RMC, 3 les configurations de départ, 4 l'ajustement de données neutroniques avec RMCProfile, 5 rayons X et Bragg, 6 contraintes et potentiels, 7 corrections (les formes mesurées de RESOLUTION_CORRECTION et PARTICLE_RADIUS), 8 EXAFS / magnétique / diffus, 9 l'analyse des configurations, 10 les benchmarks et l'écosystème. Dirigez un utilisateur vers le chapitre, pas vers une paraphrase : chaque nombre qu'ils contiennent a été calculé dans le cahier. Pour reconstruire après avoir modifié build/part*.py :

python build/assemble.py --which 07          # régénérer un chapitre (les cahiers inchangés sont conservés avec leurs sorties)
RMCPROFILE_HOME=... python build/execute.py --which 07   # l'exécuter sur le noyau rmcprofile-mc ; bilan SUCCÈS/ÉCHEC dans logs/execute.log
python build/gallery.py                      # docs/figures + galerie README
python -m pytest tests/test_notebooks.py -q  # sources, sorties, totaux, fuites

11. Enseigner le cours

course/deck/index.html — onze conférences (L0 pourquoi la structure locale … L10 contribuer), plates et linéaires, chaque figure de chapitre sous sa légende de cahier ; course/slides.pdf est le même diaporama sans navigateur ; course/handout/handout.html le compagnon A4 ; course/notes/LECTURER_NOTES.md les notes de chaque diapositive avec sa question anticipée. Dirigez un conférencier vers course/README.md (programme, clés, reconstruction). Après avoir réexécuté un chapitre :

python course/tools/extract_figures.py      # figures + provenance (--check pour tester)
python course/tools/build_deck.py           # index.html, handout, notes (--check pour tester)
python course/tools/make_slides_pdf.py      # slides.pdf (Playwright ; commit)
python -m pytest tests/test_course.py -q

12. Surveiller en amont chaque semaine

python scripts/watch_upstream.py --weekly          # Liste SourceForge, pages/articles du site, outils conda, voisins GitHub, statut du suivi
python scripts/watch_upstream.py --snapshot        # enregistrer l'état sans rapport
powershell -File scripts/register_watch_task.ps1   # Planificateur de tâches Windows, lundis 08:00 (-DryRun, -Remove)

Les rapports vont dans <study>/docs/watch/YYYY-WW.md, l'instantané et les journaux d'audit dans <study>/forum/upstream-watch/ (gitignorés). Un flux qui ne répond pas est une ligne dans le rapport et la sortie 1 ; lisez le rapport avant de faire confiance à une semaine silencieuse. La première exécution (2026-W36) a trouvé un candidat 6.8.0-rc.1 sur SourceForge que la page de téléchargement du site ne listait pas.