openwfn 0.12.0

Wavefunction analysis, made reproducible.

Wavefunction post-processing for quantum chemistry. Use the same scientific engine from the CLI, Python, MCP or terminal chat.

openWFN reads supported quantum-chemistry files and returns analysis results with units, warnings and source provenance. Analyze individual calculations and high-throughput collections without changing the scientific engine between interfaces.

See the 0.12.0 release notes for the supported interfaces, verification and scientific boundaries.

Install and inspect a file

Published package:

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

For development from source, use a separate environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

The normal installation includes format readers, output extraction, Python API, local MCP and terminal chat in the normal installation. No model weights, Gaussian utilities or public servers are installed automatically.

openwfn molecule.molden open
openwfn molecule.molden capabilities
openwfn molecule.fchk summary
openwfn --format json molecule.fchk analyze

Guided mode offers workflows supported by the selected file. It shows settings, units and atom numbering, checks grid size, confirms save paths, and can show the equivalent command. Scripts should use explicit commands such as summary; file-only non-terminal invocations now return a bounded overview.

Supported input families

Binary .chk is a proprietary binary format. Conversion needs Gaussian's separately installed formchk; pip does not supply it. A parser cannot create wavefunction data that the input does not contain. See the format contract for variants and limitations.

Scientific analyses

The shared engine provides geometry, frontier orbitals, MO composition/cubes, Mulliken/Löwdin/Hirshfeld populations, Mayer bond orders, DOS/PDOS, density checks, ESP, supported vibrational/excited-state properties and conservative NTO analysis. It also exposes bounded QTAIM critical-point searches and ELF/LOL/NCI fields.

Population analysis uses source-reported effective nuclear charges for ECP and ghost centers; conservation failures return partial results with warnings. The direct density default is 0.15 bohr spacing, not a convergence guarantee. Use coarser settings for exploration and check convergence before reporting values.

openwfn molecule.fchk orbitals frontier --spin all
openwfn molecule.fchk population mulliken
openwfn molecule.fchk density integrate --spacing 0.3 --padding 6
openwfn calculation.out properties

Scientific status is separate from package status. Hirshfeld and other Validated methods are validated only for their named scopes. Spectroscopy, output extraction and the newer real-space tools retain their documented Experimental boundaries. QTAIM basin integration is not included.

Conservation errors and source warnings stay visible. Unknown charge/spin is not guessed; normal job termination is not proof of optimization convergence. Density settings require a convergence study for the intended property. Methods, validation and limitations explain those boundaries.

Python, collections and saved results

from openwfn import load

calculation = load("molecule.molden")
print(calculation.capabilities())
result = calculation.analyze("frontier-all")
print(result.as_dict())

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

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

JSON preserves the complete result envelope. HTML/Markdown reports, CSV tables, figures, cube files and the offline workbench are export options, not requirements for Linux or headless workflows.

Scientific assistant and MCP

Configure an existing local model; openWFN does not train or download one:

openwfn molecule.molden chat --model qwen3:8b
openwfn chat

For file questions, openWFN checks capabilities and settings and supplies the scientific values. General conversation works without a file and is labelled as model-generated, not independently verified. Remote model use requires explicit permission. See assistant setup.

The normal installation also includes a read-only local MCP server:

python -m openwfn.mcp_server --data-root ./inputs

That process waits for an MCP client on stdio; it is not a public HTTP service. MCP setup describes client configuration, confirmation and resource limits. External hosts control their own generated prose.

Documentation and contributing

• First analysis
• CLI reference and Python API
• Citation
• Contributor guide and security policy
• Release history

The package includes redistributable examples:

openwfn examples install ./openwfn-examples
openwfn ./openwfn-examples/water.fchk summary

Keep the input checksum, package version, command/settings and complete result with your work. Do not post unpublished calculations, credentials or personal paths in public issues. Project-owned code is MIT licensed; dependency terms are listed in third-party notices.