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.

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 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:

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 workflow-progress reference for pending-band counts and detailed diagnostics, and Restarting a run for launch instructions.

For a fresh run intentionally stopped with nebscape_stop_after_phase, 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.

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 export_native_nebscape_format(path=’native_nebscape_format’).

Distinguish interpolated candidates from NEB results

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.

get_initial_selected_structures(reaction_id=None, ...)	Return selected placement structures used as MinHop inputs.
get_prepare_summaries(target_kind=None, target_id=None)	Return placement preparation 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.

get_minhop_result_structures(reaction_id=None, ...)	Return all stored MinHop result structures, including rejected candidates.
get_accepted_minhop_structures(reaction_id=None, ...)	Return raw accepted-history structures for hopping audits.
get_minhop_summaries(parent_structure_id=None, ...)	Return MinHop job summaries.
get_minhop_decision_records(**criteria)	Return MinHop decisions with candidate and duplicate structure links.

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.

get_geometry_pairs(reaction_id=None, ...)	Return geometry pairs matching the requested reaction, mapping, or job.
get_selected_bands(reaction_id=None, ...)	Return bands retained for NEB evaluation.
get_dropped_bands(reaction_id=None, ...)	Return bands dropped during interpolation selection.
get_band_image_atoms(band_id)	Return interpolated band input images as ASE structures.
get_band_metadata(band_id, ...)	Return band endpoints, ancestry, and optional NEB outcome metadata.
get_reaction_lineage_trace(reaction_id, ...)	Trace structures, geometry pairs, and bands belonging to one reaction.

NEB optimization

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

get_neb_summaries(reaction_id=None, ...)	Return recorded NEB summaries for matching bands.
get_neb_result_images(band_id)	Return optimized NEB images, before optional Sella/IRC refinement.

Optional Sella and IRC refinement

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

read_neb_sella_irc_info(band_id)	Read one Sella/IRC summary by its stored identifier.
get_neb_sella_irc_frames(band_id)	Return saved Sella refinement and forward/reverse IRC trajectories.

Collected final products and export

get_final_results(reaction_id=None, band_id=None)	Collect NEB results with their optional Sella/IRC refinement outputs.
export_native_nebscape_format(path='native_nebscape_format')	Export recorded results as a native-style NEBScape analysis folder.

Exports are for analysis; use the SODA database for restarting a run. The NEBScape analyzer reference provides recipes for rejection histories, endpoint lineage, native-format exports, and optional refinement results.

See the generated API reference for full signatures, parameters, and return values.