Surface reactions with MACE¶

Run NEBScape on a slab and reaction list, then inspect the resulting pathways and barriers. This walkthrough uses the surface-reaction inputs 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:

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.

2. Prepare the calculator¶

The copied configuration selects:

[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:

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. 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 before changing sampling or convergence controls.

3. Check and launch¶

From the run directory, check the inputs:

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:

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.

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

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 to identify completed phases and pending bands. See Monitoring and outputs for common log and resource checks.

5. Inspect the results and continue¶

Use Analyzing NEBScape output 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 for tuning and Restarting a run to continue from a saved SODA database. Cite NEBScape, SODA, and the MACE model and software used in the calculation; see Citing SODA.