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 replacesctx.batchwith the selected rows and writes the same input-aligned mask toctx.accepted_mask. A previous reporting mask is replaced;ctx.sampleremains the original generated sample. An all-false mask producesBatch.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:
- Raises:
TypeError – If
confirmis not callable orfrequencyis a boolean or noninteger.ValueError – If
cutoffis not finite and positive,thresholdis not finite and nonnegative, orfrequencyis not positive.