Comment utiliser l'image Apptainer n2p2

Pour plus d’informations sur les conteneurs Apptainer et leur utilisation, nous mettons à votre disposition une description d’Apptainer, un guide rapide sur comment utiliser Apptainer, sans oublier bien sûr la documentation officielle d’Apptainer.

Fichiers d’entrée

Pour illustrer les différentes commandes, un ensemble de fichiers d’entrée pour n2p2 est disponible sous forme d’archive via ce lien.

L’archive contient les fichiers suivants destinés à l’entraînement d’un réseau de neurones pour le Cu2S et à la prédiction des énergies et des forces :

• train/input.nn : architecture du réseau de neurones et paramètres d’apprentissage,
• train/input.data : ensemble de données d’apprentissage contenant les configurations atomiques, les forces et les énergies pour le Cu2S,
• train/plot_histo.py : script Python permettant de visualiser les histogrammes des fonctions de symétrie issus de nnp-scaling,
• train/plot_learning_curve.py : script Python permettant de tracer la courbe d’apprentissage issue de nnp-train,
• predict/input.data : configurations d’entrée pour les prédictions d’énergie et de force.

Dans ce tutoriel, nous supposerons que les fichiers d’entrée contenus dans cette archive se trouvent dans le répertoire courant. Pour les extraire :

tar -xzf n2p2-tutorial-inputs.tar.gz

Pour plus d’informations sur les fichiers d’entrée et leur format, consulter la documentation relative à la procédure d’entraînement n2p2.

Guide de démarrage rapide

Pour les plus impatients, voici comment entraîner un réseau de neurones de potentiel pour le Cu2S, puis prédire les énergies et les forces sur une nouvelle configuration, dans le cas où le répertoire courant contient l’image n2p2.sif ainsi que tous les fichiers d’entrée nécessaires :

cd train
apptainer exec ../n2p2.sif mpirun -np 4 nnp-scaling 500
apptainer exec ../n2p2.sif mpirun -np 8 nnp-train
cp weights.016.000010.out ../predict/weights.016.data
cp weights.029.000010.out ../predict/weights.029.data
cp input.nn ../predict/
cp scaling.data ../predict/
cd ../predict
apptainer exec ../n2p2.sif nnp-predict 1

Utilisation détaillée du conteneur n2p2

Cette section présente un guide détaillé expliquant, étape par étape, comment utiliser l’image n2p2 pour entraîner un réseau de neurones pour le Cu2S et prédire les énergies et les forces. Pour plus de détails sur les commandes Apptainer, veuillez consulter ce tutoriel.

Introduction

n2p2 est une suite logicielle open source parallélisée via MPI, destinée à générer et à utiliser des potentiels d’énergie basés sur des réseaux de neurones pour la modélisation atomistique et moléculaire. Il permet d’entraîner des modèles sur des données issues de calculs ab initio, comme ceux provenant de la théorie de la fonctionnelle de la densité (DFT), afin de prédire avec précision les propriétés énergétiques et structurales des systèmes atomiques.

Les principaux exécutables contenus dans l’image sont les suivants :

• nnp-scaling : met à l’échelle les fonctions de symétrie pour l’ensemble de données d’apprentissage,
• nnp-train : entraîne un réseau de neurones,
• nnp-predict : prédit les énergies et les forces pour de nouvelles configurations.

Pour plus d’informations sur les outils présents dans l’image n2p2, consulter la documentation officielle.

Présentation du workflow

Le workflow pour l’entraînement et l’utilisation d’un réseau de neurones avec n2p2 comprend trois phases principales :

• Phase 1 : Mise à l’échelle des données (nnp-scaling)
• Phase 2 : Entraînement du réseau de neurones (nnp-train)
• Phase 3 : Prédiction (nnp-predict)

Les sections suivantes décrivent chaque phase en détail.

Phase 1 : Mise à l’échelle des données

La première étape de l’entraînement consiste à mettre à l’échelle les fonctions de symétrie de l’ensemble de données d’entraînement. Cette normalisation garantit que toutes les fonctions de symétrie ont des plages comparables, ce qui est essentiel pour un entraînement stable et efficace. Pour plus de détails sur le processus de mise à l’échelle, consulter la documentation nnp-scaling.

Cette phase nécessite deux fichiers d’entrée :

• input.nn : définit l’architecture du réseau de neurones et les fonctions de symétrie. Pour le Cu2S, ce fichier spécifie :

  • Éléments : S (soufre) et Cu (cuivre).
  • Fonctions de symétrie,
  • Architecture du réseau : 2 couches cachées de 15 nœuds chacune,
  • Paramètres d’apprentissage.

• input.data : contient l’ensemble des données d’apprentissage avec les configurations atomiques, les forces et les énergies pour le Cu2S. Chaque configuration est définie dans un bloc begin/end, comprenant :

  • Les vecteurs de réseau,
  • Les positions, les types d’atomes et les forces,
  • L’énergie totale et la charge pour chaque configuration.

