nvalchemi.csp.comparison.iter_matches_stream#

class nvalchemi.csp.comparison.iter_matches_stream(count, read_typed_batch, *, cutoff, threshold, type_vocabulary=None, other_count=None, read_other_typed_batch=None, device='cpu', max_batch_atoms=200_000, max_memory_fraction=0.85, pair_chunk_size=8192, summary_coordinate_count=32, include_hydrogens=True)[source]#

Yield radial matches from one or two loader-backed structure pools.

The function begins reading when the iterator is advanced. Loaders receive CPU int64 logical row IDs and return a (Batch, atom_types) pair, with an int32 or int64 type vector aligned to all Batch atoms, or None for untyped comparison. Typed loaders must use the same fixed type vocabulary in both pools and must return stable values for every requested ID.

Self-comparison emits each unordered pair once as (left, right) with left < right. Cross-pool comparison emits (left_row, right_row). Both forms are lexicographic. Output tensors are nonempty int32 [K, 2] chunks on device and contain at most pair_chunk_size pairs. Full descriptors are built for active atom-bounded pair tiles. Compact summaries and sorted search columns reside on the comparison device and grow with the pool sizes and selected coordinate count. Setting summary_coordinate_count=0 disables the outer pilot-selected check and sends every eligible pair to the radial index matcher, which may still apply its built-in conservative summary bound before full scoring. Closing the iterator releases its call-local tensors without closing either caller-owned loader.

Parameters:
  • count (int) – Number of rows available from read_typed_batch.

  • read_typed_batch (callable) – Loader for the left pool. It receives CPU int64 row IDs.

  • cutoff (float) – Radial descriptor cutoff in angstroms.

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

  • type_vocabulary (sequence of int, optional) – Fixed set of signed int32 atom type IDs used by typed loaders.

  • other_count (int, optional) – Number of rows in a second pool. Must be supplied with read_other_typed_batch; omit both for self-comparison.

  • read_other_typed_batch (callable, optional) – Loader for the right pool in a cross-pool comparison.

  • device (torch.device or str, default="cpu") – Device used to build and score descriptor tiles.

  • max_batch_atoms (int, default=200000) – Maximum retained comparison atom count in each active descriptor tile. Hydrogens are not counted when include_hydrogens=False. Cross-comparison may keep up to this many atoms on both sides at once; the shared CUDA memory budget accounts for both live descriptor sets.

  • max_memory_fraction (float, default=0.85) – Maximum fraction of CUDA memory available to PyTorch assigned to descriptor construction and scoring workspace, including reusable caching-allocator bytes. This is an estimate, not a reservation.

  • pair_chunk_size (int, default=8192) – Maximum number of logical pairs screened or yielded at once.

  • summary_coordinate_count (int, default=32) – Maximum coordinates for the preliminary conservative rejection check, from 0 through 128. The selected count may be lower. Passing pairs go to the radial index matcher; summary bounds can reject but not match. Zero disables only the outer pilot check; the matcher may retain its built-in conservative summary bound.

  • include_hydrogens (bool, default=True) – Whether hydrogen atoms participate in comparison. False removes all atomic-number-1 atoms before neighbor lists and descriptors are built. Supply types aligned with original atoms; retained labels and original structure-row IDs are preserved. The same setting applies to both loaders.

Yields:

torch.Tensor – Nonempty int32 [K, 2] matching index chunks, in lexicographic order.

Raises:
  • TypeError – If a loader, vocabulary, or option has an unsupported type.

  • ValueError – If sizes, callbacks, cutoff, threshold, or memory options are invalid.

  • MemoryError – If one structure or pair cannot fit the atom or CUDA memory limit.

Return type:

Iterator[Tensor]