openwfn 0.4.0

openWFN: lightweight wavefunction geometry analysis toolkit

openWFN

openWFN (open WaveFunction Network) is a lightweight toolkit for molecular geometry post-processing from Gaussian checkpoint data.

It is built for users who want:

• fast command-line geometry analysis from .fchk files
• reproducible atom-index-based calculations
• a minimal, script-friendly toolchain with low dependencies

Key Capabilities

• Read Gaussian .fchk files
• Convert .chk to .fchk automatically when formchk is available
• Convert coordinate units from Bohr to Angstrom internally
• Calculate distance, angle, and dihedral from atom indices
• Detect covalent bonds using tabulated covalent radii
• Build molecular fragments (connected components)
• Export coordinates to XYZ format
• Run in command mode or interactive terminal menu mode

Requirements

• Python 3.10+
• numpy
• Gaussian formchk only if you provide .chk files

Installation

git clone https://github.com/sha786muhammed/openWFN.git
cd openWFN
pip install -e .

Quick Start

Use one of the included examples:

openwfn examples/water/water.fchk summary
openwfn examples/ammonia/ammonia.fchk dist 1 2
openwfn examples/methane/methane.fchk graph
openwfn examples/water/water.fchk xyz water.xyz

If no subcommand is provided:

• in a TTY terminal, openWFN starts interactive mode
• in non-interactive contexts, openWFN runs summary

Command Reference

General form:

openwfn <file.chk|file.fchk> <command> [arguments]

Available commands:

• summary: one-page molecular overview (formula, atom count, charge, multiplicity, center of mass, energy if present, bonds, fragments)
• info: print parsed scalar metadata from FCHK
• dist i j: distance in Angstrom between atom i and atom j
• angle i j k: bond angle (i-j-k) in degrees
• dihedral i j k l: torsion angle (i-j-k-l) in degrees
• bonds: print detected covalent bonds and distances
• graph: print molecular fragments (connected components)
• xyz output.xyz: export Cartesian coordinates to XYZ file
• interactive: force interactive menu mode
• density --export out.vtk [--grid-size NxNxN]: experimental density-export pathway; currently unavailable and exits with an error
• mo <index> --export out.vtk: experimental molecular-orbital pathway; currently unavailable and exits with an error

Note:

• geometry and export commands (summary, info, dist, angle, dihedral, bonds, graph, xyz) are the stable user-facing surface today
• density and mo are reserved for future development work and should not be treated as supported end-user commands yet

Get CLI help:

openwfn --help

Interactive Mode Guide

Start:

openwfn examples/water/water.fchk

Main menu options:

Landing page
  openWFN
  Open WaveFunction Network
  A lightweight terminal toolkit for Gaussian .fchk geometry analysis.

Features
  1  Molecular summary
  2  Detailed metadata
  3  Atom index table
  4  Distance between two atoms
  5  Bond angle (i-j-k)
  6  Dihedral angle (i-j-k-l)
  7  Export XYZ
  8  List detected covalent bonds
  9  Show fragments / connectivity

Session
  0  Exit

Feature page
  Shows the selected feature
  Supports `back` to return to the landing page
  Supports `exit` to quit openWFN

Typical interactive workflow:

1. Start on the landing page and choose a feature number.
2. openWFN opens that feature as its own page.
3. Use back to return to the landing page.
4. Use exit from either the landing page or a feature page to quit immediately.

Input behavior:

• atom indices are 1-based
• invalid indices are reported as errors
• malformed numeric input is rejected and reprompted
• back returns from any feature page to the landing page
• exit quits from any page
• textual aliases such as summary, dist, bonds, graph, xyz, and exit are accepted
• interactive mode intentionally shows only the working end-user features

Example Sessions

Distance and angle:

openwfn examples/water/water.fchk dist 2 1
openwfn examples/water/water.fchk angle 2 1 3

Molecular summary:

openwfn examples/ammonia/ammonia.fchk summary

Fragment detection:

openwfn examples/methane/methane.fchk graph

XYZ export:

openwfn examples/water/water.fchk xyz outputs/water.xyz

File and Data Notes

• Atomic coordinates in Gaussian FCHK are read in Bohr and converted to Angstrom.
• Geometry commands assume coordinates are present in Current cartesian coordinates.
• Bond detection uses element covalent radii with a fixed scaling factor (currently 1.2 in code).

Current Implementation Status

Fully supported and tested:

• parsing of essential scalar and coordinate data
• geometry calculations (dist, angle, dihedral)
• bond detection and graph fragments
• XYZ export

Partially implemented:

• density is exposed for future development, but electron-density evaluation is not implemented yet; the command currently exits with an explanatory error.
• mo is exposed for future development, but molecular-orbital grid evaluation is not implemented yet; the command currently exits with an explanatory error.

Use these two commands only if you are extending the codebase.

Development

Run tests:

pytest -q

Project layout:

src/openwfn/        package source
tests/              unit and CLI regression tests
examples/           sample molecules and Gaussian artifacts

License

MIT License. See LICENSE.

Author

Muhammed Shah Shaji
PhD Researcher, Computational Chemistry
GitHub: https://github.com/sha786muhammed