nvalchemi.csp.chem.TopologicalAtomTypeMap#
- class nvalchemi.csp.chem.TopologicalAtomTypeMap(atomic_numbers, adjacency)[source]#
Reuse reference molecular topology labels across reordered structures.
Construct one map from an ordered base formula unit and its complete molecular adjacency. The map copies both inputs. For
for_batch(), callers attest that source indices refer to this exact ordered base formula unit and that relaxation preserved its molecular connectivity. The method checks field lengths and atomic-number agreement, but aBatchalone cannot establish that source indices have the claimed meaning. Forfor_connectivity(), each supplied target component is checked against a reference component by exact element and bond-preserving atom reordering.- Parameters:
atomic_numbers (torch.Tensor, shape
[N]) – Ordered base formula-unit atomic numbers with an integral dtype and values from 1 through 118.adjacency (torch.Tensor, shape
[N, N]) – Boolean or binary integer molecular bond adjacency. It must be symmetric and have a zero diagonal; floating-point adjacency is not accepted.
Notes
Atoms that can exchange places while preserving every element and bond in the complete base formula unit receive the same type ID. Matching disconnected reference molecules share corresponding labels.
for_connectivitylabels each target component that has an exact reference match; it does not check component proportions against the base formula unit. Bond order, charge, isotope labels, stereochemistry, and geometry are not part of the topology contract.Examples
>>> base_numbers = torch.tensor([6, 6, 8]) >>> base_edges = torch.tensor([[0, 1, 0], [1, 0, 1], [0, 1, 0]]) >>> atom_types = TopologicalAtomTypeMap(base_numbers, base_edges) >>> atom_types.for_connectivity( ... torch.tensor([8, 6, 6]), ... torch.tensor([[0, 1, 0], [1, 0, 1], [0, 1, 0]]), ... ) tensor([2, 1, 0], dtype=torch.int32)
- for_batch(batch)[source]#
Map a topology-preserving expanded P1 batch to shared atom types.
- Parameters:
batch (nvalchemi.data.batch.Batch) – Batch with atom-level
atomic_numbersandcsp_source_asu_atom_indexfields. Provenance indices may repeat across formula-unit copies and may occur in any atom order.- Returns:
Shared reference atom type for each batch atom, on the batch’s atomic-number device.
- Return type:
torch.Tensor, dtype
torch.int32, shape[batch.num_nodes]- Raises:
TypeError – If
batchis not aBatch, or an atom field has an unsupported dtype.ValueError – If atom fields are missing or not tensors, their shapes or lengths do not align, an index is negative, a nonempty batch uses an empty reference formula, a structure atom count is not a multiple of the reference formula size, or a source index has a different atomic number.
- for_connectivity(atomic_numbers, adjacency)[source]#
Map complete target graph components onto reference atom types.
Each connected target component must match a reference component after reordering atoms while preserving atomic numbers and bonded pairs. Target atom order is preserved in the returned shared labels. Repeated and mixed reference components are supported. This method checks that each target component is known, but does not check the counts of the different components against the reference formula unit.
- Parameters:
atomic_numbers (torch.Tensor, shape
[N]) – Target atomic numbers in target atom order, with an integral dtype and values from 1 through 118.adjacency (torch.Tensor, shape
[N, N]) – Complete target molecular adjacency with a boolean or binary integer dtype, symmetry, and a zero diagonal. Floating-point adjacency is not accepted.
- Returns:
Shared reference atom types in target atom order, on the target atomic-number device.
- Return type:
torch.Tensor, dtype
torch.int32, shape[N]- Raises:
TypeError – If either argument is not a tensor or has an unsupported dtype.
ValueError – If graph inputs are invalid or any target component has no exact reference component match.