Result Parser (result.py)

The core engine for building and running Multiwfn sequences.

pymultiwfn.analysis.result

Result container for Multiwfn job execution.

Provides the parsed-result dataclasses, the :class:MultiwfnResult container that accumulates parser output, and per-molecule JSON persistence (replacing the former storage.py).

AOMDiagnostics dataclass

Bases: ParsedMultiwfnResult

Atomic overlap matrix quality diagnostics.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class AOMDiagnostics(ParsedMultiwfnResult):
    """Atomic overlap matrix quality diagnostics."""

    error: float | None = None
    max_diagonal_deviation: float | None = None
    max_diagonal_orbital: int | None = None
    max_nondiagonal_deviation: float | None = None
    max_nondiagonal_orbitals: tuple[int, int] | None = None
    exported_file: str | None = None

Aromaticity dataclass

Bases: ParsedMultiwfnResult

Result for aromaticity analysis (Menu 25).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Aromaticity(ParsedMultiwfnResult):
    """Result for aromaticity analysis (Menu 25)."""

    NICS: float | None = None
    NICS_ZZ: float | None = None
    NICS_1: float | None = None
    HOMA: float | None = None
    HOMAC: float | None = None
    HOMER: float | None = None
    Bird: float | None = None
    EN_GEO: float | None = None
    EN_BLA: float | None = None

AromaticityIndex dataclass

Bases: ParsedMultiwfnResult

Result for aromaticity indices (Menu 15).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class AromaticityIndex(ParsedMultiwfnResult):
    """Result for aromaticity indices (Menu 15)."""

    index_name: str
    value: float

AtomInfo dataclass

Bases: ParsedMultiwfnResult

Atom entry from the atom list output.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class AtomInfo(ParsedMultiwfnResult):
    """Atom entry from the atom list output."""

    atom_id: int
    element: str
    nuclear_charge: float
    x_bohr: float
    y_bohr: float
    z_bohr: float

AtomicMultipole dataclass

Bases: ParsedMultiwfnResult

Full atomic multipole moments for one atom.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class AtomicMultipole(ParsedMultiwfnResult):
    """Full atomic multipole moments for one atom."""

    atom_id: int
    atom_element: str

    # Charge / monopole
    atomic_charge: float | None = None
    monopole_moment: float | None = None

    # Dipole
    dipole_x: float | None = None
    dipole_y: float | None = None
    dipole_z: float | None = None
    dipole_norm: float | None = None

    # Contribution to molecular dipole
    mol_dipole_contrib_x: float | None = None
    mol_dipole_contrib_y: float | None = None
    mol_dipole_contrib_z: float | None = None
    mol_dipole_contrib_norm: float | None = None

    # Quadrupole (traceless Cartesian)
    quadrupole_xx: float | None = None
    quadrupole_xy: float | None = None
    quadrupole_xz: float | None = None
    quadrupole_yy: float | None = None
    quadrupole_yz: float | None = None
    quadrupole_zz: float | None = None
    quadrupole_magnitude: float | None = None

    # Spatial extent
    spatial_extent_r2: float | None = None
    spatial_extent_x: float | None = None
    spatial_extent_y: float | None = None
    spatial_extent_z: float | None = None

    # Octopole (spherical harmonic magnitudes)
    octopole_magnitude: float | None = None

BLA_BOA dataclass

Bases: ParsedMultiwfnResult

Result for BLA/BOA.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BLA_BOA(ParsedMultiwfnResult):  # noqa: N801
    """Result for BLA/BOA."""

    bla: float | None = None
    boa: float | None = None

Basin dataclass

Bases: ParsedMultiwfnResult

Result for basin analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Basin(ParsedMultiwfnResult):
    """Result for basin analysis."""

    basin_id: int
    population: float
    attractor_atom: int | None = None
    attractor_element: str | None = None
    volume: float | None = None
    charge: float | None = None

BasisFunction dataclass

Bases: ParsedMultiwfnResult

Single basis function mapping to shell and, where printed, GTF range.

The plain "list all basis functions" listing (Menu 6 -> 2) does not print a GTF range, only shell/center/type -- gtf_start/gtf_end are only populated when the source listing includes it.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BasisFunction(ParsedMultiwfnResult):
    """Single basis function mapping to shell and, where printed, GTF range.

    The plain "list all basis functions" listing (Menu 6 -> 2) does not
    print a GTF range, only shell/center/type -- ``gtf_start``/``gtf_end``
    are only populated when the source listing includes it.
    """

    basis_index: int
    shell_index: int
    center_atom_id: int
    center_element: str
    function_type: str
    gtf_start: int | None = None
    gtf_end: int | None = None

BondAngle dataclass

Bases: ParsedMultiwfnResult

Result for bond angle analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BondAngle(ParsedMultiwfnResult):
    """Result for bond angle analysis."""

    atom1_id: int
    atom2_id: int
    atom3_id: int
    angle: float

BondLength dataclass

Bases: ParsedMultiwfnResult

Result for bond length analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BondLength(ParsedMultiwfnResult):
    """Result for bond length analysis."""

    atom1_id: int
    atom2_id: int
    length: float

BondOrder dataclass

Bases: ParsedMultiwfnResult

Single bond order entry between two atoms.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BondOrder(ParsedMultiwfnResult):
    """Single bond order entry between two atoms."""

    atom1_id: int
    atom2_id: int
    bond_order: float

BondOrderDecomposition dataclass

Bases: ParsedMultiwfnResult

Result for bond order decomposition (per orbital) analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BondOrderDecomposition(ParsedMultiwfnResult):
    """Result for bond order decomposition (per orbital) analysis."""

    orbital_id: int
    contribution: float

BondOrderSet dataclass

Bases: ParsedMultiwfnResult

A complete set of bond orders from one method.

Parameters

method Standardized method identifier. One of: "mayer", "wiberg", "mulliken", "fuzzy", "laplacian". threshold The printing threshold used, if reported (e.g. 0.05). bond_orders Per-pair bond orders.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class BondOrderSet(ParsedMultiwfnResult):
    """A complete set of bond orders from one method.

    Parameters
    ----------
    method
        Standardized method identifier.  One of: ``"mayer"``,
        ``"wiberg"``, ``"mulliken"``, ``"fuzzy"``,
        ``"laplacian"``.
    threshold
        The printing threshold used, if reported (e.g. 0.05).
    bond_orders
        Per-pair bond orders.
    """

    method: str
    threshold: float | None = None
    bond_orders: list[BondOrder] = field(default_factory=list)

    def to_dict(self) -> dict[str, Any]:
        return {
            "method": self.method,
            "threshold": self.threshold,
            "bond_orders": [asdict(b) for b in self.bond_orders],
        }

CLRKMatrix dataclass

Bases: ParsedMultiwfnResult

Condensed linear response kernel matrix (atom × atom).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class CLRKMatrix(ParsedMultiwfnResult):
    """Condensed linear response kernel matrix (atom × atom)."""

    n_atoms: int = 0
    data: dict[tuple[int, int], float] = field(default_factory=dict)

Charge dataclass

Bases: ParsedMultiwfnResult

Single atomic charge entry.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Charge(ParsedMultiwfnResult):
    """Single atomic charge entry."""

    atom_id: int
    charge: float

ChargeSet dataclass

Bases: ParsedMultiwfnResult

A complete set of atomic charges from one method.

Parameters

