nebcert 1.2.0__py3-none-any.whl

nebcert/__init__.py

@@ -0,0 +1,28 @@
+"""
+NEBCert: quality checks for NEB reaction paths, transition states and
+tunnelling-corrected rate constants.
+"""
+
+__version__ = "1.2.0"
+__author__ = "Andres Monreal-Hernández"
+__license__ = "MIT"
+
+from nebcert.core.neb_profile import calculate_neb_profile_analysis, NEBProfileResult
+from nebcert.core.ts_frequency import verify_ts_frequency_and_irc, TSFrequencyResult
+from nebcert.core.tst_kinetics import calculate_eyring_tst_rates, TSTKineticsResult
+from nebcert.core.tunneling import calculate_quantum_tunneling_corrections, TunnelingResult
+from nebcert.core.scoring import assess_reaction_pathway_quality, ReactionPathwayReport
+
+__all__ = [
+    "__version__",
+    "calculate_neb_profile_analysis",
+    "NEBProfileResult",
+    "verify_ts_frequency_and_irc",
+    "TSFrequencyResult",
+    "calculate_eyring_tst_rates",
+    "TSTKineticsResult",
+    "calculate_quantum_tunneling_corrections",
+    "TunnelingResult",
+    "assess_reaction_pathway_quality",
+    "ReactionPathwayReport"
+]

nebcert/citation.py

@@ -0,0 +1,22 @@
+"""
+Citation strings for NEBCert (concept DOI: resolves to the latest version on Zenodo).
+"""
+
+from nebcert import __version__
+
+CONCEPT_DOI = "10.5281/zenodo.22217586"
+TITLE = "NEBCert: quality checks for NEB paths, transition states and tunnelling-corrected rate constants"
+
+BIBTEX = (
+    "@software{monreal2026nebcert,\n"
+    "  author = {Monreal-Hern{\\'a}ndez, Andr{\\'e}s},\n"
+    f"  title = {{{{{TITLE}}}}},\n"
+    "  year = {2026},\n"
+    f"  version = {{{__version__}}},\n"
+    "  publisher = {Zenodo},\n"
+    f"  doi = {{{CONCEPT_DOI}}},\n"
+    "  url = {https://github.com/sircalch/nebcert}\n"
+    "}\n"
+)
+
+APA = f"Monreal-Hernández, A. (2026). {TITLE} (v{__version__}). Zenodo. https://doi.org/{CONCEPT_DOI}"

nebcert/cli.py

