First exploration with EAM¶

Run a short APE exploration starting from Pd(100) surface structures, then inspect the states and elementary processes it records. This walkthrough uses the Pd surface/EAM example at examples/ape/pd_surface_eam/. The inputs and EAM potential are already in the repository.

Use an APE-enabled build that supports EAM. The local launch below needs three available physical CPU cores and Open MPI. No GPU or external model download is required. This initial run checks the setup and output; five collection cycles do not establish 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/ape/pd_surface_eam"
export SODA_RUN="$HOME/soda-runs/ape-pd-eam"
mkdir -p "$HOME/soda-runs"
mkdir "$SODA_RUN"
cp "$SODA_EXAMPLE/config.ini" "$SODA_EXAMPLE"/pos[012].con \
  "$SODA_EXAMPLE/SoftFixAtomIDs.dat" "$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.

The example provides three starting structures:

Input	Starting system
`pos0.con`	Pd(100) island plus one adatom.
`pos1.con`	Two adatoms on a Pd(100) slab.
`pos2.con`	One adatom on a Pd(100) slab.
`potfiles/in.lammps` and `Pd_u3.eam`	LAMMPS setup and Pd EAM potential.
`SoftFixAtomIDs.dat`	Selected atoms used to seed soft-fixed environment clusters.

Keep the structure names and atom ordering consistent with SoftFixAtomIDs.dat. Soft-fixed environment clusters are an APE sampling setting; fixed atoms in a structure are a separate constraint.

When substituting your own structures, relax them with the chosen potential first, then save the optimized coordinates as pos.con or pos.xyz, or as numbered inputs for several starting states. Preserve the intended fixed atoms and boundary conditions. See structure conventions before converting formats; use one input format in a run directory.

The supplied config.ini already selects APE and limits the run to five collection cycles with [APE] max_cycle = 5. Keep the example settings for this first run. The force potential is selected in potfiles/in.lammps.

2. 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 run the potential or prove that the starting geometry is relaxed.

For a local Open MPI run, use two workers and one combined head/master, with one physical CPU core per rank:

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 mapping and binding options assign one core to each rank. This example uses the plain EAM pair style, so no OpenMP settings are needed for its force calculation.

The node’s shared queue has four slots, contributed by its two workers. The node reports readiness after two local results, subject to the runtime’s early-collection conditions. Search summaries are saved for inspection. With the time condition disabled, regular writes occur after more than one collected job summary; reaching max_cycle also forces a final write. Run on allocated compute resources when using an HPC system; see Parallel execution.

For a Raven batch run, copy the repository template:

cp "$SODA_EXAMPLE/submitjob.raven" "$SODA_RUN/"

That template requests six nodes and 72 ranks per node and uses larger queues. Adapt both its #SBATCH directives and srun arguments before using it for a smaller run, including the per-node result threshold. Set --storesummariesinfile=1 if you want the same search-summary output as the local command. Edit SODA_ROOT and BUILD_NAME near the top of the copied script; it sources build/$BUILD_NAME/modules.rc and sets SODA_EXEC from that build. After reviewing its resource requests, submit with sbatch submitjob.raven. The template removes existing output/ data when starting a fresh run.

3. Follow progress¶

Watch the terminal or scheduler output and the files under output/logs/. Worker logs are named n<node>_w<worker>_<rank>; master records workflow progress. The calculation stores its database at output/output.h5 and temporary worker files under workspace/.

For this run, look for initial-state registration, completed searches, [SODA, CYCLE=...] progress, and eventually max_cycle reached followed by normal finalization. Some searches may be unsuccessful or rediscover a known process. A short run can finish without finding a new accepted process; inspect the search outcomes before increasing the cycle limit.

See Monitoring and outputs for interpreting logs and checking CPU placement. A completed cycle is an execution check, not evidence that all relevant processes have been discovered.

4. Inspect the results and continue¶

Use Analyzing APE output to read states and barriers, export a process as a trajectory, and inspect the local-environment clusters. The same analysis applies to EAM and MACE runs.

For a longer independent exploration, copy the inputs into a new directory and increase max_cycle. APE settings explains the configuration and command-line options for sampling, descriptors, searches, and runtime control. See Restarting a run when continuing from a saved database.

Continue with Exploration with MACE to change the force and descriptor setup. Cite the APE method, SODA, and the bundled Pd EAM potential when reporting calculations based on this example.