method Standardized method identifier. One of: "mulliken", "lowdin", "hirshfeld", "vdd", "scpa", "stout_politzer", "bickelhaupt", "becke", "adch", "chelpg", "mk", "aim", "hirshfeld_i", "cm5", "eem", "resp", "gasteiger", "mbis", "ddec", "esp" (for raw ESP fit), "population" (for Mulliken/Lowdin gross populations). stage For methods with multiple stages (e.g. RESP stage 1/2), the stage identifier. "final" for the final normalized charges. "corrected" for ADC-corrected intermediate. "raw" for the raw/unnormalized charges. None if there is only one stage. charges Per-atom charges. total_charge Sum of all charges, if reported in the output.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class ChargeSet(ParsedMultiwfnResult):
    """A complete set of atomic charges from one method.

    Parameters
    ----------
    method
        Standardized method identifier.  One of: ``"mulliken"``,
        ``"lowdin"``, ``"hirshfeld"``, ``"vdd"``, ``"scpa"``,
        ``"stout_politzer"``, ``"bickelhaupt"``, ``"becke"``,
        ``"adch"``, ``"chelpg"``, ``"mk"``, ``"aim"``,
        ``"hirshfeld_i"``, ``"cm5"``, ``"eem"``, ``"resp"``,
        ``"gasteiger"``, ``"mbis"``, ``"ddec"``,
        ``"esp"`` (for raw ESP fit), ``"population"`` (for
        Mulliken/Lowdin gross populations).
    stage
        For methods with multiple stages (e.g. RESP stage 1/2),
        the stage identifier.  ``"final"`` for the final normalized
        charges.  ``"corrected"`` for ADC-corrected intermediate.
        ``"raw"`` for the raw/unnormalized charges.  ``None`` if
        there is only one stage.
    charges
        Per-atom charges.
    total_charge
        Sum of all charges, if reported in the output.
    """

    method: str
    stage: str | None = None
    charges: list[Charge] = field(default_factory=list)
    total_charge: float | None = None

    def to_dict(self) -> dict[str, Any]:
        return {
            "method": self.method,
            "stage": self.stage,
            "charges": [asdict(c) for c in self.charges],
            "total_charge": self.total_charge,
        }

ChargeTransfer dataclass

Bases: ParsedMultiwfnResult

Result for charge transfer analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class ChargeTransfer(ParsedMultiwfnResult):
    """Result for charge transfer analysis."""

    distance: float | None = None
    transfer_amount: float | None = None
    fragments: list[ChargeTransferFragment] | None = None

ChargeTransferFragment dataclass

Bases: ParsedMultiwfnResult

Individual fragment contribution to charge transfer analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class ChargeTransferFragment(ParsedMultiwfnResult):
    """Individual fragment contribution to charge transfer analysis."""

    fragment_id: int
    hole_contribution: float
    electron_contribution: float

CoefficientMatrix dataclass

Bases: ParsedMultiwfnResult

MO coefficient matrix (basis x orbitals) for one sequence.

Rows are basis functions, columns are orbital indices. Stored as a flat dict mapping (row, col) to the coefficient value, to avoid importing numpy.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class CoefficientMatrix(ParsedMultiwfnResult):
    """MO coefficient matrix (basis x orbitals) for one sequence.

    Rows are basis functions, columns are orbital indices.
    Stored as a flat dict mapping ``(row, col)`` to the coefficient
    value, to avoid importing numpy.
    """

    label: str = ""
    n_basis: int = 0
    n_orbitals: int = 0
    data: dict[tuple[int, int], float] = field(default_factory=dict)

Color dataclass

Bases: ParsedMultiwfnResult

Result for color prediction in CIE XYZ color space and RGB values.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Color(ParsedMultiwfnResult):
    """Result for color prediction in CIE XYZ color space and RGB values."""

    X: float
    Y: float  # noqa: E741
    Z: float
    R: int
    G: int
    B: int

CondensedFukui dataclass

Bases: ParsedMultiwfnResult

Result for condensed Fukui functions.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class CondensedFukui(ParsedMultiwfnResult):
    """Result for condensed Fukui functions."""

    atom_id: int
    fukui_plus: float | None = None
    fukui_minus: float | None = None
    fukui_zero: float | None = None

CoordinationNumber dataclass

Bases: ParsedMultiwfnResult

Result for coordination numbers.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class CoordinationNumber(ParsedMultiwfnResult):
    """Result for coordination numbers."""

    atom_id: int
    coordination_number: float

CorrelationIndex dataclass

Bases: ParsedMultiwfnResult

Result for correlation index analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class CorrelationIndex(ParsedMultiwfnResult):
    """Result for correlation index analysis."""

    nondynamic_correlation_index: float
    dynamic_correlation_index: float
    total_correlation_index: float

CriticalPoint dataclass

Bases: ParsedMultiwfnResult

Critical point from topology summary output.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class CriticalPoint(ParsedMultiwfnResult):
    """Critical point from topology summary output."""

    index: int
    x: float
    y: float
    z: float
    type: Literal["nuclear", "bond", "ring", "cage", "unknown"] = "unknown"
    nucleus_atom_id: int | None = None
    nucleus_element: str | None = None
    bonded_atom1_id: int | None = None
    bonded_atom2_id: int | None = None

Cube dataclass

Bases: ParsedMultiwfnResult

Result for a single cube/grid calculation sequence.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Cube(ParsedMultiwfnResult):
    """Result for a single cube/grid calculation sequence."""

    file_name: str = ""
    origin_x: float | None = None
    origin_y: float | None = None
    origin_z: float | None = None
    end_x: float | None = None
    end_y: float | None = None
    end_z: float | None = None
    spacing_x: float | None = None
    spacing_y: float | None = None
    spacing_z: float | None = None
    x_dim: int = 0
    y_dim: int = 0
    z_dim: int = 0
    total_points: int = 0
    minimum: GridExtremum | None = None
    maximum: GridExtremum | None = None
    integral_total: float | None = None
    integral_positive: float | None = None
    integral_negative: float | None = None

DOSMetadata dataclass

Bases: ParsedMultiwfnResult

Metadata from density of states calculation.

Parameters

tdos_center_au Center of TDOS in Hartree, if reported. homo_level_au HOMO energy level used for the vertical dash line, in Hartree.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DOSMetadata(ParsedMultiwfnResult):
    """Metadata from density of states calculation.

    Parameters
    ----------
    tdos_center_au
        Center of TDOS in Hartree, if reported.
    homo_level_au
        HOMO energy level used for the vertical dash line, in Hartree.
    """

    tdos_center_au: float | None = None
    homo_level_au: float | None = None

DelocalizationIndex dataclass

Bases: ParsedMultiwfnResult

Pairwise delocalization index between two atoms.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DelocalizationIndex(ParsedMultiwfnResult):
    """Pairwise delocalization index between two atoms."""

    atom1_id: int
    atom2_id: int
    index: float

DelocalizationIndexMatrix dataclass

Bases: ParsedMultiwfnResult

Full delocalization index matrix (atom × atom).

Diagonal elements are localization indices (or atomic valence for closed-shell). The label distinguishes "Total" from regular DI matrices.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DelocalizationIndexMatrix(ParsedMultiwfnResult):
    """Full delocalization index matrix (atom × atom).

    Diagonal elements are localization indices (or atomic valence
    for closed-shell).  The ``label`` distinguishes "Total" from
    regular DI matrices.
    """

    label: str = ""
    n_atoms: int = 0
    data: dict[tuple[int, int], float] = field(default_factory=dict)
    localization_indices: list[LocalizationIndex] = field(default_factory=list)

DeltaR dataclass

Bases: ParsedMultiwfnResult

Result for Delta_r index.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DeltaR(ParsedMultiwfnResult):
    """Result for Delta_r index."""

    state_id: int
    delta_r: float

DensityMatrix dataclass

Bases: ParsedMultiwfnResult

Density matrix (symmetric, basis x basis) for one sequence.

Lower-triangle storage: keys (row, col) with row >= col.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DensityMatrix(ParsedMultiwfnResult):
    """Density matrix (symmetric, basis x basis) for one sequence.

    Lower-triangle storage: keys ``(row, col)`` with ``row >= col``.
    """

    label: str = ""
    n_basis: int = 0
    data: dict[tuple[int, int], float] = field(default_factory=dict)
    trace: float | None = None
    trace_overlap: float | None = None

DensityOfStates dataclass

Bases: ParsedMultiwfnResult

Discrete DOS/PDOS arrays sampled on an energy grid.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DensityOfStates(ParsedMultiwfnResult):
    """Discrete DOS/PDOS arrays sampled on an energy grid."""

    energies_eV: list[float] = field(default_factory=list)  # noqa: N815
    dos: list[float] = field(default_factory=list)
    projected_dos: dict[str, list[float]] | None = None

DihedralAngle dataclass

Bases: ParsedMultiwfnResult

Result for dihedral angle analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DihedralAngle(ParsedMultiwfnResult):
    """Result for dihedral angle analysis."""

    atom1_id: int
    atom2_id: int
    atom3_id: int
    atom4_id: int
    angle: float

Dipole dataclass

Bases: ParsedMultiwfnResult

Result for dipole moment analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Dipole(ParsedMultiwfnResult):
    """Result for dipole moment analysis."""

    x: float
    y: float
    z: float
    total: float

