# Surface reactions with MACE

Run NEBScape on a slab and reaction list, then inspect the resulting pathways
and barriers. This walkthrough uses the
{repo}`surface-reaction inputs <examples/nebscape/surface_reactions/>` at
`examples/nebscape/surface_reactions/` and the MACE-MH-1 ASE calculator.
NEBScape defines the reaction exploration; SODA distributes its tasks and
collects the results.

Use a NEBScape-enabled build with MACE Python dependencies and GPU support
matching your hardware. The local launch below needs three available
physical CPU cores and one compatible GPU/APU. The supplied five-reaction
example involves many relaxations and NEB calculations; it is not an
instant installation test or a demonstration of scientific convergence.

## 1. Select your build and copy the inputs

Replace `your-prefix` with the name chosen in the
[installation guide](../install.md):

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

export SODA_EXAMPLE="$SODA_ROOT/examples/nebscape/surface_reactions"
export SODA_RUN="$HOME/soda-runs/nebscape-mace"
mkdir -p "$HOME/soda-runs"
mkdir "$SODA_RUN"
cp "$SODA_EXAMPLE/config.ini" "$SODA_EXAMPLE/pos.xyz" \
  "$SODA_EXAMPLE/reactions_list.txt" "$SODA_RUN/"
cp -R "$SODA_EXAMPLE/potfiles" "$SODA_RUN/"
cd "$SODA_RUN"
```

Choose a new run-directory name if this one already exists. Keep the same
`SODA_ROOT` and build selection in subsequent shells and batch jobs.

| Input | Purpose |
| --- | --- |
| `config.ini` | Selects `job = nebscape`, search settings, and the ASE calculator. |
| `pos.xyz` | Starting slab with SODA's fixed/mobile atom tags. |
| `reactions_list.txt` | Five reaction SMILES entries to explore on the surface. |
| `potfiles/` | Directory required for common worker startup; this example keeps it empty apart from `.gitkeep`. |

The supplied `pos.xyz` is already prepared for SODA: tags `1` mean fixed
atoms and `0` mean mobile atoms. Native NEBScape XYZ uses the opposite
convention. Do not convert this supplied file a second time. When replacing
the slab, check its cell, periodic boundaries, and constraints; see
[structure conventions](preparing.md#check-structures-and-conventions).

## 2. Prepare the calculator

The copied configuration selects:

```ini
[ASE Calculator]
kind = mace_foundation
device = gpu
model = mh-1
kwargs_json = {"default_dtype": "float64", "head": "oc20_usemppbe"}
```

MACE downloads the MACE-MH-1 checkpoint when needed and reuses it from
`~/.cache/mace`. Populate that cache in the matching environment on a machine
with network access before submitting to offline compute nodes. The cache
must be accessible to the workers. Keep the model head and precision settings
consistent throughout a calculation.

For example, activate the chosen build on a machine with network access and
load the model once on its CPU to populate the cache:

```bash
python - <<'PY'
from mace.calculators import mace_mp

mace_mp(model="mh-1", device="cpu", default_dtype="float64",
        head="oc20_usemppbe")
PY
```

This downloads the checkpoint if it is missing. It prepares the cache;
the actual calculation still uses `device = gpu` from `config.ini`.

This example uses MACE's Python ASE calculator. Its model setup differs from
the native LAMMPS MACE files used in the [APE MACE example](ape-mace.md).
No `in.lammps` file is needed here. On AMD hardware, `device = gpu` also
applies, with a HIP-enabled SODA build and ROCm-enabled PyTorch environment.

The supplied `[NEBScape]` settings enable placement pre-relaxation and set
`totalsteps: 10` per minima-hopping start, counting the initial relaxation.
That limit does not bound the
number of subsequent geometry pairs or NEB steps. Keep the example settings
for the first run and consult [NEBScape settings](nebscape-settings.md)
before changing sampling or convergence controls.

## 3. Check and launch

From the run directory, check the inputs:

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

Resolve blocking findings before launching. The checker does not load the
force model or establish its suitability for the surface and reactions.

For a local Open MPI run, use one combined head/master, one CPU worker,
and one GPU worker, each assigned one physical CPU core:

```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 3 --map-by slot:PE=1 --bind-to core --report-bindings \
  "$SODA_BIN" \
  --num-gpu-workers-per-node=1 \
  --storesummariesinfile=1 \
  --flushafterjobsdone=1
```

The CPU worker supplies capacity for geometry preparation and interpolation;
the GPU worker handles jobs requiring the selected calculator. This layout
uses one worker per device. On an HPC system, launch within an allocation
using the site's MPI launcher; see [Parallel execution](parallel.md).

For a batch run, copy the template for your cluster:

```bash
cp "$SODA_EXAMPLE/submitjob.raven" "$SODA_RUN/"
cp "$SODA_EXAMPLE/submitjob.viper" "$SODA_RUN/"
```

| Template | Supplied allocation and worker layout |
| --- | --- |
| Raven | Three nodes, 72 ranks per node, four A100 GPUs per node; each node has one head, 59 CPU workers, and 12 GPU workers. |
| Viper | Two nodes, nine ranks per node, two MI300A APUs per node; each node has one head, four CPU workers, and four GPU workers. |

These templates share GPUs between workers using
`--allow_gpu_oversubscribe`. Review GPU memory needs before using that layout.
For a shared GPU, each worker limits its PyTorch allocator to `1 / N` of the
device's total memory, where `N` is the number of worker groups assigned to
that device. The limit is set before model loading and recorded as
`NEBScape CUDA memory limit` in the worker log. It stays fixed when other
workers become idle. Allocations beyond the limit raise an out-of-memory
error; CUDA contexts and allocations outside PyTorch are not covered.

Edit `SODA_ROOT` and `BUILD_NAME` in the chosen script, and adapt both its
`#SBATCH` directives and `srun` arguments to your allocation. Submit only
the chosen script, for example with `sbatch submitjob.raven`.

## 4. Follow progress

Watch the terminal or scheduler output and `output/logs/`. NEBScape proceeds
through placement preparation, minima hopping, endpoint selection and
alignment, interpolation, and NEB calculations. Different phases have
different CPU/GPU demands, so worker activity can change during the run.

Results are collected in `output/output.h5`, with temporary files under
`workspace/`. A selected candidate band is an input to NEB; it is not yet a
completed pathway result. Use the workflow-progress queries on the
[analysis page](nebscape-analysis.md#check-workflow-progress) to identify
completed phases and pending bands. See [Monitoring and outputs](monitoring.md)
for common log and resource checks.

## 5. Inspect the results and continue

Use [Analyzing NEBScape output](nebscape-analysis.md) to read accepted minima,
inspect forward and reverse barriers, and export final NEB images. Check the
recorded scientific outcome and inspect the pathway before interpreting a
barrier; completed execution alone does not establish NEB convergence.

For a different slab, reaction list, or calculator, prepare a new run
directory. Use [NEBScape settings](nebscape-settings.md) for tuning and
[Restarting a run](restart.md) to continue from a saved SODA database.
Cite [NEBScape](nebscape.md#references-and-project-links), SODA, and the
MACE model and software used in the calculation; see
[Citing SODA](../citations.md).