@@ -0,0 +1,323 @@
+"""
+Command Line Interface (CLI) for NEBCert.
+"""
+
+import sys
+import os
+import argparse
+import numpy as np
+
+from nebcert import __version__
+from nebcert.citation import APA, BIBTEX
+from nebcert.parsers.vasp_neb import parse_vasp_neb_dat
+from nebcert.parsers.orca_neb import parse_orca_neb_output
+from nebcert.parsers.gaussian_irc import parse_gaussian_irc_output
+from nebcert.parsers.generic_mep_csv import parse_mep_csv
+
+from nebcert.core.neb_profile import calculate_neb_profile_analysis
+from nebcert.core.ts_frequency import verify_ts_frequency_and_irc
+from nebcert.core.tst_kinetics import calculate_eyring_tst_rates
+from nebcert.core.tunneling import calculate_quantum_tunneling_corrections
+from nebcert.core.scoring import assess_reaction_pathway_quality
+
+from nebcert.reporters.plot_generator import generate_nebcert_figures
+from nebcert.reporters.manuscript_prep import generate_nebcert_manuscript_assets
+from nebcert.reporters.html_report import generate_nebcert_html_report
+
+
+def print_banner():
+    banner = rf"""
+  _   _ ______ _____   _____          _   
+ | \ | |  ____|  _ \ / ____|        | |  
+ |  \| | |__  | |_) | |     ___ _ __| |_ 
+ | . ` |  __| |  _ <| |    / _ \ '__| __|
+ | |\  | |____| |_) | |___|  __/ |  | |_ 
+ |_| \_|______|____/ \_____\___|_|   \__| v{__version__}
+
+ Transition State, NEB Reaction Pathways & Quantum Tunneling Toolkit
+ Monreal-Hernández et al., 2026
+"""
+    print(banner)
+
+
+def run_demo(output_dir: str = "nebcert_demo_output"):
+    """
+    Executes a benchmark demonstration evaluating a hydrogen atom abstraction reaction:
+    CH4 + OH* -> CH3* + H2O with 9-image NEB band, 1st-order saddle point TS (nu_imag = -1250 cm^-1),
+    Eyring TST kinetics, and asymmetric Eckart quantum tunneling.
+    """
+    print(f"\n[NEBCert] Running demonstration benchmark on Reaction Pathway (CH4 + OH* -> CH3* + H2O)...")
+    os.makedirs(output_dir, exist_ok=True)
+
+    metadata = {
+        "reaction": "CH4 + OH* -> [TS]* -> CH3* + H2O (Hydrogen Abstraction)",
+        "functional": "wB97X-D3 / def2-TZVP",
+        "software": "SYNTHETIC DEMO DATA (ORCA-like CI-NEB / NumFreq; not a real calculation)"
+    }
+
+    # 1. 9-image NEB reaction energy profile (eV)
+    # Reactant = 0.0, Peak TS (img 4) = 0.225 eV (5.19 kcal/mol), Product (img 8) = -0.620 eV (-14.30 kcal/mol)
+    s_coords = [0.0, 0.35, 0.70, 1.05, 1.40, 1.75, 2.10, 2.45, 2.80]
+    energies_rel_ev = [0.000, 0.045, 0.120, 0.195, 0.225, 0.110, -0.220, -0.510, -0.620]
+    tangent_forces = [0.00, 0.02, 0.03, 0.02, 0.01, 0.03, 0.02, 0.02, 0.00]
+
+    print("  -> Analyzing NEB Minimum Energy Path, fitting cubic spline, and auditing CI-NEB forces...")
+    neb_res = calculate_neb_profile_analysis(
+        energies_ev=energies_rel_ev,
+        coordinates_s_ang=s_coords,
+        tangent_forces_ev_ang=tangent_forces
+    )
+
+    # 2. Transition state imaginary frequency
+    print("  -> Verifying 1st-order saddle point vibrational frequencies (nu_imag = -1250.0 cm^-1)...")
+    sample_freqs = [-1250.0, 120.0, 250.0, 480.0, 850.0, 1100.0, 1450.0, 2900.0, 3100.0, 3650.0]
+    ts_res = verify_ts_frequency_and_irc(
+        frequencies_cm1=sample_freqs,
+        min_significant_freq_cm1=50.0,
+        irc_confirmed=True
+    )
+
+    # 3. Eyring TST rate constants
+    print("  -> Computing Eyring-Polanyi TST rate constants k(T) and Arrhenius parameters...")
+    tst_res = calculate_eyring_tst_rates(
+        e_activation_ev=neb_res.e_forward_barrier_ev
+    )
+
+    # 4. Quantum tunneling corrections (Eckart & Wigner)
+    print("  -> Computing asymmetric Eckart quantum tunneling transmission factor kappa(T)...")
+    tun_res = calculate_quantum_tunneling_corrections(
+        imaginary_freq_cm1=1250.0,
+        e_forward_barrier_ev=neb_res.e_forward_barrier_ev,
+        e_reverse_barrier_ev=neb_res.e_reverse_barrier_ev
+    )
+
+    report = assess_reaction_pathway_quality(
+        metadata=metadata,
+        neb_res=neb_res,
+        ts_freq_res=ts_res,
+        tst_res=tst_res,
+        tunneling_res=tun_res
+    )
+
+    print("  -> Generating publication-ready vector figures (NEB MEP Profile, Arrhenius Plot, Tunneling Curve)...")
+    generate_nebcert_figures(report, output_dir)
+
+    print("  -> Drafting manuscript Methods text snippet, summary LaTeX tables, and BibTeX citations...")
+    assets = generate_nebcert_manuscript_assets(report, output_dir)
+
+    with open(assets["methods_text"], "r", encoding="utf-8") as f:
+        methods_txt = f.read()
+    with open(assets["citation_bib"], "r", encoding="utf-8") as f:
+        bib_txt = f.read()
+
+    html_p = os.path.join(output_dir, "report.html")
+    print(f"  -> Writing interactive report to {html_p}...")
+    generate_nebcert_html_report(report, html_p, methods_text=methods_txt, citation_bib=bib_txt)
+
+    print("\n" + "="*70)
+    print(f" [RESULT] Overall status: {report.overall_status}")
+    print(f" [SCORE]  {report.validation_score}")
+    print("="*70)
+    print(f" * Reaction Target : {report.metadata['reaction']}")
+    print(f" * Activation Barrier: E_a^fwd = {report.neb_profile.e_forward_barrier_kcal_mol:.2f} kcal/mol ({report.neb_profile.e_forward_barrier_ev:.3f} eV) | Delta E_rxn = {report.neb_profile.delta_e_reaction_kcal_mol:.2f} kcal/mol")
+    print(f" * Transition State : {report.ts_frequency.imaginary_frequency_cm1:.1f} cm^-1 | Status: {report.ts_frequency.status}")
+    print(f" * Eyring TST Rate  : k(298 K) = {report.tst_kinetics.k_298_s_minus_1:.2e} s^-1 (Arrhenius A = {report.tst_kinetics.arrhenius_pre_exponential_a_s_minus_1:.2e} s^-1, E_a = {report.tst_kinetics.arrhenius_e_activation_kcal_mol:.2f} kcal/mol)")
+    print(f" * Quantum Tunneling: kappa_Eckart(298 K) = {report.tunneling.kappa_eckart_298:.2f}")
+    print("="*70)
+    print(f"\nAll outputs successfully saved to: {os.path.abspath(output_dir)}/")
+    print(f"Open {os.path.abspath(html_p)} in your browser to inspect the full report.\n")
+
+
+def run_assess(args):
+    """
+    Evaluates user-provided MEP/NEB files or frequencies.
+    """
+    output_dir = args.output
+    os.makedirs(output_dir, exist_ok=True)
+
+    neb_res = None
+    ts_res = None
+    tst_res = None
+    tun_res = None
+
+    # 1. Parse NEB / MEP input
+    orca_neb = None
+    if args.input_neb:
+        print(f"\n[NEBCert] Parsing NEB data from: {args.input_neb}...")
+        lower = args.input_neb.lower()
+        if lower.endswith(".dat"):
+            try:
+                m_data = parse_vasp_neb_dat(args.input_neb)
+            except Exception:
+                m_data = parse_mep_csv(args.input_neb)
+        elif lower.endswith((".out", ".log")):
+            m_data = parse_orca_neb_output(args.input_neb)
+            if not m_data["energies_ev"]:
+                print("[Error] No ORCA NEB 'PATH SUMMARY' table found in the file.", file=sys.stderr)
+                sys.exit(1)
+            if m_data["n_images_without_energy"]:
+                print(f"[Error] {m_data['n_images_without_energy']} of {m_data['n_images']} images in the last "
+                      f"'PATH SUMMARY' table have no energy (E = 0): the image calculations failed or never ran; see the ORCA errors above the table.",
+                      file=sys.stderr)
+                sys.exit(1)
+            orca_neb = m_data
+            print(f"  -> ORCA NEB: {m_data['n_images']} images, NEB converged: {m_data['neb_converged']}, "
+                  f"climbing image: {m_data['ci_index']}")
+            if m_data.get("ts"):
+                print(f"  -> NEB-TS transition state: E_a = {m_data['ts']['barrier_fwd_kcal']:.2f} kcal/mol, "
+                      f"TS optimisation converged: {m_data['ts']['converged']}")
+        else:
+            m_data = parse_mep_csv(args.input_neb)
+
+        ts_data = orca_neb.get("ts") if orca_neb else None
+        neb_res = calculate_neb_profile_analysis(
+            energies_ev=m_data["energies_ev"],
+            coordinates_s_ang=m_data.get("coordinates_s_ang"),
+            tangent_forces_ev_ang=m_data.get("tangent_forces"),
+            band_converged=orca_neb["neb_converged"] if orca_neb else None,
+            ts_energy_rel_ev=ts_data["barrier_fwd_ev"] if ts_data else None,
+            ts_optimisation_converged=ts_data["converged"] if ts_data else None,
+            climbing_image_index=orca_neb["ci_index"] if orca_neb else None
+        )
+
+    # 2. Parse / evaluate TS frequencies
+    if args.frequencies:
+        freq_list = [float(x) for x in args.frequencies.split(",")]
+        ts_res = verify_ts_frequency_and_irc(
+            frequencies_cm1=freq_list,
+            irc_confirmed=args.irc
+        )
+    elif orca_neb and orca_neb.get("frequencies"):
+        ts_res = verify_ts_frequency_and_irc(
+            frequencies_cm1=orca_neb["frequencies"],
+            irc_confirmed=args.irc
+        )
+
+    # 3. Calculate kinetics and tunneling
+    # Electronic barriers (forward and reverse) for the Eckart barrier; the band already holds the
+    # optimised NEB-TS energy when there is one.
+    ea_val = None
+    ea_rev = neb_res.e_reverse_barrier_ev if neb_res else None
+    if neb_res:
+        ea_val = neb_res.e_forward_barrier_ev
+    elif args.barrier_ev:
+        ea_val = float(args.barrier_ev)
+    elif args.barrier_kcal:
+        ea_val = float(args.barrier_kcal) / 23.06054887
+
+    if args.gibbs_barrier_kcal is not None:
+        tst_res = calculate_eyring_tst_rates(e_activation_ev=float(args.gibbs_barrier_kcal) / 23.06054887,
+                                             barrier_type="gibbs")
+    elif ea_val is not None:
+        tst_res = calculate_eyring_tst_rates(e_activation_ev=ea_val, barrier_type="electronic")
+    if ea_val is not None and ts_res and ts_res.imaginary_frequency_cm1:
+        tun_res = calculate_quantum_tunneling_corrections(
+            imaginary_freq_cm1=ts_res.imaginary_frequency_cm1,
+            e_forward_barrier_ev=ea_val,
+            e_reverse_barrier_ev=ea_rev
+        )
+
+    meta = {
+        "reaction": args.reaction or "the reaction",
+        "functional": args.functional or "an unstated level of theory",
+        "software": args.software or ("ORCA" if orca_neb else "an unstated program")
+    }
+
+    report = assess_reaction_pathway_quality(
+        metadata=meta,
+        neb_res=neb_res,
+        ts_freq_res=ts_res,
+        tst_res=tst_res,
+        tunneling_res=tun_res
+    )
+
+    print("  -> Generating publication figures...")
+    generate_nebcert_figures(report, output_dir)
+
+    print("  -> Generating manuscript text, LaTeX summary table, and BibTeX citations...")
+    assets = generate_nebcert_manuscript_assets(report, output_dir)
+
+    with open(assets["methods_text"], "r", encoding="utf-8") as f:
+        methods_txt = f.read()
+    with open(assets["citation_bib"], "r", encoding="utf-8") as f:
+        bib_txt = f.read()
+
+    html_p = os.path.join(output_dir, "report.html")
+    print(f"  -> Writing HTML quality report to {html_p}...")
+    generate_nebcert_html_report(report, html_p, methods_text=methods_txt, citation_bib=bib_txt)
+
+    print("\n" + "="*70)
+    print(f" [RESULT] Overall status: {report.overall_status}")
+    print(f" [SCORE]  {report.validation_score}")
+    print("="*70)
+    if report.neb_profile:
+        print(f" * Barrier (E_a^fwd): {report.neb_profile.e_forward_barrier_kcal_mol:.2f} kcal/mol ({report.neb_profile.e_forward_barrier_ev:.3f} eV)")
+    if report.tst_kinetics:
+        print(f" * TST Rate (298 K) : k = {report.tst_kinetics.k_298_s_minus_1:.2e} s^-1")
+    print("="*70)
+    print(f"\nReport ready at: {os.path.abspath(html_p)}\n")
+
+
+def print_citation():
+    print()
+    print("If you use NEBCert in your publications, please cite:")
+    print()
+    print("APA Style:")
+    print(APA)
+    print()
+    print("BibTeX:")
+    print(BIBTEX)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="nebcert",
+        description="NEBCert: Transition State, NEB Reaction Pathways, Quantum Tunneling, and TST Kinetics Certification."
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"nebcert {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Assess command
+    assess_parser = subparsers.add_parser("assess", help="Assess NEB pathway, TS frequencies, and reaction kinetics")
+    assess_parser.add_argument("-i", "--input-neb", default=None, help="Path to NEB file: VASP neb.dat, ORCA NEB/NEB-CI/NEB-TS output (.out/.log), or CSV/TSV table of image energies")
+    assess_parser.add_argument("--frequencies", default=None, help="Comma-separated vibrational frequencies in cm^-1 (e.g. '-1250,150,300,800')")
+    assess_parser.add_argument("--barrier-ev", type=float, default=None, help="Activation energy in eV (if not using NEB profile)")
+    assess_parser.add_argument("--barrier-kcal", type=float, default=None, help="Activation energy in kcal/mol")
+    assess_parser.add_argument("--gibbs-barrier-kcal", type=float, default=None, help="Gibbs free energy of activation (kcal/mol) for the Eyring rate constant; without it the rate uses the electronic barrier and is flagged")
+    assess_parser.add_argument("--irc", action="store_const", const=True, default=None, help="Declare that an IRC connected the intended minima (not checked by NEBCert); omit when no IRC was run")
+    assess_parser.add_argument("-o", "--output", default="nebcert_output", help="Directory for output report (default: nebcert_output)")
+    assess_parser.add_argument("--reaction", default=None, help="Reaction description (e.g. 'CH4 + OH -> CH3 + H2O')")
+    assess_parser.add_argument("--functional", default=None, help="DFT functional / level of theory")
+    assess_parser.add_argument("--software", default=None, help="Software code (e.g. 'VASP', 'ORCA', 'Gaussian')")
+
+    # Demo command
+    demo_parser = subparsers.add_parser("demo", help="Run benchmark demonstration (H-abstraction 9-image NEB + TS + TST + Tunneling)")
+    demo_parser.add_argument("-o", "--output", default="nebcert_demo_output", help="Output directory (default: nebcert_demo_output)")
+
+    # Cite command
+    subparsers.add_parser("cite", help="Display BibTeX and APA citation details")
+
+    if len(sys.argv) == 1:
+        print_banner()
+        parser.print_help()
+        sys.exit(0)
+
+    args = parser.parse_args()
+
+    if args.command == "assess":
+        print_banner()
+        run_assess(args)
+    elif args.command == "demo":
+        print_banner()
+        run_demo(args.output)
+    elif args.command == "cite":
+        print_banner()
+        print_citation()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()
+

