AKMC with MACE¶

Use native MACE forces for the AKMC example of two oxygen atoms on a Pd(110) slab. This walkthrough uses examples/akmc/pd_oxygen_mace/ and builds on First diffusion run with EAM.

The repository example supplies the structure and configuration. You must provide a compatible model for O and Pd and an AKMC build with native MACE support for your GPU or APU. Choose AKMC, MACE, and your hardware in the installation selector. A Python-only MACE installation does not provide the native LAMMPS force interface.

1. Prepare a separate run¶

export SODA_ROOT="$HOME/soda"
export SODA_BIN="$SODA_ROOT/build/your-mace-prefix/soda"
source "$SODA_ROOT/build/your-mace-prefix/modules.rc"

export SODA_EXAMPLE="$SODA_ROOT/examples/akmc/pd_oxygen_mace"
export SODA_RUN="$HOME/soda-runs/akmc-pd-oxygen-mace"
mkdir -p "$HOME/soda-runs"
mkdir "$SODA_RUN"
cp "$SODA_EXAMPLE/config.ini" "$SODA_EXAMPLE/pos.con" "$SODA_RUN/"
cp -R "$SODA_EXAMPLE/potfiles" "$SODA_RUN/"
cd "$SODA_RUN"

Use a new directory for a different potential. Optimize the starting structure with the selected MACE model, preserving its fixed atoms and cell, and use the optimized coordinates as the input. Follow the structure conventions when changing file formats or atom ordering.

2. Set the force-model path¶

The example uses pair_style mace, which needs a LibTorch export of the model. In the environment containing the matching MACE package, export it if needed:

python -m mace.cli.create_lammps_model /absolute/path/to/your.model \
  --format libtorch

This writes /absolute/path/to/your.model-lammps.pt. Select an appropriate head during export if the model has several heads; see the MACE LAMMPS guide. Model suitability for Pd/O surface chemistry needs separate validation.

Replace the placeholder pair_coeff path in potfiles/in.lammps:

pair_style mace no_domain_decomposition
pair_coeff * * /absolute/path/to/your.model-lammps.pt O Pd

Keep the other LAMMPS settings. The O Pd order matches this example’s atom types. Put the model on storage visible to every compute node.

Difference from the APE/MACE example: AKMC only needs the force-model path here. It does not use [Descriptors] mace_path, DECAF clusters, or a SoftFixAtomIDs.dat file to choose its search centers.

3. Set a short step limit and check¶

Add job = akmc to the existing [Main] section, and change the existing [AKMC] max_kmc_steps from 2000000 to 1. Keep the supplied temperature of 600 K, confidence = 0.99, and the remaining search settings. One step can still require many force and prefactor evaluations.

python "$SODA_ROOT/src/python/soda_analyzer.py" check-run-folder . \
  --soda-exe "$SODA_BIN" --check

Resolve blocking findings before launching. File checks do not establish that the model can load on the selected hardware.

4. Launch on a GPU allocation¶

For Open MPI on a workstation or an existing GPU allocation, start with one head/master and one GPU worker. Allocate two physical CPU cores and one compatible GPU:

export OMP_NUM_THREADS=1
export OMP_PLACES=cores
export OMP_PROC_BIND=close
export MKL_NUM_THREADS=1
export OPENBLAS_NUM_THREADS=1
mpirun -n 2 --map-by slot:PE=1 --bind-to core --report-bindings \
  "$SODA_BIN" \
  --num-gpu-workers-per-node=1 \
  --numjobsperwgroup=2 \
  --numjobsdonetotriggerupdate=2 \
  --storesummariesinfile=1 \
  --flushafterjobsdone=1 \
  --flushafterminutes=0

Keep lammps_threads unset or 0 for the native MACE GPU recipe, which does not enable the LAMMPS OPENMP package. When expanding this GPU-force setup, make every process-search worker GPU-capable.

For HPC runs, copy the appropriate submission template into the run directory. Edit SODA_ROOT and BUILD_NAME, review the allocation, and submit with sbatch.

Template	Supplied layout
`submitjob.raven`	One node, 17 ranks: one head and 16 GPU workers sharing four A100 GPUs.
`submitjob.viper`	Two nodes, six ranks per node: one head and five GPU workers sharing two MI300A APUs on each node.

These larger templates enable GPU sharing and disable stored search summaries; set --storesummariesinfile=1 to retain them as in the local command. Check model memory use before increasing the worker count. Adapt both scheduler directives and srun arguments, and review fresh-run output cleanup in the selected script.

5. Check and analyze the result¶

Follow AKMC progress. Check GPU assignment and [LAMMPS runtime] entries in worker logs as well as confidence and KMC step messages. A model or device error must be resolved before extending the run.

Analyzing AKMC output applies to MACE output using SodaLibrary(..., workflow="akmc"). Use 600 K when comparing example rates. Different potentials can change both the transition network and its rates; the oxygen system is also different from the EAM adatom benchmark.

Cite AKMC, EON, SODA, MACE, and the specific trained model used. AKMC settings summarizes the configuration and the current integration’s limitations.