From Code to Figure: A FAIR-Aligned Data Provenance Chain for Reproducible Simulation Research in Numerical Physics

Este artigo apresenta um fluxo de trabalho integrado e alinhado com os princípios FAIR que combina controle de versão, testes automatizados, registro estruturado e pós-processamento padronizado para estabelecer uma cadeia completa de proveniência de dados, garantindo a reprodutibilidade desde o desenvolvimento do código até as figuras publicadas em simulações de física numérica.

O essencial

Imagine que você é um chef que passou anos aperfeiçoando uma receita complexa para um prato que muda ligeiramente a cada vez que você o prepara. Um dia, você publica uma foto do prato final em um livro de receitas. Um ano depois, alguém tenta recriá-lo, mas não consegue. Por quê? Porque essa pessoa não sabe exatamente qual versão da receita você usou, qual marca específica de ingredientes você tinha em sua despensa naquele dia, ou se você ajustou a temperatura do forno no meio do cozimento.

Este artigo, escrito por Markus Uehlein e sua equipe, trata de resolver exatamente esse problema para cientistas que executam simulações computacionais em vez de preparar refeições. No mundo da "física numérica" (uso de computadores para modelar como os materiais se comportam), as "receitas" são códigos de software que estão sendo atualizados constantemente, e os "pratos" são conjuntos massivos de dados.

Aqui está como os autores propõem manter tudo rastreável, usando um fluxo de trabalho simples de quatro etapas que eles chamam de Cadeia de Proveniência de Dados.

1. O Livro de Receitas (Controle de Versão e Revisão de Código)

No passado, se um cientista alterasse uma linha de código, ele poderia simplesmente salvá-la como simulacao_final_v2_real_final.cpp. Isso é um desastre de receita esperando para acontecer.

Os autores utilizam um sistema chamado Git (pense nele como um livro de receitas que viaja no tempo). Sempre que alguém altera o código, ele recebe um carimbo de tempo único e uma "revisão" de um colega antes de ser salvo. Isso garante que, se você examinar uma simulação de cinco anos atrás, poderá ver a versão exata do código utilizada, até a linha específica de texto. É como ter uma foto das mãos do chef e dos ingredientes exatos na bancada no momento em que o prato foi preparado.

2. As Verificações de Segurança (Testes Automatizados)

Antes de uma simulação ser executada, o software realiza "verificações de segurança" automáticas.

• Verificações de Unidade: O código verifica se a matemática faz sentido fisicamente. Por exemplo, ele não permitirá que você adicione "metros" a "segundos" (não se pode adicionar distância a tempo!). Se você tentar, o computador o impedirá antes mesmo da simulação começar.
• Verificações de Física: O código executa pequenas simulações de teste para garantir que a física se comporte como deveria (por exemplo, "Se eu aquecer isso, a energia aumenta?"). Se a resposta for não, o sistema sabe que algo está quebrado.

3. O Gravador "Caixa Preta" (Registro Estruturado e Metadados)

Quando a simulação realmente é executada, ela não apenas joga fora uma lista de números. Ela cria um arquivo hierárquico (uma estrutura de pasta digital sofisticada) que atua como um gravador de "caixa preta" em um avião.

Dentro deste arquivo, os cientistas armazenam:

• Os dados brutos (os resultados).
• As configurações de entrada exatas (a receita).
• O "log de compilação" (qual versão do código foi usada).
• O ambiente (que tipo de CPU de computador foi usado).
• Um diário da execução (qualquer aviso ou erro que ocorreu enquanto estava sendo preparado).

Eles utilizam um formato padrão chamado HDF5/NeXus. Pense nisso como um recipiente universal que mantém os dados organizados para que, mesmo que o cientista original esqueça o que fez, qualquer outra pessoa possa abrir a caixa e entender exatamente o que aconteceu.

4. O Prato (De Dados a Figuras)

Finalmente, os cientistas transformam esses dados brutos nos gráficos e imagens bonitos que você vê em um artigo publicado. Normalmente, essa etapa é bagunçada — os cientistas podem escrever um script único para criar um gráfico e depois apagá-lo.

Neste fluxo de trabalho, a etapa para criar a imagem também é controlada por versão. O script usado para fazer o gráfico é salvo, e o gráfico em si é carimbado com um link de volta aos dados brutos e ao código usado para criá-lo.

A Visão Geral: A "Cadeia de Custódia"

O ponto principal deste artigo é que essas quatro etapas não devem ser ilhas separadas. Elas precisam ser uma cadeia.

