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 for signatures, parameters, and return values generated from the analyzer source. The analyzer operations guide 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:

export SODA_ROOT="$HOME/soda"

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

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:

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 analyzer setup reference.

3. Verify the setup¶

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:

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.

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 get_final_results(workflow=None, …) for a result bundle of NEBScape bands and separate optional Sella/IRC outputs, with their status records:

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 explains the outputs and queries for individual phases.

For EZGA, use get_latest_complete_commit(agent_id=None, stage_index=None, …) to select a saved generation and inspect its population and structures directly. The EZGA analysis tutorial 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 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. Use db.read_dynamics() for transitions actually taken; the AKMC analysis tutorial also shows visited state IDs and the full history with times and rates.