rmcprofile-skill 0.5.5
Um kit de ferramentas Python para o RMCProfile, o programa de Monte Carlo Reverso para espalhamento total (rmcprofile.ornl.gov). Ele lê e escreve todos os formatos de entrada e saída da versão 6.7.9 (references/formats.md), verifica um conjunto de entrada contra os erros sobre os quais o manual alerta, executa o binário instalado pelo usuário e analisa configurações de forma autônoma (references/method.md), faz auto-verificação cruzada com o pacote instalado (scripts/upstream_adapter.py) e inclui um pequeno motor RMC de sala limpa para ensino (scripts/rmclite.py, references/rmclite.md). O RMCProfile é de código fechado e distribuído sob seus próprios termos de "fins não lucrativos"; este skill nunca distribui ou copia o código — ele o encontra através de RMCPROFILE_HOME (references/package.md). Leia references/pitfalls.md antes de tocar em um diretório de execução. Execute tudo a partir da raiz do produto com o conda env rmcprofile e PYTHONIOENCODING=utf-8; todas as flags estão listadas em AGENTS.md.
1. Configuração e verificação
scripts/install_rmcprofile_windows.ps1 # ou scripts/install_rmcprofile.sh; ambos aceitam um dry-run
export RMCPROFILE_HOME=/caminho/para/RMCProfile_package # o diretório que contém exe/ e tutorial/
python scripts/verify_rmcprofile.py # imports, formatos, identidade de Keen, camadas de sal-gema, teste de fumaça do pacote
O pacote é baixado pelo usuário de rmcprofile.ornl.gov/download/ (SourceForge) e descompactado; sem RMCPROFILE_HOME, toda verificação e teste vinculado ao pacote é ignorado, não falhado. verify_rmcprofile.py sai com 0 apenas quando todas as verificações passam; seu teste de fumaça copia tutorial/ex_1 para um diretório temporário e o executa (alguns segundos, χ²/gl 0,4201 em ambas as compilações).
2. Verificar um conjunto de entrada antes de executar
python scripts/rmcprofile_tools.py check STEM --dir RUNDIR
Imprime uma linha por achado, NÍVEL código: mensagem, sai com 1 em qualquer ERRO. Códigos: no-dat, dat-parse, no-configuration, rmc6f-parse, atom-order (ATOMS :: e a configuração discordam), 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 (o programa esperaria para sempre), bulk-rho-missing (PARTICLE_RADIUS :: sem BULK_RHO ::, o programa para); avisos end-point-beyond-data, filename-case (Linux/macOS não encontrariam o arquivo), no-weight, hkl-range-unspecified, stale-neighbour-files, history-file (um .his6f de uma passagem de zero movimentos envenena a próxima execução); informações potential-lists-regenerated, summary.
3. Executar RMCProfile e ler o resultado
python scripts/rmcprofile_tools.py run STEM --dir RUNDIR --timeout 10 # minutos; --home substitui RMCPROFILE_HOME
O verificador é executado primeiro e se recusa a iniciar em caso de erro. A saída padrão da execução vai para RUNDIR/run.log; a linha de resumo fornece o código de retorno, tempo de parede e o número de arquivos de saída; final: exibe a última linha de <stem>.chi2. Em Python: res = run_rmcprofile(stem, rundir, find_package()) → res.returncode, res.seconds, res.outputs, res.final_chi2. Leia o ajuste com read_csv_pair("<stem>_PDF1.csv") (r, calc, expt), read_partials_csv("<stem>_PDFpartials.csv"), read_chi2_history("<stem>.chi2"). Uma configuração ausente faz o RMCProfile parar com código de saída 0 — confie em outputs e final_chi2, não no código.
4. Preparar arquivos de dados
from rmcprofile_tools import write_data_file, read_data_file
write_data_file("sample_gr.dat", r, G, "amostra 300 K", style="two-line") # ou style="stog"
DATA_TYPE/FIT_TYPE são G(r), D(r), T(r) no espaço real e F(Q), S(Q), i(Q) no espaço recíproco; as definições, a identidade r → 0 G(0) = −(Σ c_i b_i)² e os pesos estão em references/method.md. Um G(r) cujo platô de baixo r não é −(Σ c b)² não foi normalizado da forma que o RMCProfile espera.
5. Construir ou editar um .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 mantém escalares, a linha ATOMS :: e cada bloco na ordem do arquivo e os escreve de volta de forma estável em termos de bytes; d.get(block, key), d.data_blocks(), d.filenames(). A regra de bloco versus escalar e cada palavra-chave vista no pacote estão em references/formats.md. Mantenha NUMBER_DENSITY igual à densidade do cabeçalho da configuração.
6. Analisar uma configuração sem o binário
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 escreve <stem>_PDFpartials.csv (g_ij), <stem>_GofR.csv (G(r) de Keen em barn) e <stem>_FofQ.csv; coord imprime o histograma de coordenação; angles escreve o histograma do ângulo B-A-C. Verificação de sanidade: o primeiro valor de G(r) deve ser −(Σ c_i b_i)² (−0,2759 barn para SF6). Em Python: read_rmc6f, partial_gr, total_gr, fq_from_gr, coordination, bond_angles, average_cell, NEUTRON_B. --rmax deve permanecer abaixo da metade da menor borda da supercélula.
7. Armadilhas
references/pitfalls.md: a espera do .poly, código de saída 0 em um erro fatal, precedência do .his6f, arquivos de vizinhos obsoletos, taxa de movimento CUDA versus CPU, lentidão de /mnt/* no WSL, os dois layouts de linha de átomo do .rmc6f, CRLF, a convenção da grade r, pesos de abundância natural, consoles cp1252.
8. Verificação cruzada com o pacote instalado
python scripts/upstream_adapter.py list # os oito exercícios fornecidos e suas receitas de preparação
python scripts/upstream_adapter.py crosscheck ex_1 --timeout 3
crosscheck prepara as entradas originais do exercício em um diretório temporário (saídas removidas, .poly/.fs/.sf mantidos, TIME_LIMIT de ex_7 reduzido para 5 min), executa o pacote e então compara nossas parciais e G(r) de Keen para o .rmc6f resultante com os _PDFpartials.csv e _PDF1.csv do próprio pacote. "within tolerance: True" significa que cada par está dentro de tolerance_partials (1e-3; o pacote calcula em precisão simples, medido 2.8e-4 no pico g = 20) e G(r) dentro de tolerance_gofr (1e-4 barn, medido 3e-5) de tests/records/crosscheck_v1.json. --update-records reescreve os máximos medidos e a proveniência — apenas após uma medição deliberada. Em Python: crosscheck_partials(rmc6f, partials_csv), crosscheck_gofr(rmc6f, pdf_csv), stage_exercise, run_and_crosscheck.
9. Ensinar com rmclite
python scripts/rmclite.py synth truth.rmc6f --displace 0.05 --rmax 5 --outdir out # alvos da verdade + uma cópia deslocada
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 escreve <stem>_fit.rmc6f, <stem>_fit.chi2 (cabeçalho do RMCProfile m_accepted m_generated m_tested chi2), <stem>_fit_PDFpartials.csv e <stem>_fit_GofR.csv — leia-os com os mesmos leitores da saída do RMCProfile. A regra de aceitação é Δ = Δχ²/2 + ΔU/k_BT, aceite se Δ ≤ 0 caso contrário com probabilidade e^(−Δ). Comece da estrutura média, nunca de uma distorção aleatória; nunca ajuste alvos sem alargamento (delta-sharp); espere que a distribuição de pares seja reproduzida, não as coordenadas (references/rmclite.md §5). Em Python: Box.from_rmc6f, Histogram, PartialTarget, TotalGTarget, FqTarget, ClosestApproach, DistanceWindow, BondPotential, RmcLite(...).run(n), synth_targets.
10. Ler ou reconstruir o livro
chapters/RMCProfile_NN_*.ipynb — onze cadernos executados (§1–40, índice em chapters/README.md): 1 espalhamento total e a PDF, 2 o algoritmo RMC, 3 configurações iniciais, 4 ajuste de dados de nêutrons com RMCProfile, 5 raios-X e Bragg, 6 restrições e potenciais, 7 correções (as formas medidas de RESOLUTION_CORRECTION e PARTICLE_RADIUS), 8 EXAFS / magnético / difuso, 9 análise de configurações, 10 benchmarks e ecossistema. Direcione um usuário para o capítulo, não para uma paráfrase: cada número neles foi calculado no caderno. Para reconstruir após editar build/part*.py:
python build/assemble.py --which 07 # regenerar um capítulo (cadernos inalterados são mantidos com suas saídas)
RMCPROFILE_HOME=... python build/execute.py --which 07 # executá-lo no kernel rmcprofile-mc; resumo PASS/FAIL em logs/execute.log
python build/gallery.py # docs/figures + galeria README
python -m pytest tests/test_notebooks.py -q # fontes, saídas, totais, vazamentos
11. Ensinar o curso
course/deck/index.html — onze palestras (L0 por que estrutura local … L10 contribuindo), planas e lineares, cada figura de capítulo sob sua legenda de caderno; course/slides.pdf é o mesmo deck sem navegador; course/handout/handout.html o acompanhamento A4; course/notes/LECTURER_NOTES.md as notas de cada slide com sua pergunta antecipada. Direcione um palestrante para course/README.md (programa, chaves, reconstrução). Após reexecutar um capítulo:
python course/tools/extract_figures.py # figuras + proveniência (--check para testar)
python course/tools/build_deck.py # index.html, handout, notes (--check para testar)
python course/tools/make_slides_pdf.py # slides.pdf (Playwright; commitado)
python -m pytest tests/test_course.py -q
12. Observar upstream semanalmente
python scripts/watch_upstream.py --weekly # listagem do SourceForge, páginas/postagens do site, ferramentas conda, vizinhos no GitHub, status do rastreador
python scripts/watch_upstream.py --snapshot # registrar o estado sem relatório
powershell -File scripts/register_watch_task.ps1 # Agendador de Tarefas do Windows, Segundas 08:00 (-DryRun, -Remove)
Relatórios vão para <study>/docs/watch/YYYY-WW.md, o instantâneo e logs de auditoria para <study>/forum/upstream-watch/ (gitignored). Um feed que não responde é uma linha no relatório e saída 1; leia o relatório antes de confiar em uma semana silenciosa. A primeira execução (2026-W36) encontrou um candidato 6.8.0-rc.1 no SourceForge que a página de download do site não listava.