crossvib 0.1.0

Cross-environment vibrational normal-mode correlation and classification (VMARD/.nma and ORCA .hess)

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

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:

crossvib single molecule.nma          # or: molecule.hess

Correlate two calculations of the same solute in different environments:

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:

crossvib multi-compare fragA.hess fragB.hess complex.hess

You can also run it as a module:

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.