torchref.base.alignment.superposition module

Superposition functions for coordinate alignment.

Functions for computing optimal superposition of coordinate sets using the Kabsch algorithm and related methods.

torchref.base.alignment.superposition.superpose_vectors_robust_torch(ref_coords, mov_coords, weights=None, max_iterations=10)[source]

Perform weighted superposition of two coordinate sets using SVD (PyTorch version).

Parameters:

  • ref_coords (torch.Tensor) – Reference coordinates of shape (N, 3).

  • mov_coords (torch.Tensor) – Mobile coordinates of shape (N, 3) to be superposed onto reference.

  • weights (torch.Tensor, optional) – Weights for each atom of shape (N, 1). Default is uniform weights.

  • max_iterations (int, optional) – Maximum number of iterations for refinement. Default is 10.

Returns:

4x4 transformation matrix (shape (3, 4) returned).

Return type:

torch.Tensor

torchref.base.alignment.superposition.superpose_vectors_robust(target_coords, mobile_coords, weights=None, max_iterations=1)[source]

Superpose mobile coordinates onto target coordinates using the Kabsch algorithm.

Computes the optimal rotation and translation to minimize the weighted RMSD between two sets of 3D coordinates, with robust handling of special cases such as reflection.

Parameters:

  • target_coords (numpy.ndarray) – Target coordinates with shape (N, 3).

  • mobile_coords (numpy.ndarray) – Mobile coordinates with shape (N, 3) to be superposed onto target.

  • weights (numpy.ndarray, optional) – Per-atom weights for the superposition with shape (N,). Default is uniform weights.

  • max_iterations (int, optional) – Number of iterations for refinement. Default is 1 (standard Kabsch).

Returns:

  • transformation_matrix (numpy.ndarray) – 4x4 transformation matrix that maps mobile_coords onto target_coords.

  • rmsd (float) – Weighted root-mean-square deviation after superposition.

Raises:

ValueError – If input coordinate arrays have different shapes.

Notes

The algorithm uses SVD decomposition of the covariance matrix and handles the reflection case by checking the determinant of the rotation matrix.

torchref.base.alignment.superposition.align_torch(xyz1, xyz2, idx_to_move=None)[source]

Align two coordinate sets using superposition (PyTorch version).

Parameters:

  • xyz1 (torch.Tensor) – Target coordinates of shape (N, 3).

  • xyz2 (torch.Tensor) – Coordinates to be aligned of shape (N, 3).

  • idx_to_move (torch.Tensor, optional) – Indices of atoms to use for alignment. If None, uses all atoms.

Returns:

Aligned coordinates of shape (N, 3).

Return type:

torch.Tensor

torchref.base.alignment.superposition.get_alignement_matrix(xyz1, xyz2, idx_to_move=None)[source]

Get the alignment transformation matrix between two coordinate sets.

Parameters:

  • xyz1 (torch.Tensor) – Target coordinates of shape (N, 3).

  • xyz2 (torch.Tensor) – Coordinates to be aligned of shape (N, 3).

  • idx_to_move (torch.Tensor, optional) – Indices of atoms to use for alignment. If None, uses all atoms.

Returns:

Transformation matrix of shape (3, 4).

Return type:

torch.Tensor

torchref.base.alignment.superposition.align_pdbs(pdb1, pdb2, Atoms=None)[source]

Align two PDB structures using the Kabsch algorithm.

Superimposes pdb2 onto pdb1 by minimizing the RMSD between corresponding atoms. The transformation is applied in-place to pdb2.

Parameters:

  • pdb1 (pandas.DataFrame) – Reference PDB structure with ‘x’, ‘y’, ‘z’, ‘name’, and ‘tempfactor’ columns.

  • pdb2 (pandas.DataFrame) – Mobile PDB structure to be aligned onto pdb1.

  • Atoms (list, optional) – List of atom names to use for alignment. If None, all atoms are used.

Returns:

  • pdb2 (pandas.DataFrame) – Transformed pdb2 with updated coordinates.

  • rmsd (float) – Root-mean-square deviation after alignment.

torchref.base.alignment.superposition.get_alignment_matrix(pdb1, pdb2, Atoms=None)[source]

Calculate the transformation matrix to align two PDB structures.

Computes the 4x4 transformation matrix that would superimpose pdb2 onto pdb1 without actually applying the transformation.

Parameters:

  • pdb1 (pandas.DataFrame) – Reference PDB structure with ‘x’, ‘y’, ‘z’, ‘name’, and ‘tempfactor’ columns.

  • pdb2 (pandas.DataFrame) – Mobile PDB structure.

  • Atoms (list, optional) – List of atom names to use for alignment. If None, all atoms are used.

Returns:

  • transformation_matrix (numpy.ndarray) – 4x4 transformation matrix.

  • rmsd (float) – Root-mean-square deviation that would result from the alignment.

torchref.base.alignment.superposition.apply_transformation(points, transformation_matrix)[source]

Apply a 4x4 transformation matrix to 3D points (PyTorch version).

Parameters:

  • points (torch.Tensor) – 3D points of shape (N, 3).

  • transformation_matrix (torch.Tensor) – Transformation matrix of shape (3, 4) or (4, 4).

Returns:

Transformed 3D points of shape (N, 3).

Return type:

torch.Tensor

torchref.base.alignment.superposition.apply_transformation_numpy(points, transformation_matrix)[source]

Apply a 4x4 transformation matrix to 3D points (NumPy version).

Converts points to homogeneous coordinates, applies the transformation, and returns the transformed 3D coordinates.

Parameters:

  • points (numpy.ndarray) – 3D coordinates with shape (N, 3).

  • transformation_matrix (numpy.ndarray) – 4x4 transformation matrix containing rotation and translation.

Returns:

Transformed 3D coordinates with shape (N, 3).

Return type:

numpy.ndarray

torchref.base.alignment.superposition.invert_transformation_matrix(transformation_matrix)[source]

Compute the inverse of a 4x4 transformation matrix.

Efficiently inverts a rigid-body transformation matrix by transposing the rotation component and computing the inverse translation.

Parameters:

transformation_matrix (numpy.ndarray) – 4x4 transformation matrix containing rotation (top-left 3x3) and translation (top-right 3x1).

Returns:

Inverse 4x4 transformation matrix.

Return type:

numpy.ndarray

Notes

This function assumes the input is a valid rigid-body transformation (rotation + translation). For such matrices, the inverse rotation is simply the transpose, and the inverse translation is computed as -R^T @ t.