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).
