Utility Functions

Utility Functions#

strainjedi.utils._convert_units(use_ase_units: bool, rim_list, E_RIMs, deltaE=None, delta_q=None, E_RIMs_total=None)[source]#

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.

strainjedi.utils.get_hbonds(mol, *, covf=1.3, vdwf=0.9, extra_hpartners=())[source]#

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 (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:

Array of hydrogen bonds as [H_index, acceptor_index] pairs.

Return type:

ndarray of shape (n, 2), dtype int

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.

strainjedi.utils.validate_hessian(modes: VibrationsData, atoms0) → tuple[ndarray[tuple[Any, ...], dtype[_ScalarT]], bool][source]#

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