# AKMC

Adaptive kinetic Monte Carlo (AKMC) is an established method for simulating
kinetic evolution through transitions between states. The implementation
available through SODA uses EON-derived components and provides **core AKMC
functionality only**, primarily for **benchmarking and framework testing**.
Advanced features such as **basining (superbasin handling) are not implemented**.
These tutorials cover controlled example runs, execution checks, and
performance comparisons using SODA's parallel execution and data-collection
infrastructure.

For AKMC simulation runs, consult the [current EON documentation](https://eondocs.org/)
and its [AKMC guide](https://eondocs.org/user_guide/akmc).

Start with [installation](../install.md) and [SODA basics](concepts.md).

## Examples

Begin with the single-adatom EAM example. It uses the same small system as
the shared [run-preparation walkthrough](preparing.md).

| Example | What you will do | Requirements |
| --- | --- | --- |
| [First diffusion run with EAM](akmc-eam.md) | Run the lightweight Pd adatom benchmark with its supplied settings and check the expected 36 states and four processes per state. Also introduces the larger island example. | AKMC-enabled build, CPU cores, and the bundled Pd EAM potential. |
| [AKMC with GAP](akmc-gap.md) | Prepare the bundled Pd/O GAP model and run a short example with threaded CPU workers. | AKMC build with LAMMPS/QUIP and OPENMP support. |
| [AKMC with MACE](akmc-mace.md) | Configure native MACE forces for two oxygen atoms on Pd(110) and launch GPU workers. | Native MACE-enabled AKMC build, a compatible GPU/APU, and an external model file. |

Inputs live in `examples/akmc/`. Each walkthrough copies them into a separate
run directory so you can adapt the calculation without editing the examples.

```{tip}
Optimize your starting structure with the potential or model selected for
the run. Preserve its cell, periodic boundaries, and fixed atoms, and save
it as `pos.con` or `pos.xyz`. Re-optimize when changing the potential.
```

The EAM walkthrough retains the supplied 20,000 KMC steps. The more expensive
GAP and MACE walkthroughs start with a short setup check; each KMC step can
require multiple saddle searches before the confidence target is reached.

## Settings and analysis

- [AKMC settings](akmc-settings.md): concise explanations of confidence,
  thermal windows, searches, and SODA runtime options, including differences
  from native EON behavior.
- [Analyzing AKMC output](akmc-analysis.md): inspect states and processes,
  read the KMC transition history and simulated time, and export structures.

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

akmc-eam
akmc-gap
akmc-mace
akmc-settings
akmc-analysis
```

## References and project links

**AKMC method:** Xu, L., and Henkelman, G. “Adaptive kinetic Monte Carlo for
first-principles accelerated dynamics.” *The Journal of Chemical Physics* **129**(11), 114104
(2008). [doi:10.1063/1.2976010](https://doi.org/10.1063/1.2976010).

**EON software:** Chill, S. T., et al. “EON: software for long time simulations
of atomic scale systems.” *Modelling and Simulation in Materials Science and
Engineering* **22**(5), 055002 (2014).
[doi:10.1088/0965-0393/22/5/055002](https://doi.org/10.1088/0965-0393/22/5/055002).

**Source used by SODA:** [EON, SVN revision r2545](https://theory.cm.utexas.edu/svn/eon/?p=2545).
Use this archived revision when identifying the origin of SODA's EON-derived
components. The {repo}`provenance table <THIRD_PARTY_NOTICES.md#eon>` maps those
components to their upstream files.

When reporting AKMC calculations run through SODA, cite the AKMC method and
EON software alongside SODA's supporting infrastructure. See
[Citing SODA](../citations.md) for these references and those for the potential
or model used in your calculation.