# SODA basics

SODA provides a common computational foundation for independently developed
scientific workflows. It supplies parallel task execution, resource
coordination, and data collection. These pages explain how to use that
infrastructure to run workflows such as APE, EZGA, NEBScape, and AKMC.

Each workflow defines its scientific methods and exploration strategy, with
its own research contributions and references. SODA provides the shared
infrastructure that supports their execution.

Start with the [installation guide](../install.md) if you need a SODA build.

:::{admonition} Analyze an existing database
:class: tip

If you already have a results database and want to inspect it, go directly to
[Output analysis](analyzer.md).
:::

## How a calculation fits together

A **workflow** decides which calculations to perform and how their results
contribute to the exploration. It creates **tasks**, such as relaxing a
candidate structure or searching for a transition state. As results arrive,
the workflow can select more tasks.

A **potential** or trained model describes the atomic interactions. A
**calculator** provides the energies and forces used by the calculation. For
example, an EAM potential can be evaluated through LAMMPS, while a supported
machine-learning model may be evaluated through a LAMMPS or ASE interface.
The workflow and the calculator are separate choices, with compatibility
determined by the workflow integration and the installed build.

SODA distributes the tasks defined by the selected workflow among workers
using MPI and collects their results in HDF5. The workflow supplies the
scientific logic; the framework provides the execution and data-management
infrastructure.

| Term | Meaning in these tutorials |
| --- | --- |
| Run | One prepared calculation, with its own inputs, working directory, and outputs. |
| Workflow | The method that selects tasks and interprets their results. |
| Task | A unit of simulation work assigned to a worker. |
| Worker | An execution resource that performs tasks during the run. |
| Scheduler job | The CPU/GPU allocation requested from an HPC scheduler such as Slurm. |

One scheduler job can execute many workflow tasks through SODA. The `[Main] job` setting in
`config.ini` names the workflow; it does not describe the scheduler allocation.

## Choose the scientific workflow

The following methods and frameworks can be run through the available SODA
integrations. Their tutorial pages link to the original scientific work and,
where applicable, the independently maintained software projects.

| Workflow | What it explores | Starting point |
| --- | --- | --- |
| APE | Elementary processes and connected states, guided by local atomic environments. | [APE tutorial](ape.md) |
| EZGA | Candidate structures through evolutionary populations and generations. | [EZGA tutorial](ezga.md) |
| NEBScape | Surface-reaction structures, pathways, and transition-state barriers. | [NEBScape tutorial](nebscape.md) |
| AKMC | Kinetic evolution through transitions between states; the implementation available through SODA is preliminary and used primarily for benchmarking and framework testing. | [AKMC tutorial](akmc.md) |

Choose a potential appropriate for the elements and environments you want to
study. Then use the [installation selector](../install.md) to identify the
required software. Installing a calculator does not establish that its model
is suitable for a particular scientific system.

The SODA guides describe the supported EZGA and NEBScape integration paths.
When adapting inputs from their native frameworks, use the conversion and
configuration guidance linked from each workflow tutorial.

## Follow a run from inputs to results

| Page | What you will learn |
| --- | --- |
| [Preparing a run](preparing.md) | Select a build, create a run directory, configure the workflow, and check its inputs. |
| [Parallel execution](parallel.md) | Understand master/head/worker roles and choose a CPU/GPU launch layout. |
| [Monitoring and outputs](monitoring.md) | Follow progress, locate results, and open a database. |
| [Restarting a run](restart.md) | Resume a calculation from saved results and understand its recovery point. |

For the infrastructure design, see the SODA manuscript. For the scientific
methods, see each workflow's original publications. Both are listed in
[Citing SODA](../citations.md).

Continue with [Preparing a run](preparing.md).