openwfn 0.10.0

Wavefunction analysis, made reproducible.

A unified post-processing toolkit for turning quantum-chemistry calculations into traceable, reproducible, review-ready results.

Get started · CLI reference · Validation · Citation

openWFN connects scientific analysis, automation, validation evidence, and research output through one typed calculation model. It works locally through the command line or Python, from individual calculations and high-throughput collections.

Analyze · Automate · Validate · Publish

• Analyze molecular structure, orbitals, electron density, atomic populations, electrostatic potential, and derived properties.
• Automate with stable CLI commands, a typed Python API, structured results, resumable batches, and JSON/CSV exports.
• Validate using explicit capability status, parser provenance, transformations, numerical controls, and fixture-backed evidence.
• Publish durable reports, figures, cube files, structures, and batch manifests.

Stable release 0.10.0

openWFN 0.10.0 adds everyday QC interpretation and tested automation and resource workflows. Install the exact release with python -m pip install "openwfn[interop,resources]==0.10.0". See the release notes.

The release includes 11 real molecular examples and an Experimental coverage audit. The audit retains convergence failures and unsupported legacy entry points. These methods are Validated within the documented reference scope; package stability does not change individual scientific validation labels.

See the design and roadmap, validation and limitations, and method documentation. Native Hirshfeld and later spectroscopy/real-space phases are not implemented; the validation document records their scientific gates. Existing CLI/API/result schemas are retained.

Install

openWFN supports Python 3.10–3.13.

Install the stable release:

python -m pip install --upgrade openwfn
openwfn --version

Install the exact release when reproducing research:

python -m pip install openwfn==0.10.0

First analysis

openwfn examples install ./openwfn-examples
openwfn ./openwfn-examples/water.fchk doctor
openwfn ./openwfn-examples/water.fchk summary
openwfn ./openwfn-examples/water.fchk orbitals frontier

For your own calculation, replace the example path:

openwfn molecule.fchk summary

Run a collection of calculations with resumable, structured output:

openwfn batch ./calculations \
  --analyses summary,frontier \
  --output-dir ./results \
  --resume

Use JSON when another program will consume the result:

openwfn --format json --output summary.json molecule.fchk summary

Scientific correctness safeguards

openWFN uses source-faithful electronic metadata wherever Gaussian FCHK provides it. ECP and ghost centers use the file's effective nuclear charges instead of blindly substituting atomic numbers, and density validation prefers the source electron-count records. Population and density conservation failures return partial results with warnings rather than presenting inconsistent numbers as clean successes.

For unrestricted calculations, request the spin-complete frontier view with openwfn FILE orbitals frontier --spin all; batch workflows support the same spin selection. Post-HF files explicitly report when the available SCF density is being analyzed rather than implying that a correlated density was used.

The default density spacing of 0.15 bohr is an accuracy/performance tradeoff, not a universal convergence guarantee. Check the returned conservation status and converge spacing/padding for the system and property being reported.

Capability map

“Validated” is deliberately scoped. Review the validation evidence and limitations before research use.

Input support

Version 0.10.0 includes optional interoperability support and resource/export safety fixes. See the 0.10.0 release notes. Install python -m pip install "openwfn[interop]==0.10.0" for additional formats. The optional reader is pinned to IOData 1.0.1 and has a 25-format ingestion matrix with capability discovery. Format ingestion does not imply that every file has orbitals, density, or an applicable analysis. The cross-format validation compares five water representations from one originating calculation; it is not broad independent scientific validation.

Gaussian formatted-checkpoint (.fchk) remains the preferred full-wavefunction path. Gaussian .chk is a proprietary binary format; openWFN calls Gaussian's separately installed formchk utility and does not decode it directly.

XYZ, MOL/SDF, and PDB inputs provide structure-only records. The optional backend also reads structure, periodic, grid, and integral-only formats; use openwfn FILE capabilities to check the actual data before analysis.

In openWFN 0.10.0, use --input-format FORMAT_ID when a filename is ambiguous (for example, a GAMESS .dat). A structure without a complete wavefunction gets a partial summary; it does not get inferred orbitals, density, or electron counts. Mixed batches can use --format-map and record unsupported files with reasons in the manifest. A batch exits nonzero if any input fails or is unsupported. See the batch guide for the exact contract.

openwfn calculation.chk formchk calculation.fchk
openwfn calculation.fchk convert --to sdf --output molecule.sdf
openwfn calculation.fchk density cube density.cube

Documentation

Output properties preview

Version 0.10.0 can extract source-reported properties from QC text output through the optional cclib reader:

python -m pip install "openwfn[outputs]==0.10.0"
python -m openwfn.cli --format json calculation.out properties

Python exposes the same result through openwfn.read_output(path). See the output properties preview for units, provenance, missing-data behavior and the current Experimental validation boundary.

• First analysis
• CLI workflows
• Complete CLI reference
• Python API
• Scientific methods
• Validation status
• Optional workbench
• Troubleshooting

Security and privacy

Computations are local, but input and generated artifacts can contain unpublished research. Never post private checkpoint files, credentials, personal filesystem paths, or license details in public issues. Read the security and data-privacy guide.

Development

python -m pip install -e ".[test,docs]"
python -m pytest
python -m ruff check .
python scripts/run_validation.py
python scripts/check_docs.py --root .
python -m mkdocs build --strict

Contributions should include tests, documented units and assumptions, and validation evidence appropriate to the claim. See Contributing.

Project policies: Code of Conduct · Security · Maintainers · Contributors · Roadmap

Citation and license

Cite the exact version used and the project repository; see the citation guide. openWFN is released under the MIT License.

Author: Muhammed Shah Shaji

Development resource checks and their measured scope are documented in Runtime and resource validation.