DipoleMoment dataclass

Bases: Dipole

Utility-menu dipole vector (same data model as :class:Dipole).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DipoleMoment(Dipole):
    """Utility-menu dipole vector (same data model as :class:`Dipole`)."""

DispersionContribution dataclass

Bases: ParsedMultiwfnResult

Result for dispersion contributions.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DispersionContribution(ParsedMultiwfnResult):
    """Result for dispersion contributions."""

    atom_id: int
    contribution: float

DualDescriptor dataclass

Bases: ParsedMultiwfnResult

Result for dual descriptor.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class DualDescriptor(ParsedMultiwfnResult):
    """Result for dual descriptor."""

    atom_id: int
    value: float

ElectricMultipoleMomentReport dataclass

Bases: ParsedMultiwfnResult

Comprehensive electric multipole report for Menu 300.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class ElectricMultipoleMomentReport(ParsedMultiwfnResult):
    """Comprehensive electric multipole report for Menu 300."""

    positive_charge_center_angstrom: tuple[float, float, float] | None = None
    negative_charge_center_angstrom: tuple[float, float, float] | None = None
    nuclear_dipole_au: tuple[float, float, float] | None = None
    electronic_dipole_au: tuple[float, float, float] | None = None
    total_dipole_au: tuple[float, float, float] | None = None
    total_dipole_debye: tuple[float, float, float] | None = None
    dipole_magnitude_au: float | None = None
    dipole_magnitude_debye: float | None = None
    quadrupole_standard_cartesian: dict[str, float] = field(default_factory=dict)
    quadrupole_traceless_cartesian: dict[str, float] = field(default_factory=dict)
    quadrupole_traceless_magnitude: float | None = None
    quadrupole_spherical_harmonic: dict[str, float] = field(default_factory=dict)
    quadrupole_spherical_magnitude: float | None = None
    octopole_cartesian: dict[str, float] = field(default_factory=dict)
    octopole_spherical_harmonic: dict[str, float] = field(default_factory=dict)
    octopole_spherical_magnitude: float | None = None
    hexadecapole: dict[str, float] = field(default_factory=dict)
    electronic_spatial_extent_r2: float | None = None
    electronic_spatial_extent_components: tuple[float, float, float] | None = None

EnergyDecompositionAnalysis dataclass

Bases: ParsedMultiwfnResult

Result for energy decomposition analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class EnergyDecompositionAnalysis(ParsedMultiwfnResult):
    """Result for energy decomposition analysis."""

    electrostatic: float | None = None
    exchange: float | None = None
    repulsion: float | None = None
    polarization: float | None = None
    dispersion: float | None = None
    orbital_interaction: float | None = None
    total_interaction: float | None = None

ExportedMatrix dataclass

Bases: ParsedMultiwfnResult

Record that a matrix was exported to a file.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class ExportedMatrix(ParsedMultiwfnResult):
    """Record that a matrix was exported to a file."""

    file_name: str = ""
    label: str = ""

FLUReferenceParameter dataclass

Bases: ParsedMultiwfnResult

FLU reference bond order for one element pair.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class FLUReferenceParameter(ParsedMultiwfnResult):
    """FLU reference bond order for one element pair."""

    element1: str
    element2: str
    reference_value: float

FuzzyIntegrationEntry dataclass

Single atom entry in a fuzzy integration table.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class FuzzyIntegrationEntry:
    """Single atom entry in a fuzzy integration table."""

    atom_id: int
    atom_element: str
    value: float
    pct_of_sum: float
    pct_of_sum_abs: float

FuzzyIntegrationResult dataclass

Bases: ParsedMultiwfnResult

Result of fuzzy space integration for one property.

Parameters

integrated_property Standardized identifier: "edensity", "norm_rho", "laplacian", "orb_wfn_homo", "orb_wfn_lumo", "espin_density", "kr", "gr", "esp_charges", "elf", "lol", "local_entropy", "esp", "rdg", "rdg_promolecular", "lambda2rho", "lambda2rho_promolecular", "alie", "edr", "orb_overlap_dr", "deltag_promolecular", "deltag_hirshfeld", "iri".

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class FuzzyIntegrationResult(ParsedMultiwfnResult):
    """Result of fuzzy space integration for one property.

    Parameters
    ----------
    integrated_property
        Standardized identifier: ``"edensity"``, ``"norm_rho"``,
        ``"laplacian"``, ``"orb_wfn_homo"``, ``"orb_wfn_lumo"``,
        ``"espin_density"``, ``"kr"``, ``"gr"``, ``"esp_charges"``,
        ``"elf"``, ``"lol"``, ``"local_entropy"``, ``"esp"``,
        ``"rdg"``, ``"rdg_promolecular"``, ``"lambda2rho"``,
        ``"lambda2rho_promolecular"``, ``"alie"``, ``"edr"``,
        ``"orb_overlap_dr"``, ``"deltag_promolecular"``,
        ``"deltag_hirshfeld"``, ``"iri"``.
    """

    integrated_property: str
    entries: list[FuzzyIntegrationEntry] = field(default_factory=list)
    total_sum: float | None = None
    total_sum_abs: float | None = None

GaussianTypeFunction dataclass

Bases: ParsedMultiwfnResult

Single Gaussian-type function (GTF) from basis set info.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class GaussianTypeFunction(ParsedMultiwfnResult):
    """Single Gaussian-type function (GTF) from basis set info."""

    gtf_index: int
    center_atom_id: int
    center_element: str
    function_type: str
    exponent: float

GridExtremum dataclass

Position and value of a grid minimum or maximum.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class GridExtremum:
    """Position and value of a grid minimum or maximum."""

    value: float
    x_bohr: float
    y_bohr: float
    z_bohr: float

GridStatistics dataclass

Bases: ParsedMultiwfnResult

Statistics of grid point values, optionally within a sub-region.

Produced by Menu 13's "Show statistic data of grid points" option.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class GridStatistics(ParsedMultiwfnResult):
    """Statistics of grid point values, optionally within a sub-region.

    Produced by Menu 13's "Show statistic data of grid points" option.
    """

    minimum: float | None = None
    minimum_x_bohr: float | None = None
    minimum_y_bohr: float | None = None
    minimum_z_bohr: float | None = None
    maximum: float | None = None
    maximum_x_bohr: float | None = None
    maximum_y_bohr: float | None = None
    maximum_z_bohr: float | None = None
    average: float | None = None
    rms: float | None = None
    std_dev: float | None = None
    volume_positive_bohr3: float | None = None
    volume_negative_bohr3: float | None = None
    volume_all_bohr3: float | None = None
    sum_positive: float | None = None
    sum_negative: float | None = None
    sum_all: float | None = None
    integral_positive: float | None = None
    integral_negative: float | None = None
    integral_all: float | None = None

HOMOLUMOGap dataclass

Bases: ParsedMultiwfnResult

HOMO-LUMO gap information.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class HOMOLUMOGap(ParsedMultiwfnResult):
    """HOMO-LUMO gap information."""

    homo_index: int
    homo_energy_au: float
    homo_energy_eV: float  # noqa: N815
    lumo_index: int
    lumo_energy_au: float
    lumo_energy_eV: float  # noqa: N815
    gap_au: float
    gap_eV: float  # noqa: N815
    gap_kJ_mol: float  # noqa: N815

HoleElectron dataclass

Bases: ParsedMultiwfnResult

Result for hole-electron analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class HoleElectron(ParsedMultiwfnResult):
    """Result for hole-electron analysis."""

    hole_id: float
    electron_id: float
    transition_index: float
    electron_delocalisation_index: float
    hole_delocalisation_index: float
    Sr: float
    d_index: float
    hole_centroid: tuple[float, float, float] = (0.0, 0.0, 0.0)
    electron_centroid: tuple[float, float, float] = (0.0, 0.0, 0.0)

IBSIAnalysis dataclass

Bases: ParsedMultiwfnResult

Complete IBSI analysis result set.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class IBSIAnalysis(ParsedMultiwfnResult):
    """Complete IBSI analysis result set."""

    entries: list[IBSIEntry] = field(default_factory=list)

    def to_dict(self) -> dict[str, Any]:
        return {
            "entries": [asdict(e) for e in self.entries],
        }

IBSIEntry dataclass

Bases: ParsedMultiwfnResult

