# SODA documentation **Scalable Orchestration and Data Aggregation** SODA is an MPI-based infrastructure framework that supports independently developed scientific workflows. It provides parallel task execution, resource coordination, and data aggregation across CPUs and GPUs, collecting results incrementally in HDF5. Workflows such as APE, EZGA, NEBScape, and AKMC define the scientific methods for exploring atomic structures, elementary processes, and reaction pathways. SODA provides a common foundation for executing their tasks and collecting their results. Simulation engines such as LAMMPS and workflow-specific calculators evaluate energies and forces. Choose a workflow and an interatomic potential suited to your scientific problem, and refer to each method's original work for its scientific foundations. :::{admonition} More tutorials will be added :class: note Suggestions for tutorial topics and examples are welcome. See the [contact details below](#project-links). ::: ## Start here ::::{container} start-cards :::{container} start-card ### [Install SODA](install.md) Select your workflows, potentials, and Linux workstation or HPC environment to generate installation steps. ::: :::{container} start-card ### [Analyze results](tutorials/analyzer.md) Inspect HDF5 output with `soda_analyzer` and export structures for further analysis. No SODA compilation is needed. ::: :::: Read [SODA basics](tutorials/concepts.md) for run preparation, parallel execution, outputs, and restarts. The {repo}`examples index ` provides starting points for every workflow. ## Choose a workflow The available integrations support the following methods and frameworks. Each has its own scientific references, linked below. | Your goal | Workflow and starting example | | --- | --- | | Discover elementary processes and the states they connect on a potential-energy surface. | **APE — automatic process exploration** ([Lai et al., 2025](https://doi.org/10.1103/PhysRevLett.134.096201)). Start with the {repo}`Pd surface/EAM example ` and the [APE guide](tutorials/ape.md). | | Explore candidate structures through evolutionary search over populations and generations. | **EZGA** ([Lombardi et al., 2026](https://doi.org/10.1016/j.cpc.2026.110354)). Start with [FCC argon with Lennard–Jones](tutorials/ezga-fcc.md) and the [EZGA guide](tutorials/ezga.md). | | Explore surface-reaction pathways and transition-state barriers. | **NEBScape** ([Jung et al., 2026](https://doi.org/10.1038/s41524-026-02298-1)). Start with the {repo}`surface-reactions example ` and the [NEBScape guide](tutorials/nebscape.md). | | **Benchmarking and testing:** compare performance and check the framework with controlled simulation runs. | **AKMC — adaptive kinetic Monte Carlo** ([Xu and Henkelman, 2008](https://doi.org/10.1063/1.2976010)). Follow the [AKMC benchmarking and testing guide](tutorials/akmc.md), starting with [First diffusion run with EAM](tutorials/akmc-eam.md). The implementation is preliminary. | The potential supplies the energies and forces for the selected workflow. Examples cover classical EAM, GAP, MACE, and supported ASE calculators. The [installation selector](install.md) shows the available combinations; an example's README identifies any model files you need to provide. ## How it works ```{raw} html
  1. Starting structuresAtomic configurations and potential or model files
  2. Choose a workflowAPE, EZGA, NEBScape, or AKMC
  3. Parallel calculationsSimulation tasks on CPUs and GPUs
  4. Collected resultsStructures, energies, and workflow records in HDF5
  5. AnalysisInspect and export results with soda_analyzer
A scientific workflow run using SODA's execution and data-collection infrastructure.
``` The selected workflow determines new tasks as results arrive. SODA coordinates their execution through MPI, including multicore CPU or GPU work within individual tasks when supported by the chosen calculator. Results are written to `output/output.h5` by default; logs and temporary worker files are stored separately. See the {repo}`run setup instructions ` and {repo}`analyzer guide ` for the input and output details. ## Project status The {repo}`repository README ` documents the current version as **0.0.6**. The available integrations support running APE, EZGA, and NEBScape through SODA. A preliminary AKMC implementation is also available, primarily for benchmarking and framework testing. The EZGA and NEBScape integrations support the configuration and execution paths documented in the SODA guides. Consult the {repo}`workflow setup instructions ` for integration coverage when adapting a calculation from either framework's native software. The installation and reference pages are available here. The workflow tutorials are still being expanded and link to the existing repository guides and examples. ## Project links - [Source repository](https://gitlab.mpcdf.mpg.de/fhi-theory/soda) and [issue tracker](https://gitlab.mpcdf.mpg.de/fhi-theory/soda/-/issues) for bug reports and feature requests. The issue tracker requires an MPCDF GitLab account. You can also contact the developer at [king.lai@mpcdf.mpg.de](mailto:king.lai@mpcdf.mpg.de) for help, bug reports, feature requests, or tutorial suggestions. - [Citation guide](citations.md): cite SODA, the workflow, and the potential or model used in your publication. - [SODA preprint](https://doi.org/10.26434/chemrxiv.15008845/v1): “A scalable framework for goal-driven task-based simulations,” *ChemRxiv*, 15 September 2026. - {repo}`MIT license for SODA's original code ` and [third-party notices](third_party_notices.md) for incorporated code and dependency licenses. ```{toctree} :maxdepth: 2 :caption: Getting started :hidden: install tutorials/analyzer ``` ```{toctree} :maxdepth: 1 :caption: SODA basics :hidden: Overview tutorials/preparing tutorials/parallel tutorials/monitoring tutorials/restart ``` ```{toctree} :maxdepth: 2 :caption: Workflows :hidden: tutorials/ape tutorials/ezga tutorials/nebscape tutorials/akmc ``` ```{toctree} :maxdepth: 2 :caption: Reference :hidden: api/index citations third_party_notices ```