La commande suivante exécute la phase de mise à l’échelle en parallèle sur 4 cœurs. Le paramètre 500 détermine le nombre de classes pour les histogrammes de la fonction de symétrie. La sortie de cette commande contient une estimation des besoins en mémoire de la phase d’entraînement à venir.

cd train
apptainer exec ../n2p2.sif mpirun -np 4 nnp-scaling 500

La commande nnp-scaling génère plusieurs fichiers de sortie, parmi lesquels :

• scaling.data : contient les paramètres de mise à l’échelle (minimum, maximum, moyenne et écart-type) pour chaque fonction de symétrie. Ces paramètres sont utilisés pour normaliser les fonctions de symétrie pendant l’apprentissage. Par exemple, les premières lignes du fichier scaling.data indiquent les paramètres de mise à l’échelle pour les fonctions de symétrie de l’élément S :

  #  e_index   sf_index   sf_min   sf_max   sf_mean   sf_sigma
  1          1   9,06E-06   1,05E-04   3,68E-05   1,78E-05
  1          2   9,74E-01   1,37E+00   1,14E+00   7,82E-02

• sf.*.histo : fichiers d’histogrammes pour chaque fonction de symétrie, montrant la distribution des valeurs de la fonction de symétrie dans l’ensemble de données. Par exemple, sf.016.0001.histo contient l’histogramme de la première fonction de symétrie de l’élément S.

• nnp-scaling.log.* : fichiers de logs pour chaque processus MPI, contenant des informations détaillées sur le processus de mise à l’échelle.

Le script plot_histo.py permet de visualiser les histogrammes des fonctions de symétrie :

python plot_histo.py

Ce script lit un fichier d’histogramme et génère un graphique à barres illustrant la distribution des valeurs de la fonction de symétrie (par exemple, sf.016.0064.histo contient l’histogramme de la fonction de symétrie 64 pour les atomes S). Le nom du fichier spécifié dans le fichier plot_histo.py peut être modifié pour visualiser un autre fichier de sortie histo.

Pour plus de détails sur l’interprétation des histogrammes et des paramètres de mise à l’échelle, consulter la documentation nnp-scaling.

Phase 2 : Entraînement du réseau de neurones

Une fois les fonctions de symétrie mises à l’échelle, l’étape suivante consiste à entraîner le réseau de neurones à l’aide de l’ensemble de données mis à l’échelle. L’outil nnp-train utilise l’architecture définie dans input.nn et les données mises à l’échelle pour optimiser les poids du réseau de neurones. Pour plus de détails sur le processus d’entraînement, consulter la documentation de nnp-train.

Cette phase nécessite les fichiers d’entrée suivants :

• input.nn : architecture du réseau de neurones et paramètres d’entraînement (identiques à ceux de la phase 1),

• input.data : ensemble de données d’apprentissage (identique à celui de la phase 1).

• scaling.data : paramètres de mise à l’échelle générés par nnp-scaling lors de la phase 1. Ce fichier est automatiquement lu par nnp-train pour normaliser les fonctions de symétrie.

La commande suivante permet d’entraîner le réseau de neurones en utilisant 8 processeurs en parallèle :

apptainer exec ../n2p2.sif mpirun -np 8 nnp-train

Cette commande prend généralement quelques minutes à s’exécuter, en fonction de la taille de l’ensemble de données et du nombre de processus MPI utilisés.

La commande nnp-train génère plusieurs fichiers de sortie, parmi lesquels :

• learning-curve.out : contient les données de la courbe d’apprentissage, y compris l’erreur quadratique moyenne (RMSE) pour les énergies et les forces, tant pour l’ensemble d’entraînement que pour l’ensemble de test, sur toutes les époques. Par exemple, les premières lignes du fichier learning-curve.out présentent les colonnes suivantes :

  # époque RMSEpa_Etrain_pu  RMSEpa_Etest_pu  RMSE_Ftrain_pu  RMSE_Ftest_pu
  0   8,06E-02   7,56E-02   5,21E-01   4,57E-01
  1   4,88E-03   1,63E-03   2,20E-01   2,44E-01
  2   1,82E-03   6,41E-04   1,35E-01   1,46E-01

  Ici, RMSEpa_Etrain_pu correspond à l’erreur quadratique moyenne (RMSE) des énergies d’entraînement par atome, et RMSE_Ftrain_pu à celle des forces d’entraînement. La courbe d’apprentissage montre comment les erreurs diminuent à chaque époque, ce qui indique l’amélioration du réseau de neurones.

• weights.*.data : fichiers de poids du réseau de neurones pour chaque époque. Par exemple, weights.016.000010.out contient les poids après la 10e époque. Ces fichiers sont utilisés pour restaurer le réseau de neurones en vue de prédictions ou d’un apprentissage ultérieur.

• timing.out : informations de chronométrage pour chaque époque.

Le script Python fourni plot_learning_curve.py permet de visualiser la courbe d’apprentissage :