Single IBSI analysis entry between two atoms.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class IBSIEntry(ParsedMultiwfnResult):
    """Single IBSI analysis entry between two atoms."""

    atom1_id: int
    atom2_id: int
    distance: float
    int_dg_pair: float
    ibsi: float

LMOAtomContribution dataclass

Single atom contribution to a localized molecular orbital.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class LMOAtomContribution:
    """Single atom contribution to a localized molecular orbital."""

    atom_id: int
    atom_element: str
    contribution_pct: float

LambdaIndex dataclass

Bases: ParsedMultiwfnResult

Result for Lambda index.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class LambdaIndex(ParsedMultiwfnResult):
    """Result for Lambda index."""

    state_id: int
    lambda_index: float

LineProfile dataclass

Bases: ParsedMultiwfnResult

Summary statistics for a real-space function sampled along a line.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class LineProfile(ParsedMultiwfnResult):
    """Summary statistics for a real-space function sampled along a line."""

    origin_x_bohr: float | None = None
    origin_y_bohr: float | None = None
    origin_z_bohr: float | None = None
    end_x_bohr: float | None = None
    end_y_bohr: float | None = None
    end_z_bohr: float | None = None
    n_points: int | None = None
    minimum: float | None = None
    maximum: float | None = None
    sum_all_values: float | None = None
    integration_value: float | None = None

LocalizationConvergence dataclass

Convergence history for one localization run.

Parameters

orbital_set Which orbitals were localized: "occupied" or "unoccupied" or "all". n_cycles Number of cycles to convergence. final_p Final value of the localization functional p. converged Whether the localization converged successfully.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class LocalizationConvergence:
    """Convergence history for one localization run.

    Parameters
    ----------
    orbital_set
        Which orbitals were localized: ``"occupied"`` or
        ``"unoccupied"`` or ``"all"``.
    n_cycles
        Number of cycles to convergence.
    final_p
        Final value of the localization functional p.
    converged
        Whether the localization converged successfully.
    """

    orbital_set: str
    n_cycles: int = 0
    final_p: float | None = None
    converged: bool = False

LocalizationIndex dataclass

Bases: ParsedMultiwfnResult

Localization index for one atom.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class LocalizationIndex(ParsedMultiwfnResult):
    """Localization index for one atom."""

    atom_id: int
    index: float
    atom_element: str | None = None

LocalizedOrbital dataclass

Character of a single localized molecular orbital.

Parameters

orbital_id 1-based LMO index. category One of "single_center", "two_center", "delocalized". contributions Atom contributions listed for this LMO, ordered by decreasing percentage.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class LocalizedOrbital:
    """Character of a single localized molecular orbital.

    Parameters
    ----------
    orbital_id
        1-based LMO index.
    category
        One of ``"single_center"``, ``"two_center"``,
        ``"delocalized"``.
    contributions
        Atom contributions listed for this LMO, ordered by
        decreasing percentage.
    """

    orbital_id: int
    category: Literal["single_center", "two_center", "delocalized"]
    contributions: list[LMOAtomContribution] = field(default_factory=list)

MolecularMultipole dataclass

Bases: ParsedMultiwfnResult

Molecular dipole and multipole moments.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class MolecularMultipole(ParsedMultiwfnResult):
    """Molecular dipole and multipole moments."""

    total_electrons: float | None = None
    net_charge: float | None = None

    # Dipole
    dipole_x_au: float | None = None
    dipole_y_au: float | None = None
    dipole_z_au: float | None = None
    dipole_magnitude_au: float | None = None
    dipole_x_debye: float | None = None
    dipole_y_debye: float | None = None
    dipole_z_debye: float | None = None
    dipole_magnitude_debye: float | None = None

    # Quadrupole (traceless Cartesian)
    quadrupole_xx: float | None = None
    quadrupole_xy: float | None = None
    quadrupole_xz: float | None = None
    quadrupole_yy: float | None = None
    quadrupole_yz: float | None = None
    quadrupole_zz: float | None = None
    quadrupole_magnitude: float | None = None

    # Spatial extent
    spatial_extent_r2: float | None = None
    spatial_extent_x: float | None = None
    spatial_extent_y: float | None = None
    spatial_extent_z: float | None = None

    # Octopole magnitude
    octopole_magnitude: float | None = None

MultiCenterBondOrder dataclass

Bases: ParsedMultiwfnResult

Result for multi-center bond order analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class MultiCenterBondOrder(ParsedMultiwfnResult):
    """Result for multi-center bond order analysis."""

    atom_ids: list[int] = field(default_factory=list)
    bond_order: float = 0.0

MultipoleMoments dataclass

Bases: ParsedMultiwfnResult

Result for multipole moments.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class MultipoleMoments(ParsedMultiwfnResult):
    """Result for multipole moments."""

    moments: dict[str, float] = field(default_factory=dict)

MultiwfnResult

Container for parsed Multiwfn analysis results.

Each instance is bound to a single :class:Menu analysis type. After :meth:parse is called with raw stdout, the parsed :class:ParsedMultiwfnResult objects are available in :attr:result.

Parameters

analysis The Menu enum member identifying this analysis.

Source code in src/pymultiwfn/analysis/result.py

class MultiwfnResult:
    """Container for parsed Multiwfn analysis results.

    Each instance is bound to a single :class:`Menu` analysis type.
    After :meth:`parse` is called with raw stdout, the parsed
    :class:`ParsedMultiwfnResult` objects are available in
    :attr:`result`.

    Parameters
    ----------
    analysis
        The Menu enum member identifying this analysis.

    """

    def __init__(self, analysis: Menu) -> None:
        self.analysis: Menu = analysis
        self.result: list[ParsedMultiwfnResult] = []

    def parse(self, stdout: str) -> None:
        """Parse *stdout* using the router and store results.

        Imports :class:`ParserRoute` lazily to avoid circular imports
        (parsers.py imports dataclasses from this module).
        """
        from pymultiwfn.analysis.parsers import ParserRoute

        parser_cls = ParserRoute.ROUTE_TABLE.get(self.analysis)
        if parser_cls is None:
            return

        parsed = parser_cls.parse_for_result(self.analysis, stdout)
        if parsed:
            self.result.extend(parsed)

    # ── serialisation ────────────────────────────────────────────────────

    def to_dict(self) -> dict[str, Any]:
        """Serialise the result list to a JSON-safe dict."""
        return {
            "analysis": self.analysis.name,
            "results": [r.to_dict() for r in self.result],
        }

    def __repr__(self) -> str:
        return (
            f"MultiwfnResult(analysis={self.analysis.name!r}, "
            f"n_results={len(self.result)})"
        )

parse(stdout)

Parse stdout using the router and store results.

Imports :class:ParserRoute lazily to avoid circular imports (parsers.py imports dataclasses from this module).

Source code in src/pymultiwfn/analysis/result.py

def parse(self, stdout: str) -> None:
    """Parse *stdout* using the router and store results.

    Imports :class:`ParserRoute` lazily to avoid circular imports
    (parsers.py imports dataclasses from this module).
    """
    from pymultiwfn.analysis.parsers import ParserRoute

    parser_cls = ParserRoute.ROUTE_TABLE.get(self.analysis)
    if parser_cls is None:
        return

    parsed = parser_cls.parse_for_result(self.analysis, stdout)
    if parsed:
        self.result.extend(parsed)

to_dict()

Serialise the result list to a JSON-safe dict.

Source code in src/pymultiwfn/analysis/result.py

def to_dict(self) -> dict[str, Any]:
    """Serialise the result list to a JSON-safe dict."""
    return {
        "analysis": self.analysis.name,
        "results": [r.to_dict() for r in self.result],
    }

NCIAnalysis dataclass

Bases: ParsedMultiwfnResult

Result for NCI (RDG) analysis (Menu.NCI_ANALYSIS).

