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 whereadjacency[i, j]is true or 1 when atomsiandjare 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)