# 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 {repo}`Pd surface/EAM example <examples/ape/pd_surface_eam/README.md>` 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](../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/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](preparing.md#check-structures-and-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:

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

```bash
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](parallel.md).

For a Raven batch run, copy the repository template:

```bash
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](monitoring.md) 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](ape-analysis.md) 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](ape-settings.md) explains the
configuration and command-line options for sampling, descriptors, searches,
and runtime control. See [Restarting a run](restart.md) when
continuing from a saved database.

Continue with [Exploration with MACE](ape-mace.md) to change the force and
descriptor setup. Cite the [APE method](ape.md#references), SODA, and the
{repo}`bundled Pd EAM potential <examples/ape/pd_surface_eam/README.md#references>`
when reporting calculations based on this example.