Multiwfn prints no NCI numbers to stdout; the RDG / sign(lambda2)rho data live in the scatter file and cube files. This records the grid the analysis was run on and where each output was written; the spikes are added from the scatter file when the output directory is scanned (see pymultiwfn.analysis.file_parsers).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class NCIAnalysis(ParsedMultiwfnResult):
    """Result for NCI (RDG) analysis (``Menu.NCI_ANALYSIS``).

    Multiwfn prints no NCI numbers to stdout; the RDG / sign(lambda2)rho
    data live in the scatter file and cube files. This records the grid
    the analysis was run on and where each output was written; the
    spikes are added from the scatter file when the output directory is
    scanned (see ``pymultiwfn.analysis.file_parsers``).
    """

    total_electrons: float | None = None
    grid_origin_bohr: list[float] | None = None
    grid_end_bohr: list[float] | None = None
    grid_spacing_bohr: list[float] | None = None
    grid_points_xyz: list[int] | None = None
    grid_points_total: int | None = None
    wall_time_s: float | None = None
    scatter_file: str | None = None
    sign_lambda2_rho_cube: str | None = None
    rdg_cube: str | None = None
    # Filled from the scatter file by scan_output_directory.
    spikes: list[NCISpike] | None = None

NCISpike dataclass

Bases: ParsedMultiwfnResult

One NCI interaction region (a low-RDG "spike" in the scatter plot).

Built from a spatially connected set of grid points with low RDG and low density. sign_lambda2_rho_at_min is the spike's position on the sign(lambda2)rho axis, read at the point of lowest RDG.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class NCISpike(ParsedMultiwfnResult):
    """One NCI interaction region (a low-RDG "spike" in the scatter plot).

    Built from a spatially connected set of grid points with low RDG and
    low density. ``sign_lambda2_rho_at_min`` is the spike's position on
    the sign(lambda2)rho axis, read at the point of lowest RDG.
    """

    interaction_type: Literal["attractive", "van_der_waals", "repulsive"]
    sign_lambda2_rho_at_min: float
    rdg_min: float
    sign_lambda2_rho_range: list[float]
    n_points: int
    volume_bohr3: float
    min_position_angstrom: list[float]
    centroid_angstrom: list[float]
    nearest_atoms: list[dict[str, Any]] | None = None

NICSScan dataclass

Bases: ParsedMultiwfnResult

Result for Nucleus Independent Chemical Shift scan.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class NICSScan(ParsedMultiwfnResult):
    """Result for Nucleus Independent Chemical Shift scan."""

    distances: list[float] = field(default_factory=list)
    values: list[float] = field(default_factory=list)

Orbital dataclass

Bases: ParsedMultiwfnResult

Orbital descriptor used by wavefunction and DOS parsers.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Orbital(ParsedMultiwfnResult):
    """Orbital descriptor used by wavefunction and DOS parsers."""

    orbital_id: int
    energy_au: float
    energy_eV: float  # noqa: N815
    occupation: float | None = None
    spin: Literal["alpha", "beta"] | None = None

OrbitalAtomComposition dataclass

Bases: ParsedMultiwfnResult

Per-atom contribution to an orbital (Hirshfeld/Becke/fragment methods).

Simpler than OrbitalBasisComposition — only atom-level contributions are available, no basis/shell breakdown.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalAtomComposition(ParsedMultiwfnResult):
    """Per-atom contribution to an orbital (Hirshfeld/Becke/fragment methods).

    Simpler than ``OrbitalBasisComposition`` — only atom-level
    contributions are available, no basis/shell breakdown.
    """

    method: str
    orbital_id: int
    energy_au: float
    occupation: float
    orbital_type: str = ""

    atom_contributions: list[OrbitalAtomEntry] = field(default_factory=list)
    delocalization_index: float | None = None
    sum_before_normalization: float | None = None

OrbitalAtomEntry dataclass

Single atom contribution to an orbital.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalAtomEntry:
    """Single atom contribution to an orbital."""

    atom_id: int
    atom_element: str
    composition_pct: float

OrbitalBasisComposition dataclass

Bases: ParsedMultiwfnResult

Per-basis-function contribution to an orbital.

Each orbital that has detailed composition output produces one of these containers. The method field distinguishes which decomposition scheme was used (Mulliken/SCPA/Stout-Politzer).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalBasisComposition(ParsedMultiwfnResult):
    """Per-basis-function contribution to an orbital.

    Each orbital that has detailed composition output produces one
    of these containers.  The ``method`` field distinguishes which
    decomposition scheme was used (Mulliken/SCPA/Stout-Politzer).
    """

    method: str
    orbital_id: int
    energy_au: float
    occupation: float
    orbital_type: str = ""

    # Per-basis contributions
    basis_contributions: list[OrbitalBasisEntry] = field(default_factory=list)

    # Per-shell contributions
    shell_contributions: list[OrbitalShellEntry] = field(default_factory=list)

    # Per-shell-type (angular momentum) contributions
    shell_type_composition: OrbitalShellTypeComposition | None = None

    # Per-atom contributions
    atom_contributions: list[OrbitalAtomEntry] = field(default_factory=list)

    # Summary
    delocalization_index: float | None = None

OrbitalBasisEntry dataclass

Single basis function contribution to an orbital.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalBasisEntry:
    """Single basis function contribution to an orbital."""

    basis_index: int
    function_type: str
    atom_id: int
    atom_element: str
    shell_index: int
    local_pct: float
    cross_pct: float
    total_pct: float

OrbitalEnergy dataclass

Bases: ParsedMultiwfnResult

Orbital energy and occupation entry.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalEnergy(ParsedMultiwfnResult):
    """Orbital energy and occupation entry."""

    index: int
    energy_eV: float  # noqa: N815
    occupation: float

OrbitalLocalizationResult dataclass

Bases: ParsedMultiwfnResult

Complete result for one orbital localization run.

Each Menu sequence (e.g. Pipek-Mezey/Hirshfeld/occupied) produces one of these. The method, population_scheme, and orbital_set together uniquely identify the calculation.

Parameters

method Localization method: "pipek_mezey" or "boys". population_scheme Population analysis used for Pipek-Mezey: "hirshfeld", "lowdin", "becke". None for Boys. orbital_set Which orbitals: "occupied", "all". convergence Convergence history for each sub-run (occupied and/or unoccupied). occupied_lmos Character of occupied LMOs. unoccupied_lmos Character of unoccupied LMOs (only present for "all" runs). exported_file Name of the exported file, if any.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalLocalizationResult(ParsedMultiwfnResult):
    """Complete result for one orbital localization run.

    Each ``Menu`` sequence (e.g. Pipek-Mezey/Hirshfeld/occupied)
    produces one of these.  The ``method``, ``population_scheme``,
    and ``orbital_set`` together uniquely identify the calculation.

    Parameters
    ----------
    method
        Localization method: ``"pipek_mezey"`` or ``"boys"``.
    population_scheme
        Population analysis used for Pipek-Mezey: ``"hirshfeld"``,
        ``"lowdin"``, ``"becke"``.  ``None`` for Boys.
    orbital_set
        Which orbitals: ``"occupied"``, ``"all"``.
    convergence
        Convergence history for each sub-run (occupied and/or
        unoccupied).
    occupied_lmos
        Character of occupied LMOs.
    unoccupied_lmos
        Character of unoccupied LMOs (only present for "all"
        runs).
    exported_file
        Name of the exported file, if any.
    """

    method: str
    population_scheme: str | None = None
    orbital_set: str = ""

    convergence: list[LocalizationConvergence] = field(default_factory=list)
    occupied_lmos: list[LocalizedOrbital] = field(default_factory=list)
    unoccupied_lmos: list[LocalizedOrbital] = field(default_factory=list)
    exported_file: str | None = None

OrbitalShellEntry dataclass

Single shell contribution to an orbital.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalShellEntry:
    """Single shell contribution to an orbital."""

    shell_index: int
    shell_type: str
    atom_id: int
    atom_element: str
    composition_pct: float

OrbitalShellTypeComposition dataclass

Angular momentum type composition of an orbital.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalShellTypeComposition:
    """Angular momentum type composition of an orbital."""

    s: float = 0.0
    p: float = 0.0
    d: float = 0.0
    f: float = 0.0
    g: float = 0.0
    h: float = 0.0

OrbitalWeightDecomposition dataclass

Bases: ParsedMultiwfnResult

Decomposition of orbital-weighted Fukui into orbital contributions.

Parameters

fukui_type Which Fukui function: "f+", "f-".

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalWeightDecomposition(ParsedMultiwfnResult):
    """Decomposition of orbital-weighted Fukui into orbital contributions.

    Parameters
    ----------
    fukui_type
        Which Fukui function: ``"f+"``, ``"f-"``.
    """

    fukui_type: str
    entries: list[OrbitalWeightEntry] = field(default_factory=list)
    total_weight_pct: float | None = None

