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

Questo articolo presenta un flusso di lavoro integrato e allineato ai principi FAIR che combina il controllo di versione, i test automatizzati, la registrazione strutturata e l'elaborazione post-standardizzata per stabilire una catena completa di provenienza dei dati che garantisca la riproducibilità dallo sviluppo del codice alle figure pubblicate nelle simulazioni di fisica numerica.

L'essenziale

Immagina di essere uno chef che ha passato anni a perfezionare una ricetta complessa per un piatto che cambia leggermente ogni volta che lo prepari. Un giorno, pubblichi una foto del piatto finale in un libro di cucina. Un anno dopo, qualcuno tenta di ricrearlo, ma non ci riesce. Perché? Perché non sa esattamente quale versione della ricetta hai usato, quale marca specifica di ingredienti avevi nella dispensa quel giorno, o se hai modificato la temperatura del forno durante la cottura.

Questo articolo, scritto da Markus Uehlein e il suo team, riguarda la soluzione di esattamente quel problema per gli scienziati che eseguono simulazioni al computer invece di cucinare pasti. Nel mondo della "fisica numerica" (l'uso di computer per modellare il comportamento dei materiali), le "ricette" sono codici software che vengono costantemente aggiornati, e i "piatti" sono enormi set di dati.

Ecco come gli autori propongono di mantenere tutto tracciabile, utilizzando un semplice flusso di lavoro in quattro fasi che chiamano Catena di Provenienza dei Dati.

1. Il Libro delle Ricette (Controllo Versioni e Revisione del Codice)

In passato, se uno scienziato modificava una riga di codice, poteva semplicemente salvarla come simulazione_finale_v2_reale_finale.cpp. Questo è un disastro culinario in attesa di accadere.

Gli autori utilizzano un sistema chiamato Git (pensalo come un libro delle ricette che viaggia nel tempo). Ogni volta che qualcuno modifica il codice, riceve un timestamp unico e una "revisione" da un collega prima di essere salvato. Questo garantisce che, se guardi una simulazione di cinque anni fa, tu possa vedere la versione esatta del codice utilizzata, fino alla specifica riga di testo. È come avere una foto delle mani dello chef e degli ingredienti esatti sul bancone nel momento in cui il piatto è stato preparato.

2. I Controlli di Sicurezza (Test Automatizzati)

Prima che una simulazione venga eseguita, il software esegue automatici "controlli di sicurezza".

• Controlli Unitari: Il codice verifica se la matematica ha senso dal punto di vista fisico. Ad esempio, non ti permetterà di aggiungere "metri" a "secondi" (non puoi aggiungere distanza al tempo!). Se ci provi, il computer ti ferma prima ancora che la simulazione inizi.
• Controlli Fisici: Il codice esegue piccole simulazioni di prova per assicurarsi che la fisica si comporti come dovrebbe (ad esempio, "Se riscaldo questo, l'energia aumenta?"). Se la risposta è no, il sistema sa che qualcosa è rotto.

3. Il Registratore "Scatola Nera" (Registrazione Strutturata e Metadati)

Quando la simulazione viene effettivamente eseguita, non si limita a sputare fuori un elenco di numeri. Crea un file gerarchico (una sofisticata struttura di cartelle digitali) che funge da registratore "scatola nera" su un aereo.

All'interno di questo file, gli scienziati archiviano:

• I dati grezzi (i risultati).
• Le impostazioni di input esatte (la ricetta).
• Il "registro di compilazione" (quale versione del codice è stata utilizzata).
• L'ambiente (che tipo di CPU del computer è stata utilizzata).
• Un diario dell'esecuzione (qualsiasi avviso o errore verificatosi durante la cottura).

Utilizzano un formato standard chiamato HDF5/NeXus. Pensalo come un contenitore universale che mantiene i dati organizzati in modo che, anche se lo scienziato originale dimentica cosa ha fatto, chiunque altro possa aprire la scatola e capire esattamente cosa è successo.

4. L'Impiattamento (Dai Dati alle Figure)

Infine, gli scienziati trasformano quei dati grezzi nei bei grafici e immagini che vedi in un articolo pubblicato. Di solito, questo passaggio è disordinato: gli scienziati potrebbero scrivere uno script una tantum per creare un grafico e poi cancellarlo.

In questo flusso di lavoro, anche il passaggio per creare l'immagine è sotto controllo versione. Lo script utilizzato per creare il grafico viene salvato, e il grafico stesso viene timbrato con un collegamento che lo riattacca ai dati grezzi e al codice utilizzati per crearlo.

Il Quadro Generale: La "Catena di Custodia"

Il punto principale di questo articolo è che questi quattro passaggi non dovrebbero essere isole separate. Devono formare una catena.

• Vecchio Metodo: Pubblichi un'immagine. Qualcuno chiede: "Come hai ottenuto questo?". Rispondi: "Ho eseguito una simulazione". Chiedono: "Quale?". Rispondi: "Credo fosse quella di martedì scorso". La riproducibilità fallisce.
• Nuovo Metodo (Il Metodo dell'Articolo): Pubblichi un'immagine. Fai clic su un collegamento e ti mostra la versione esatta del codice, il file di input esatto, il computer su cui è stata eseguita e lo script utilizzato per creare l'immagine. La riproducibilità riesce.

Gli autori hanno testato questo sul loro software di simulazione a lungo termine (chiamato monstr), che è stato utilizzato per molti studi nel corso di diversi anni. Hanno dimostrato che collegando codice, dati e figure insieme, hanno creato un sistema in cui chiunque può tracciare un risultato pubblicato fino allo stato originale del software, garantendo che le scoperte scientifiche rimangano affidabili e riutilizzabili a lungo termine.

In sintesi: Hanno costruito un sistema in cui ogni risultato scientifico viene fornito con la propria "scontrino" che prova esattamente come è stato realizzato, impedendo al problema "funziona sulla mia macchina" di distruggere la fiducia scientifica.

Sommario tecnico

1. Enunciazione del Problema

La fisica computazionale si basa sempre più su grandi dataset di simulazione generati da software che evolve nel corso di molti anni. Ciò crea sfide significative per la riproducibilità:

• Software di lunga durata: I framework di simulazione spesso sopravvivono al mandato dei singoli ricercatori, portando a molteplici contributori e cicli di sviluppo sovrapposti.
• Provenienza interrotta: La riproducibilità richiede più della semplice conservazione dei file di output; esige un collegamento esplicito e tracciabile tra specifiche versioni del codice, input di simulazione, configurazioni di runtime, passaggi di analisi e figure finali pubblicate.
• Costi della gestione dei dati: Una gestione dei dati inefficace porta a sprechi di sforzi di ricerca e a costi annuali di miliardi di euro (specificamente notati nel contesto dell'UE).
• Divario di conformità FAIR: Sebbene i principi FAIR (Findable, Accessible, Interoperable, Reusable) siano stabiliti, integrarli nell'intero ciclo di vita dello sviluppo software e della simulazione rimane una sfida pratica.

2. Metodologia

Gli autori propongono un flusso di lavoro integrato che collega lo sviluppo software, l'esecuzione della simulazione, l'archiviazione strutturata dei dati e l'elaborazione post-standardizzata. Questo flusso di lavoro è dimostrato utilizzando il framework di simulazione monstr (modular object-oriented nonequilibrium spin- and time-resolved relaxation), scritto in C++.

La metodologia è strutturata in quattro passaggi connessi:

A. Sviluppo Software e Provenienza dell'Eseguibile

• Controllo Versioni: Utilizza Git con un'istanza remota GitLab per lo sviluppo basato su branch, il tracciamento delle issue e le revisioni obbligatorie del codice.
• Cattura dello Stato dell'Eseguibile: Il sistema di build registra non solo l'identificatore del commit Git, ma anche le modifiche locali non committate del sorgente al momento della build. Ciò garantisce che lo stato esatto del sorgente utilizzato per generare l'eseguibile sia preservato.
• Registrazione dell'Ambiente: I metadati includono modelli CPU e configurazioni MPI per garantire che il contesto di esecuzione sia riproducibile.

B. Garanzie di Implementazione e Assicurazione della Qualità

• Analisi Dimensionale: Utilizza la libreria Boost.Units per l'analisi dimensionale a tempo di compilazione. Le grandezze fisiche vengono assegnate a tipi (ad es. Energy, Volume), permettendo al compilatore di rifiutare espressioni dimensionalmente incoerenti.
• Stabilità Numerica: Internamente, le simulazioni utilizzano unità atomiche (energia di Hartree, costante di Planck ridotta, ecc.) per minimizzare gli errori di arrotondamento in virgola mobile su ordini di grandezza, mantenendo unità SI per le interfacce di input/output.
• Test Automatici: Una pipeline GitLab CI esegue test automatici di unità e integrazione (utilizzando GoogleTest) ogni volta che il codice viene inviato. Questi test verificano la coerenza fisica (ad es. assicurando che l'energia interna degli elettroni aumenti monotonicamente con la temperatura).
• Documentazione: La documentazione (generata tramite Doxygen) viene ricostruita automaticamente per rimanere sincronizzata con la base di codice.

C. Input Validati e Registrazione Strutturata

• Validazione degli Input: I parametri di configurazione (modelli, materiali, solver) sono definiti in file YAML. Un database YAML separato e controllato per le versioni definisce i sistemi di materiale per garantire la coerenza, con validazione eseguita prima del lancio del calcolo.
• Diagnostica di Runtime: Le diagnostiche basate sulla fisica (ad es. conservazione del numero di particelle e dell'energia) sono monitorate durante l'esecuzione.
• Registrazione Strutturata: Utilizza la libreria spdlog per generare log con livelli di gravità (debug, info, warning, error). Questi log sono archiviati insieme ai risultati per fornire un contesto di esecuzione.

D. Archiviazione Gerarchica (HDF5/NeXus)

• Formato: I dati sono archiviati in file HDF5 (Hierarchical Data Format), aderendo allo standard NeXus.
• Struttura: I file contengono gruppi (contenitori) e dataset (dati numerici).
• Integrazione dei Metadati: La struttura del file include:
  • Risultati scientifici (vettori, matrici).
  • Metadati di esecuzione (commit Git, diff locali, configurazione CPU/MPI).
  • File di input (YAML) e log di runtime.
  • Attributi NeXus: Definisce le unità fisiche e le relazioni segnale/asse per la visualizzazione standardizzata.
• Interoperabilità: I file possono essere ispezionati tramite H5Web e processati tramite Python (nexusformat), garantendo l'accessibilità a lungo termine.

E. Elaborazione Post-Standardizzata e Pubblicazione

• Analisi Versionata: Una libreria Python separata e controllata per le versioni gestisce tutta l'elaborazione post e la generazione di figure. Ciò evita script ad hoc.
• Propagazione della Provenienza: Gli script di analisi estraggono identificatori (commit Git, hash del file di input) direttamente dall'output NeXus.
• Metadati delle Figure: Quando le figure vengono esportate, l'ID del commit della libreria di analisi e l'identificatore persistente del dataset sorgente sono incorporati nei metadati della figura.
• Pubblicazione dei Dati: I dataset grezzi sono pubblicati in repository (ad es. Zenodo, NOMAD) con Identificatori Persistenti (DOI), collegati direttamente al manoscritto.

3. Contributi Chiave

• Catena di Provenienza End-to-End: L'articolo dimostra un'implementazione pratica di una catena che collega Codice $\to$ Stato dell'Eseguibile $\to$ Input $\to$ Output $\to$ Analisi $\to$ Figura.
• Fedeltà dello Stato dell'Eseguibile: Catturando le modifiche locali al momento della build e i dettagli dell'ambiente, gli autori garantiscono che una simulazione possa essere ricostruita anche anni dopo, non solo per la versione del codice ma per lo stato esatto del sorgente.
• Integrazione FAIR nella Fisica: Il flusso di lavoro supera i principi FAIR teorici per un'implementazione ingegneristica concreta utilizzando C++ (Boost, HighFive), Python e standard HDF5/NeXus.
• Assicurazione della Qualità Automatizzata: L'integrazione di controlli dimensionali a tempo di compilazione e test di integrazione basati sulla fisica nella pipeline CI riduce significativamente gli errori numerici silenziosi.

4. Risultati e Dimostrazione

• Applicazione: Il flusso di lavoro è stato applicato al framework monstr, che è in sviluppo attivo dal 2019 e supporta diversi argomenti di ricerca (dinamica di spin ultrafast, accoppiamento elettrone-fonone, interazione laser-materia).
• Tracciabilità: Il sistema genera con successo file NeXus in cui ogni punto dati può essere tracciato fino al commit specifico del codice sorgente, alle modifiche locali, al file YAML di input e alla versione dello script di analisi utilizzati per crearlo.
• Riutilizzabilità: Il formato NeXus standardizzato consente a diversi script di analisi di elaborare dati da diversi modelli fisici senza modifiche, a condizione che lo schema sia coerente.
• Pubblicazione: Gli autori hanno già pubblicato dataset NeXus associati a studi precedenti su Zenodo, dimostrando la fattibilità del passaggio di pubblicazione.

5. Significato

• Assicurazione della Qualità Scientifica: L'articolo sostiene che le pratiche software sostenibili (controllo versioni, test, registrazione strutturata) non sono un onere ingegneristico opzionale ma componenti essenziali dell'assicurazione della qualità scientifica nella fisica numerica.
• Riproducibilità a Lungo Termine: L'approccio affronta specificamente il problema del "software di lunga durata", garantendo che la ricerca rimanga riproducibile nonostante il turnover del personale e l'evoluzione del software.
• Generalizzabilità: Sebbene dimostrato in C++ per la fisica dello stato solido, la metodologia (Git, CI, HDF5/NeXus, analisi versionata) è indipendente dal linguaggio e applicabile ad altri campi scientifici intensivi di dati, inclusi i flussi di lavoro sperimentali.
• Cambiamento Culturale: Gli autori sostengono un cambiamento in cui la tracciabilità diventa parte della pratica scientifica quotidiana piuttosto che un compito di registrazione retrospettiva, riducendo infine i costi di ricerca e aumentando la fiducia nei risultati computazionali.