Python API reference

Load a file, check its capabilities, and run an available analysis. This page lists the public Python functions, their parameters and the returned fields. Source-output extraction remains Experimental; reading a file does not make every analysis available.

The stable import surface is declared by openwfn.__all__. Import from openwfn rather than internal modules when possible.

Public import inventory

Name	Role
read_fchk	Read FCHK records
parse_fchk_arrays	Parse atomic arrays
parse_fchk_scalars	Parse scalar metadata
parse_fchk_density	Parse density matrices
parse_fchk_basis	Parse basis data
parse_fchk_mos	Parse molecular-orbital data
distance	Cartesian distance
angle	Three-point angle
dihedral	Signed torsion
detect_bonds	Covalent-radius bond heuristic
MolecularGraph	Molecular graph type
build_graph	Build connectivity and fragments
eval_s_type_gto	Evaluate an s-type Gaussian function
compute_density	Evaluate compatible density data
evaluate_mo	Evaluate a molecular orbital
make_bounding_box_grid	Build a Cartesian molecular grid
export_vtk	Write a VTK scalar grid
export_json	Write JSON properties
export_csv	Write a CSV point table
export_molecule_viewer	Write a standalone molecular viewer
OpenWFNCalculation	High-level calculation API
OpenWFNData	Canonical interoperable input record
StructureData	Atomic structure component
PeriodicData	Periodic-cell component
IntegralData	Explicit integral collection
IntegralTerm	Integral entry
SourceMetadata	Normalized source metadata
INTEROP_SCHEMA_VERSION	Interoperability model schema identifier
Capability	Inferred data-availability record
CapabilityRequirement	Named requirement for an analysis
infer_capabilities	Inspect canonical data components
MODEL_SCHEMA_VERSION	Model schema identifier
BoundaryConditions	Boundary-condition record
CalculationData	Canonical calculation model
Provenance	Input provenance record
RESULT_SCHEMA_VERSION	Result schema identifier
ResultRecord	Versioned analysis result
BATCH_SCHEMA_VERSION	Batch manifest schema identifier
available_analyses	List registered analysis names
discover_inputs	Discover batch inputs
run_analysis	Run one registered analysis
run_batch	Run batch analyses
load	Load a high-level calculation
read_output	Extract source-reported QC text-output properties into a ResultRecord

Source-reported output properties

read_output(path) -> ResultRecord

This Experimental function uses cclib==1.8.1, included in the normal installation. It reads QC text output directly, independently of load() and the wavefunction-analysis registry:

from openwfn import read_output

result = read_output("calculation.out")
print(result.as_dict())

Coordinates and dipole origin are in angstrom; SCF energy in hartree; dipole in Debye; frontier energies in eV; atomic charges in elementary-charge units. Orbital indices are 1-based. Missing fields remain null or empty. Printed atomic charges are source-reported, not recalculated population results. SCF energy is not substituted for correlated or thermal energy, and normal termination does not establish optimization convergence. Unconfirmed termination, missing SCF energy, or diagnostic warnings return a partial result.

The function raises DataUnavailableError when the reader is unavailable or the output is unrecognized, ValueError for malformed/nonfinite selected properties, and filesystem exceptions for unreadable paths. Provenance records the input hash, parser/software versions and source path. See output properties for current evidence and limits.

Loading and models

load(path, *, format_hint=None) -> OpenWFNCalculation

Load a supported file through native ingestion or the IOData 1.0.1 adapter. The returned object exposes OpenWFNData via .data; it may hold structure, a full isolated calculation, periodic data, grids, integrals, and metadata as separate optional components. Only use molecular analysis methods when their required records are present. Check calculation.capabilities() or the capability reference first for mixed inputs. For an ambiguous filename, pass a registered format ID explicitly:

from openwfn import load

calculation = load("water.dat", format_hint="gamess")
print(calculation.capabilities())

OpenWFNCalculation

Top-level calculation model used by the current analysis stack. Check optional fields before electronic analyses.

Method	Contract
analyze(name, **parameters)	Preferred reproducible route for a registered named analysis
capabilities()	Inferred component states (available, derived, or missing) for this loaded file
analyze_geometry()	Basic atom count, charge, and multiplicity
geometry_distance(i, j)	Distance in ångströms; one-based atom numbers
geometry_angle(i, j, k)	Angle in degrees; one-based atom numbers
geometry_dihedral(i, j, k, l)	Signed torsion in degrees; one-based atom numbers
orbitals(spin)	Frontier orbitals for "alpha", "beta", or spin-complete "all"
population(method)	Populations for "mulliken", "lowdin" or "hirshfeld"
density(kind, spacing_bohr=0.15, padding_bohr=6.0)	Grid integration for "total", "alpha", "beta", or "spin"
nci_cube(output, field="signed_density", ...)	Experimental total-density NCI cube for rho, lambda2, signed_density, or bounded rdg

