nvalchemi.csp.hooks.DeduplicateHook#

class nvalchemi.csp.hooks.DeduplicateHook(engine, *, frequency=1)[source]#

Filter generated Batches through a caller-selected deduplication engine.

The hook runs at GenerationStage.AFTER_GENERATE. Its engine receives the Batch entering this hook and returns a boolean keep mask for that Batch. The hook replaces ctx.batch with the selected rows and writes the same input-aligned mask to ctx.accepted_mask. A previous reporting mask is replaced; ctx.sample remains the original generated sample. An all-false mask produces Batch.empty_like(input_batch), retaining its materialized schema and capacities. Engine, validation, and selection errors leave hook-owned context fields unchanged when the engine obeys the no-in-place-mutation contract; a mutating engine cannot be rolled back.

Parameters:
  • engine (DeduplicationEngine) – Object with a callable deduplicate(batch) method returning a boolean mask on the input Batch’s device. It must not mutate the input Batch in place.

  • frequency (int, default=1) – Run the engine on every frequency-th eligible generation call. Frequency gating is performed by the hook registry.

Notes

radial() constructs a stateless, within-Batch approximate radial engine. Without confirmation, its proposed matches can remove distinct structures; atomic-number typing and typed neighbors make screening element-sensitive but do not establish structural identity.

classmethod radial(*, cutoff, threshold, confirm=None, frequency=1)[source]#

Create a within-Batch element-sensitive radial deduplication hook.

Parameters:
  • cutoff (float) – Positive radial cutoff in angstroms.

  • threshold (float) – Finite nonnegative fractional mismatch limit for approximate radial matches.

  • confirm (callable, optional) – Optional comparison confirmation callback. It receives proposed int32 [K, 2] input-row pairs on the Batch device, with the candidate in column zero and its earlier retained representative in column one. It returns an ordered subset on that device. Without it, radial proposals are accepted as matches.

  • frequency (int, default=1) – Run the engine on every frequency-th eligible generation call.

Returns:

Hook using a fresh radial comparison index for each nonempty Batch.

Return type:

DeduplicateHook

Raises:
  • TypeError – If confirm is not callable or frequency is a boolean or noninteger.

  • ValueError – If cutoff is not finite and positive, threshold is not finite and nonnegative, or frequency is not positive.