Metadata-Version: 2.1
Name: openwfn
Version: 0.4.0
Summary: openWFN: lightweight wavefunction geometry analysis toolkit
Author: Muhammed Shah Shaji
License: MIT
Project-URL: Homepage, https://github.com/sha786muhammed/openWFN
Project-URL: Repository, https://github.com/sha786muhammed/openWFN
Project-URL: Issues, https://github.com/sha786muhammed/openWFN/issues
Keywords: computational chemistry,gaussian,geometry,molecular modeling,quantum chemistry,wavefunction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"

# openWFN

![Tests](https://github.com/sha786muhammed/openWFN/actions/workflows/tests.yml/badge.svg)
![License](https://img.shields.io/badge/license-MIT-green)
![Python](https://img.shields.io/badge/python-3.10+-blue)

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
```bash
git clone https://github.com/sha786muhammed/openWFN.git
cd openWFN
pip install -e .
```

## Quick Start
Use one of the included examples:
```bash
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:
```bash
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:
```bash
openwfn --help
```

## Interactive Mode Guide
Start:
```bash
openwfn examples/water/water.fchk
```

Main menu options:
```text
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:
```bash
openwfn examples/water/water.fchk dist 2 1
openwfn examples/water/water.fchk angle 2 1 3
```

Molecular summary:
```bash
openwfn examples/ammonia/ammonia.fchk summary
```

Fragment detection:
```bash
openwfn examples/methane/methane.fchk graph
```

XYZ export:
```bash
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:
```bash
pytest -q
```

Project layout:
```text
src/openwfn/        package source
tests/              unit and CLI regression tests
examples/           sample molecules and Gaussian artifacts
```

## License
MIT License. See [LICENSE](LICENSE).

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