nvalchemi.csp.comparison.RadialComparisonIndex#

class nvalchemi.csp.comparison.RadialComparisonIndex(descriptor_store, cutoff, atom_types, typed_neighbors, device, block_size, max_memory_fraction, cuda_memory_budget_bytes, summary, typed_summary, center_type_presence, include_hydrogens=True)[source]#

Compare structures by local radial distributions of atom-neighbor distances.

cutoff and coordinates are in angstroms. For two positive distances, the fractional mismatch is max(d1, d2) / min(d1, d2) - 1. The score is the largest mismatch after matching compatible atom environments in both directions. Thus threshold=0.1 allows the larger distance to be at most 10% above the smaller one. This radial comparison is approximate: a low score can be a false positive and does not establish structural equivalence.

Without atom_types, all atoms share one comparison type; atomic numbers are not inferred. Supplied types always constrain center matching; typed_neighbors controls whether neighbor distances are separated by type. Missing cell or PBC metadata means nonperiodic geometry; per-axis PBC flags support partially periodic structures. If a center type is absent from the other structure, the pair’s score is infinite. Cross-index comparisons require equal cutoff, device, and typing modes and a shared semantic mapping of type IDs.

For matching, a finite threshold is converted to FP32 and advanced one representable value toward positive infinity.

Parameters:
  • descriptor_store (DescriptorStore)

  • cutoff (float)

  • atom_types (Tensor | None)

  • typed_neighbors (bool)

  • device (torch.device)

  • block_size (int)

  • max_memory_fraction (float)

  • cuda_memory_budget_bytes (int | None)

  • summary (Tensor)

  • typed_summary (Tensor)

  • center_type_presence (Tensor)

  • include_hydrogens (bool)

classmethod build(batch, *, cutoff, atom_types=None, typed_neighbors=True, dtype=torch.float32, device=None, max_memory_fraction=0.70, structure_block_size=None, include_hydrogens=True)[source]#

Build a reusable index of local atom-neighbor distances for each structure.

Parameters:
  • batch (Batch) – Source structures. Geometry and optional types are copied during construction; later source-batch mutations do not affect results.

  • cutoff (float) – Maximum atom-neighbor distance included, in angstroms.

  • atom_types (torch.Tensor, optional) – Caller-supplied integer type for each original, unfiltered atom, using one shared ID mapping across structures. Retained atoms keep these labels when hydrogens are omitted; values must fit signed int32, and the int32 minimum is reserved for descriptor padding.

  • typed_neighbors (bool, default=True) – When types are supplied, compare neighbor distances separately by type.

  • dtype (torch.dtype, default=torch.float32) – Descriptor and score dtype. Only FP32 is supported.

  • device (torch.device or str, optional) – Device used for descriptor construction and scoring. Defaults to the batch device.

  • max_memory_fraction (float, default=0.70) – Fraction in (0, 0.70] of CUDA memory available to PyTorch at build time used as an estimated descriptor-construction and owned-storage budget. The estimate includes reusable caching-allocator bytes. Host-backed descriptor staging and typed-summary tiles use the remaining allowance; caller inputs and returned results are excluded. Later staging also depends on current free memory. This is an estimate, not a memory reservation: backend workspace and allocator behavior can make actual peak use differ, and an allocation can still fail.

  • structure_block_size (int, optional) – Target limit on distinct structures staged for a descriptor block. One pair may require more; resident descriptor blocks are not sliced.

  • include_hydrogens (bool, default=True) – Whether hydrogen atoms participate in descriptors. When false, the batch must include atomic numbers; atoms with atomic number 1 are removed before neighbor lists and descriptors are built, for both centers and neighbors. Source data remains unchanged.

Returns:

Eagerly built index for scoring and matching the frozen structures copied from batch.

Return type:

RadialComparisonIndex

Raises:
  • TypeError – If the batch, dtype, type IDs, or option types are unsupported.

  • ValueError – If geometry or numerical options are invalid.

  • MemoryError – If estimated CUDA descriptor or typed-summary workspace exceeds the configured memory budget.

deduplicate(*, threshold, confirm=None, pair_chunk_size=None)[source]#

Keep each structure that does not match an earlier retained structure.

