import ase.units
import ase.vibrations
import numpy as np
from numpy.typing import NDArray
from strainjedi import constants
[docs]
def get_hbonds(mol, *, covf=constants.COVALENCY_FACTOR, vdwf=constants.VAN_DER_WAALS_FACTOR, extra_hpartners=()):
"""
Identify hydrogen bonds in an atomic structure.
A hydrogen bond is defined as an X–H···Y interaction where X and Y are typically
N, O, or F (extendable via `extra_hpartners`). The H···Y distance must be smaller
than `vdwf` times the sum of van der Waals radii, and the X–H···Y angle must exceed 90°.
The donor X-H bond is identified from ASE covalent neighbor detection (:func:`ase.neighborlist.natural_cutoffs`),
scaled by `covf`.
Parameters
----------
mol : ase.Atoms or similar
Atomic structure containing positions and symbols.
covf : float, optional
Scaling factor for covalent bond detection cutoffs (default from constants).
vdwf : float, optional
Scaling factor for van der Waals distance criterion (default from constants).
extra_hpartners : iterable of str, optional
Additional elements to treat as hydrogen-bond partners.
Returns
-------
ndarray of shape (n, 2), dtype int
Array of hydrogen bonds as [H_index, acceptor_index] pairs.
Raises
------
ValueError
If an element in `extra_hpartners` is not recognized by ASE atomic data.
Notes
-----
- Covalent bonds are reduced to a single representation per bond (i–j instead of both i–j and j–i)
to avoid double-counting during hydrogen bond donor identification.
"""
from ase.data import atomic_numbers
from ase.data.vdw import vdw_radii
from ase.neighborlist import natural_cutoffs, neighbor_list
cutoff = natural_cutoffs(mol, mult=covf) ## cutoff for covalent bonds see Bakken et al.
bl = np.vstack(neighbor_list("ij", a=mol, cutoff=cutoff)).T # determine covalent bonds
bl = bl[bl[:, 0] < bl[:, 1]] # remove double mentioned
bl = np.unique(bl, axis=0)
hpartners = {"N", "O", "F", *extra_hpartners}
try:
hcutoff = {
("H", elem): vdwf * (vdw_radii[atomic_numbers["H"]] + vdw_radii[atomic_numbers[elem]]) for elem in hpartners
} # save the maximum distances for given pairs to be taken account as interactions
except KeyError as e:
raise ValueError(f"Unknown element symbol: {e.args[0]!r}") from None
acceptors = [i for i, symbol in enumerate(mol.symbols) if symbol in hpartners]
hbonds = []
for a, b in bl:
if mol.symbols[a] == "H" and mol.symbols[b] in hpartners:
h, donor = a, b
elif mol.symbols[b] == "H" and mol.symbols[a] in hpartners:
h, donor = b, a
else:
continue
for acceptor in acceptors:
if acceptor == donor:
continue
if (
mol.get_distance(h, acceptor, mic=True) < hcutoff[("H", mol.symbols[acceptor])]
and mol.get_angle(donor, h, acceptor, mic=True) > 90
):
hbonds.append([h, acceptor])
hbonds = np.asarray(hbonds, dtype=int)
if hbonds.size == 0:
return np.empty((0, 2), dtype=int)
hbonds = np.unique(hbonds, axis=0)
return hbonds
[docs]
def validate_hessian(modes: ase.vibrations.VibrationsData, atoms0) -> tuple[NDArray, bool]:
"""
Validate and, if necessary, reorder a Hessian matrix to match an Atoms object.
This function checks whether the atomic ordering implicit in the Hessian
(`modes`) is consistent with the ordering of atoms in `atoms0`. If the
ordering differs, the Hessian is permuted to match `atoms0`.
Parameters
----------
modes : numpy.ndarray
Cartesian Hessian matrix or modal representation associated with a
molecular structure. Typically has shape (3N, 3N), where N is the
number of atoms.
atoms0 : ase.Atoms
Reference atomic structure defining the correct atom ordering.
Returns
-------
hessian : numpy.ndarray
Hessian reordered (if necessary) to match the atom ordering of
`atoms0`. If the ordering already matches, the input is returned
unchanged.
ok : bool
True if the original Hessian ordering already matched `atoms0`,
False if a reordering was performed.
Notes
-----
- The function assumes that the Hessian ordering corresponds directly to
the atomic ordering in Cartesian blocks (x, y, z per atom).
- Reordering is performed at the atomic block level, not individual
Cartesian components.
- No physical transformation is applied; only index permutation.
Examples
--------
>>> H, ok = validate_hessian(H, atoms)
>>> if not ok:
... print("Hessian was reordered to match atomic structure.")
"""
perm = []
for atom in atoms0:
match = None
for i, vib_atom in enumerate(modes._atoms):
if atom.symbol != vib_atom.symbol:
continue
if np.allclose(atom.position, vib_atom.position, rtol=1e-5, atol=1e-5):
match = i
break
perm.append(match)
try:
perm = np.asarray(perm, dtype=int)
except TypeError:
raise ValueError("hessian does not appear to match atoms") from None
if np.array_equal(perm, np.arange(len(atoms0))):
hessian = modes._hessian2d
return hessian, True
dof = np.repeat(perm, 3) * 3 + np.tile(np.arange(3), len(perm))
hessian = modes._hessian2d[np.ix_(dof, dof)]
return hessian, False
[docs]
def _convert_units(use_ase_units: bool, rim_list, E_RIMs, deltaE=None, delta_q=None, E_RIMs_total=None):
"""
Convert RIC-related energies and coordinate displacements between ASE and
chemical energy units.
This function performs unit conversions for redundant internal coordinate
(RIC) analysis outputs, including coordinate displacements and energy
decompositions. It supports switching between ASE-native units (eV, Å and degrees) and
chemistry-friendly units (kcal/mol, Bohr and radians).
Important
---------
This internal API may change at any time; users are encouraged to instead make use of
the `ase_units` parameters on Jedi.run() and Jedi.visualize().
Parameters
----------
use_ase_units : bool
If True, convert outputs to ASE units (Å for lengths, degrees for
angles, eV for energies). If False, convert to chemical units
(Bohr for lengths, radians for angles, kcal/mol for energies).
rim_list : sequence of numpy.ndarray
RIC definition used to determine how many entries correspond to bond
and custom bond coordinates versus angular coordinates.
E_RIMs : array_like
Energies associated with each redundant internal coordinate.
deltaE : float or array_like, optional
Total energy difference between geometries.
delta_q : numpy.ndarray, optional
Coordinate differences along RICs. Modified in-place if provided.
E_RIMs_total : float or array_like, optional
Total summed RIC energy.
Returns
-------
E_RIMs : array_like
Converted RIC energies.
deltaE : float or array_like or None
Converted total energy difference, if provided.
delta_q : numpy.ndarray or None
Converted RIC displacements, if provided.
E_RIMs_total : float or array_like or None
Converted total RIC energy, if provided.
Notes
-----
Conversion behavior:
- Length-like coordinates (bonds and custom bonds) use Bohr ↔ Å.
- Angular coordinates use radians ↔ degrees.
- Energies are converted between eV and kcal/mol using ASE constants.
"""
if use_ase_units:
b = rim_list[0].shape[0] + rim_list[1].shape[0]
if delta_q is not None:
dq = delta_q.copy()
dq[:b] = dq[:b] * ase.units.Bohr
dq[b:] = np.degrees(dq[b:])
delta_q = dq
E_RIMs = E_RIMs * ase.units.Hartree
if E_RIMs_total is not None:
E_RIMs_total = E_RIMs_total * ase.units.Hartree
if deltaE is not None:
deltaE = deltaE * ase.units.Hartree
else:
E_conversion = ase.units.mol / ase.units.kcal * ase.units.Hartree
E_RIMs = E_RIMs * E_conversion
if E_RIMs_total is not None:
E_RIMs_total = E_RIMs_total * E_conversion
if deltaE is not None:
deltaE = deltaE * E_conversion
return E_RIMs, deltaE, delta_q, E_RIMs_total