nvalchemi.csp.comparison.deduplicate_batch#

class nvalchemi.csp.comparison.deduplicate_batch(batch, *, atom_types=None, cutoff, threshold, priority_order=None, device=None, max_batch_atoms=200_000, max_memory_fraction=0.85, summary_coordinate_count=32, include_hydrogens=True, confirm=None)[source]#

Deduplicate every structure in one Batch with the tiled stream engine.

Geometry and supplied atom types are read from batch by structure ID. The result uses original Batch row IDs and contains int32 tensors on the comparison device. With supplied types, one shared vocabulary is derived from the full type vector and the same pair must pass untyped, center-typed, then fully typed radial screens. Without supplied types, only the untyped screen is used.

Parameters:
  • batch (Batch) – Input structure pool.

  • atom_types (torch.Tensor, optional) – Generic int32 or int64 label for every atom. Values are compared as caller-defined IDs and are not inferred from atomic numbers.

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

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

  • priority_order (sequence of int or torch.Tensor, optional) – Permutation of Batch row IDs defining greedy retention order.

  • device (torch.device or str, optional) – Descriptor and score device. Defaults to batch.device.

  • max_batch_atoms (int, default=200000) – Maximum retained comparison atoms in one descriptor tile; hydrogens are not counted when include_hydrogens=False.

  • 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.

  • summary_coordinate_count (int, default=32) – Maximum coordinates used by the conservative preliminary rejection check, from 0 through 128. The selected count may be lower. Pairs that pass go to the radial index matcher; summary bounds can reject a pair but never establish a match. Zero disables the pilot and outer check and sends all still-eligible pairs to the index matcher, which may use its built-in conservative summary bounds before scoring full descriptors.

  • 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.

  • confirm (callable, optional) – Receives ordered radial-match proposals as int32 [K, 2] original row IDs on the comparison device. Column zero is the candidate; column one is an earlier retained representative. Return an ordered subset on the same device. A rejected proposal does not discard the candidate; later representatives are tried. Without a callback, radial matches suffice. Calls may be grouped across candidates; decisions must depend on pair data rather than the global callback invocation order.

Returns:

Retained Batch row IDs, each row’s representative ID, and retained multiplicities, all as int32 tensors on the comparison device.

Return type:

DeduplicationResult