GNNPAL

GNNPAL contains analysis workflows for atomistic simulations with classical and graph neural network potentials.

This repository is part of Aluminum solidification and nanopolycrystal deformation via a Graph Neural Network Potential and Million-Atom Simulations by Ian Störmer and Julija Zavadlav.

Repository Layout

gnnpal/
  predictions/          Prediction workflows
    ase/                Prediction tasks that are bound to ASE
    lammps_scripts/     LAMMPS scripts used for property predictions
  simulations/          Simulation workflows
    lammps_scripts/     LAMMPS scripts used for simulations.
  training/             Scripts for training and refining GNNP-Al models
  external/             External git repositories.
    chemtrain/            Vendored training utilities (frozen, see below)
    chemutils/            Vendored chemistry utilities (frozen, see below)
pyproject.toml          Package metadata and dependencies

Data

Some relevant data is not included in this repository, but is stored on Zenodo. This includes:

• Potential files necessary for running simulations
• Datasets used for some property predictions
• Reference data for plotting
• Simulation results and property predictions resulting from running the provided scripts

On Zenodo you will find 5 folders. Each of them has a target destination in this repository with a corresponding README.md explaining the data.

Zenodo folder	Target directory
data	gnnpal/data
datasets	gnnpal/datasets
potentials	gnnpal/potentials
ref_data	gnnpal/predictions/ref_data
ase_models	gnnpal/predictions/ase/models

Installation

Clone this repository:

git clone <repo-url>
cd gnnpal

GNNPAL has two optional dependency groups that are mutually incompatible and must be installed in separate environments due to conflicting requirements (numpy, scipy, protobuf). Choose the environment(s) you need:

Training environment

For JAX-based training workflows based on chemtrain:

conda create -n gnnpal_train python=3.12
conda activate gnnpal_train
cd gnnpal/external/chemtrain && pip install -e . && cd ../../..
cd gnnpal/external/chemutils && pip install -e . && cd ../../..
pip install -e ".[train]"

Note that this environment is also necessary to run predictions/parity.py but not predictions/ase/parity.py due to the use of chemutils for loading the dataset.

Prediction environment

For ASE-based inference and analysis workflows, i.e., scaling tests and running UMA and ANI-Al models:

conda create -n gnnpal_predict python=3.12
conda activate gnnpal_predict
pip install -e ".[ase]"

Base installation

For the core workflows only, i.e., predictions and simulations (no training or ASE dependencies):

conda create -n gnnpal python=3.12
conda activate gnnpal
pip install -e .

Configuration

GNNPAL expects external LAMMPS executables and potential files to be available on your machine. Copy the example configuration files and replace the dummy paths with your local paths:

cp gnnpal/config.dummy.yaml gnnpal/config.local.yaml
cp gnnpal/activate_plugin.dummy.sh gnnpal/activate_plugin.local.sh

Usage

Run any of the following property predictions or simulations using

gnnpal-<task> (--<flag>)

The possible tasks and flags are explained below.

Tasks

• gnnpal-scaling: Speed and memory scaling with respect to system size.
• gnnpal-parity: Force and energy predictions of a reference dataset.
• gnnpal-sfe: Stacking fault energy of an FCC crystal.
• gnnpal-energy_volume: Energy per volume curves for different crystal structures.
• gnnpal-lattice_param: Lattice parameters over temperature.
• gnnpal-elasticity: Elasticity tensor over temperature.
• gnnpal-rdf: Radial distribution function at different temperatures.
• gnnpal-diffusion: Diffusion coefficient over temperature.
• gnnpal-melting_temp: Predicted melting temperature.
• gnnpal-quench: Solidification simulation.
• gnnpal-tensile: Deformation simulation.

Flags

You can add the following arguments and options:

• --models: one or more model names to run.
• --config_path: path to the YAML config file. Defaults to gnnpal/config.local.yaml.
• --num_cores: number of CPU cores for classical potential runs.
• --gpu: GPU ID for GNNP runs.
• --recompute: overwrite existing final result files.
• --recompute_full: overwrite intermediate per-displacement result files too.
• --debug: print more detailed log output.

The workflow writes intermediate results to the configured data directory and saves the final plot to the configured figures directory.

External Dependencies

The train environment depends on the chemtrain and chemutils modules (chemtrain, chemutils). Frozen snapshots are vendored in external/ and are not updated automatically.

Module	SHA
chemtrain	440095abecc91df117934594d81215e781da157a
chemutils	f3764b98bf87562e593927e879c7b00d57f71be3