Analysis methods return ResultRecord. Specialized methods are convenience interfaces; use analyze(name) when analysis identity, registry version, and elapsed time are important to an automated workflow. Every high-level result includes available source provenance and parser warnings. Unsupported option values can raise ValueError. Registered analyses and methods such as density() and esp() return failed ResultRecord objects for missing data; check .status and .error before reading scientific values. Low-level evaluators and some geometry preconditions can raise DataUnavailableError. analyze_geometry() also reports known physical nuclei, ghosts, and unknown effective-charge centers. A structure-only analyze("summary") returns a partial result; missing electronic values remain None.

Excited-state analyses use the same generic API and remain Experimental:

calculation = load("tddft.log")
states = calculation.analyze("excited-states")
state2 = calculation.analyze("excited-state", state=2)
dipoles = calculation.analyze("transition-dipoles")
uvvis = calculation.analyze("uvvis-spectrum", fwhm_ev=0.20, points=1501)

State and job selectors are one-based. Gaussian, ORCA, and Q-Chem source adapters normalize source-reported states into one typed model while preserving method family/detail and source-specific conventions. UV–Vis broadening is derived post-processing; source oscillator strengths remain authoritative. See Excited states and UV–Vis.

Model schema

MODEL_SCHEMA_VERSION is "2.0". Molecule.boundary_conditions accepts isolated systems only. Periodic structures can be loaded as separate data components, but do not enable periodic wavefunction analysis.

Provenance records the source path, SHA-256 checksum, parser name, source format, parser version, warnings, and named transformations. These fields make ingestion decisions traceable without changing scientific values. Existing constructor forms covered by the compatibility tests remain supported. StructureData.effective_nuclear_charges preserves source-provided zero ghost charges and modified ECP charges separately from atomic numbers. An absent charge stays unknown and is never inferred from the element symbol.

Migration from 0.8

The high-level .data property now exposes OpenWFNData, not just CalculationData. For a complete FCHK wavefunction, .data.calculation contains the prior canonical calculation, and the high-level .molecule property still provides the same molecule. Existing FCHK CLI commands retain their meaning and native FCHK remains the preferred parser. Scripts that access .data.molecule, .data.basis, or .data.alpha_orbitals directly should migrate to .data.calculation or use the high-level methods. Structure- only, periodic, grid-only, and integral-only files do not fabricate a complete wavefunction. Pin the exact package version when reproducing published work.

Scientific result safeguards

For Gaussian formatted-checkpoint inputs, openWFN preserves source electronic metadata instead of reconstructing it when the file provides the authoritative record. FCHK Nuclear charges supplies effective nuclear charges for ECP and ghost centers. FCHK Number of electrons is the preferred total-electron expectation for density conservation; alpha and beta electron records are used for spin-resolved expectations. If a required source value is absent, the deterministic fallback is recorded in result warnings.

Mulliken and Löwdin population results carry a conservation error. A scientifically inconsistent but still numerically usable result is retained with status="partial" and a warning instead of being labeled as a clean success. Density integration and cube export use the same principle: validation status is assigned from the actual generated grid and its electron-conservation check.

For post-HF calculations, openWFN does not claim correlated-density support unless a supported post-SCF density is actually parsed and selected. If the available matrix is the SCF density, the result names density_source="scf" and emits a warning that the SCF density was used.

For unrestricted calculations, select spin="all"; calculation.orbitals(spin="all") returns both channels plus the true overall HOMO. The corresponding registered analysis is frontier-all. The default alpha-only view remains available for backward compatibility but warns when a beta channel exists.

The default density-grid spacing is 0.15 bohr with 6.0 bohr padding. These defaults are an accuracy/performance starting point, not a convergence guarantee. Density grids are evaluated in bounded chunks to reduce peak AO-matrix memory, but researchers should still converge spacing and padding for the molecule and property being reported.

ELF and LOL localization descriptors

