First diffusion run with EAM¶

Run the lightweight AKMC example for one Pd adatom on a fixed Pd(100) surface, then inspect its states, processes, and KMC trajectory. This walkthrough uses the single-adatom example at examples/akmc/pd_adatom_eam/. The structure and EAM potential are already in the repository.

Use an AKMC-enabled build that supports EAM. The local launch needs three available physical CPU cores and Open MPI. No GPU or external model download is required. The expected diffusion network has 36 states with four processes from each state, making this a simple benchmark for the AKMC integration.

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/akmc/pd_adatom_eam"
export SODA_RUN="$HOME/soda-runs/akmc-pd-adatom-eam"
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"

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

Input	Used for
`pos.con`	Pd(100) slab and one mobile adatom; fixed-atom flags constrain the surface.
`config.ini`	Temperature, confidence, saddle searches, and structure comparison.
`potfiles/in.lammps`	LAMMPS force setup using `pair_style eam`.
`potfiles/Pd_u3.eam`	Bundled Pd potential, referenced by its relative filename in `in.lammps`.

When substituting your own structure, relax it with the chosen potential first. Preserve the cell, boundaries, and fixed atoms. Follow the structure conventions, and keep only the chosen input format in the run directory.

2. Review the supplied settings¶

Use the copied config.ini unchanged. This example is inexpensive, so keep the supplied 20,000 KMC steps. The relevant entries are:

[Main]
temperature = 600
random_seed = 721

[AKMC]
confidence = 0.95
confidence_scheme = new
thermally_accessible_window = 20.0
thermally_accessible_buffer = 2.0
max_kmc_steps = 20000

[Main] job defaults to akmc, so adding it is optional. Keep the remaining sections from the example. In particular, the under-coordinated displacement settings select search centers, and [Recycling] use_recycling = true enables reuse of predecessor searches. AKMC does not use APE’s SoftFixAtomIDs.dat or descriptor-cluster sampling.

The step limit counts KMC transitions, not saddle searches or collection cycles. The trajectory revisits the same 36 states, reusing their discovered processes. See AKMC settings when adapting the example.

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. This checks configuration and files; it does not run the potential or prove the structure is relaxed.

Use two workers and one combined head/master, with one CPU core per rank:

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=0 \
  --numjobsperwgroup=2 \
  --numjobsdonetotriggerupdate=2 \
  --storesummariesinfile=1 \
  --flushafterjobsdone=1 \
  --flushafterminutes=0

The small shared queue has four slots on this node. Collection can proceed after two local results, or earlier under the runtime’s queue and buffer conditions. The flush settings request writes after more than one collected job summary; a final write also occurs at the step limit.

If a local Open MPI 4.1 run fails in MPI_Win_create, use the documented window-backend workaround. Those MPI options go before "$SODA_BIN"; the SODA options go after it.

For Raven, copy the example’s submitjob.raven into the run directory. It requests one node with five ranks, giving four workers and one head. Edit SODA_ROOT and BUILD_NAME, review the resource requests and queue settings, then submit with sbatch submitjob.raven. The template removes existing output/ data when starting a fresh run. See Parallel execution for adapting allocations.

4. Follow progress¶

Look in the terminal or scheduler output and output/logs/master for Exploring state=, [STATE=..., CYCLE=...], confidence updates, and KMC step from state ... through process ... to state .... The run should write output/output.h5 and finalize after 20,000 transitions.

Worker logs are named n<node>_w<worker>_<rank>. Unsuccessful searches and rediscoveries can occur before confidence is reached. A discovered process is an available transition; it is not necessarily the transition selected by KMC. Monitoring and outputs explains the shared logs and temporary workspace/ files.

5. Inspect the results and continue¶

The fixed Pd(100) slab provides a predictable diffusion network:

Quantity	Expected result
States	36, corresponding to the adatom’s adsorption sites in the periodic surface cell.
Processes per state	4, corresponding to hops to neighboring sites in the four surface directions.
KMC transitions	20,000, as set by the supplied configuration; states and processes are visited repeatedly.

Use Analyzing AKMC output to check these counts, read barriers and prefactors, inspect the transition history, or export a reactant–saddle–product trajectory. A saved state with fewer than four processes has an incomplete process catalogue. The database records simulated time separately from wall-clock runtime.

The repository’s adatom validation script checks the state count and process geometry for this benchmark. Use Restarting a run to continue from a saved database.

Try the island example¶

The Pd island/EAM example uses a Pd(100) slab with a nanoisland and an adatom. Repeat the preparation in a new directory using examples/akmc/pd_island_eam/, keeping its own config.ini, pos.con, and potfiles/. Add job = akmc and reduce its max_kmc_steps = 2000000 to a short positive limit before launching.

This example has more possible atomic rearrangements and need not finish a step as quickly as the fixed-surface benchmark. Review its own batch script before submission; it does not use the adatom example’s small allocation.

Continue with GAP or MACE to change the force model and worker setup. Cite the AKMC and EON references, SODA, and the Pd EAM potential reference when reporting this example.