Source code for mfml_qc.rpr

"""
Rotate-Predict-Rotate (RPR) frame canonicalization for vector-valued KRR.

Provides a per-geometry canonical frame from the inertia tensor and a
composable wrapper (``RPRVectorKRR``) that works with any model exposing
``.train(X, Y)`` / ``.predict(X)``.

The canonical frame is defined by the principal axes of inertia. Sign
ambiguity is resolved using the mass-weighted cubic moment along each
axis: s_i = Σ_a m_a (r_a · e_i)^3. This is computed in the molecular
frame and is therefore rotationally covariant.

Degeneracy handling:
  - Linear molecules (one eigenvalue ≈ 0): warning emitted, fallback
    convention based on the heaviest off-axis atom.
  - Symmetric tops (two equal eigenvalues): similar fallback with warning.

Reference: [1] J. Martinka, M. Pederzoli, M. Barbatti, P. O. Dral, J. Pittner, A simple approach to rotationally invariant machine learning of a vector quantity, J. Chem. Phys. 161, 174104 (2024). DOI: 10.1063/5.0230176
"""

import numpy as np
import warnings

ATOMIC_MASSES = {
    1: 1.00794,
    2: 4.00260,
    3: 6.941,
    4: 9.01218,
    5: 10.811,
    6: 12.011,
    7: 14.007,
    8: 15.999,
    9: 18.998,
    10: 20.180,
    11: 22.990,
    12: 24.305,
    13: 26.982,
    14: 28.086,
    15: 30.974,
    16: 32.065,
    17: 35.453,
    18: 39.948,
    19: 39.098,
    20: 40.078,
    26: 55.845,
    29: 63.546,
    30: 65.380,
    35: 79.904,
    53: 126.904,
}


[docs] def canonicalize(coords, masses, degeneracy_tol=1e-6): """ Compute the RPR canonical frame for a molecular geometry. Parameters ---------- coords : np.ndarray, shape (N_atoms, 3) Cartesian coordinates in the lab frame. masses : np.ndarray, shape (N_atoms,) Atomic masses. degeneracy_tol : float Relative tolerance for detecting degenerate inertia eigenvalues. Returns ------- U : np.ndarray, shape (3, 3) Rotation matrix whose columns are the principal axes. Right-handed (det = +1). Sign convention: cubic moment along each axis is non-negative. com : np.ndarray, shape (3,) Center of mass. """ total_mass = np.sum(masses) com = np.sum(masses[:, None] * coords, axis=0) / total_mass r = coords - com r_sq = np.sum(r**2, axis=1) I = np.einsum("a,a->", masses, r_sq) * np.eye(3) - np.einsum( "a,ai,aj->ij", masses, r, r ) eigvals, eigvecs = np.linalg.eigh(I) max_eigval = np.max(np.abs(eigvals)) if max_eigval > 0: if eigvals[0] < degeneracy_tol * max_eigval: warnings.warn( "Near-linear molecule detected (smallest eigenvalue " f"{eigvals[0]:.2e} vs largest {max_eigval:.2e}). " "The two degenerate perpendicular axes use a fallback " "convention based on the heaviest off-axis atom.", stacklevel=2, ) elif (eigvals[1] - eigvals[0]) < degeneracy_tol * max_eigval: warnings.warn( f"Near-degenerate eigenvalues: {eigvals}. " "Canonical frame may be less stable for nearly " "symmetric-top geometries.", stacklevel=2, ) for i in range(3): proj = r @ eigvecs[:, i] cubic_moment = np.sum(masses * proj**3) if cubic_moment < -1e-14: eigvecs[:, i] *= -1 elif abs(cubic_moment) < 1e-14: max_idx = np.argmax(np.abs(proj)) if proj[max_idx] < 0: eigvecs[:, i] *= -1 if np.linalg.det(eigvecs) < 0: eigvecs[:, 2] *= -1 return eigvecs, com
[docs] class RPRVectorKRR: """ RPR wrapper around any vector-valued model with .train/.predict. During training, each geometry is canonicalized: descriptors are computed from canonical coordinates, and targets are rotated to the canonical frame. During prediction, predictions in the canonical frame are rotated back to the lab frame. Parameters ---------- model : object Inner model with ``.train(X, Y)`` and ``.predict(X)`` methods. Z : array-like, shape (N_atoms,) Atomic numbers. descriptor_fn : callable Maps ``(Z=atomic_numbers, R=coordinates)`` to a 1D descriptor array. E.g., ``mfml_qc.representations.compute_flat_coulomb``. """ def __init__(self, model, Z, descriptor_fn): self.model = model self.Z = np.asarray(Z, dtype=np.int32) self.masses = np.array([ATOMIC_MASSES[int(z)] for z in self.Z]) self.n_atoms = len(self.Z) self.descriptor_fn = descriptor_fn def _process_geometries(self, X_flat, Y=None): """ Canonicalize geometries and compute descriptors. Parameters ---------- X_flat : np.ndarray, shape (N, N_atoms*3) Y : np.ndarray, shape (N, d), optional Returns ------- descriptors : np.ndarray, shape (N, n_features) Y_canon : np.ndarray, shape (N, d) or None Us : list of np.ndarray, each (3, 3) """ N = X_flat.shape[0] coords_all = X_flat.reshape(N, self.n_atoms, 3) descriptors = [] Us = [] Y_canon = np.zeros_like(Y) if Y is not None else None for i in range(N): U, com = canonicalize(coords_all[i], self.masses) coords_canon = (coords_all[i] - com) @ U desc = self.descriptor_fn(Z=self.Z, R=coords_canon) descriptors.append(desc) Us.append(U) if Y is not None: Y_canon[i] = U.T @ Y[i] return np.array(descriptors), Y_canon, Us
[docs] def train(self, X_train, Y_train): """ Train the RPR-wrapped model. Parameters ---------- X_train : np.ndarray, shape (N, N_atoms*3) Flattened Cartesian coordinates. Y_train : np.ndarray, shape (N, d) Vector targets in the lab frame. """ X_desc, Y_canon, _ = self._process_geometries(X_train, Y_train) self.model.train(X_desc, Y_canon)
[docs] def predict(self, X_test): """ Predict and rotate back to lab frame. Parameters ---------- X_test : np.ndarray, shape (M, N_atoms*3) Flattened Cartesian coordinates. Returns ------- np.ndarray, shape (M, d) Predictions in the lab frame. """ X_desc, _, Us = self._process_geometries(X_test) preds_canon = self.model.predict(X_desc) preds = np.zeros_like(preds_canon) for i in range(len(Us)): preds[i] = Us[i] @ preds_canon[i] return preds