crossvib 0.1.0__tar.gz

crossvib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adalberto V. S. de Araújo
+
+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.

crossvib-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.2
+Name: crossvib
+Version: 0.1.0
+Summary: Cross-environment vibrational normal-mode correlation and classification (VMARD/.nma and ORCA .hess)
+Author: Adalberto V. S. de Araújo
+License: MIT
+Project-URL: Homepage, https://github.com/YOUR_USERNAME/crossvib
+Project-URL: Repository, https://github.com/YOUR_USERNAME/crossvib
+Project-URL: Issues, https://github.com/YOUR_USERNAME/crossvib/issues
+Keywords: vibrational-spectroscopy,normal-mode-analysis,computational-chemistry,quantum-chemistry,raman,infrared,vibanalysis,orca
+Classifier: Development Status :: 4 - Beta
+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 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: networkx>=2.6
+Provides-Extra: calibration
+Requires-Dist: openpyxl>=3.0; extra == "calibration"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# CrossVib
+
+**Cross-environment vibrational normal-mode correlation and classification.**
+
+CrossVib classifies vibrational modes from vibAnalysis (VMARD) `.nma` output — or
+directly from ORCA `.hess` files — and correlates modes between two calculations of
+the same chemical system in *different environments* (solvent, surface, method,
+oxidation state).
+
+The comparison projects both calculations onto a **common internal-coordinate basis**
+(the intersection of canonicalised internals after atom mapping), builds a phase-aware
+**signed overlap matrix**, and reduces it with a symmetrised **Shannon mixing index**.
+The primary reported quantity is the identity-retention metric
+
+```
+P_ret = 1 - H_bar        (in [0, 1];  higher = better preserved across environments)
+```
+
+Because the basis is an *intersection*, the analysis is **independent of atom count** —
+the signature capability for free-molecule vs. interacting-system comparisons.
+
+## Installation
+
+```bash
+pip install crossvib
+```
+
+Runtime dependencies: `numpy`, `networkx`. The optional calibration-pool tooling also
+needs `openpyxl` (`pip install "crossvib[calibration]"`).
+
+## Usage
+
+CrossVib has three subcommands: `single`, `compare`, and `multi-compare`.
+
+Classify the modes of a single calculation:
+
+```bash
+crossvib single molecule.nma          # or: molecule.hess
+```
+
+Correlate two calculations of the same solute in different environments:
+
+```bash
+crossvib compare free.nma sers.nma \
+    --xyz-a free.xyz --xyz-b sers.xyz \
+    --range 200 3500 \
+    --emit-extras ./results/
+```
+
+For `.hess` input, geometry and normal modes are read directly from the ORCA Hessian
+file, so `--xyz-a` / `--xyz-b` are not required. For `.nma` input they **are** required.
+
+Multi-source (N ≥ 2 fragments) cooperativity analysis `(A₁ + A₂ + … + Aₙ) → B`:
+
+```bash
+crossvib multi-compare fragA.hess fragB.hess complex.hess
+```
+
+You can also run it as a module:
+
+```bash
+python -m crossvib compare free.nma sers.nma --xyz-a free.xyz --xyz-b sers.xyz
+```
+
+Output formats are selectable with `--format {tsv|csv|md|pretty}`. The
+`--emit-extras DIR` flag writes per-analysis TSVs (overlap matrix, robustness ranking,
+frequency shifts, Raman transfer, EF decomposition, silent-mode activations).
+
+## Method
+
+The full methodology — internal-coordinate canonicalisation, VF2-based atom mapping,
+phase-aware overlap, the symmetrised mixing index, conservation classes (C/X/R), and
+the vCAL landmark pool — is documented in the accompanying methods paper.
+
+## Citing
+
+If CrossVib is useful in your work, please cite it. A `CITATION.cff` and DOI will be
+added on first release.
+
+## License
+
+See [LICENSE](./LICENSE).

crossvib-0.1.0/README.md