• Antigo Jeito: Você publica uma imagem. Alguém pergunta: "Como você chegou a isso?" Você diz: "Eu executei uma simulação." Eles perguntam: "Qual delas?" Você diz: "Acho que foi a de terça-feira passada." A reprodutibilidade falha.
• Novo Jeito (Método do Artigo): Você publica uma imagem. Você clica em um link, e ele mostra a versão exata do código, o arquivo de entrada exato, o computador em que foi executado e o script usado para fazer a imagem. A reprodutibilidade tem sucesso.

Os autores testaram isso em seu próprio software de simulação de longa duração (chamado monstr), que tem sido usado para muitos estudos ao longo de vários anos. Eles mostraram que, ao vincular o código, os dados e as figuras juntos, criaram um sistema onde qualquer pessoa pode rastrear um resultado publicado de volta ao estado original do software, garantindo que as descobertas científicas permaneçam confiáveis e reutilizáveis a longo prazo.

Em resumo: Eles construíram um sistema onde cada resultado científico vem com seu próprio "recibo" que prova exatamente como foi feito, impedindo que o problema "funciona na minha máquina" arruíne a confiança científica.

Resumo técnico

1. Declaração do Problema

A física computacional depende cada vez mais de grandes conjuntos de dados de simulação gerados por software que evolui ao longo de muitos anos. Isso cria desafios significativos de reprodutibilidade:

• Software de Longa Duração: Frameworks de simulação frequentemente sobrevivem ao mandato de pesquisadores individuais, levando a múltiplos colaboradores e ciclos de desenvolvimento sobrepostos.
• Proveniência Quebrada: A reprodutibilidade exige mais do que apenas armazenar arquivos de saída; demanda um link explícito e rastreável entre versões específicas de código, entradas de simulação, configurações de tempo de execução, etapas de análise e figuras finais publicadas.
• Custos de Gerenciamento de Dados: O gerenciamento ineficaz de dados leva a esforço de pesquisa desperdiçado e bilhões de euros em custos anuais (especificamente notado no contexto da UE).
• Lacuna de Conformidade FAIR: Embora os princípios FAIR (Localizável, Acessível, Interoperável, Reutilizável) estejam estabelecidos, integrá-los em todo o ciclo de vida de desenvolvimento de software e simulação permanece um desafio prático.

2. Metodologia

Os autores propõem um fluxo de trabalho integrado que conecta desenvolvimento de software, execução de simulação, armazenamento estruturado de dados e pós-processamento padronizado. Este fluxo de trabalho é demonstrado usando o framework de simulação monstr (relaxação modular orientada a objetos resolvida em spin e tempo fora do equilíbrio), escrito em C++.

A metodologia é estruturada em quatro passos conectados:

A. Desenvolvimento de Software e Proveniência de Executáveis

• Controle de Versão: Utiliza Git com uma instância remota do GitLab para desenvolvimento baseado em branches, rastreamento de issues e revisões de código obrigatórias.
• Captura de Estado do Executável: O sistema de build registra não apenas o identificador do commit do Git, mas também modificações locais de código não confirmadas no momento da compilação. Isso garante que o estado exato da fonte usado para gerar o executável seja preservado.
• Registro de Ambiente: Metadados incluem modelos de CPU e configurações de MPI para garantir que o contexto de execução seja reprodutível.

B. Salvaguardas de Implementação e Garantia de Qualidade

• Análise Dimensional: Utiliza a biblioteca Boost.Units para análise dimensional em tempo de compilação. Quantidades físicas são atribuídas a tipos (por exemplo, Energia, Volume), permitindo que o compilador rejeite expressões dimensionalmente inconsistentes.
• Estabilidade Numérica: Internamente, as simulações usam unidades atômicas (energia de Hartree, constante de Planck reduzida, etc.) para minimizar erros de arredondamento de ponto flutuante através de ordens de grandeza, mantendo unidades SI para interfaces de entrada/saída.
• Testes Automatizados: Um pipeline GitLab CI executa testes automatizados de unidade e integração (usando GoogleTest) sempre que o código é enviado. Esses testes verificam a consistência física (por exemplo, garantindo que a energia interna do elétron aumente monotonicamente com a temperatura).
• Documentação: A documentação (gerada via Doxygen) é reconstruída automaticamente para permanecer sincronizada com a base de código.

C. Entradas Validadas e Registro Estruturado

• Validação de Entrada: Parâmetros de configuração (modelos, materiais, solucionadores) são definidos em arquivos YAML. Um banco de dados YAML separado e controlado por versão define sistemas de materiais para garantir consistência, com validação realizada antes do lançamento do cálculo.
• Diagnósticos em Tempo de Execução: Diagnósticos baseados em física (por exemplo, número de partículas e conservação de energia) são monitorados durante a execução.
• Registro Estruturado: Utiliza a biblioteca spdlog para gerar logs com níveis de severidade (debug, info, warning, error). Esses logs são armazenados junto com os resultados para fornecer um contexto de execução.