OrbitalWeightEntry dataclass

Single orbital's weight in f+ or f- decomposition.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalWeightEntry:
    """Single orbital's weight in f+ or f- decomposition."""

    orbital_id: int
    orbital_label: str
    weight_pct: float
    e_diff_eV: float  # noqa: N815

OrbitalWeightedFukuiEntry dataclass

Per-atom orbital-weighted Fukui values.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalWeightedFukuiEntry:
    """Per-atom orbital-weighted Fukui values."""

    atom_id: int
    atom_element: str
    ow_f_plus: float
    ow_f_minus: float
    ow_f_zero: float
    ow_dd: float

OrbitalWeightedFukuiResult dataclass

Bases: ParsedMultiwfnResult

Complete orbital-weighted Fukui analysis.

Contains per-atom values and sums of f+ and f-.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OrbitalWeightedFukuiResult(ParsedMultiwfnResult):
    """Complete orbital-weighted Fukui analysis.

    Contains per-atom values and sums of f+ and f-.
    """

    entries: list[OrbitalWeightedFukuiEntry] = field(default_factory=list)
    sum_ow_f_plus: float | None = None
    sum_ow_f_minus: float | None = None

OverlapIntegrationMatrix dataclass

Bases: ParsedMultiwfnResult

Overlap region integration matrix for one sign category.

Parameters

category One of "positive", "negative", "all".

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OverlapIntegrationMatrix(ParsedMultiwfnResult):
    """Overlap region integration matrix for one sign category.

    Parameters
    ----------
    category
        One of ``"positive"``, ``"negative"``, ``"all"``.
    """

    category: str
    integrated_property: str = ""
    n_atoms: int = 0
    data: dict[tuple[int, int], float] = field(default_factory=dict)
    sum_diagonal: float | None = None
    sum_nondiagonal: float | None = None
    sum_all: float | None = None

OxidationState dataclass

Bases: ParsedMultiwfnResult

Integer oxidation state inferred for one atom.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class OxidationState(ParsedMultiwfnResult):
    """Integer oxidation state inferred for one atom."""

    atom_id: int
    oxidation_state: int

ParsedMultiwfnResult dataclass

Base class for all Multiwfn parsed result types.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class ParsedMultiwfnResult:
    """Base class for all Multiwfn parsed result types."""

    def to_dict(self) -> dict[str, Any]:
        """Serialise to a plain dict (JSON-safe)."""
        return asdict(self)

to_dict()

Serialise to a plain dict (JSON-safe).

Source code in src/pymultiwfn/analysis/result.py

def to_dict(self) -> dict[str, Any]:
    """Serialise to a plain dict (JSON-safe)."""
    return asdict(self)

PlaneMap dataclass

Bases: ParsedMultiwfnResult

Summary statistics for a real-space function mapped onto a plane.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class PlaneMap(ParsedMultiwfnResult):
    """Summary statistics for a real-space function mapped onto a plane."""

    origin_x_bohr: float | None = None
    origin_y_bohr: float | None = None
    origin_z_bohr: float | None = None
    end_x_bohr: float | None = None
    end_y_bohr: float | None = None
    end_z_bohr: float | None = None
    minimum: float | None = None
    maximum: float | None = None

PoincareHopfCounts dataclass

Bases: ParsedMultiwfnResult

Critical point counts and Poincare-Hopf verification.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class PoincareHopfCounts(ParsedMultiwfnResult):
    """Critical point counts and Poincare-Hopf verification."""

    nuclear: int = 0
    bond: int = 0
    ring: int = 0
    cage: int = 0
    satisfied: bool = False

Polarizability dataclass

Bases: ParsedMultiwfnResult

Result for polarizability.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Polarizability(ParsedMultiwfnResult):
    """Result for polarizability."""

    isotropic: float | None = None
    anisotropic: float | None = None
    beta_total: float | None = None
    gamma_total: float | None = None
    tensor: PolarizabilityTensor | None = None

PolarizabilityTensor dataclass

Bases: ParsedMultiwfnResult

Result for polarizability tensor.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class PolarizabilityTensor(ParsedMultiwfnResult):
    """Result for polarizability tensor."""

    alpha_xx: float = 0.0
    alpha_xy: float = 0.0
    alpha_xz: float = 0.0
    alpha_yy: float = 0.0
    alpha_yz: float = 0.0
    alpha_zz: float = 0.0

QuadrupoleMoment dataclass

Bases: ParsedMultiwfnResult

Result for quadrupole moment analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class QuadrupoleMoment(ParsedMultiwfnResult):
    """Result for quadrupole moment analysis."""

    xx: float | None = None
    xy: float | None = None
    xz: float | None = None
    yy: float | None = None
    yz: float | None = None
    zz: float | None = None

Reactivity dataclass

Bases: ParsedMultiwfnResult

Result for global reactivity indices.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Reactivity(ParsedMultiwfnResult):
    """Result for global reactivity indices."""

    chemical_potential: float | None = None
    chemical_potential_eV: float | None = None  # noqa: N815
    hardness: float | None = None
    softness: float | None = None
    electrophilicity: float | None = None
    nucleophilicity: float | None = None
    ionization_potential: float | None = None
    electron_affinity: float | None = None
    homo_energy_au: float | None = None
    homo_energy_eV: float | None = None  # noqa: N815
    lumo_energy_au: float | None = None
    lumo_energy_eV: float | None = None  # noqa: N815
    delta_parameter_au: float | None = None
    delta_parameter_eV: float | None = None  # noqa: N815

ResultStore

Per-molecule result store with optional JSON persistence.

Parsed results are always cached in memory so that :meth:has_result and :meth:get_result work regardless of whether a JSON file exists on disk.

Parameters

input_file Path to the wavefunction input file. work_dir Directory used for the working data. Created if it does not exist. json_path Controls JSON persistence:

* ``None`` (the default) — results are cached in memory only;
  no file is written to disk.
* A :class:`~pathlib.Path` — results are written to that exact
  file every time :meth:`store` is called.  If the file already
  exists it is loaded on construction so that previous results
  are available immediately.

The value can be changed at any time via the :attr:`json_path`
property.  Setting it from ``None`` to a ``Path`` will
immediately flush the current in-memory data to disk.

Source code in src/pymultiwfn/analysis/result.py

