Source code for nvalchemi.csp.hooks

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Generation hooks for crystal-structure generation."""

from __future__ import annotations

from collections.abc import Callable
from typing import Protocol

import torch
from torch import Tensor

from nvalchemi.csp._validation import (
    finite_nonnegative,
    finite_positive,
    positive_integer,
)
from nvalchemi.csp.comparison import RadialComparisonIndex
from nvalchemi.data import Batch
from nvalchemi.gen.stages import GenerationStage
from nvalchemi.hooks._context import GenerationContext

__all__ = ["DeduplicationEngine", "DeduplicateHook"]


[docs] class DeduplicationEngine(Protocol): """Structural interface for generation-time Batch deduplication. Implementations return a one-dimensional ``torch.bool`` keep mask of length ``batch.num_graphs`` on exactly ``batch.device`` and must not mutate the supplied Batch in place. Engines may keep their own state across calls; the bundled radial engine compares only within each input Batch. """
[docs] def deduplicate(self, batch: Batch) -> Tensor: """Return a ``torch.bool [batch.num_graphs]`` mask on ``batch.device``.""" ...
class _RadialDeduplicationEngine: """Build and use a fresh typed radial index for one input Batch.""" def __init__( self, *, cutoff: float, threshold: float, confirm: Callable[[Tensor], Tensor] | None, ) -> None: self.cutoff = cutoff self.threshold = threshold self.confirm = confirm def deduplicate(self, batch: Batch) -> Tensor: """Return retained input rows using element-sensitive radial screening.""" index = RadialComparisonIndex.build( batch, cutoff=self.cutoff, atom_types=batch.atomic_numbers, typed_neighbors=True, ) result = index.deduplicate(threshold=self.threshold, confirm=self.confirm) keep = torch.zeros(batch.num_graphs, dtype=torch.bool, device=batch.device) keep[result.retained_indices.to(dtype=torch.long)] = True return keep
[docs] class DeduplicateHook: """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 ----- :meth:`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. """ stage = GenerationStage.AFTER_GENERATE def __init__(self, engine: DeduplicationEngine, *, frequency: int = 1) -> None: """Create a hook around a structural deduplication engine. Parameters ---------- engine : DeduplicationEngine Custom implementation of the boolean-mask engine protocol. frequency : int, default=1 Positive number of generation calls between eligible dispatches. Raises ------ TypeError If ``engine`` lacks a callable ``deduplicate`` method, or if ``frequency`` is a boolean or noninteger. ValueError If ``frequency`` is not positive. """ if not callable(getattr(engine, "deduplicate", None)): raise TypeError("engine must provide a callable deduplicate(batch) method") if isinstance(frequency, bool) or not isinstance(frequency, int): raise TypeError("frequency must be a positive integer") try: positive_integer(frequency, name="frequency") except ValueError: raise ValueError("frequency must be a positive integer") from None self.engine = engine self.frequency = frequency
[docs] @classmethod def radial( cls, *, cutoff: float, threshold: float, confirm: Callable[[Tensor], Tensor] | None = None, frequency: int = 1, ) -> DeduplicateHook: """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 ------- DeduplicateHook Hook using a fresh radial comparison index for each nonempty Batch. 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. """ cutoff_value = finite_positive(cutoff, "cutoff") try: threshold_value = finite_nonnegative(threshold, "threshold") except TypeError: raise ValueError("threshold must be finite and nonnegative") from None if confirm is not None and not callable(confirm): raise TypeError("confirm must be callable or None") return cls( _RadialDeduplicationEngine( cutoff=cutoff_value, threshold=threshold_value, confirm=confirm ), frequency=frequency, )
def __call__(self, ctx: GenerationContext, stage: GenerationStage) -> None: """Validate engine output, then replace the generated Batch locally.""" if stage is not GenerationStage.AFTER_GENERATE: return batch = ctx.batch if not isinstance(batch, Batch): raise TypeError("DeduplicateHook requires ctx.batch to be a Batch") if batch.num_graphs == 0: keep = torch.empty((0,), dtype=torch.bool, device=batch.device) selected = batch else: keep = self.engine.deduplicate(batch) if not isinstance(keep, Tensor): raise TypeError("deduplication engine must return a torch.Tensor") if keep.dtype is not torch.bool: raise TypeError("deduplication engine must return a torch.bool mask") if keep.ndim != 1: raise ValueError("deduplication engine mask must be one-dimensional") if keep.numel() != batch.num_graphs: raise ValueError( "deduplication engine mask length must match batch.num_graphs" ) if keep.device != batch.device: raise ValueError( "deduplication engine mask must be on the input Batch device" ) if torch.any(keep): selected = batch[keep] else: selected = Batch.empty_like(batch) ctx.batch = selected ctx.accepted_mask = keep