nebcert/core/__init__.py

@@ -0,0 +1,22 @@
+"""
+Core kinetics, NEB spline analysis, and quantum tunneling engines for NEBCert.
+"""
+
+from nebcert.core.neb_profile import calculate_neb_profile_analysis, NEBProfileResult
+from nebcert.core.ts_frequency import verify_ts_frequency_and_irc, TSFrequencyResult
+from nebcert.core.tst_kinetics import calculate_eyring_tst_rates, TSTKineticsResult
+from nebcert.core.tunneling import calculate_quantum_tunneling_corrections, TunnelingResult
+from nebcert.core.scoring import assess_reaction_pathway_quality, ReactionPathwayReport
+
+__all__ = [
+    "calculate_neb_profile_analysis",
+    "NEBProfileResult",
+    "verify_ts_frequency_and_irc",
+    "TSFrequencyResult",
+    "calculate_eyring_tst_rates",
+    "TSTKineticsResult",
+    "calculate_quantum_tunneling_corrections",
+    "TunnelingResult",
+    "assess_reaction_pathway_quality",
+    "ReactionPathwayReport"
+]

nebcert/core/neb_profile.py

@@ -0,0 +1,240 @@
+"""
+Nudged Elastic Band (NEB / CI-NEB) profile analysis, spline interpolation, and MEP force audit.
+"""
+
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass
+import numpy as np
+from scipy.interpolate import CubicSpline
+
+EV_TO_KCAL_MOL = 23.06054887
+
+
+@dataclass
+class NEBImagePoint:
+    image_index: int
+    reaction_coordinate_s_ang: float
+    energy_ev: float
+    relative_energy_ev: float
+    relative_energy_kcal_mol: float
+    tangent_force_ev_ang: Optional[float]
+
+
+@dataclass
+class NEBProfileResult:
+    n_images: int
+    total_path_length_ang: float
+    ts_image_index: int
+    ts_position_s_ang: float
+    e_forward_barrier_ev: float
+    e_forward_barrier_kcal_mol: float
+    e_reverse_barrier_ev: float
+    e_reverse_barrier_kcal_mol: float
+    delta_e_reaction_ev: float
+    delta_e_reaction_kcal_mol: float
+    max_tangent_force_ev_ang: Optional[float]
+    is_climbing_image_converged: bool
+    has_intermediate_minimum: bool
+    interpolated_s: List[float]
+    interpolated_e_rel_ev: List[float]
+    image_points: List[NEBImagePoint]
+    status: str  # 'PASS', 'WARNING', 'FAIL'
+    diagnostic_message: str
+    e_forward_barrier_spline_ev: Optional[float] = None
+    barrier_source: str = "spline"
+    band_converged: Optional[bool] = None
+    ts_optimisation_converged: Optional[bool] = None
+    deepest_intermediate_well_kcal_mol: float = 0.0
+
+
+def calculate_neb_profile_analysis(
+    energies_ev: List[float],
+    coordinates_s_ang: Optional[List[float]] = None,
+    tangent_forces_ev_ang: Optional[List[float]] = None,
+    force_convergence_threshold: float = 0.05,  # eV/Å
+    warning_force_threshold: float = 0.10,
+    band_converged: Optional[bool] = None,
+    ts_energy_rel_ev: Optional[float] = None,
+    ts_optimisation_converged: Optional[bool] = None,
+    min_well_depth_kcal_mol: float = 0.5,
+    min_path_length_ang: float = 0.05,
+    climbing_image_index: Optional[int] = None
+) -> NEBProfileResult:
+    """
+    Analyzes NEB minimum energy path, fits cubic spline interpolation, calculates
+    forward and reverse activation barriers, and audits force convergence and continuity.
+
+    Parameters
+    ----------
+    energies_ev : list of float
+        Total DFT energies for all images along the band (eV).
+    coordinates_s_ang : list of float, optional
+        Cumulative reaction coordinates s (Å). If None, uniform spacing 0..1 is used.
+    tangent_forces_ev_ang : list of float, optional
+        Parallel / residual forces along band (eV/Å).
+    force_convergence_threshold : float, default 0.05 eV/Å
+        Limit on the force at the image nearest the barrier.
+    warning_force_threshold : float, default 0.10 eV/Å
+        Unused; kept for backward compatibility.
+    band_converged : bool, optional
+        Convergence flag of the band as printed by the program (ORCA: "THE NEB OPTIMIZATION HAS
+        CONVERGED"). False gives FAIL: an unconverged band does not locate the barrier.
+    ts_energy_rel_ev : float, optional
+        Energy of an optimised transition state (e.g. ORCA NEB-TS) relative to image 0. When given it
+        replaces the spline maximum as the forward barrier; the spline value is kept for comparison.
+    ts_optimisation_converged : bool, optional
+        False gives FAIL (the TS energy is then not a saddle-point energy). When True, the force check on the
+        band is skipped: NEB-TS converges the band only loosely by design and the TS optimisation refines it.
+    climbing_image_index : int, optional
+        Index of the climbing image. When the band converged and no optimised TS is given, the climbing-image
+        energy is the barrier (a converged climbing image sits at the saddle point; a spline through a coarse
+        band does not).
+    min_well_depth_kcal_mol : float, default 0.5
+        An interior image lower than both neighbours by more than this is reported as an intermediate
+        minimum; shallower dips are treated as noise of the band.
+    min_path_length_ang : float, default 0.05
+        When coordinates_s_ang are distances along the path (Å), a shorter path means that both end points
+        are the same structure (e.g. one end point slid into the other during pre-optimisation): FAIL.
+
+    Returns
+    -------
+    result : NEBProfileResult
+    """
+    e_arr = np.asarray(energies_ev, dtype=float)
+    n_img = len(e_arr)
+    if n_img < 3:
+        raise ValueError("NEB reaction path requires at least 3 images (Reactant, TS, Product).")
+
+    if coordinates_s_ang is not None and len(coordinates_s_ang) == n_img:
+        s_arr = np.asarray(coordinates_s_ang, dtype=float)
+    else:
+        s_arr = np.linspace(0.0, float(n_img - 1), n_img)
+
+    # Reference energies relative to Reactant (image 0)
+    e_rel = e_arr - e_arr[0]
+    total_length = float(s_arr[-1] - s_arr[0])
+    # Distances printed with few decimals can repeat (e.g. a band whose end points coincide); the spline
+    # then needs a strictly increasing abscissa, so it falls back to the image index.
+    if not np.all(np.diff(s_arr) > 0):
+        s_arr = np.linspace(0.0, float(n_img - 1), n_img)
+
+    # Fit natural cubic spline
+    spline = CubicSpline(s_arr, e_rel, bc_type='natural')
+    s_fine = np.linspace(s_arr[0], s_arr[-1], 300)
+    e_fine = spline(s_fine)
+
+    # Find peak (Transition State candidate)
+    ts_fine_idx = int(np.argmax(e_fine))
+    ts_s_pos = float(s_fine[ts_fine_idx])
+    ts_peak_e_rel = float(e_fine[ts_fine_idx])
+
+    # Nearest discrete image to TS peak
+    ts_img_idx = int(np.argmin(np.abs(s_arr - ts_s_pos)))
+
+    spline_barrier_ev = max(0.0, ts_peak_e_rel)
+    barrier_source = "spline"
+    if ts_energy_rel_ev is not None:
+        ts_peak_e_rel = float(ts_energy_rel_ev)
+        barrier_source = "optimised TS"
+    elif climbing_image_index is not None and band_converged and 0 < climbing_image_index < n_img - 1:
+        ts_peak_e_rel = float(e_rel[climbing_image_index])
+        barrier_source = "climbing image"
+    e_fwd_barrier_ev = max(0.0, ts_peak_e_rel)
+    e_fwd_barrier_kcal = float(e_fwd_barrier_ev * EV_TO_KCAL_MOL)
+
+    e_product_rel_ev = float(e_rel[-1])
+    e_rev_barrier_ev = max(0.0, ts_peak_e_rel - e_product_rel_ev)
+    e_rev_barrier_kcal = float(e_rev_barrier_ev * EV_TO_KCAL_MOL)
+
+    delta_e_rxn_ev = e_product_rel_ev
+    delta_e_rxn_kcal = float(delta_e_rxn_ev * EV_TO_KCAL_MOL)
+
+    # Check for intermediate minima (valleys along MEP)
+    # Check if there is an internal local minimum between 0 and -1
+    well = 0.0
+    for i in range(1, n_img - 1):
+        if e_rel[i] < e_rel[i-1] and e_rel[i] < e_rel[i+1]:
+            # depth below the lower of the two barriers that bound it
+            depth = min(np.max(e_rel[:i]), np.max(e_rel[i+1:])) - e_rel[i]
+            well = max(well, float(depth * EV_TO_KCAL_MOL))
+    has_interm_min = well > min_well_depth_kcal_mol
+
+    # Force audit
+    max_f = None
+    ts_f = None
+    is_f_conv = True
+    if tangent_forces_ev_ang is not None and len(tangent_forces_ev_ang) == n_img:
+        # Check force specifically at climbing image
+        f_arr = np.abs(np.asarray(tangent_forces_ev_ang, dtype=float))
+        max_f = float(np.max(f_arr))
+        ts_f = float(f_arr[ts_img_idx])
+        if ts_f > force_convergence_threshold and ts_optimisation_converged is not True:
+            is_f_conv = False
+
+    # Image points
+    img_points = []
+    for i in range(n_img):
+        f_val = float(tangent_forces_ev_ang[i]) if tangent_forces_ev_ang is not None and i < len(tangent_forces_ev_ang) else None
+        img_points.append(NEBImagePoint(
+            image_index=i,
+            reaction_coordinate_s_ang=float(s_arr[i]),
+            energy_ev=float(e_arr[i]),
+            relative_energy_ev=float(e_rel[i]),
+            relative_energy_kcal_mol=float(e_rel[i] * EV_TO_KCAL_MOL),
+            tangent_force_ev_ang=f_val
+        ))
+
+    # Decision logic (first matching condition wins)
+    bar = f"E_a^fwd = {e_fwd_barrier_kcal:.2f} kcal/mol ({barrier_source})"
+    if coordinates_s_ang is not None and total_length < min_path_length_ang:
+        status = "FAIL"
+        diag = (f"The path is {total_length:.4f} Å long: both end points are the same structure, so the band "
+                f"describes no reaction. Check the end-point optimisations.")
+    elif band_converged is False:
+        status = "FAIL"
+        diag = f"The band did not converge; the highest image does not locate the barrier ({bar})."
+    elif ts_optimisation_converged is False:
+        status = "FAIL"
+        diag = f"The transition-state optimisation did not converge ({bar})."
+    elif e_fwd_barrier_ev < 1e-4 and abs(delta_e_rxn_ev) < 1e-4:
+        status = "FAIL"
+        diag = "Flat energy profile (barrier and reaction energy < 1e-4 eV). Check the end points."
+    elif not is_f_conv:
+        status = "WARNING"
+        diag = (f"Force at the image nearest the barrier is {ts_f:.3f} eV/Å > {force_convergence_threshold:.2f} "
+                f"eV/Å ({bar}).")
+    elif has_interm_min:
+        status = "WARNING"
+        diag = (f"Intermediate minimum {well:.2f} kcal/mol deep along the band: the path has more than one "
+                f"step, which should be located separately ({bar}).")
+    else:
+        status = "PASS"
+        conv = " Band convergence not reported." if band_converged is None else ""
+        diag = (f"No problem found in the band: {bar}, Delta E_rxn = {delta_e_rxn_kcal:.2f} kcal/mol, "
+                f"no intermediate minimum deeper than {min_well_depth_kcal_mol:.1f} kcal/mol.{conv}")
+
+    return NEBProfileResult(
+        n_images=n_img,
+        total_path_length_ang=total_length,
+        ts_image_index=ts_img_idx,
+        ts_position_s_ang=ts_s_pos,
+        e_forward_barrier_ev=e_fwd_barrier_ev,
+        e_forward_barrier_kcal_mol=e_fwd_barrier_kcal,
+        e_reverse_barrier_ev=e_rev_barrier_ev,
+        e_reverse_barrier_kcal_mol=e_rev_barrier_kcal,
+        delta_e_reaction_ev=delta_e_rxn_ev,
+        delta_e_reaction_kcal_mol=delta_e_rxn_kcal,
+        max_tangent_force_ev_ang=max_f,
+        is_climbing_image_converged=is_f_conv,
+        has_intermediate_minimum=has_interm_min,
+        interpolated_s=s_fine.tolist(),
+        interpolated_e_rel_ev=e_fine.tolist(),
+        image_points=img_points,
+        status=status,
+        diagnostic_message=diag,
+        e_forward_barrier_spline_ev=float(spline_barrier_ev),
+        barrier_source=barrier_source,
+        band_converged=band_converged,
+        ts_optimisation_converged=ts_optimisation_converged,
+        deepest_intermediate_well_kcal_mol=well
+    )