class ResultStore:
    """Per-molecule result store with optional JSON persistence.

    Parsed results are always cached in memory so that
    :meth:`has_result` and :meth:`get_result` work regardless of
    whether a JSON file exists on disk.

    Parameters
    ----------
    input_file
        Path to the wavefunction input file.
    work_dir
        Directory used for the working data.  Created if it does not
        exist.
    json_path
        Controls JSON persistence:

        * ``None`` (the default) — results are cached in memory only;
          no file is written to disk.
        * A :class:`~pathlib.Path` — results are written to that exact
          file every time :meth:`store` is called.  If the file already
          exists it is loaded on construction so that previous results
          are available immediately.

        The value can be changed at any time via the :attr:`json_path`
        property.  Setting it from ``None`` to a ``Path`` will
        immediately flush the current in-memory data to disk.

    """

    def __init__(
        self,
        input_file: Path,
        work_dir: Path,
        json_path: Path | None = None,
    ) -> None:
        self._input_file = Path(input_file)
        self._work_dir = Path(work_dir)
        self._work_dir.mkdir(parents=True, exist_ok=True)

        self._json_path: Path | None = (
            Path(json_path) if json_path is not None else None
        )
        self._data: dict[str, Any] = self._load()

    @property
    def json_path(self) -> Path | None:
        """Path to the JSON file, or ``None`` if persistence is disabled."""
        return self._json_path

    @json_path.setter
    def json_path(self, value: Path | None) -> None:
        self._json_path = Path(value) if value is not None else None
        if self._json_path is not None:
            # Flush current in-memory data to disk immediately.
            self._save()

    @property
    def data(self) -> dict[str, Any]:
        """Return a *copy* of the stored data."""
        return dict(self._data)

    # ── persistence ──────────────────────────────────────────────────────

    def _load(self) -> dict[str, Any]:
        if self._json_path is not None and self._json_path.exists():
            with Path.open(self._json_path, encoding="utf-8") as f:
                return json.load(f)
        return {
            "input_file": str(self._input_file),
            "analyses": {},
        }

    def _save(self) -> None:
        if self._json_path is None:
            return
        self._json_path.parent.mkdir(parents=True, exist_ok=True)
        with Path.open(self._json_path, "w", encoding="utf-8") as f:
            json.dump(self._data, f, indent=2, default=str)

    # ── read / write ─────────────────────────────────────────────────────

    def has_result(self, analysis: Menu) -> bool:
        """Check whether a parsed result already exists for *analysis*."""
        return analysis.name in self._data.get("analyses", {})

    def get_result(self, analysis: Menu) -> dict[str, Any] | None:
        """Retrieve a previously stored parsed result, or ``None``."""
        return self._data.get("analyses", {}).get(analysis.name)

    def store(self, mwfn_result: MultiwfnResult) -> None:
        """Cache a :class:`MultiwfnResult` in memory.

        If :attr:`json_path` is not ``None``, the result is also
        written to the JSON file on disk.

        Parameters
        ----------
        mwfn_result
            A fully parsed ``MultiwfnResult`` whose ``.result`` list
            is non-empty.

        """
        if not mwfn_result.result:
            return

        entry: dict[str, Any] = {
            "parsed": mwfn_result.to_dict(),
            "timestamp": datetime.now().isoformat(),
        }
        self._data.setdefault("analyses", {})[mwfn_result.analysis.name] = entry
        self._save()

    def store_scan(self, output_dir: Path, scan: dict[str, Any]) -> None:
        """Merge a directory scan into the store.

        This is the counterpart to :meth:`store` for the file-based
        parsing pipeline: rather than one analysis at a time, it merges
        the *whole* result of scanning a molecule's flat output
        directory (see
        :func:`pymultiwfn.analysis.file_parsers.scan_output_directory`)
        in a single call. Existing entries are updated rather than
        replaced, so calling this repeatedly (e.g. across runs that
        reuse cached analyses) only adds to what is already stored.

        Parameters
        ----------
        output_dir
            The molecule's flat output directory that was scanned.
        scan
            The dict returned by ``scan_output_directory`` for
            *output_dir*.

        """
        self._data["output_dir"] = str(output_dir)

        existing_files = set(self._data.get("generated_files", []))
        existing_files.update(scan.get("generated_files", []))
        self._data["generated_files"] = sorted(existing_files)

        analyses = self._data.setdefault("analyses", {})
        timestamp = datetime.now().isoformat()
        for name, entry in scan.get("analyses", {}).items():
            analyses[name] = {**entry, "timestamp": timestamp}

        self._save()

    def store_from_stdout(
        self,
        analysis: Menu,
        stdout: str,
    ) -> MultiwfnResult | None:
        """Parse *stdout*, persist, and return the :class:`MultiwfnResult`.

        Convenience method combining :meth:`MultiwfnResult.parse` and
        :meth:`store` in a single call.

        Returns ``None`` if no parser is available or parsing yields no
        results.
        """
        result = MultiwfnResult(analysis=analysis)
        result.parse(stdout)
        if not result.result:
            return None
        self.store(result)
        return result

data property

Return a copy of the stored data.

json_path property writable

Path to the JSON file, or None if persistence is disabled.

get_result(analysis)

Retrieve a previously stored parsed result, or None.

Source code in src/pymultiwfn/analysis/result.py

def get_result(self, analysis: Menu) -> dict[str, Any] | None:
    """Retrieve a previously stored parsed result, or ``None``."""
    return self._data.get("analyses", {}).get(analysis.name)

has_result(analysis)

Check whether a parsed result already exists for analysis.

Source code in src/pymultiwfn/analysis/result.py

def has_result(self, analysis: Menu) -> bool:
    """Check whether a parsed result already exists for *analysis*."""
    return analysis.name in self._data.get("analyses", {})

store(mwfn_result)

Cache a :class:MultiwfnResult in memory.

If :attr:json_path is not None, the result is also written to the JSON file on disk.

Parameters

mwfn_result A fully parsed MultiwfnResult whose .result list is non-empty.

Source code in src/pymultiwfn/analysis/result.py

def store(self, mwfn_result: MultiwfnResult) -> None:
    """Cache a :class:`MultiwfnResult` in memory.

    If :attr:`json_path` is not ``None``, the result is also
    written to the JSON file on disk.

    Parameters
    ----------
    mwfn_result
        A fully parsed ``MultiwfnResult`` whose ``.result`` list
        is non-empty.

    """
    if not mwfn_result.result:
        return

    entry: dict[str, Any] = {
        "parsed": mwfn_result.to_dict(),
        "timestamp": datetime.now().isoformat(),
    }
    self._data.setdefault("analyses", {})[mwfn_result.analysis.name] = entry
    self._save()

store_from_stdout(analysis, stdout)

Parse stdout, persist, and return the :class:MultiwfnResult.

Convenience method combining :meth:MultiwfnResult.parse and :meth:store in a single call.

Returns None if no parser is available or parsing yields no results.

Source code in src/pymultiwfn/analysis/result.py

def store_from_stdout(
    self,
    analysis: Menu,
    stdout: str,
) -> MultiwfnResult | None:
    """Parse *stdout*, persist, and return the :class:`MultiwfnResult`.

    Convenience method combining :meth:`MultiwfnResult.parse` and
    :meth:`store` in a single call.

    Returns ``None`` if no parser is available or parsing yields no
    results.
    """
    result = MultiwfnResult(analysis=analysis)
    result.parse(stdout)
    if not result.result:
        return None
    self.store(result)
    return result

store_scan(output_dir, scan)

Merge a directory scan into the store.

This is the counterpart to :meth:store for the file-based parsing pipeline: rather than one analysis at a time, it merges the whole result of scanning a molecule's flat output directory (see :func:pymultiwfn.analysis.file_parsers.scan_output_directory) in a single call. Existing entries are updated rather than replaced, so calling this repeatedly (e.g. across runs that reuse cached analyses) only adds to what is already stored.

Parameters

output_dir The molecule's flat output directory that was scanned. scan The dict returned by scan_output_directory for output_dir.

Source code in src/pymultiwfn/analysis/result.py

def store_scan(self, output_dir: Path, scan: dict[str, Any]) -> None:
    """Merge a directory scan into the store.

    This is the counterpart to :meth:`store` for the file-based
    parsing pipeline: rather than one analysis at a time, it merges
    the *whole* result of scanning a molecule's flat output
    directory (see
    :func:`pymultiwfn.analysis.file_parsers.scan_output_directory`)
    in a single call. Existing entries are updated rather than
    replaced, so calling this repeatedly (e.g. across runs that
    reuse cached analyses) only adds to what is already stored.

    Parameters
    ----------
    output_dir
        The molecule's flat output directory that was scanned.
    scan
        The dict returned by ``scan_output_directory`` for
        *output_dir*.

    """
    self._data["output_dir"] = str(output_dir)

    existing_files = set(self._data.get("generated_files", []))
    existing_files.update(scan.get("generated_files", []))
    self._data["generated_files"] = sorted(existing_files)

    analyses = self._data.setdefault("analyses", {})
    timestamp = datetime.now().isoformat()
    for name, entry in scan.get("analyses", {}).items():
        analyses[name] = {**entry, "timestamp": timestamp}

    self._save()

Spectrum dataclass

Bases: ParsedMultiwfnResult

Result for spectrum analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Spectrum(ParsedMultiwfnResult):
    """Result for spectrum analysis."""

    maximum: list[int] | None = None
    X: list[float] | None = None
    value: list[float] | None = None
    frequencies: list[float] | None = None
    intensities: list[float] | None = None
    wavelengths: list[float] | None = None
    atom_indices: list[int] | None = None
    chemical_shifts: list[float] | None = None

SpectrumCurveExtrema dataclass

Bases: ParsedMultiwfnResult

Collection of extrema reported for a spectrum curve.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SpectrumCurveExtrema(ParsedMultiwfnResult):
    """Collection of extrema reported for a spectrum curve."""

    extrema: list[SpectrumExtremum] = field(default_factory=list)

SpectrumExtremum dataclass

Bases: ParsedMultiwfnResult

Single extremum point on a simulated spectrum curve.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SpectrumExtremum(ParsedMultiwfnResult):
    """Single extremum point on a simulated spectrum curve."""

    kind: Literal["maximum", "minimum"]
    index: int
    x: float
    value: float

