Preparing a run

A workflow run through SODA starts with a working directory containing config.ini and the inputs required by the selected method. Launch SODA from that directory so it can find the inputs and keep the resulting files together.

The shared walkthrough uses a single Pd adatom diffusing on a fixed Pd(100) surface with AKMC and an EAM potential. It has one input structure, a bundled potential, and runs on CPUs, making it a small example for learning the setup and checking the framework. Starting examples for the other workflows are listed below.

Select the installation

SODA_ROOT identifies your source checkout. A named build contains the executable and an activation script that restores its matching environment. Replace your-build with the name chosen during installation:

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

Use the activation script belonging to that build in both interactive shells and batch jobs. It supplies the matching dependencies, Python environment, and, on an HPC system, recorded module setup. The build must support the workflow and calculator selected for the run.

The run directory is separate from the installation. You can use the same build for several calculations, each with its own directory. Keep simultaneous runs in separate directories because they also create worker files under workspace/.

Start from an example

The examples index lists the supplied run setups and their model requirements. Choose an example for the method you want to run, using a build with the matching dependencies:

Workflow	Starting example	What it demonstrates and requires
APE	Pd surface / EAM	Exploration from several surface structures, guided by local atomic environments. Uses CPUs and a bundled EAM potential.
EZGA	FCC argon / Lennard–Jones	Relax a periodic FCC supercell and run one evolutionary generation with cell-strain mutations. Uses ASE on CPUs; no external model or GPU is needed.
NEBScape	Surface reactions	Surface-reaction exploration. The supplied configuration uses a GPU and the MACE-MH-1 model; prepare the checkpoint and NEBScape/MACE dependencies as described in its README.
AKMC	Single Pd adatom / EAM	Single-adatom diffusion on a fixed surface. Uses CPUs and a bundled EAM potential. This is the shared walkthrough’s starting example.

Each README lists the files to copy and the calculator setup. Follow the corresponding workflow tutorial for method-specific guidance. The AKMC example below is used as a small benchmark; the AKMC guide describes the scope of the implementation available through SODA.

Copy the single-adatom example

Choose a new run-directory name and copy the AKMC/EAM inputs:

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

The new directory initially contains:

pd-adatom-eam/
├── config.ini
├── pos.con
└── potfiles/
    ├── in.lammps
    └── Pd_u3.eam

The single-adatom example README explains the structure and potential setup. The copied directory contains the inputs needed for this CPU example; no external model download is required.

Understand the input files

Input	Purpose
config.ini	Selects the workflow to run through SODA and configures its settings.
Structure files	Supply atomic species, positions, cells, and constraints in the format expected by the workflow.
Potential/model files	Supply the interaction model used for energy and force evaluation.
Additional workflow inputs	May include reaction lists, native YAML settings, seed-structure JSON, or calculator modules.

APE and AKMC LAMMPS examples configure their potential in potfiles/in.lammps. NEBScape uses [ASE Calculator]; it currently also needs a potfiles/ directory for worker startup, even when no LAMMPS input is used. EZGA selects its simulator/calculator through the native YAML referenced by [EZGA] config_yaml.

Resolve input paths according to the example and the field’s documented meaning. SODA reads config.ini from the run directory, but some paths are used after files have been staged into worker workspaces. For example, the AKMC/EAM pair_coeff line names Pd_u3.eam within the staged potential files. Changing the shell’s working directory cannot fix every model-path error.

Check structures and conventions

Before changing an example to your own system, inspect the species, atom ordering, simulation cell, periodic boundaries, and constrained atoms. Use the units expected by the chosen calculator and the configuration field; consult the workflow guide when translating settings from another package.

For SODA XYZ inputs, ASE tags encode 1 for fixed atoms and 0 for mobile atoms. Native NEBScape XYZ uses the opposite fixed/mobile convention, while native EZGA/SAGE uses a separate fixed property. Use the documented structure converters when moving between formats, and inspect the converted constraints before running.

Prepare relaxed starting states for APE

For APE starting states, optimize the structures with the potential or model you will use for exploration, then use the optimized structures as pos.con or pos.xyz (or numbered inputs). Preserve the intended fixed atoms and cell conditions, and repeat the optimization when changing the potential.

Configure the workflow

Use the single-adatom example’s copied config.ini unchanged. This is a lightweight benchmark, so keep its supplied 20,000 KMC steps. The relevant entries are:

[Main]
temperature = 600
random_seed = 721

[AKMC]
max_kmc_steps = 20000

Retain the other example settings; this excerpt is not a complete input file. The expected diffusion network has 36 states and four processes per state. The KMC trajectory revisits these states over its 20,000 transitions. See the EAM walkthrough for the expected output.

The accepted workflow names are ape, ezga, nebscape, and akmc. The bundled AKMC input omits job, which already defaults to akmc; adding job = akmc is optional. Set job when selecting a different workflow.

INI settings describe the calculation, including workflow parameters, convergence criteria, and calculator settings. Command-line options describe runtime choices such as output location, restart input, and worker layout.

Look up available settings

Inspect the options supported by your executable with:

"$SODA_BIN" --help
"$SODA_BIN" --help-config

SODA initializes MPI even for these help commands. On systems requiring an allocation or a launcher for MPI programs, run them through the site’s normal launch procedure.

Validate the prepared directory

From the run directory, use the standalone analyzer’s file and configuration check:

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

The checker reports missing inputs and configuration problems it can detect without starting a simulation. Supplying the intended executable also enables binary checks where supported. --check returns a failing status for blocking problems. Full schema validation requires PyYAML; the report identifies any checks that were skipped.

The analyzer needs its Python dependencies; see Output analysis if they are missing. A successful input check should be followed by a small run using the intended calculator and hardware, since the checker does not execute force calls.

Continue with Parallel execution.