Source code for strainjedi.bmatrix

import ase.geometry
import ase.units
import numpy as np
from numpy.typing import NDArray


[docs] def calculate(atoms0, rim_list, indices=None) -> NDArray: """ Compute the Wilson B-matrix for a set of redundant internal coordinates (RICs). The function evaluates the derivatives of bond lengths, angles, and dihedral angles with respect to Cartesian coordinates and assembles them into the Wilson B-matrix. Periodic boundary conditions are handled through ASE's minimum-image convention (`mic=True`). Parameters ---------- atoms0 : ase.Atoms Atomic structure for which the B-matrix is evaluated. rim_list : sequence of array_like Collection of redundant internal coordinates. The expected order is: - ``rim_list[0]``: bond-length coordinates - ``rim_list[1]``: additional bond-length coordinates - ``rim_list[2]``: bond-angle coordinates, shape ``(n_angles, 3)`` - ``rim_list[3]``: dihedral coordinates, shape ``(n_dihedrals, 4)`` Bond coordinates are defined by atom pairs ``(i, j)``, angles by triplets ``(i, j, k)``, and dihedrals by quadruplets ``(i, j, k, l)``. indices : array_like of int, optional Indices of atoms whose Cartesian coordinates are included in the B-matrix. If ``None`` (default), all atoms are included. Returns ------- numpy.ndarray Wilson B-matrix of shape ``(n_rics, 3 * n_atoms_selected)``, where ``n_rics`` is the total number of internal coordinates and ``n_atoms_selected`` is ``len(indices)``. Each row contains the derivatives of a single internal coordinate with respect to the selected Cartesian coordinates. Notes ----- The returned matrix is assembled from: - Bond-length derivatives computed with ``ase.geometry.get_distances_derivatives``. - Bond-angle derivatives computed with ``_bond_angle_derivatives``. - Dihedral-angle derivatives computed with ``ase.geometry.get_dihedrals_derivatives``. Dihedral derivatives are converted from degrees to radians and scaled by ``ase.units.Bohr`` before insertion into the matrix. """ mol = atoms0 if indices is None: indices = np.arange(0, len(mol)) rim_size = sum(np.shape(length)[0] for length in rim_list) b = np.zeros([int(len(indices) * 3), int(rim_size)], dtype=float) # shape of B-matrix (NCarts,NRIMs) # map atom index -> row block start in B (only for selected indices) # (so we can write to the right rows without scanning indices) idx_pos = {int(a): p for p, a in enumerate(indices)} # get all derivatives column = 0 # Initialization of columns to specify position in B-Matrix for q in rim_list[0].tolist() + rim_list[1].tolist(): q_i, q_j = map(int, q[:2]) u = mol.get_distance(q_i, q_j, mic=True, vector=True) du = ase.geometry.get_distances_derivatives(np.atleast_2d(u))[0] # (2,3) d_i, d_j = du[0], du[1] pi = idx_pos.get(q_i) if pi is not None: _write_row_block(b, pi, column, d_i) pj = idx_pos.get(q_j) if pj is not None: _write_row_block(b, pj, column, d_j) column += 1 for angle in rim_list[2]: q_i, q_j, q_k = map(int, angle) u = mol.get_distance(q_i, q_j, mic=True, vector=True) v = mol.get_distance(q_k, q_j, mic=True, vector=True) # Compute derivatives once for this angle. # d[0] -> atom i, d[1] -> atom j (center), d[2] -> atom k d = _bond_angle_derivatives(np.atleast_2d(u), np.atleast_2d(v))[0] dmap = {q_i: -d[0], q_j: -d[1], q_k: -d[2]} for pos, atom in enumerate(indices): vec = dmap.get(int(atom)) if vec is not None: _write_row_block(b, pos, column, vec) column += 1 for dihedral in rim_list[3]: q_i, q_j, q_k, q_l = map(int, dihedral) # Copy needed because ASE derivative function might mutate input arrays... u = np.copy(np.atleast_2d(mol.get_distance(q_i, q_j, mic=True, vector=True))) w = np.copy(np.atleast_2d(mol.get_distance(q_k, q_l, mic=True, vector=True))) v = np.copy(np.atleast_2d(mol.get_distance(q_j, q_k, mic=True, vector=True))) # Compute derivatives once. # d[0] -> atom i, d[1] -> atom j, d[2] -> atom k, d[3] -> atom l d = ase.geometry.get_dihedrals_derivatives(u, v, w)[0] d = np.radians(d) * ase.units.Bohr dmap = {q_i: d[0], q_j: d[1], q_k: d[2], q_l: d[3]} for pos, atom in enumerate(indices): vec = dmap.get(int(atom)) if vec is not None: _write_row_block(b, pos, column, vec) column += 1 return np.transpose(b)
[docs] def hessian_to_ric(B, H_cart): """ Transform a Cartesian Hessian into redundant internal coordinate (RIC) space. The transformation is performed using the Moore–Penrose pseudoinverse of the Wilson B-matrix. For redundant coordinate sets, the projected Hessian is additionally constrained to the physically valid RIC subspace using the projection matrix returned by ``p_matrix``. Parameters ---------- B : numpy.ndarray Wilson B-matrix relating Cartesian displacements to internal coordinate displacements. For a system with ``n_rics`` redundant internal coordinates and ``n_cart`` Cartesian coordinates, the matrix typically has shape ``(n_rics, n_cart)``. H_cart : numpy.ndarray Cartesian Hessian matrix of shape ``(n_cart, n_cart)``. Returns ------- numpy.ndarray Hessian matrix expressed in redundant internal coordinate space. The returned array has shape ``(n_rics, n_rics)`` for a two-dimensional B-matrix. Notes ----- The transformation is given by .. math:: H_\\mathrm{RIC} = B^{+T} H_\\mathrm{cart} B^+, where :math:`B^+` denotes the Moore–Penrose pseudoinverse of the B-matrix. For redundant internal coordinates, the result is projected into the valid RIC subspace using .. math:: H_\\mathrm{RIC} = P B^{+T} H_\\mathrm{cart} B^+ P, where :math:`P` is the projector obtained from ``p_matrix(B, B_plus)``. """ B_plus = pinv(B) B_transp_plus = pinv(B.T) if B.ndim == 1: return B_transp_plus.dot(H_cart).dot(B_plus) P = p_matrix(B, B_plus) return P.dot(B_transp_plus).dot(H_cart).dot(B_plus).dot(P)
[docs] def p_matrix(B, B_plus): """ Compute the projection matrix in redundant internal coordinate (RIC) space. The projection matrix maps vectors in redundant internal coordinate space onto the subspace spanned by the Wilson B-matrix. It is commonly used to remove components that do not correspond to physically valid internal coordinate displacements. Parameters ---------- B : numpy.ndarray Wilson B-matrix of shape ``(n_rics, n_cart)``, relating Cartesian coordinate displacements to redundant internal coordinate displacements. B_plus : numpy.ndarray Moore–Penrose pseudoinverse of ``B``, typically of shape ``(n_cart, n_rics)``. Returns ------- numpy.ndarray Projection matrix of shape ``(n_rics, n_rics)`` defined as .. math:: P = B B^+. Notes ----- For a non-redundant coordinate set, the projection matrix is the identity matrix (up to numerical precision). For redundant coordinate sets, it projects vectors onto the physically valid RIC subspace. """ return np.dot(B, B_plus)
[docs] def pinv(B, rcond=1e-4): """ Compute the pseudoinverse of a Wilson B-matrix. For two-dimensional matrices, the Moore–Penrose pseudoinverse is computed using :func:`numpy.linalg.pinv`. One-dimensional inputs are treated as a special case and scaled by a factor of one-half. Parameters ---------- B : numpy.ndarray Wilson B-matrix or vector to invert. Typical matrix dimensions are ``(n_rics, n_cart)``. rcond : float, optional Relative cutoff for small singular values passed to :func:`numpy.linalg.pinv`. Singular values smaller than ``rcond * largest_singular_value`` are treated as zero. The default is ``1e-4``. Returns ------- numpy.ndarray Pseudoinverse of ``B``. For a matrix input with shape ``(n_rics, n_cart)``, the returned array has shape ``(n_cart, n_rics)``. Notes ----- The one-dimensional special case .. math:: B^+ = \\frac{B}{2} is included for compatibility with code paths that represent a single internal coordinate as a vector rather than a matrix. """ if B.ndim == 1: return B / 2 return np.linalg.pinv(B, rcond)
[docs] def restrict(B, indices): """ Restrict a Wilson B-matrix to a subset of Cartesian coordinates. The function constructs a reduced B-matrix containing only the Cartesian coordinates associated with the specified atoms. Contributions from all other atoms are first removed by setting their Cartesian columns to zero, after which the matrix is sliced to retain only the selected coordinate columns. Parameters ---------- B : numpy.ndarray Wilson B-matrix of shape ``(n_rics, 3 * n_atoms)``, where rows correspond to internal coordinates and columns correspond to Cartesian coordinates ordered as ``(x_0, y_0, z_0, x_1, y_1, z_1, ...)``. indices : array_like of int Indices of atoms whose Cartesian coordinates should be retained in the reduced matrix. Returns ------- numpy.ndarray Restricted B-matrix of shape ``(n_rics, 3 * len(indices))`` containing only the Cartesian coordinates of the selected atoms. Raises ------ ValueError If the number of columns in ``B`` is not divisible by three, indicating that the matrix does not represent a valid set of Cartesian coordinates. Notes ----- A copy of ``B`` is created internally, so the input matrix is never modified in place. The ordering of Cartesian coordinates in the returned matrix follows the order of atoms given in ``indices``. """ if B.shape[1] % 3 != 0: raise ValueError("B matrix does not have 3N cartesian columns") idx_set = set(map(int, indices)) # Work on a copy to avoid mutating the caller's matrix. Bz = np.array(B, copy=True) # zero columns for atoms not in subset n_atoms = Bz.shape[1] // 3 for atom_i in range(n_atoms): if atom_i not in idx_set: Bz[:, atom_i * 3 : atom_i * 3 + 3] = 0.0 # slice to subset cartesian coordinates col = np.array([[i * 3, i * 3 + 1, i * 3 + 2] for i in indices]).ravel() return np.take(Bz, col, axis=1)
# ---- internal helpers ---- # def _bond_angle_derivatives(u, v): """ Return bond-angle derivatives for B-matrix construction. Parameters ---------- u, v : array-like Vectors defining the angle (ASE convention: angle between `u` and `v`). Returns ------- numpy.ndarray Array shaped like ASE's angle-derivative output (per-atom derivative vectors), converted to radians and multiplied by `ase.units.Bohr` to match this code's historical unit handling. Notes ----- Handles linear angles (0°/180°) using an auxiliary vector fallback. """ angle = ase.geometry.get_angles(u, v) # angle between v and u tolerance = 5e-6 if np.abs(np.radians(angle) - np.pi) < tolerance or np.abs(np.radians(angle)) < tolerance: (u, v), (lu, lv) = ase.geometry.conditional_find_mic([u, v], cell=None, pbc=None) nu = u / lu nv = v / lv # Normalize auxiliary vector and check collinearity (parallel or anti-parallel) aux_normalized = np.array([1, -1, 1]) / np.sqrt(3) arccos_val = np.arccos(np.clip(np.dot(nu, aux_normalized), -1, 1)) # If nu is parallel (arccos ≈ 0) or anti-parallel (arccos ≈ π) to auxiliary, swap if np.abs(arccos_val) < tolerance or np.abs(arccos_val - np.pi) < tolerance: w = np.cross(nu, [-1, 1, 1]) else: w = np.cross(nu, [1, -1, 1]) nw = w / np.linalg.norm(w) d_ba1 = np.cross(nu, nw) / np.linalg.norm(u) d_ba2 = (-np.cross(nu, nw) / np.linalg.norm(u)) + (-np.cross(nw, nv) / np.linalg.norm(v)) d_ba3 = np.cross(nw, nv) / np.linalg.norm(v) d_ba = np.array([[d_ba1[0], d_ba2[0], d_ba3[0]]]) else: d_ba = np.radians(ase.geometry.get_angles_derivatives(u, v)) return d_ba * ase.units.Bohr def _write_row_block(b, row_pos, column, vec) -> None: """ Write a 3-component derivative vector into the B-matrix row block for one atom. Parameters ---------- b : numpy.ndarray Working B-matrix buffer with shape (3 * len(indices), rim_size) in `calculate()`, i.e. Cartesian rows stacked as x,y,z blocks per selected atom. row_pos : int Position of the atom within the selected `indices` list (0-based), not the global atom index. The written rows are [3*row_pos : 3*row_pos+3]. column : int Column index of the current RIC (bond/angle/dihedral) in the B-matrix buffer. vec : array-like, shape (3,) Derivative components to write into the (x, y, z) rows. """ r = 3 * row_pos b[r : r + 3, column] = vec