Sobre o projeto

# ML informado pela física para o fortalecimento de Hall–Petch em MPEAs CFC Este repositório serve como material complementar do manuscrito da *Acta Materialia* intitulado "Revisiting Hall–Petch strengthening in FCC multi-principal element alloys: what grain size, composition, and processing can and cannot explain", de M. Mulukutla, S. P. Padhy, et al. Ele contém o conjunto de dados completo, o pipeline de análise completo, todas as tabelas de resultados e figuras apresentadas no artigo, fontes LaTeX, um relatório abrangente regenerado a partir de resultados ao vivo e testes de regressão que fixam os valores canônicos do manuscrito. ## A Questão Modelos de propriedades baseados em aprendizado de máquina podem induzir a erros no projeto de ligas quando a interpolação é confundida com transferência, ou quando um descritor com motivação física é lido como mecanismo sem que se demonstre que ele adiciona informação além das entradas medidas. Este repositório aborda esse problema de ponta a ponta para o limite de escoamento (YS) e a dureza Vickers (HV) de 94 condições de ligas CFC no sistema Al–Co–Cr–Cu–Fe–Mn–Ni–V. ## Cinco Famílias de Modelos As análises são organizadas pelas cinco famílias do manuscrito. Um número de família mais alto significa mais flexibilidade, não mais fidelidade física. - **Família 1**: Hall–Petch clássico (leis de tamanho de grão clássicas e alternativas) - **Família 2**: Descritores físicos (VLC, Labusch, Toda-Caraballo; Wen; PCA-OLS) - **Família 3**: Composição / processamento (a hierarquia do modelo M, incl. M15) - **Família 4**: ML não linear (estimadores lineares e não lineares emparelhados) - **Família 5**: Regressão simbólica (PySR, SISSO, formas fechadas fixas) O protocolo de validação inclui 5-fold, LOO, LOBO, literatura e verificações de singularidade. ## Resultados Principais Todos os valores são Q² agrupado fora da amostra, recalculados no momento do teste a partir de `data/derived/data_with_vlc.csv`. | Alvo | Modelo | 5-fold | LOO | LOBO | |---|---|---|---|---| | YS | Família 1 Hall–Petch clássico | 0.405 | 0.406 | 0.373 | | YS | Família 2 PCA-OLS (contido no fold) | 0.462 | 0.480 | 0.362 | | YS | Família 3 M3 (σ₀ dependente da composição) | 0.666 | 0.652 | 0.625 | | YS | **Família 3 M15 (+ interação SD_grain)** | **0.731** | **0.694** | **0.694** | | YS | Família 4 Lasso S2 (configurações fixas) | 0.683 | 0.674 | 0.621 | | YS | Família 4 LightGBM S2 (configurações fixas) | 0.632 | 0.574 | 0.615 | | YS | Família 4 Bayesian ridge S2 (ARMOTE-CV aninhado) | 0.685 | 0.666 | 0.613 | | HV | Família 1 Hall–Petch clássico | 0.086 | 0.136 | −0.077 | | HV | Família 4 LightGBM S1 | 0.195 | 0.323 | 0.112 | | HV | Família 5 forma fixa (pós-selecionada) | 0.725 | 0.727 | 0.636 | Três achados fazem a maior parte do trabalho: - **A largura da distribuição de grãos ajuda apenas em uma forma específica.** Adicionar SD_grain ao M3 como um termo aditivo independente eleva o LOO para 0.668, mas reduz o LOBO para 0.595. Permitir que ele modifique o termo de Hall–Petch (M15) fornece 0.694 em ambos, com ΔBIC = −20.1 em relação ao M3. O controle aditivo é o que torna essa distinção visível. - **A não linearidade não traz nada com entradas emparelhadas.** Lasso e LightGBM alcançam 0.621 e 0.615 sob validação com lote retido, com intervalos bootstrap sobrepostos. - **Nada transfere para a literatura.** Toda forma fechada avaliada tem R² negativo nos registros de literatura de medição direta, de modo que esse conjunto é relatado como um teste de estresse, e não como um benchmark externo. ## Estrutura ``` data/raw/ Grain_Size_Summary_v3.xlsx — a única entrada verdadeira data/derived/ descritores computados, regenerados por `make data` scripts/ _config.py caminhos compartilhados; torna cada pasta de família importável _figstyle.py uma paleta e uma escala tipográfica para cada figura 00_data_preparation/ descritores, quantidades VLC, escada de features 01_family1_grain_size/ leis de escala, inclinações dentro de réplicas 02_family2_physics_descriptors/ benchmark SSS, auditoria de redundância, PCA-OLS 03_family3_composition_processing/ hierarquia do modelo M, modelos SD_grain 04_family4_nonlinear_ml/ painel ajustado, comparação com entradas emparelhadas 05_family5_symbolic_regression/ grade PySR, variantes SISSO 06_validation/ CV agrupada, teste de literatura, auditoria de singularidade 07_hardness_tabor/ razão de Tabor e análise de rank HV–YS figures/ todas as figuras de publicação results/ saídas CSV; cada uma é produzida por um script nomeado analysis_plots/ figuras exploratórias e de diagnóstico paper/ main.tex, supplementary.tex, references.bib, figures/ report/ generate_report.py + Comprehensive_Analysis_Report.docx notebook/ gerador + .ipynb gerado docs/ reproducing.md, validation_protocol.md tests/ testes de regressão que fixam os valores canônicos ``` ## Início rápido ```bash pip install -r requirements.txt make test # ~1 s — recalcula e verifica cada valor principal make figures # regenera todas as figuras de publicação a partir de resultados em cache make report # reconstrói o relatório Word a partir de resultados ao vivo make paper # compila main.pdf e supplementary.pdf make help # todos os alvos ``` Ordem completa dos estágios e tempos: `docs/reproducing.md`. ## Reprodutibilidade `make test` recalcula a hierarquia do modelo M, as linhas de base da Família 1, a razão de Tabor e a auditoria do conjunto de dados **a partir dos dados derivados brutos** e os verifica em relação aos valores impressos no manuscrito. Também verifica que toda figura e tabela é referenciada cruzadamente no texto e que todo arquivo de figura incluído existe. Se uma análise mudar, os testes falham antes que o manuscrito possa se desviar. O **painel ARMOTE-CV aninhado** é verificado, e não reexecutado. Seu gerador armazena um estudo Optuna, um conjunto de parâmetros selecionado e um par de escaladores de features e alvo por fold. Ao longo dos seis folds LOBO, os cinco hiperparâmetros ajustados do Bayesian-ridge assumem seis valores distintos, e cada escalador é ajustado apenas em sua divisão de treino. Recarregar esses objetos e prever cada lote retido reproduz exatamente todas as seis pontuações de fold e fornece um Q² LOBO agrupado de 0.613 (RMSE 50.5 MPa). O aninhamento, portanto, é demonstrado, não afirmado. Esses artefatos são distribuídos com o repositório, em `scripts/04_family4_nonlinear_ml/armote_cv/` — consulte o README lá para saber o que foi mantido e o que foi deixado upstream. Duas análises são **arquivais** e não são regeneradas aqui, no manuscrito ou por `make`: | Resultado arquival | Motivo | |---|---| | Pesos de stacking PSIS-LOO bayesianos | As amostras posteriores do PyMC não foram retidas | | Desempenho do PySR no loop externo | as equações foram selecionadas em frentes de dados completos | O manuscrito relata esses resultados como arquivais, e as quantidades frequentistas correspondentes que *podem* ser recalculadas (coeficientes OLS do M15, critérios de informação e pontuações de CV agrupada) são regeneradas por `make sdgrain`. ## Figuras Toda figura importa `scripts/_figstyle.py`, de modo que todo o documento usa uma paleta Okabe–Ito e uma escala tipográfica. A cor nunca é o único canal: os lotes carregam formas de marcadores distintas, as famílias de modelos são separadas por posição, e quantidades com sinal imprimem seu valor. As figuras são desenhadas em sua largura final de impressão, de modo que um tamanho de ponto no script é o mesmo tamanho de ponto na página. A paleta foi verificada sob deuteranopia, protanopia e tritanopia simuladas. ## Citação Consulte `CITATION.cff`. Metadados arquivais para o Zenodo estão em `.zenodo.json`. ## Licença MIT — consulte `LICENSE`. O conjunto de dados experimentais brutos e a compilação da literatura estão incluídos; PDFs da literatura citada não são redistribuídos. ## Agradecimento Patrocinado pelo Army Research Laboratory sob o Cooperative Agreement W911NF-22-2-0106.