Visit input structures in order. Compare each with structures already kept and assign it to its first confirmed match, or retain it if none matches. If A matches B and B matches C but A does not match C, input order A, B, C retains A and C.

Parameters:
  • threshold (float) – Inclusive finite nonnegative fractional score threshold.

  • confirm (callable, optional) – Receives each proposed-match chunk as ordered int32 [K, 2] original-pool indices on this index’s device. It must return an ordered subset on the same device. Column zero is the candidate and column one is an earlier retained representative. Without a callback, all proposed matches are accepted.

  • pair_chunk_size (int, optional) – Upper bound on candidate-to-representative pair work per chunk.

Returns:

Retained indices, each structure’s representative index, and multiplicities aligned with retained structures.

Return type:

DeduplicationResult

Raises:
  • TypeError – If confirm is not callable.

  • ValueError – If the threshold, pair chunk size, or callback result is invalid.

  • MemoryError – If one descriptor pair or typed-filter tile exceeds the configured CUDA workspace.

find_matches(other=None, *, threshold, pair_indices=None, pair_chunk_size=None)[source]#

Collect proposed matches in deterministic pair order.

Parameters:
  • other (RadialComparisonIndex, optional) – Cross-compare against this second pool. Defaults to self-comparison over unordered pairs.

  • threshold (float) – Inclusive finite nonnegative fractional score threshold.

  • pair_indices (torch.Tensor, optional) – Explicit ordered int32 or int64 [K, 2] pairs to test.

  • pair_chunk_size (int, optional) – Upper bound on temporary pair work; returned matches are collected in one tensor regardless of this value.

Returns:

Matching int32 [M, 2] pairs on this index’s device.

Return type:

torch.Tensor

Raises:
  • TypeError – If an index or explicit pair tensor has an unsupported type.

  • ValueError – If index settings, threshold, or chunk size are invalid.

  • IndexError – If an explicit pair contains an out-of-range index.

  • MemoryError – If one descriptor pair or typed-filter tile exceeds the configured CUDA workspace.

property include_hydrogens: bool#

Whether this index includes hydrogen atoms in its descriptors.

iter_matches(other=None, *, threshold, pair_indices=None, pair_chunk_size=None)[source]#

Yield matching pair indices in deterministic bounded chunks.

Parameters:
  • other (RadialComparisonIndex, optional) – Cross-compare against this second pool. Defaults to self-comparison over unordered pairs.

  • threshold (float) – Inclusive finite nonnegative fractional score threshold.

  • pair_indices (torch.Tensor, optional) – Explicit ordered int32 or int64 [K, 2] pairs to test.

  • pair_chunk_size (int, optional) – Upper bound on pair work per chunk. Defaults to at most 4096 pairs on CPU or 8192 on CUDA.

Yields:

torch.Tensor – Matching int32 [M, 2] index chunks on this index’s device.

Raises:
  • TypeError – If an index or explicit pair tensor has an unsupported type.

  • ValueError – If index settings, threshold, or chunk size are invalid.

  • IndexError – If an explicit pair contains an out-of-range index.

  • MemoryError – If one descriptor pair or typed-filter tile exceeds the configured CUDA workspace.

Return type:

Iterator[Tensor]

property num_structures: int#

Return the number of frozen structure rows represented by the index.

Returns:

Number of logical structures in the source pool.

Return type:

int

Notes

The value is independent of how many descriptor blocks are resident during a comparison.

score_pairs(pair_indices, other=None, *, pair_chunk_size=None)[source]#

Return one local-distance mismatch score for each requested pair.

Parameters:
  • pair_indices (torch.Tensor) – int32 or int64 [K, 2] indices. Column zero indexes this index and column one indexes other when supplied.

  • other (RadialComparisonIndex, optional) – Index providing the second structure pool. Defaults to this index.

  • pair_chunk_size (int, optional) – Upper bound on pairs processed together. The device default is capped at 4096 pairs on CPU and 8192 on CUDA.

Returns:

FP32 scores in input order on this index’s device.

Return type:

torch.Tensor

Raises:
  • TypeError – If pair indices or other have an unsupported type.

  • ValueError – If index settings are incompatible or the chunk size is invalid.

  • IndexError – If a pair contains an out-of-range structure index.

  • MemoryError – If one descriptor pair exceeds the configured CUDA workspace.