SuperdelocalizabilityEntry dataclass

Per-atom superdelocalizability values.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SuperdelocalizabilityEntry:
    """Per-atom superdelocalizability values."""

    atom_id: int
    atom_element: str
    d_n: float
    d_e: float
    d_n_0: float
    d_e_0: float

SuperdelocalizabilityResult dataclass

Bases: ParsedMultiwfnResult

Complete superdelocalizability analysis.

Contains the alpha parameter, per-atom values, and sums.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SuperdelocalizabilityResult(ParsedMultiwfnResult):
    """Complete superdelocalizability analysis.

    Contains the alpha parameter, per-atom values, and sums.
    """

    alpha_parameter: float | None = None
    entries: list[SuperdelocalizabilityEntry] = field(default_factory=list)
    sum_d_n: float | None = None
    sum_d_e: float | None = None
    sum_d_n_0: float | None = None
    sum_d_e_0: float | None = None

    def to_dict(self) -> dict[str, Any]:
        return {
            "alpha_parameter": self.alpha_parameter,
            "entries": [asdict(e) for e in self.entries],
            "sum_d_n": self.sum_d_n,
            "sum_d_e": self.sum_d_e,
            "sum_d_n_0": self.sum_d_n_0,
            "sum_d_e_0": self.sum_d_e_0,
        }

SurfaceAnalysisResult dataclass

Bases: ParsedMultiwfnResult

Complete surface analysis for one mapped property.

Bundles geometry, extrema, and statistics so that each sequence (ESP, ALIE, etc.) is stored as a single coherent result that won't overwrite other sequences.

Parameters

mapped_property Standardized identifier: "esp", "alie", "lea", "leae", "edr", "maxedr", "edensity", "lambda2_rho".

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SurfaceAnalysisResult(ParsedMultiwfnResult):
    """Complete surface analysis for one mapped property.

    Bundles geometry, extrema, and statistics so that each
    sequence (ESP, ALIE, etc.) is stored as a single coherent
    result that won't overwrite other sequences.

    Parameters
    ----------
    mapped_property
        Standardized identifier: ``"esp"``, ``"alie"``, ``"lea"``,
        ``"leae"``, ``"edr"``, ``"maxedr"``, ``"edensity"``,
        ``"lambda2_rho"``.
    """

    mapped_property: str
    geometry: SurfaceGeometry | None = None
    minima: list[SurfaceExtremum] = field(default_factory=list)
    maxima: list[SurfaceExtremum] = field(default_factory=list)
    statistics: SurfaceStatistics | None = None

    @property
    def area(self) -> float | None:
        if self.geometry is None:
            return None
        return self.geometry.area_angstrom2

    @property
    def volume(self) -> float | None:
        if self.geometry is None:
            return None
        return self.geometry.volume_angstrom3

    @property
    def V_S_plus(self) -> float | None:  # noqa: N802
        if self.statistics is None:
            return None
        return self.statistics.positive_surface_volume

    @property
    def V_S_minus(self) -> float | None:  # noqa: N802
        if self.statistics is None:
            return None
        return self.statistics.negative_surface_volume

SurfaceExtremum dataclass

Bases: ParsedMultiwfnResult

A single surface extremum (minimum or maximum).

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SurfaceExtremum(ParsedMultiwfnResult):
    """A single surface extremum (minimum or maximum)."""

    type: Literal["min", "max"]
    index: int
    value_au: float
    value_eV: float  # noqa: N815
    value_kcal_mol: float
    x_angstrom: float
    y_angstrom: float
    z_angstrom: float
    is_global: bool = False

SurfaceGeometry dataclass

Bases: ParsedMultiwfnResult

Isosurface geometry statistics.

Extracted once per surface calculation regardless of mapped property.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SurfaceGeometry(ParsedMultiwfnResult):
    """Isosurface geometry statistics.

    Extracted once per surface calculation regardless of mapped
    property.
    """

    volume_bohr3: float | None = None
    volume_angstrom3: float | None = None
    area_bohr2: float | None = None
    area_angstrom2: float | None = None
    sphericity: float | None = None
    density_g_cm3: float | None = None
    n_vertices: int | None = None
    n_edges: int | None = None
    n_facets: int | None = None

SurfaceStatistics dataclass

Bases: ParsedMultiwfnResult

Summary statistics for a mapped surface property.

Parameters

mapped_property Standardized identifier for what was mapped onto the surface. One of: "esp", "alie", "lea", "leae", "edr", "maxedr", "edensity", "lambda2_rho".

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class SurfaceStatistics(ParsedMultiwfnResult):
    """Summary statistics for a mapped surface property.

    Parameters
    ----------
    mapped_property
        Standardized identifier for what was mapped onto the
        surface.  One of: ``"esp"``, ``"alie"``, ``"lea"``,
        ``"leae"``, ``"edr"``, ``"maxedr"``, ``"edensity"``,
        ``"lambda2_rho"``.
    """

    mapped_property: str

    # Global extrema
    global_min_au: float | None = None
    global_max_au: float | None = None
    global_min_kcal_mol: float | None = None
    global_max_kcal_mol: float | None = None

    # Area breakdown
    overall_area_bohr2: float | None = None
    overall_area_angstrom2: float | None = None
    positive_area_bohr2: float | None = None
    positive_area_angstrom2: float | None = None
    negative_area_bohr2: float | None = None
    negative_area_angstrom2: float | None = None

    # Averages
    overall_average_au: float | None = None
    overall_average_kcal_mol: float | None = None
    positive_average_au: float | None = None
    positive_average_kcal_mol: float | None = None
    negative_average_au: float | None = None
    negative_average_kcal_mol: float | None = None

    # Variances
    sigma2_total_au2: float | None = None
    sigma2_total_kcal_mol2: float | None = None
    positive_variance_au2: float | None = None
    positive_variance_kcal_mol2: float | None = None
    negative_variance_au2: float | None = None
    negative_variance_kcal_mol2: float | None = None

    # Descriptors
    nu: float | None = None
    sigma2_tot_times_nu_au2: float | None = None
    sigma2_tot_times_nu_kcal_mol2: float | None = None
    pi_au: float | None = None
    pi_kcal_mol: float | None = None
    mpi_eV: float | None = None  # noqa: N815
    mpi_kcal_mol: float | None = None

    # Polar surface area
    nonpolar_area_angstrom2: float | None = None
    nonpolar_area_pct: float | None = None
    polar_area_angstrom2: float | None = None
    polar_area_pct: float | None = None

    # Skewness
    overall_skewness: float | None = None
    positive_skewness: float | None = None
    negative_skewness: float | None = None

    negative_area_pct: float | None = None

    positive_surface_volume: float | None = None
    negative_surface_volume: float | None = None

TopologyPath dataclass

Bases: ParsedMultiwfnResult

A gradient path connecting two critical points.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class TopologyPath(ParsedMultiwfnResult):
    """A gradient path connecting two critical points."""

    path_id: int
    bcp_index: int
    bcp_type: Literal["nuclear", "bond", "ring", "cage", "unknown"]
    target_cp_index: int
    target_cp_type: Literal["nuclear", "bond", "ring", "cage", "unknown"]
    length_bohr: float

    @property
    def atom1_id(self) -> int:
        return self.bcp_index

    @property
    def atom2_id(self) -> int:
        return self.target_cp_index

    @property
    def path_length(self) -> float:
        return self.length_bohr

Transition dataclass

Bases: ParsedMultiwfnResult

Result for transition analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Transition(ParsedMultiwfnResult):
    """Result for transition analysis."""

    state: int
    energy_eV: float  # noqa: N815
    wavelength_nm: float
    osc_strength: float
    rot_strength: float | None = None

Valence dataclass

Bases: ParsedMultiwfnResult

Result for valence analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class Valence(ParsedMultiwfnResult):
    """Result for valence analysis."""

    atom_id: int
    type: Literal["total_valence", "free_valence"]
    valence: float

WeakInteraction dataclass

Bases: ParsedMultiwfnResult

Result for weak interaction analysis.

Source code in src/pymultiwfn/analysis/result.py

@dataclass
class WeakInteraction(ParsedMultiwfnResult):
    """Result for weak interaction analysis."""

    delta_g_inter: float = 0.0
    delta_g_intra: float = 0.0
    isosurface_integral: float | None = None
    cube_names: list[str] | None = None