# APE

```{image} ../../assets/ape_logo.png
:alt: Automatic process exploration (APE) logo
:width: 200px
:align: center
```

Automatic process exploration (APE) discovers elementary processes and
the states they connect on a potential-energy surface. The exploration is
guided by the diversity of local atomic environments.

The APE method is described in the original work cited below. These tutorials
cover running APE using SODA's parallel execution and data-collection
infrastructure.

Start with [installation](../install.md) and
[SODA basics](concepts.md) if you need a build or an introduction to the runtime.

## Examples

Follow an example using EAM or MACE to learn how to prepare and run an APE
calculation.

| Example | What you will do | Requirements |
| --- | --- | --- |
| [First exploration with EAM](ape-eam.md) | Prepare Pd surface inputs, run a short exploration, and inspect states, processes, and local environments. | APE-enabled build, CPU cores, and the bundled Pd EAM potential. |
| [Exploration with MACE](ape-mace.md) | Set up MACE forces and descriptors, select a GPU build, and reuse the analysis steps. | Native MACE-enabled APE build, a compatible GPU/APU, and external model files. |

Inputs live in the repository's `examples/ape/` directories. Each walkthrough
points to the files to copy into a separate run directory; edit those copies
for your calculation.

```{tip}
Before starting APE, optimize your input structures with the same potential
or model you will use for exploration. Use the optimized structures as
`pos.con` or `pos.xyz` (or the numbered `pos0`, `pos1`, … inputs), preserving
the intended cell, periodic boundaries, and fixed atoms. Re-optimize when
changing the potential.
```

More tutorials on choosing descriptors, tuning exploration, and interpreting
kinetic networks are coming soon.

## Settings and analysis

- [APE settings](ape-settings.md): short explanations of relevant `config.ini`
  entries and SODA command-line options.
- [Analyzing APE output](ape-analysis.md): read states and processes, export
  structures, and query the local environments used by the DECAF classifier.

```{toctree}
:maxdepth: 1
:hidden:

ape-eam
ape-mace
ape-settings
ape-analysis
```

## References

Lai, K. C., et al. “Automatic Process Exploration through Machine Learning
Assisted Transition State Searches.” *Physical Review Letters* **134**, 096201
(2025). [doi:10.1103/PhysRevLett.134.096201](https://doi.org/10.1103/PhysRevLett.134.096201).

Cite the APE work for the exploration method and SODA for the supporting
infrastructure used in the calculation. See [Citing SODA](../citations.md)
for the framework reference and references for the potential or model used.