La reproductibilité dans la chimie et la simulation des matériaux ne consiste pas seulement à stocker un script, à télécharger un ensemble de données ou à conserver un dossier de fichiers d’entrée. Un flux de travail est reproductible lorsqu’un autre chercheur peut comprendre comment une question scientifique est devenue un modèle, comment ce modèle est devenu un exécutable, comment l’exécution a produit des résultats et comment ces sorties sont devenues un résultat signalé.
Cette chaîne est facile à casser. Une dépendance modifiée, un paramètre de solveur non documenté, un fichier de sortie renommé ou une figure générée à partir d’une feuille de calcul modifiée manuellement peut rendre difficile une analyse par ailleurs précieuse. Le problème n’est pas toujours une mauvaise science. Souvent, il manque le contexte.
Pour les équipes de recherche de chimie et de matériaux informatiques, la documentation doit préserver plus que la réponse finale. Il doit préserver le raisonnement, la configuration, l’état d’exécution et le chemin d’interprétation qui ont rendu la réponse possible.
Ce que signifie réellement un flux de travail de simulation reproductible
Un flux de travail de simulation reproductible est le chemin documenté de l’intention scientifique au résultat interprétable. Il comprend le modèle, les entrées, l’état du logiciel, l’environnement d’exécution, les données générées, les étapes de post-traitement et le raisonnement utilisé pour connecter les sorties à une revendication.
Dans un contexte de chimie ou de matériaux, cela peut impliquer des structures moléculaires, des modèles de champ de phase, des hypothèses de réaction, des potentiels interatomiques, des conditions aux limites, des choix de maillage, des critères de convergence, des paramètres thermodynamiques ou des paramètres de solveur numérique. En pratique, les éléments exacts varient selon la méthode. Le principe ne le fait pas.
Un flux de travail reproductible devrait permettre à un futur lecteur de répondre à quatre questions :
- Qu’est-ce que la simulation essayait de tester ou de démontrer ?
- Quelles hypothèses et paramètres ont façonné le résultat ?
- Quel état de calcul exact a produit la sortie ?
- Comment les résultats ont-ils été transformés en interprétation rapportée ?
Sans ces réponses, un résultat peut toujours être intéressant, mais il est plus difficile de faire confiance, de comparer, d’étendre ou de déboguer.
La chaîne de documentation des revendications à exécuter
Le moyen le plus utile de documenter le travail de simulation est de commencer par la revendication que le flux de travail prend en charge et de remonter jusqu’à la course qui l’a produit. Cela évite un échec de documentation courant : préserver les fragments techniques sans montrer comment ils se connectent.
La chaîne de revendications à exécuter a cinq couches.
1. La couche de revendication
Cette couche enregistre la conclusion, la figure, la tendance, la comparaison ou la propriété que le flux de travail est censé prendre en charge. Il doit indiquer le résultat de la simulation utilisé pour argumenter, et non seulement le fichier généré.
Par exemple, un flux de travail peut prendre en charge une affirmation concernant le comportement de diffusion, la stabilité de phase, l’énergie de formation de défauts, les effets de solvant, l’évolution de la morphologie ou les performances relatives de deux configurations de modèle. La documentation doit rendre ce but visible.
2. Le calque du modèle
Cette couche explique la représentation scientifique et mathématique derrière la course. Il comprend des hypothèses, des équations régissant, des approximations, des limites de modèles, des paramètres sélectionnés et des simplifications connues.
Le but n’est pas d’écrire un manuel dans chaque dossier de projet. L’objectif est de laisser suffisamment de contexte pour qu’un autre membre de l’équipe puisse voir pourquoi ce modèle a été choisi et où ses limites commencent.
3. La couche d’exécution
Cette couche capture l’état de calcul de l’exécution : versions du logiciel, validations, dépendances, fichiers d’environnement, configuration des tâches, contexte matériel, graines aléatoires et journaux d’exécution.
Les détails d’exécution sont souvent traités comme un bruit administratif jusqu’à ce que quelque chose change. Ensuite, ils deviennent le seul moyen d’expliquer pourquoi une rediffusion diffère de l’original.
4. La couche de données
Cette couche préserve les sorties brutes, les sorties dérivées, les métadonnées, les conventions de nommage, les unités, les transformations et les relations de fichiers. Il doit être clair quels fichiers sont des produits de simulation directe et lesquels ont été créés par analyse ou filtrage.
5. La couche d’interprétation
Cette couche relie les sorties à l’interprétation scientifique finale. Il comprend des scripts d’analyse, du code de traçage, des exécutions exclues, des échecs, des décisions manuelles, des notes de problèmes et des étapes de génération de chiffres.
C’est là que de nombreux workflows perdent leur reproductibilité. La simulation peut être réexaminée, mais le chiffre ou la conclusion rapportés peuvent ne pas être traçables.
Quoi documenter avant la course
La documentation en pré-exécution doit expliquer pourquoi la simulation existe et quelles conditions définissent un résultat significatif. Ceci est particulièrement important lorsqu’un flux de travail sera réexaminé après un brouillon de papier, un changement de code, un commentaire d’examen par les pairs ou un transfert d’équipe.
Au minimum, les équipes doivent documenter la question de recherche, le système chimique ou des matériaux, l’approche de modélisation, les hypothèses formulées et les critères utilisés pour juger si la course a réussi.
Pour la recherche sur la chimie et les matériaux, cela signifie souvent enregistrer :
- Composition, structure, géométrie ou description de phase du système;
- hypothèses de modèles et simplifications connues ;
- conditions initiales et limites ;
- unités et sources de paramètres ;
- Paramètres de solveur, de discrétisation, de maillage ou de convergence ;
- Critères d’acceptation pour un résultat stable ou utilisable ;
- résultats attendus et comment ils seront interprétés.
Cette information n’a pas besoin d’être longue. Un fichier de lecture concise, une note d’exécution structurée ou un modèle de projet peut suffire s’il capture les décisions qui sont par ailleurs faciles à oublier.
Que capturer lors de l’exécution
La documentation d’exécution est la partie de la reproductibilité qui semble souvent routinière jusqu’à ce qu’elle soit manquante. Une simulation peut produire une sortie en apparence valide tout en masquant les avertissements, les changements de dépendance, les interruptions du planificateur, les chemins d’entrée modifiés ou le comportement de repli silencieux.
L’enregistrement d’exécution doit inclure l’état exact du logiciel utilisé pour l’exécution. Cela signifie que les numéros de version, le référentiel valident, le cas échéant, les fichiers de dépendance, les fichiers de configuration, les arguments de ligne de commande et les détails de l’environnement. Pour les systèmes HPC ou partagés, les paramètres du planificateur et l’allocation des ressources peuvent également avoir une importance.
Lorsque des résultats inattendus apparaissent, ces enregistrements font partie du processus de diagnostic. Les équipes qui traitent reproductibilité comme une aide de débogage pratique sont généralement mieux placées pour déterminer si un changement provenait du modèle, des données, du logiciel ou de l’environnement d’exécution.
Les journaux ne doivent pas être écartés trop rapidement. Les avertissements, les messages de convergence, les diagnostics de solveur, les erreurs d’exécution et le comportement de redémarrage peuvent expliquer pourquoi un résultat doit être approuvé, répété ou exclu.
Que conserver après la course
La documentation post-exécution doit rendre la voie de sortie visible. Un flux de travail reproductible ne s’arrête pas à la fin de la simulation. Cela se termine lorsque l’équipe peut montrer comment les sorties brutes sont devenues des données, des chiffres, des tableaux ou des revendications.
Conservez les sorties brutes séparément des sorties traitées. Gardez les scripts d’analyse à proximité des données qu’ils transforment. Enregistrer les unités, les filtres, les choix de lissage, les seuils et les cas exclus. Si une figure apparaît dans un rapport ou un manuscrit, le flux de travail doit indiquer quel exécution, script et ensemble de données l’ont produit.
Les courses ratées méritent également un record. Une simulation échouée peut expliquer pourquoi les paramètres ont changé, pourquoi un modèle a été réduit ou pourquoi un résultat a été réexécuté ultérieurement. Lorsque les anomalies ou les rediffusions affectent l’interprétation, cela aide à préserver la connexion entre la sortie et la décision de l’équipe qui a suivi, y compris Connexion des résultats de simulation à l’historique des problèmes derrière eux.
Test utile : Si un chiffre ne peut pas être régénéré à partir d’entrées, de scripts et de sorties documentées, le flux de travail n’est pas entièrement documenté même si l’image finale est enregistrée.
Une carte de documentation pratique
| Étape du flux de travail | Quoi documenter | Pourquoi c’est important | Enregistrement minimum acceptable |
|---|---|---|---|
| Cadre scientifique | Question, revendication, système, sortie attendue | Montre pourquoi la simulation a été exécutée | Note de projet courte ou section Lisez-moi |
| Configuration du modèle | Hypothèses, équations, paramètres, conditions aux limites | Rend la base scientifique inspectable | Note de modèle avec unités et sources de paramètres |
| Exécution | Version du logiciel, validation, dépendances, environnement, commande, journaux | Permet les rediffusions et le débogage | Fichier d’environnement, exécution de la commande, journaux enregistrés |
| Sorties | Fichiers bruts, fichiers dérivés, métadonnées, conventions de dénomination | Empêche la confusion entre les données originales et traitées | Manifeste de sortie avec descriptions de fichiers |
| Une analyse | Scripts, filtres, transformations, étapes de traçage | Connecter les données aux chiffres et conclusions | Script d’analyse et carte de la figure |
| Exceptions | Exécutions échouées, exclusions, avertissements, corrections manuelles | Explique les écarts et empêche les fausses certitudes | Note d’issue ou journal des écarts |
Les gestionnaires de flux de travail, les ordinateurs portables, les scripts et les travaux HPC nécessitent des enregistrements différents
Toutes les équipes de recherche n’ont pas besoin du même système de documentation. Un petit ordinateur portable exploratoire, un balayage de paramètres scriptés, un flux de travail conteneurisé et un pipeline HPC en plusieurs étapes présentent des risques de reproductibilité différents.
Pour les ordinateurs portables, le principal risque est l’état caché. Les cellules peuvent être exécutées dans le désordre, les variables intermédiaires peuvent rester en mémoire et les chiffres peuvent dépendre des étapes manuelles. La documentation doit clarifier l’ordre d’exécution, les données d’entrée, les versions des packages et l’état final du script ou du bloc-notes utilisé pour les résultats rapportés.
Pour les scripts ad hoc, le risque est un contexte dispersé. Une commande peut dépendre des chemins d’accès locaux, des valeurs par défaut non documentées ou des fichiers en dehors du contrôle de version. Les équipes doivent capturer des exemples de commandes, des fichiers de configuration, une structure de répertoires attendues et des emplacements de sortie.
Pour les gestionnaires de flux de travail, le risque est de supposer que l’automatisation est égale à la compréhension. La provenance automatisée est précieuse, mais une documentation lisible par l’homme est toujours nécessaire pour expliquer pourquoi un flux de travail a été configuré d’une certaine manière.
Pour les courses de HPC, le risque est la dérive environnementale. Les paramètres de file d’attente, les modules, les types de nœuds, les choix de parallélisation, le stockage temporaire et le comportement de redémarrage peuvent influer sur le fait qu’une exécution est vraiment reproductible sur un autre système.
Points faibles communs qui cassent la reproductibilité
La plupart des échecs de reproductibilité ne sont pas dramatiques. Ce sont de petits écarts qui s’aggravent avec le temps.
- Unités manquantes : Une valeur de paramètre est enregistrée, mais son unité ne l’est pas.
- Origine de paramètre incertaine : Une valeur s’affiche dans un fichier de configuration sans aucune explication quant à savoir s’il provient de la littérature, de l’étalonnage ou de la commodité.
- Dépendances modifiées : Un script s’exécute toujours, mais une mise à jour de la bibliothèque change de comportement.
- Modifications de fichiers manuels : Un jeu de données corrigé est utilisé, mais la correction n’est pas documentée.
- Chiffres détachés : Un graphique survit, mais les données et le script qui l’ont créé ne sont pas clairs.
- Circuits échoués invisibles : Il ne reste que des sorties réussies, masquant le chemin qui a conduit à des choix de paramètres finaux.
- Paramètres du solveur non documenté : Un résultat dépend des tolérances, de la résolution du maillage ou des critères de convergence qui ne sont pas enregistrés.
Ces points faibles sont importants parce qu’ils rendent l’interprétation ultérieure fragile. Un futur chercheur peut relancer le flux de travail et obtenir une réponse différente sans savoir si la différence est scientifique, numérique, environnementale ou procédurale.
Documentation minimale viable pour les équipes de recherche
Une équipe n’a pas besoin d’une infrastructure parfaite avant de pouvoir documenter de manière reproductible. Un enregistrement minimum viable est souvent suffisant pour éviter les pires pertes de contexte.
Pour de nombreux projets de chimie et de simulation de matériaux, la structure suivante est un point de départ réaliste :
- un Lisez-moi expliquant la question scientifique et la mise en page du flux de travail ;
- une note de modèle répertoriant les hypothèses, les paramètres, les unités et les critères d’acceptation ;
- un fichier d’environnement ou un enregistrement de dépendance ;
- un répertoire de fichiers d’entrée versionnés ;
- une commande d’exécution enregistrée ou une configuration de workflow ;
- journaux et avertissements d’exécution ;
- un manifeste de sortie qui distingue les fichiers bruts et traités ;
- scripts d’analyse utilisés pour générer des tableaux et des figures ;
- une figure cartographique reliant les visuels rapportés à des données et des scripts ;
- Un court journal des écarts pour les exécutions, les exclusions et les rediffusions.
Il ne s’agit pas de créer de la paperasse pour elle-même. Le but est de rendre le flux de travail compréhensible au moment où la mémoire n’est plus fiable.
La reproductibilité est la mémoire d’équipe
Les flux de travail de simulation survivent souvent à la personne qui les a construites en premier. Un chercheur diplômé part, une dépendance change, un examinateur demande des éclaircissements, un collaborateur interroge un chiffre ou une équipe décide d’étendre un ancien modèle à un nouveau système chimique.
Dans ces moments-là, la documentation devient la mémoire d’équipe. Cela explique non seulement ce qui a été exécuté, mais aussi pourquoi il a été exécuté de cette façon, ce qui a changé le long du chemin et comment le résultat final doit être interprété.
Les flux de travail reproductibles les plus solides n’archivent pas simplement les artefacts de calcul. Ils préservent la relation entre la revendication scientifique, le modèle, l’état exécutable, les données et l’interprétation. Cette relation est ce qui permet aux équipes de recherche sur la chimie et les matériaux de faire confiance à un résultat après que le contexte d’origine s’est estompé.