nvalchemi.csp.chem.topological_atom_types_from_connectivity#

nvalchemi.csp.chem.topological_atom_types_from_connectivity(atomic_numbers, adjacency)[source]#

Label atoms with equivalent element-and-bond connectivity.

Parameters:
  • atomic_numbers (torch.Tensor, shape [N]) – Integral atomic numbers in the range 1 through 118.

  • adjacency (torch.Tensor, shape [N, N]) – Boolean or binary integer matrix where adjacency[i, j] is true or 1 when atoms i and j are bonded. It must be symmetric, with false or zero on its diagonal.

Returns:

One local type ID per atom on the same device as atomic_numbers. Interchangeable atoms share an ID; IDs follow the first atom in each group.

Return type:

torch.Tensor, dtype torch.int32, shape [N]

Raises:
  • TypeError – If either input is not a tensor or has an unsupported dtype.

  • ValueError – If array shapes, element numbers, or bond connections are invalid.

Notes

These labels restrict which atoms can match during structure comparison. Two atoms share a type if the molecule can be relabeled to exchange them while preserving every element identity and bond connection. Bond order, charge, isotope labels, stereochemistry, and geometry are not considered. The check runs on CPU; output stays on the atomic-number tensor’s device.

In the example below, ethanol (CH3-CH2-OH) has six types in atom order: the methyl carbon, its three equivalent hydrogens, the methylene carbon, its two equivalent hydrogens, the oxygen, and the hydroxyl hydrogen.

Examples

>>> numbers = torch.tensor([6, 1, 1, 1, 6, 1, 1, 8, 1])
>>> bonds = torch.tensor([[0, 1], [0, 2], [0, 3], [0, 4],
...                       [4, 5], [4, 6], [4, 7], [7, 8]])
>>> adjacency = torch.zeros((9, 9), dtype=torch.bool)
>>> adjacency[bonds[:, 0], bonds[:, 1]] = True
>>> adjacency[bonds[:, 1], bonds[:, 0]] = True
>>> topological_atom_types_from_connectivity(numbers, adjacency)
tensor([0, 1, 1, 1, 2, 3, 3, 4, 5], dtype=torch.int32)