calculation.analyze("elf", ...) and calculation.analyze("lol", ...) evaluate Experimental localization descriptors at explicit Cartesian points in bohr. Both use openWFN's positive-definite half-gradient-square kinetic-energy-density convention. Total-channel ELF/LOL is accepted only for demonstrably restricted closed-shell data; open-shell calculations must request channel="alpha" or channel="beta" so spin conventions are not silently mixed.

ELF uses the Becke-Edgecombe Pauli-excess form and LOL uses the Schmider-Becke kinetic-energy ratio. The result records the exact formula label, homogeneous-electron-gas reference convention, density floor and negative-noise tolerances. Points at or below the density floor, materially negative Pauli excess, materially negative KED, or nonfinite input fields are returned as explicit null values with diagnostics rather than plausible-looking numbers. These methods remain Experimental pending broader independent reference validation.

points = [[0.2, 0.1, 0.3], [0.5, -0.2, 0.4]]
elf = calculation.analyze("elf", points_bohr=points, channel="total")
lol = calculation.analyze("lol", points_bohr=points, channel="total")

NCI and reduced density gradient

calculation.analyze("nci", points_bohr=...) evaluates Experimental total-density RDG and Hessian-sign NCI fields at explicit Cartesian points in bohr. RDG is |grad(rho)|/[2(3*pi^2)^(1/3)rho^(4/3)]; Hessian eigenvalues are ordered ascending algebraically and signed density is exactly sign(lambda2)*rho.

RDG validity is intentionally independent from Hessian validity. A point with a valid density/gradient but a materially nonsymmetric Hessian retains its RDG while Hessian-derived fields are null. The density floor is a numerical safeguard, not an interaction threshold. Near-zero lambda2 signs are retained with an ambiguity mask instead of being forced into an interaction interpretation.

points = [[0.0, 0.0, 1.0], [0.0, 0.0, 2.0]]
nci = calculation.analyze("nci", points_bohr=points)
calculation.nci_cube("signed.cube", field="signed_density")
calculation.nci_cube("rdg.cube", field="rdg", rdg_cap=2.0)

RDG cube export requires an explicit positive finite rdg_cap; only the declared low-density tail may be substituted by that cap, while other invalid/nonfinite fields abort export. See NCI and reduced density gradient.

Registered named analyses

Name	Result
beta-frontier	Beta-spin HOMO, LUMO, and gap
density-derivatives	Experimental analytic density value, gradient, Hessian, and Laplacian at explicit bohr points
dos	Gaussian orbital-energy DOS; Validated for the documented reference scope
elf	Experimental Becke-Edgecombe electron-localization function at explicit bohr points
excited-state	Experimental inspection of one one-based source excited state
excited-states	Experimental source excited-state job/state table
frontier	Alpha/default HOMO, LUMO, and gap
frontier-all	Alpha and beta frontiers plus the true overall HOMO for unrestricted calculations
hirshfeld	Validated ordinary neutral-pro-atom Hirshfeld populations and charges for the documented in-scope cases
ir-spectrum	Experimental source IR sticks plus Gaussian-broadened curve
kinetic-energy-density	Experimental positive-definite half-gradient-square kinetic-energy density at explicit bohr points
lol	Experimental Schmider-Becke localized-orbital locator at explicit bohr points
lowdin	Löwdin populations and charges
mayer	Spin-corrected Mayer bond orders; Validated for the documented reference scope
mulliken	Mulliken populations and charges
nci	Experimental total-density RDG, ordered density-Hessian eigenvalues, lambda2, and sign(lambda2)*rho at explicit bohr points
normal-mode	Experimental source normal-mode metadata and displacement vectors
nto	Experimental Natural Transition Orbitals from complete explicitly supported occupied-to-virtual transition matrices
orbital-composition	Default HOMO/alpha/Löwdin AO projections; Validated for the documented reference scope
pdos	Atom-resolved Löwdin PDOS by default; Validated for the documented reference scope
qtaim	Experimental bounded QTAIM critical-point topology and optional bond-path diagnostics; search completeness is never implied
raman-spectrum	Experimental source Raman activities plus Gaussian-broadened activity curve
summary	Version 2: complete molecular summary or partial structure-only/periodic summary
transition-dipoles	Experimental source-reported excited-state transition dipoles
uvvis-spectrum	Experimental source oscillator-strength sticks plus Gaussian-broadened UV–Vis profile
vibrations	Experimental source-reported vibrational mode table

Use available_analyses() to discover registered names. Run an analysis with calculation.analyze(name) after load(path), or use run_analysis(calculation_data, name) when working directly with the canonical model.

