openwfn 0.4.0__tar.gz

openwfn-0.4.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Muhammed Shah Shaji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

openwfn-0.4.0/PKG-INFO

@@ -0,0 +1,212 @@
+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

openwfn-0.4.0/README.md

@@ -0,0 +1,184 @@
+# 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

openwfn-0.4.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "openwfn"
+version = "0.4.0"
+description = "openWFN: lightweight wavefunction geometry analysis toolkit"
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Muhammed Shah Shaji" }]
+keywords = [
+    "computational chemistry",
+    "gaussian",
+    "geometry",
+    "molecular modeling",
+    "quantum chemistry",
+    "wavefunction",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.20.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/sha786muhammed/openWFN"
+Repository = "https://github.com/sha786muhammed/openWFN"
+Issues = "https://github.com/sha786muhammed/openWFN/issues"
+
+
+[project.scripts]
+openwfn = "openwfn.cli:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

openwfn-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openwfn-0.4.0/src/openwfn/__init__.py

@@ -0,0 +1,37 @@
+"""
+openWFN - open WaveFunction Network
+A lightweight toolkit for wavefunction geometry and spatial property analysis.
+"""
+
+__version__ = "0.4.0"
+
+from .fchk import read_fchk, parse_fchk_arrays, parse_fchk_scalars, parse_fchk_density, parse_fchk_basis, parse_fchk_mos  # type: ignore
+from .geometry import distance, angle, dihedral, detect_bonds  # type: ignore
+from .graph import MolecularGraph, build_graph  # type: ignore
+from .basis import eval_s_type_gto  # type: ignore
+from .density import compute_density  # type: ignore
+from .mo import evaluate_mo  # type: ignore
+from .grid import make_bounding_box_grid  # type: ignore
+from .export import export_vtk, export_json, export_csv  # type: ignore
+
+__all__ = [
+    "read_fchk",
+    "parse_fchk_arrays",
+    "parse_fchk_scalars",
+    "parse_fchk_density",
+    "parse_fchk_basis",
+    "parse_fchk_mos",
+    "distance",
+    "angle",
+    "dihedral",
+    "detect_bonds",
+    "MolecularGraph",
+    "build_graph",
+    "eval_s_type_gto",
+    "compute_density",
+    "evaluate_mo",
+    "make_bounding_box_grid",
+    "export_vtk",
+    "export_json",
+    "export_csv",
+]

openwfn-0.4.0/src/openwfn/basis.py

@@ -0,0 +1,29 @@
+# src/openwfn/basis.py
+
+import numpy as np  # type: ignore
+
+def eval_s_type_gto(r_points: np.ndarray, center: np.ndarray, alpha: np.ndarray, d: np.ndarray) -> np.ndarray:
+    """
+    Vectorized evaluation of an s-type Contracted Gaussian Type Orbital over N points.
+    
+    Args:
+        r_points: (N, 3) float array of Cartesian coordinates.
+        center: (3,) float array of the basis function center.
+        alpha: (K,) float array of orbital exponents.
+        d: (K,) float array of orbital contraction coefficients.
+        
+    Returns:
+        (N,) float array of the evaluated basis function amplitude at each point.
+    """
+    # r_squared: shape (N,)
+    r_squared = np.sum((r_points - center)**2, axis=1)
+    
+    # exponentials: shape (N, K)
+    # alpha is shape (K,), r_squared is broadcasted by outer product
+    exponentials = np.exp(-np.outer(r_squared, alpha))
+    
+    # Contract with coefficients d: shape (N,)
+    return np.dot(exponentials, d)
+
+# P and D type orbital implementations would go here, multiplying the unnormalized
+# s-type contracted Gaussians by the corresponding cartesian polynomials (x, y, z, xy, x2-y2, etc.)