# AKMC with GAP

Run the AKMC example of two oxygen atoms on a Pd(110) slab with the bundled
GAP model. This walkthrough uses the
{repo}`Pd/O GAP example <examples/akmc/pd_oxygen_gap/README.md>` at
`examples/akmc/pd_oxygen_gap/` and follows the preparation and monitoring
pattern of [First diffusion run with EAM](akmc-eam.md).

Choose **AKMC**, **GAP**, and **CPU** in the
[installation selector](../install.md). The threaded setup below requires
LAMMPS built with QUIP and its OPENMP package, as provided by the matching
installation recipe.

## 1. Copy and unpack the inputs

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

export SODA_EXAMPLE="$SODA_ROOT/examples/akmc/pd_oxygen_gap"
export SODA_RUN="$HOME/soda-runs/akmc-pd-oxygen-gap"
mkdir -p "$HOME/soda-runs"
mkdir "$SODA_RUN"
cp "$SODA_EXAMPLE/config.ini" "$SODA_EXAMPLE/pos.con" \
  "$SODA_EXAMPLE/GAP_model.tar.bz2" "$SODA_EXAMPLE/decompress.sh" "$SODA_RUN/"
cd "$SODA_RUN"
bash ./decompress.sh
```

Use a new run-directory name if this one already exists. The script unpacks
`GAP_model/` and creates `potfiles/in.lammps` with an absolute path to
`GAP_model/GAP_0.xml`. Keep the complete model directory, including its
auxiliary files, on storage accessible to every node. If you move the run,
update that path before launching.

The generated LAMMPS input uses `pair_style quip`; the atomic numbers `8 46`
map its atom types to O and Pd. Preserve that mapping when adapting inputs.
Optimize replacement structures with the selected GAP model first, keeping
the intended cell, fixed atoms, and
[input-format conventions](preparing.md#check-structures-and-conventions).

## 2. Match settings to a small CPU run

Add `job = akmc` to the existing `[Main]` section and set the existing
`[AKMC] max_kmc_steps` to `1` for the first check (the supplied value is `2`).
Keep the example's temperature of 600 K and `confidence = 0.99`.

For the local command below, change the existing potential entry from nine
threads to three:

```ini
[Potential]
lammps_threads = 3
```

A positive `lammps_threads` overrides the thread count passed to LAMMPS via
`OMP_NUM_THREADS`. Match both to the CPU cores allocated per rank; setting
threads does not allocate cores. See
[threaded workers](parallel.md#match-worker-threads-to-cpu-cores).

## 3. Check and launch

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

After resolving blocking findings, use the following Open MPI command on
a machine or allocation with **nine available physical CPU cores**. It
assigns three cores to each of two workers and one head/master:

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

For Raven, copy `submitjob.raven` from the example directory. It requests
**three nodes with eight ranks per node and nine cores per rank**. Restore
`lammps_threads = 9` if using that allocation, or adjust the INI entry,
Slurm directives, and `srun` arguments together for a smaller run. Edit
`SODA_ROOT` and `BUILD_NAME` before submitting with `sbatch`.
The template removes existing `output/` data and disables search summaries;
set `--storesummariesinfile=1` to retain them.

## 4. Inspect the result

Follow [AKMC progress](akmc-eam.md#4-follow-progress) and check
`[LAMMPS runtime]` measurements after the first force evaluation. Confirm
that the model loads and that the CPU placement and thread count agree.
A one-step run can still take many searches; it is not a performance or
kinetics convergence result.

Use [Analyzing AKMC output](akmc-analysis.md) for states, process barriers,
the transition history, and structure exports. The
[settings reference](akmc-settings.md) explains confidence and thermal windows.
Cite [AKMC and EON](akmc.md#references-and-project-links), SODA, and the
{repo}`GAP model publication <examples/akmc/pd_oxygen_gap/README.md#references>`
when reporting calculations based on this example.