Every registered analysis returns a ResultRecord using result schema RESULT_SCHEMA_VERSION, currently "1.0". Its JSON representation includes the analysis name and version, scientific data and units, validation status, input provenance, warnings, elapsed time, execution status, and structured failure details. Existing ResultRecord(kind, data, units, validation_status) construction remains supported.

Batch API

run_batch(...) accepts the existing inputs, operation, workers, and output_dir arguments plus optional named analyses, resume/discovery controls, format_hint, format_hints={Path(...): "format_id"}, and frontier_spin="alpha"|"beta"|"all". The spin selector applies when frontier is requested: alpha preserves the historical analysis, beta maps it to beta-frontier, and all maps it to the spin-complete frontier-all analysis.

Batch records keep usable partial results and their warnings. An input record is error if parsing fails or every requested analysis fails. BatchManifest.status is success, partial, or failed; unsupported paths have reasons and readable checksums in unsupported_details. The manifest also reports attempted count and whether fail-fast stopped early. Resume fingerprints include input checksums, analysis/backend/software versions, and effective format hints; cached error records are retried.

FCHK parsing

• read_fchk(path) — read FCHK records.
• parse_fchk_scalars(lines) — extract scalar metadata.
• parse_fchk_arrays(lines) — extract atomic numbers and coordinates.
• parse_fchk_density(lines) — parse density matrices when present.
• parse_fchk_basis(lines) — parse basis data.
• parse_fchk_mos(lines) — parse molecular-orbital data. These low-level functions are public for specialized workflows, but load is the recommended entry point.

Geometry and topology

• distance(i, j, coordinates) — Euclidean distance between atoms i and j.
• angle(i, j, k, coordinates) — angle centered at atom j, in degrees.
• dihedral(i, j, k, l, coordinates) — signed torsion, in degrees.
• detect_bonds(atomic_numbers, coordinates, scale=1.2) — covalent-radius heuristic.
• build_graph(num_atoms, bonds) and MolecularGraph(num_atoms) — connectivity and fragments.

Pass coordinates as a sequence of (x, y, z) values. The low-level distance function returns the same length unit as those coordinates; it does not convert units. The high-level calculation methods use ångströms.

These public geometry and topology functions use one-based atom numbers, matching the CLI and OpenWFNCalculation geometry methods. Internal model fields and Python arrays retain normal zero-based indexing: examples include molecule.atoms, BasisShell.atom_index, Bond.atom1/Bond.atom2, and orbital coefficient arrays. Each public method documents which convention it accepts; do not assume one convention applies to every integer field.

Summary bond and fragment counts are inferred with the covalent-radius heuristic, not read as authoritative connectivity from FCHK. Ghost centers are excluded from physical formula, center-of-mass, bond, and fragment summaries while remaining represented as calculation centers.

Basis, density, and orbitals

• eval_s_type_gto(...) — evaluate an s-type Gaussian basis function.
• compute_density(...) — evaluate density from compatible basis and matrix data.
• evaluate_mo(...) — evaluate a molecular orbital.
• make_bounding_box_grid(...) — build a molecular Cartesian grid.

These are numerical building blocks. Units and array shapes must match the function contract, and non-finite scientific values are rejected by the public models and result envelope. Add convergence checks to research code.

Export functions

• export_vtk(...)
• export_json(...)
• export_csv(...)
• export_molecule_viewer(...)

Outputs can disclose the underlying molecular data. Apply the same access controls used for the source file.

Compatibility

The public import surface is versioned, but scientific behavior can be clarified between releases. Pin an exact openWFN version for reproducible work and review the release history.

orbital_cube(output, mo="homo", spin="alpha", spacing_bohr=.15, padding_bohr=6.) saves signed amplitudes. orbital_composition(mo="homo", spin="alpha", method="lowdin") returns AO contributions. See MO cubes and composition.

Pass analysis options with calculation.analyze(name, **parameters). Unknown parameters are rejected, including structure-only summaries. The convenience methods mayer(threshold=.05), dos(sigma_ev=.3, spin="all", energy_min_ev=None, energy_max_ev=None, points=None) and pdos(group_by="atom", method="lowdin", ...) return the same shared result envelopes. See DOS/PDOS.

Point ESP uses the same Gaussian-integral core as the CLI:

result = calculation.esp((1.127, 1.434, 1.741), component="total", method="integrals")
print(result.data["value"])  # hartree/e; input coordinates are angstrom

Unavailable data and singular nuclear potentials return structured failed results. The explicit method="grid" retains the legacy convergence-controlled method.