python plot_learning_curve.py learning-curve.out

Ce script lit le fichier learning-curve.out et génère un graphique représentant l’erreur quadratique moyenne (RMSE) pour les énergies et les forces, tant pour l’ensemble d’entraînement que pour l’ensemble de test, sur l’ensemble des époques. La courbe d’apprentissage permet de suivre la progression de l’entraînement et d’identifier des problèmes tels que le sur-apprentissage ou une convergence lente.

Par exemple, la courbe d’apprentissage de ce tutoriel montre une diminution régulière de la RMSE tant pour les énergies que pour les forces, ce qui indique un fonctionnement correct de la phase d’entraînement :

• Époque 0 : RMSE énergie (entraînement) = 8,06E-02, RMSE force (entraînement) = 5,21E-01
• Époque 10 : RMSE énergie (entraînement) = 2,72E-04, RMSE force (entraînement) = 4,99E-02

Cela démontre que le réseau de neurones apprend à prédire avec précision à la fois les énergies et les forces du système Cu2S.

Pour plus de détails sur l’interprétation de la courbe d’apprentissage et des résultats de l’entraînement, consulter la documentation de nnp-train.

Phase 3 : Prédiction

Une fois le réseau de neurones entraîné, la dernière étape consiste à l’utiliser pour prédire les énergies et les forces associées à de nouvelles configurations. L’outil nnp-predict applique le potentiel entraîné aux configurations d’entrée et renvoie les valeurs prédites. Pour plus de détails sur le processus de prédiction, consulter la documentation de nnp-predict.

Cette phase nécessite les fichiers d’entrée suivants :

• input.nn : architecture du réseau de neurones (identique à celle des phases 1 et 2),

• weights.*.data : fichiers de poids du réseau de neurones pour chaque élément. Pour le Cu2S, cela comprend :

  • weights.016.data : poids pour l’élément S (soufre).
  • weights.029.data : poids pour l’élément Cu (cuivre). Ces fichiers sont générés par nnp-train et doivent être copiés depuis le répertoire d’entraînement. Pour ce tutoriel, nous utilisons les poids de la dernière époque (époque 10),

• scaling.data : paramètres de mise à l’échelle générés par nnp-scaling lors de la phase 1. Ce fichier est nécessaire pour normaliser les fonctions de symétrie lors de la prédiction,

• input.data : configurations d’entrée pour lesquelles les énergies et les forces seront prédites. Ce fichier contient des configurations atomiques au même format que les données d’entraînement.

La commande suivante permet de prédire les énergies et forces pour la configuration décrite dans le fichier input.data :

cd ../predict
cp ../train/weights.016.000010.out weights.016.data
cp ../train/weights.029.000010.out weights.029.data
cp ../train/input.nn .
cp ../train/scaling.data .
apptainer exec ../n2p2.sif nnp-predict 1

La commande nnp-predict génère plusieurs fichiers de sortie :

• energy.out : contient la comparaison entre les énergies prédites et les énergies de référence. Par exemple :

  # Ennp    Eref    Ediff    E_offset
  -5,73669358E+02  -5,73700369E+02  -3,10110046E-02   0,00000000E+00

  Ici, Ennp correspond à l’énergie prédite par le réseau de neurones, Eref à l’énergie de référence et Ediff à la différence entre les deux. Dans cet exemple, l’énergie prédite est de -573,669 eV, tandis que l’énergie de référence est de -573,700 eV, ce qui donne une différence de -0,031 eV,

• nnforces.out : contient la comparaison entre les forces prédites et les forces de référence pour chaque atome. Par exemple, les premières lignes de nnforces.out affichent :

  # fx     fy     fz     fxRef   fyRef   fzRef   fxDiff   fyDiff   fzDiff
  -1,26E-01  1,93E-02  5,72E-02  -1,25E-01  2,84E-02  3,12E-02  7,56E-04  9,13E-03  -2,60E-02

  Ici, fx, fy et fz sont les composantes de force prédites, tandis que fxRef, fyRef et fzRef sont les composantes de force de référence. Les différences (fxDiff, fyDiff, fzDiff) indiquent dans quelle mesure le potentiel du réseau de neurones reproduit fidèlement les forces de référence,

• output.data : contient la configuration d’entrée à laquelle ont été ajoutées les énergies et les forces prédites,

• structure.out : contient des informations détaillées sur la structure, notamment les positions atomiques et les forces prédites.

Pour plus de détails sur l’interprétation des résultats de prédiction, consulter la documentation de nnp-predict.

Pour aller plus loin

Pour plus d’informations, consulter la documentation n2p2 et la documentation spécifique à chaque outil :

• nnp-scaling
• nnp-train
• nnp-predict

Les commandes ci-dessus utilisent le mode parallèle « embarqué » d’Apptainer. Plus d’informations sur l’utilisation des conteneurs Apptainer en parallèle, y compris sur les clusters, sont disponibles sur cette page.