# 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](akmc-eam.md).

The {repo}`repository example <examples/akmc/pd_oxygen_mace/README.md>` 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](../install.md). A Python-only MACE installation
does not provide the native LAMMPS force interface.

## 1. Prepare a separate run

```bash
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](preparing.md#check-structures-and-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:

```bash
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](https://mace-docs.readthedocs.io/en/latest/guide/lammps.html).
Model suitability for Pd/O surface chemistry needs separate validation.

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

```text
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.

```bash
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:

```bash
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](akmc-eam.md#4-follow-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](akmc-analysis.md) 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](akmc.md#references-and-project-links), SODA, MACE, and the
specific trained model used. [AKMC settings](akmc-settings.md) summarizes the
configuration and the current integration's limitations.