GetConformerRMSMatrix#

nvmolkit.conformerRmsd.GetConformerRMSMatrix(
mol: Mol,
prealigned: bool = False,
stream: Stream | None = None,
*,
output_format: str = 'condensed',
) → AsyncGpuResult | Tensor#

Compute the pairwise RMSD matrix between all conformers of a molecule on GPU.

GPU-accelerated equivalent of AllChem.GetConformerRMSMatrix(mol, prealigned=prealigned). For N conformers with M atoms, computes N*(N-1)/2 pairwise RMSD values using one GPU thread-block per pair. When prealigned is False (default), each pair is optimally superimposed via the Kabsch algorithm before computing RMSD.

Differences from RDKit:

  • Zero-atom molecules always raise ValueError regardless of conformer count. RDKit returns [nan] for exactly 2 zero-atom conformers and raises ZeroDivisionError for 3 or more.

  • Results are returned as an AsyncGpuResult (device tensor) rather than a Python list, to keep the conformer-selection pipeline on the GPU.

By default, the result matches RDKit’s condensed lower-triangle shape. Use output_format="square" when a downstream API expects an N x N distance matrix, such as nvmolkit.clustering.butina().

Parameters:

  • mol – RDKit molecule with two or more conformers. Strip hydrogens first (Chem.RemoveHs) if you want heavy-atom RMSD, as this function operates on all atoms present in the molecule.

  • prealigned – If True, skip Kabsch alignment and compute RMSD on raw coordinates. If False (default), optimally align each pair.

  • stream – CUDA stream to use. If None, uses the current stream.

  • output_format – "condensed" returns an AsyncGpuResult wrapping a 1-D RDKit-style lower-triangle vector. "square" returns a symmetric torch.Tensor of shape (N, N) on the GPU with zeros on the diagonal.

Returns:

With output_format="condensed", an AsyncGpuResult wrapping a 1-D tensor of shape (N*(N-1)/2,) containing RMSD values in lower-triangle condensed order. The RMSD for conformer pair (i, j) with i > j is at index i*(i-1)//2 + j.

With output_format="square", a symmetric CUDA torch.Tensor of shape (N, N).

Raises:

  • ValueError – If mol is None or has conformers but no atoms.

  • TypeError – If stream is not a torch.cuda.Stream or None.

Example

>>> from rdkit import Chem
>>> from rdkit.Chem import AllChem, rdDistGeom
>>> from nvmolkit.conformerRmsd import GetConformerRMSMatrix
>>> from nvmolkit.clustering import butina
>>>
>>> mol = Chem.AddHs(Chem.MolFromSmiles('CCCCCC'))
>>> rdDistGeom.EmbedMultipleConfs(mol, numConfs=50)
>>> no_h = Chem.RemoveHs(mol)
>>>
>>> # GPU equivalent of: AllChem.GetConformerRMSMatrix(no_h)
>>> rmsd_matrix = GetConformerRMSMatrix(no_h)
>>>
>>> # Request square output for GPU Butina clustering
>>> square = GetConformerRMSMatrix(no_h, output_format="square")
>>> clusters = butina(square, cutoff=0.5)