# Analyzing NEBScape output

Use `soda_analyzer` to follow reaction inputs through accepted minima,
endpoint pairs, candidate bands, and final NEB results. These examples apply
to the [MACE surface-reaction run](nebscape-mace.md).

Run the Python snippets after the calculation has finished or stopped, from
its run directory, with the matching SODA environment activated. For a
copied database, use the
[standalone analyzer setup](analyzer.md#install-the-analyzer-only) and
replace `output/output.h5` with its path. Reading stored structures and
barriers does not require loading the MACE model.

## What the database contains

| Item | Meaning |
| --- | --- |
| Reaction | A catalog entry derived from the reaction list, identified by `reaction_id`. |
| Structure | A placement, minimum, or endpoint-related structure with its role and parentage. |
| Geometry pair | Candidate initial and final geometries for a pathway. |
| Band | Interpolated images for one candidate pathway, including selection information. |
| NEB summary | A completed NEB task's scientific outcome and barrier data. |
| Workflow checkpoint | A record of phase progress used to interpret completion and restart. |

## Check workflow progress

Start with table counts and saved phases:

```python
import soda_analyzer as soda

db = soda.SodaLibrary("output/output.h5", workflow="nebscape")
try:
    neb = db.nebscape
    print("Table counts:", neb.get_table_counts())
    for checkpoint in neb.get_workflow_checkpoints():
        print("Phase:", checkpoint["phase_name"],
              "Status:", checkpoint["status_name"])
finally:
    db.close()

report = soda.summarize_nebscape_workflow_progress("output/output.h5")
resume = report["loadrun_resume"]
print("Last complete phase:", resume["last_complete_phase_name"])
print("Latest started phase:", resume["latest_started_phase_name"])
print("Partial NEB rows retained:", resume["partial_neb_rows_retained"])
```

A phase with some saved rows may still be incomplete. For a partial NEB
restart, SODA retains completed summaries and resumes selected bands that
still lack completed results. Use the
{repo}`workflow-progress reference <docs/soda_analyzer_nebscape.md#inspecting-workflow-progress-loadrun-and-partial-neb-rows>`
for pending-band counts and detailed diagnostics, and
[Restarting a run](restart.md) for launch instructions.

For a fresh run intentionally stopped with
[`nebscape_stop_after_phase`](nebscape-settings.md#stop-at-a-phase-boundary),
the last complete phase should match the target, with no later started phase
or uncheckpointed rows. A `final_interpolation` stop contains selected input
bands and images but no newly computed NEB/Sella results. Remove the option
and use ordinary `--loadrun` to continue. If the source already contained
historical partial downstream results, an earlier cutoff preserves them;
their presence alone does not mean the stopped invocation ran those jobs.
Check the run log alongside the database diagnostics.

## Read final NEB and refinement outputs

`neb.get_final_results()` collects each recorded NEB result together with its
optional Sella/IRC outputs. The same wrapper is available as
`db.get_final_results()` when the database workflow is NEBScape. Use
`reaction_id=...` or `band_id=...` to select a subset.

```python
from ase.io import write
import soda_analyzer as soda

db = soda.SodaLibrary("output/output.h5", workflow="nebscape")
try:
    results = db.get_final_results()
    if not results["bands"]:
        print("No NEB results have been recorded yet.")
    for result in results["bands"]:
        band_id = result["band_id"]
        summary = result["neb_summary"]
        print("Reaction:", result["reaction_id"], "Band:", band_id)
        print("  NEB outcome:", summary.scientific_outcome_name)
        print("  NEB barriers [eV]:", summary.forward_barrier,
              summary.reverse_barrier)
        images = [image.atoms for image in result["neb_images"]]
        if images:
            write(f"band{band_id}_neb.xyz", images, format="extxyz")

        info = result["sella_irc_info"]
        if info is not None:
            print("  Sella/IRC status:", info.status_name,
                  "IRC connected:", info.irc_connected)
        for kind, frames in result["sella_irc_frames"].items():
            if frames:
                write(f"band{band_id}_{kind}.xyz",
                      [frame.atoms for frame in frames], format="extxyz")
finally:
    db.close()
```

The bundle keeps **optimized NEB images**, **Sella refinement frames**, and
**forward/reverse IRC trajectories** separate. Sella refines a transition-state
candidate; it does not produce a replacement NEB band. The reported barriers
remain those of the NEB result. Frames retain `sella_restart` so separate
refinement attempts can be distinguished.

Inspect `scientific_outcome_name`, refinement `status_name`, and
`irc_connected` before selecting results for analysis. The wrapper includes
unsuccessful recorded outcomes and can return results from a partial run.
A missing refinement record gives `sella_irc_info=None`; missing trajectories
give empty lists. In particular, IRC may have run without saving its frames
unless `return_irc_traj=true` was configured.

Forward and reverse barriers refer to the initial and final NEB endpoints,
respectively. Several bands can represent the same reaction. For native-style
`NEB_climb.xyz`, `sella.xyz`, and `irc.xyz` files, use
{tutorial-func}`soda_analyzer.nebscape_lib_class.export_native_nebscape_format`.

:::{admonition} Distinguish interpolated candidates from NEB results
:class: tip

`get_band_image_atoms(band_id)` returns the candidate's interpolated input
images. `get_neb_result_images(band_id)` returns stored result-image objects;
use each object's `.atoms` for ASE export. Selecting a band for NEB does not
mean that its optimization has finished or converged.
:::

## Results at each phase

Function signatures show key arguments; `...` marks additional options in
the linked API reference.

These methods belong to `neb = db.nebscape`. Keep the database open while
loading structures and images. The summaries below come from the source
docstrings; follow a function link for its filters and return values.

### Placement preparation

Inspect the selected starting geometries and their preparation outcomes.

```{eval-rst}
.. tutorial-autosummary::

   ~soda_analyzer.nebscape_lib_class.get_initial_selected_structures
   ~soda_analyzer.nebscape_lib_class.get_prepare_summaries
```

### Minima hopping or optimization

Inspect both the recorded minima and the accepted history used for pairing.
The accepted-history helper defaults to active records accepted for pairing;
add `require_intact=True` and `require_converged=True` for those checks.

```{eval-rst}
.. tutorial-autosummary::

   ~soda_analyzer.nebscape_lib_class.get_minhop_result_structures
   ~soda_analyzer.nebscape_lib_class.get_accepted_minhop_structures
   ~soda_analyzer.nebscape_lib_class.get_minhop_summaries
   ~soda_analyzer.nebscape_lib_class.get_minhop_decision_records
```

### Endpoint pairing and band selection

Inspect endpoint pairs, retained or dropped candidates, and interpolation
images before NEB optimization. The lineage trace connects these to their
source minima.

```{eval-rst}
.. tutorial-autosummary::

   ~soda_analyzer.nebscape_lib_class.get_geometry_pairs
   ~soda_analyzer.nebscape_lib_class.get_selected_bands
   ~soda_analyzer.nebscape_lib_class.get_dropped_bands
   ~soda_analyzer.nebscape_lib_class.get_band_image_atoms
   ~soda_analyzer.nebscape_lib_class.get_band_metadata
   ~soda_analyzer.nebscape_lib_class.get_reaction_lineage_trace
```

### NEB optimization

Read optimized bands and their outcome and barrier records. Image views
provide `.atoms`, `.potential_energy`, and `.forces` for analysis.

```{eval-rst}
.. tutorial-autosummary::

   ~soda_analyzer.nebscape_lib_class.get_neb_summaries
   ~soda_analyzer.nebscape_lib_class.get_neb_result_images
```

### Optional Sella and IRC refinement

Read refinement status and connectivity separately from the saved frames.
Frame views expose `.atoms`, `.potential_energy`, and `.sella_restart`.

```{eval-rst}
.. tutorial-autosummary::

   ~soda_analyzer.nebscape_lib_class.read_neb_sella_irc_info
   ~soda_analyzer.nebscape_lib_class.get_neb_sella_irc_frames
```

### Collected final products and export

```{eval-rst}
.. tutorial-autosummary::

   ~soda_analyzer.nebscape_lib_class.get_final_results
   ~soda_analyzer.nebscape_lib_class.export_native_nebscape_format
```

Exports are for analysis; use the SODA database for restarting a run.
The {repo}`NEBScape analyzer reference <docs/soda_analyzer_nebscape.md>`
provides recipes for rejection histories, endpoint lineage, native-format
exports, and optional refinement results.

See the [generated API reference](../api/nebscape.rst) for full signatures,
parameters, and return values.