@@ -0,0 +1,82 @@
+# CrossVib
+
+**Cross-environment vibrational normal-mode correlation and classification.**
+
+CrossVib classifies vibrational modes from vibAnalysis (VMARD) `.nma` output — or
+directly from ORCA `.hess` files — and correlates modes between two calculations of
+the same chemical system in *different environments* (solvent, surface, method,
+oxidation state).
+
+The comparison projects both calculations onto a **common internal-coordinate basis**
+(the intersection of canonicalised internals after atom mapping), builds a phase-aware
+**signed overlap matrix**, and reduces it with a symmetrised **Shannon mixing index**.
+The primary reported quantity is the identity-retention metric
+
+```
+P_ret = 1 - H_bar        (in [0, 1];  higher = better preserved across environments)
+```
+
+Because the basis is an *intersection*, the analysis is **independent of atom count** —
+the signature capability for free-molecule vs. interacting-system comparisons.
+
+## Installation
+
+```bash
+pip install crossvib
+```
+
+Runtime dependencies: `numpy`, `networkx`. The optional calibration-pool tooling also
+needs `openpyxl` (`pip install "crossvib[calibration]"`).
+
+## Usage
+
+CrossVib has three subcommands: `single`, `compare`, and `multi-compare`.
+
+Classify the modes of a single calculation:
+
+```bash
+crossvib single molecule.nma          # or: molecule.hess
+```
+
+Correlate two calculations of the same solute in different environments:
+
+```bash
+crossvib compare free.nma sers.nma \
+    --xyz-a free.xyz --xyz-b sers.xyz \
+    --range 200 3500 \
+    --emit-extras ./results/
+```
+
+For `.hess` input, geometry and normal modes are read directly from the ORCA Hessian
+file, so `--xyz-a` / `--xyz-b` are not required. For `.nma` input they **are** required.
+
+Multi-source (N ≥ 2 fragments) cooperativity analysis `(A₁ + A₂ + … + Aₙ) → B`:
+
+```bash
+crossvib multi-compare fragA.hess fragB.hess complex.hess
+```
+
+You can also run it as a module:
+
+```bash
+python -m crossvib compare free.nma sers.nma --xyz-a free.xyz --xyz-b sers.xyz
+```
+
+Output formats are selectable with `--format {tsv|csv|md|pretty}`. The
+`--emit-extras DIR` flag writes per-analysis TSVs (overlap matrix, robustness ranking,
+frequency shifts, Raman transfer, EF decomposition, silent-mode activations).
+
+## Method
+
+The full methodology — internal-coordinate canonicalisation, VF2-based atom mapping,
+phase-aware overlap, the symmetrised mixing index, conservation classes (C/X/R), and
+the vCAL landmark pool — is documented in the accompanying methods paper.
+
+## Citing
+
+If CrossVib is useful in your work, please cite it. A `CITATION.cff` and DOI will be
+added on first release.
+
+## License
+
+See [LICENSE](./LICENSE).

crossvib-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "crossvib"
+version = "0.1.0"
+description = "Cross-environment vibrational normal-mode correlation and classification (VMARD/.nma and ORCA .hess)"
+readme = "README.md"
+requires-python = ">=3.7"
+license = { text = "MIT" }            # TODO: confirm your license choice (see LICENSE)
+authors = [
+    { name = "Adalberto V. S. de Araújo" },
+]
+keywords = [
+    "vibrational-spectroscopy",
+    "normal-mode-analysis",
+    "computational-chemistry",
+    "quantum-chemistry",
+    "raman",
+    "infrared",
+    "vibanalysis",
+    "orca",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.21",
+    "networkx>=2.6",
+]
+
+[project.optional-dependencies]
+calibration = ["openpyxl>=3.0"]   # only needed for the vCAL calibration-pool tooling
+dev = ["build", "twine", "pytest"]
+
+[project.urls]
+Homepage = "https://github.com/YOUR_USERNAME/crossvib"        # TODO: update after creating the repo
+Repository = "https://github.com/YOUR_USERNAME/crossvib"
+Issues = "https://github.com/YOUR_USERNAME/crossvib/issues"
+
+[project.scripts]
+crossvib = "crossvib.core:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

crossvib-0.1.0/setup.cfg

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

crossvib-0.1.0/src/crossvib/__init__.py

@@ -0,0 +1,18 @@
+"""CrossVib — cross-environment vibrational normal-mode correlation and classification.
+
+Classifies vibrational modes from vibAnalysis (VMARD) ``.nma`` output — or directly
+from ORCA ``.hess`` files — and correlates modes between two calculations of the same
+chemical system in different environments (solvent, surface, method, oxidation state).
+
+The comparison uses a common internal-coordinate projection with a phase-aware signed
+overlap and a symmetrised Shannon mixing index, giving the identity-retention metric
+``P_ret = 1 - H_bar`` in [0, 1]. Because the basis is the *intersection* of internal
+coordinates after atom mapping, the analysis is independent of atom count — the
+signature capability for free-molecule vs. interacting-system comparisons.
+"""
+from __future__ import annotations
+
+from crossvib.core import main
+
+__all__ = ["main", "__version__"]
+__version__ = "0.1.0"

crossvib-0.1.0/src/crossvib/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for ``python -m crossvib``."""
+from __future__ import annotations
+
+import sys
+
+from crossvib.core import main
+
+if __name__ == "__main__":
+    sys.exit(main())