# Output analysis

Use `soda_analyzer` to inspect and postprocess workflow results collected in
HDF5 by SODA.
It also generates launch templates. Basic analysis requires Python, NumPy,
h5py, ASE, and `ruamel.yaml`; it does not require compiling SODA or installing
the simulation engines used for the calculation.

Use the standalone setup below, the workflow analysis tutorials, and the
[API reference](../api/index.rst) for signatures, parameters, and return values
generated from the analyzer source. The
{repo}`analyzer operations guide <docs/soda_analyzer.md>` provides additional recipes.

## Install the analyzer only

These steps use Bash, Git, and Python with `pip` and `venv`. On an HPC system,
load your site's Python module first. The analyzer is provided in the SODA
source checkout; you only need to install its Python dependencies.

If you already installed SODA with a generalized installer, the analyzer is
available after sourcing that installation's `build/<prefix>/modules.rc`.

### 1. Get the source

Set the location of your SODA checkout:

```bash
export SODA_ROOT="$HOME/soda"
```

If you already have a checkout, use its path above and skip the clone. Otherwise:

```bash
git clone https://gitlab.mpcdf.mpg.de/fhi-theory/soda.git "$SODA_ROOT"
```

No recursive clone or submodule installation is needed for the analyzer.

### 2. Create an analysis environment

The following creates a separate virtual environment in `venv/analyzer`:

```bash
python3 -m venv "$SODA_ROOT/venv/analyzer"
source "$SODA_ROOT/venv/analyzer/bin/activate"
python -m pip install numpy h5py ase 'ruamel.yaml>=0.18.6,<0.19'
export PYTHONPATH="$SODA_ROOT/src/python${PYTHONPATH:+:$PYTHONPATH}"
```

Keep the source checkout: the analyzer imports supporting modules from
`src/python`. Optional helpers may need additional packages, such as `PyYAML`
for full run-configuration validation; see the
{repo}`analyzer setup reference <docs/soda_analyzer.md#setup>`.

### 3. Verify the setup

```bash
python -c "import soda_analyzer; print(soda_analyzer.__file__)"
python -m soda_analyzer --help
```

The first command should print the path to `src/python/soda_analyzer.py` in your
checkout. The second lists the command-line helpers.

### 4. Use it in a new shell

Repeat the environment setup each time you open a new shell, using the same
checkout path:

```bash
export SODA_ROOT="$HOME/soda"
source "$SODA_ROOT/venv/analyzer/bin/activate"
export PYTHONPATH="$SODA_ROOT/src/python${PYTHONPATH:+:$PYTHONPATH}"
```

Run your analysis scripts with `python`. Use `deactivate` when finished.

## Open a results database

Replace the example path with your SODA output file. You can analyze a database
copied from another machine.

```python
import soda_analyzer as soda

db = soda.SodaLibrary(
    "/path/to/output.h5",
    workflow="auto",
    state_load=False,
    structure_load=False,
)
try:
    print("Workflow:", db.workflow)
    print("Database groups:", list(db.h5.keys()))
finally:
    db.close()
```

## Inspect workflow results

Use {tutorial-func}`soda_analyzer.soda_lib_class.get_final_results` for a result bundle
of NEBScape bands and separate optional Sella/IRC outputs, with their status
records:

```python
import soda_analyzer as soda

db = soda.SodaLibrary("output/output.h5", workflow="nebscape", state_load=False)
try:
    results = db.get_final_results()
    print("Recorded NEB results:", len(results["bands"]))
finally:
    db.close()
```

These are the available saved products; a partial run can have results too.
Check the status records before drawing conclusions. Keep the database open
while accessing returned views. For a mixed database, pass
`workflow="nebscape"` to `get_final_results()` explicitly. The
[NEBScape analysis tutorial](nebscape-analysis.md#results-at-each-phase)
explains the outputs and queries for individual phases.

For EZGA, use
{tutorial-func}`soda_analyzer.ezga_lib_class.get_latest_complete_commit`
to select a saved generation and inspect its population and structures directly.
The [EZGA analysis tutorial](ezga-analysis.md#inspect-the-latest-saved-generation)
shows how to select the latest or an earlier generation, exclude incomplete
writes, and inspect convergence separately. A complete save does not imply
that the search has converged.

For APE and AKMC, `db.state_list` holds the loaded state catalogue. APE's
`db.read_process_product_states()` reads its environment connection table;
[APE analysis](ape-analysis.md) also covers `db.environment_lib` and saved
search summaries. For AKMC, read resolved destinations from each state's
`process_table`, as shown in [catalogue connections](akmc-analysis.md#read-catalogue-connections).
Use `db.read_dynamics()` for transitions actually taken; the
[AKMC analysis tutorial](akmc-analysis.md) also shows visited state IDs and
the full history with times and rates.

## Further reading

For states, processes, and environment clusters, start with
[Analyzing APE output](ape-analysis.md). Other workflow results are covered by [EZGA](ezga.md),
and [NEBScape](nebscape.md). For benchmark results and framework checks, see
[Analyzing AKMC output](akmc-analysis.md).