D. Armazenamento Hierárquico (HDF5/NeXus)

• Formato: Os dados são armazenados em arquivos HDF5 (Hierarchical Data Format), aderindo ao padrão NeXus.
• Estrutura: Os arquivos contêm grupos (contêineres) e conjuntos de dados (dados numéricos).
• Integração de Metadados: A estrutura do arquivo inclui:
  • Resultados científicos (vetores, matrizes).
  • Metadados de execução (commit do Git, diffs locais, configuração CPU/MPI).
  • Arquivos de entrada (YAML) e logs de tempo de execução.
  • Atributos NeXus: Define unidades físicas e relações sinal/eixo para visualização padronizada.
• Interoperabilidade: Os arquivos podem ser inspecionados via H5Web e processados via Python (nexusformat), garantindo acessibilidade a longo prazo.

E. Pós-Processamento Padronizado e Publicação

• Análise Versada: Uma biblioteca Python separada e controlada por versão gerencia todo o pós-processamento e geração de figuras. Isso evita scripts ad-hoc.
• Propagação de Proveniência: Scripts de análise extraem identificadores (commit do Git, hash do arquivo de entrada) diretamente da saída NeXus.
• Metadados de Figuras: Quando as figuras são exportadas, o ID de commit da biblioteca de análise e o identificador persistente do conjunto de dados de origem são incorporados nos metadados da figura.
• Publicação de Dados: Conjuntos de dados brutos são publicados em repositórios (por exemplo, Zenodo, NOMAD) com Identificadores Persistentes (DOIs), vinculados diretamente ao manuscrito.

3. Contribuições Principais

• Cadeia de Proveniência de Ponta a Ponta: O artigo demonstra uma implementação prática de uma cadeia ligando Código $\to$ Estado do Executável $\to$ Entrada $\to$ Saída $\to$ Análise $\to$ Figura.
• Fidelidade do Estado do Executável: Ao capturar modificações locais no momento da compilação e detalhes do ambiente, os autores garantem que uma execução de simulação possa ser reconstruída mesmo anos depois, não apenas pela versão do código, mas pelo estado exato da fonte.
• Integração FAIR em Física: O fluxo de trabalho vai além dos princípios teóricos FAIR para uma implementação de engenharia concreta usando C++ (Boost, HighFive), Python e padrões HDF5/NeXus.
• Garantia de Qualidade Automatizada: A integração de verificações dimensionais em tempo de compilação e testes de integração baseados em física no pipeline de CI reduz significativamente erros numéricos silenciosos.

4. Resultados e Demonstração

• Aplicação: O fluxo de trabalho foi aplicado ao framework monstr, que está em desenvolvimento ativo desde 2019 e suporta diversos tópicos de pesquisa (dinâmica de spin ultrafast, acoplamento elétron-fônon, interação laser-matéria).
• Rastreabilidade: O sistema gera com sucesso arquivos NeXus onde cada ponto de dados pode ser rastreado de volta ao commit específico do código-fonte, modificações locais, YAML de entrada e versão do script de análise usados para criá-lo.
• Reutilizabilidade: O formato NeXus padronizado permite que diferentes scripts de análise processem dados de diferentes modelos físicos sem modificação, desde que o esquema seja consistente.
• Publicação: Os autores já publicaram conjuntos de dados NeXus associados a estudos anteriores no Zenodo, demonstrando a viabilidade da etapa de publicação.

5. Significado

• Garantia de Qualidade Científica: O artigo argumenta que práticas de software sustentáveis (controle de versão, testes, registro estruturado) não são sobrecarga de engenharia opcional, mas componentes essenciais da garantia de qualidade científica na física numérica.
• Reprodutibilidade a Longo Prazo: A abordagem aborda especificamente o problema do "software de longa duração", garantindo que a pesquisa permaneça reprodutível apesar da rotatividade de pessoal e da evolução do software.
• Generalizabilidade: Embora demonstrado em C++ para física do estado sólido, a metodologia (Git, CI, HDF5/NeXus, análise versada) é agnóstica à linguagem e aplicável a outros campos científicos intensivos em dados, incluindo fluxos de trabalho experimentais.
• Mudança de Cultura: Os autores defendem uma mudança onde a rastreabilidade se torna parte da prática científica cotidiana, em vez de uma tarefa de registro retrospectivo, reduzindo finalmente os custos de pesquisa e aumentando a confiança nos resultados computacionais.