Source code for nvalchemi.gen.generator

# 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.
"""Batched generative inference driven by a user-supplied callable.

``AtomisticGenerator`` (the *driver* throughout this module) wraps your generation
code -- a function, or a callable object holding the trained model -- and runs
a fixed pipeline per call: optionally condition the inputs, generate, and
return a :class:`~nvalchemi.data.Batch`. Any sampling procedure works
(diffusion, flow matching, GANs, VAEs, search loops); the callable owns the
model and does the sampling.

The pipeline per :meth:`AtomisticGenerator.sample` looks like::

    # condition step -- only when a condition callable is provided:
    BEFORE_CONDITION   hooks  (edit or replace ctx.inputs)
    ctx.inputs = condition(ctx.inputs, num_samples=..., rng=...)
    AFTER_CONDITION    hooks  (replace what the function is called with)
    # generation and mapping:
    ctx.sample = generator_func(ctx.inputs, num_samples=..., rng=...)
    if isinstance(ctx.sample, Batch):   # the Batch path:
        ctx.batch = ctx.sample
        AFTER_GENERATE hooks (filtering = subsetting ctx.batch)
        return ctx.batch
    return ctx.sample      # any other container passes through as-is

Conditioning is optional: pass ``condition_func``, or set a ``condition``
attribute on the generating function, to transform inputs before generation.
It prepares the request -- what the procedure is asked to do -- it does not
constrain what comes out (output constraints live in guidance, rejection
hooks, or pipeline stages). With neither, the inputs reach the function
untouched and the ``BEFORE_CONDITION``/``AFTER_CONDITION`` stages do not
fire.

Hooks registered at the
:class:`~nvalchemi.gen.stages.GenerationStage` points receive one shared
:class:`~nvalchemi.hooks.GenerationContext` per call and mutate it by
replacing its fields; the driver re-reads the context after each dispatch.
Hooks run in list order at each stage, and a raising hook aborts the call.
See the stage enum for what may change where and when each stage fires.
Hooks reach the procedure via ``ctx.workflow.generator_func``;
``ctx.model`` is always ``None`` -- the driver has no model field.

The defaults chain
------------------
Every cross-cutting knob resolves the same way: an explicit driver argument
wins, then the generating function's attribute, then the module default.

* conditioning: ``condition_func`` > ``generator_func.condition`` > ``None``
  (no condition step; the inputs pass through untouched).
* field declarations: constructor ``required_inputs`` / ``outputs`` >
  ``generator_func``'s attributes > ``None`` (undeclared;
  :class:`~nvalchemi.gen.pipeline.GenerationPipeline` validation fails fast).
* device: ``device`` > ``generator_func.device`` > ``None`` (no stream, no
  device-residency check, CPU session RNG).

Materialization is the function's own, and the output contract is a
:class:`~nvalchemi.data.Batch`: the driver fires the ``AFTER_GENERATE``
hooks on it, validates it, and pipelines compose it (including driving
dynamics). A function may return any other container, but then
``sample()`` passes it through untouched: no ``AFTER_GENERATE`` hooks, and
no feeding dynamics stages.

Examples
--------
A GAN, one forward pass, returning a batch directly::

    def gan_generate(inputs=None, *, num_samples=1, rng=None, **kwargs):
        z = torch.randn(num_samples, latent_dim, generator=rng)
        positions = decode(z).reshape(num_samples, num_atoms, 3)
        numbers = torch.full((num_atoms,), 6)
        return Batch.from_data_list(
            [AtomicData(positions=x, atomic_numbers=numbers) for x in positions]
        )

    gan = AtomisticGenerator(generator_func=gan_generate)

Model-owning procedures -- a callable object carries the model (plus
``device`` and field declarations the driver reads as defaults); the tests
and examples ship such objects::

    gen = AtomisticGenerator(generator_func=GANGenerate(gan_model))

Streaming -- one ``sample()`` call per input item; ``None`` means repeated
unconditional draws (an infinite stream unless capped)::

    for batch in gen.stream(None, max_batches=10):
        ...

Composition -- sequential pipelines mirror the dynamics ``|`` sugar
(:class:`~nvalchemi.gen.pipeline.GenerationPipeline`)::

    pipe = gen_a | gen_b
    out = pipe(inputs)

Sessions: streams, RNG, and compile -- the driver is a context manager.
Entering a session (``with gen:``) creates a dedicated CUDA stream when the
resolved device is CUDA (unless ``dedicated_stream=False``), seeds a
session-scoped :class:`torch.Generator` (advanced per draw), compiles the
generating function when ``compile_generate`` is set, and opens
context-manager hooks; exiting unwinds all of it::

    with gen.compile():
        for batch in gen.stream(inputs):
            ...
"""

from __future__ import annotations

import inspect
import itertools
from collections.abc import Iterator, Mapping
from contextlib import ExitStack
from dataclasses import dataclass
from typing import (
    TYPE_CHECKING,
    Any,
    Protocol,
    TypeVar,
    runtime_checkable,
)

import torch
from pydantic import (
    BaseModel,
    ConfigDict,
    Field,
    FieldSerializationInfo,
    field_serializer,
    field_validator,
    model_validator,
)
from tensordict import TensorDictBase

from nvalchemi._serialization import _wrap_custom_type, capture_callable_spec
from nvalchemi.data import AtomicData, Batch
from nvalchemi.gen._device import normalize_device
from nvalchemi.gen.stages import GenerationStage
from nvalchemi.hooks import GenerationContext, Hook, HookRegistryMixin
from nvalchemi.training import create_model_spec, create_model_spec_from_json

if TYPE_CHECKING:
    from nvalchemi.gen.pipeline import GenerationPipeline

__all__ = [
    "GeneratingFunction",
    "ConditionFunction",
    "AtomisticGenerator",
]

InputT = TypeVar("InputT")
SampleT = TypeVar("SampleT")


@dataclass
class _PreparedGeneration:
    """Resolved per-call state after generation preparation."""

    ctx: GenerationContext
    num_samples: int
    rng: torch.Generator | None
    kwargs: dict[str, Any]


_SerializableOptionalDevice: TypeAlias = _wrap_custom_type(torch.device) | None
"""Field annotation for ``device`` on spec-serializable models.

A plain ``torch.device | None`` cannot be dumped to JSON by pydantic, so
this alias routes the field through the ``torch.device`` serializer
registered in :mod:`nvalchemi._serialization`.

Round-trips via :func:`str` / :class:`torch.device` — the pair registered in
:mod:`nvalchemi._serialization` (``register_type_serializer``)."""


[docs] @runtime_checkable class GeneratingFunction(Protocol[InputT, SampleT]): """Callable that encapsulates a family-specific generation strategy. A :class:`GeneratingFunction` owns everything generation needs -- including the model, when there is one (held as a closure or an attribute of a callable object) -- samples from it, and returns the generated artifact. Conditioning may live inside the function, or as a ``condition`` attribute the driver calls before generation (see below); with neither, the inputs pass through untouched as the first positional argument. ``num_samples`` semantics are the function's own (per-conditioning-entry draws vs an unconditional total); the driver passes its ``num_samples`` straight through. ``rng`` is ``None`` unless the driver has a ``seed``, a session, or a per-call ``rng=`` -- handle ``None`` (torch sampling ops accept it). Outside a session the resolved RNG is CPU-resident even when generating on CUDA; inside a session it lives on the resolved device. When you draw on a device, make sure the generator matches it (e.g. ``torch.randn(..., generator=rng, device=...)``). Return a :class:`~nvalchemi.data.Batch`: that is the output contract. The driver fires the ``AFTER_GENERATE`` hooks on it, validates its device and declared ``outputs``, and pipelines compose it (including driving dynamics on it). Any other container is a fallback with real losses: ``sample()`` passes it through untouched, the ``AFTER_GENERATE`` hooks are skipped, and it cannot feed dynamics stages. Inside the function, a :class:`~tensordict.TensorDict` survives ``torch.compile`` where arbitrary containers graph-break under ``compile_generate``; convert it to a ``Batch`` before returning. Library-native sampling loops (e.g. PhysicsNeMo diffusion samplers) plug in through a thin adapter with this signature. **Optional attributes.** A callable object (rather than a plain function) may carry attributes the :class:`AtomisticGenerator` reads as defaults when the driver does not set them explicitly: - ``condition`` -- a :class:`ConditionFunction` mapping the call's raw inputs to the conditioned value the function is then called with (e.g. tiling a conditioning :class:`~nvalchemi.data.Batch` so each graph gets ``num_samples`` draws). The driver runs it between the ``BEFORE_CONDITION`` and ``AFTER_CONDITION`` dispatches, which fire only when a condition step is provided; an explicit driver ``condition_func`` takes precedence over this attribute. There is no default condition: functions implement their own per use case, binding any extra context in their closure. - ``device`` -- a :class:`torch.device` (or parseable device string), used when the driver's ``device`` is unset. - ``required_inputs`` / ``outputs`` -- batch-field declarations, used when the driver does not pass them at construction. """ def __call__( self, inputs: InputT | AtomicData | Batch | None = None, *, num_samples: int = 1, rng: torch.Generator | None = None, **kwargs: Any, ) -> SampleT: ...
[docs] @runtime_checkable class ConditionFunction(Protocol): """Translate a call's raw request into the generating function's working input. Receives the raw inputs, the resolved ``num_samples``, and the resolved ``rng``; returns the conditioned value the generating function is then called with. The return type is the procedure's own -- conditioning may change the type (e.g. a SMILES string becomes a :class:`~nvalchemi.data.Batch`). There is no default: procedures implement their own per use case. The job is preparation, not enforcement: conditioning decides what the procedure is *asked* to do, not what it must emit. Constraints on the output (e.g. "structures with a carboxyl group") live elsewhere -- guidance inside the generating function, rejection via hooks at :class:`~nvalchemi.gen.stages.GenerationStage.AFTER_GENERATE` or a wrapper generating function, or an explicit stage in a :class:`~nvalchemi.gen.pipeline.GenerationPipeline`. """ def __call__( self, inputs: Any, *, num_samples: int, rng: torch.Generator | None ) -> Any: ...
[docs] class AtomisticGenerator(BaseModel, HookRegistryMixin): """Generative inference driver: optionally condition the inputs, generate, optionally materialize to a :class:`~nvalchemi.data.Batch`. Attributes ---------- generator_func The :class:`GeneratingFunction` driving generation. Required; the function owns the model when there is one. condition_func Optional :class:`ConditionFunction` run before generation: maps the call's raw inputs to the conditioned value the generating function is then called with. It prepares the request -- it does not constrain what comes out. Takes precedence over the generating function's own ``condition`` attribute. When neither is provided, no conditioning happens -- the inputs pass through untouched and the ``BEFORE_CONDITION``/``AFTER_CONDITION`` stages do not fire. device Optional execution device. When unset, the generating function's ``device`` attribute is used. Bare ``"cuda"`` is resolved to the current GPU at construction, and that GPU remains fixed for this generator. If neither declares a device, no managed device or output-device check applies. dedicated_stream When ``True`` (default), entering a session creates a dedicated CUDA stream if the resolved device is CUDA. When ``False``, no stream is created even then. hooks Generation hooks, each with a :class:`GenerationStage` ``stage``. Validated at registration; see :class:`~nvalchemi.hooks.HookRegistryMixin`. Serialized as attribute-faithful class specs (each ``__init__`` parameter read back from the same-named attribute). required_inputs Batch fields this generator's input reads (empty means unconditional). Defaults from the generating function's ``required_inputs`` attribute; required by :class:`~nvalchemi.gen.pipeline.GenerationPipeline` for link validation. outputs Batch fields this generator's output carries (written or forwarded). Defaults from the generating function's ``outputs`` attribute. num_samples Independent draws requested per call, passed straight through to the generating function (per-entry vs total-draw semantics are the function's own). Per-call override via :meth:`sample`'s ``num_samples`` keyword. seed Optional base seed. Inside a session (``with gen:``) one :class:`torch.Generator` is seeded at entry and advanced per draw; outside a session each call derives ``torch.Generator().manual_seed(seed + step_count)``. A per-call ``rng=`` kwarg overrides both. step_count Runtime counter of generation calls -- incremented in a ``finally``, so failed calls count too. Drives hook frequency gating. Excluded from serialization. compile_generate Compile the generating function with ``torch.compile`` -- immediately via :meth:`compile`, or lazily at session entry. Default ``False``. compile_kwargs Keyword arguments forwarded to ``torch.compile``. Notes ----- ``generator_func`` and the other callables are held as arbitrary types (``arbitrary_types_allowed=True``). ``AtomisticGenerator`` is a context manager (``with gen:``): a session owns a dedicated CUDA stream (when the resolved device is CUDA and ``dedicated_stream`` is set), a session-scoped RNG, lazy compilation, and context-manager hooks. See :meth:`__enter__`. """ model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid") generator_func: GeneratingFunction condition_func: ConditionFunction | None = None device: _SerializableOptionalDevice = Field( default=None, description=( "Execution device, defaulting to generator_func.device. Bare CUDA " "is pinned to the current GPU at construction; CUDA availability " "and index bounds are validated." ), ) dedicated_stream: bool = Field( default=True, description=( "Create a dedicated CUDA stream at session entry when the resolved " "device is CUDA. Set False to suppress stream creation." ), ) hooks: list[Hook] = Field( default_factory=list, description=( "Generation hooks, fired at GenerationStage points with a shared " "GenerationContext per call." ), ) required_inputs: frozenset[str] | None = Field( default=None, description=( "Batch fields the input carries (empty = unconditional). " "Defaults from generator_func.required_inputs when available. " "Checked against the (conditioned) inputs on every call." ), ) outputs: frozenset[str] | None = Field( default=None, description=( "Batch fields the output carries (written or forwarded). " "Defaults from generator_func.outputs when available. " "Checked against the materialized batch before each return." ), ) num_samples: int = Field( default=1, ge=1, description="Independent draws per call, passed straight through to the generating function.", ) seed: int | None = Field( default=None, description="Base seed for per-draw RNGs (seed + step_count per call).", ) enable_inference_mode: bool = Field( default=False, description=( "Run generation under `torch.inference_mode` in the context manager. " "This disables gradient tracking; enable it for workflows that do " "not need gradients." ), ) step_count: int = Field( default=0, ge=0, exclude=True, description="Runtime counter of generation calls (hook frequency).", ) compile_generate: bool = Field( default=False, description=( "Compile the generating function with torch.compile (immediate via " "compile(), or lazily at session entry)." ), ) compile_kwargs: dict[str, Any] = Field( default_factory=dict, description=( "Keyword arguments forwarded to torch.compile; validated against " "its signature at construction and in compile()." ), ) @property def _stage_type(self) -> type[GenerationStage]: """Hook stage enum accepted by this engine (see :class:`HookRegistryMixin`). A property rather than a class attribute: pydantic collects the mixin's ``_stage_type`` annotation as a private attribute initialised to ``None``, and a plain class assignment does not override that on instances. """ return GenerationStage
[docs] def model_post_init(self, __context: Any) -> None: """Bind the execution device, register hooks, and initialize run state. Hook ``stage`` values arriving as raw ints or name strings (e.g. deserialized from a spec payload) are coerced to :class:`GenerationStage` before registration. """ if self.device is None: declared_device = getattr(self.generator_func, "device", None) if isinstance(declared_device, (torch.device, str)): self.device = normalize_device(declared_device) for hook in self.hooks: stage = getattr(hook, "stage", None) if isinstance(stage, str): hook.stage = GenerationStage[stage] elif isinstance(stage, int): hook.stage = GenerationStage(stage) self._init_hooks(list(self.hooks)) self._ctx: GenerationContext | None = None self._stream: torch.cuda.Stream | None = None self._stream_ctx: Any = None self._session_rng: torch.Generator | None = None self._compiled_generate: Any = None self._session_stack: ExitStack | None = None
@field_validator("device", mode="before") @classmethod def _validate_device(cls, value: Any) -> torch.device | None: """Normalize an optional device and validate CUDA availability. ``None`` leaves placement to the generating function. CUDA devices are resolved to an explicit GPU index at construction. Other device types are accepted as parsed. Parameters ---------- value The raw ``device`` input: ``None``, a device string, or a :class:`torch.device`. Returns ------- torch.device | None The normalized device. Raises ------ ValueError If the string cannot be parsed, the input is neither a string nor a :class:`torch.device`, or a CUDA device is requested that the host cannot provide. """ if value is None: return None return normalize_device(value) @field_validator("generator_func", "condition_func", "hooks", mode="before") @classmethod def _deserialize_spec_payloads(cls, v: Any) -> Any: """Rebuild live objects from spec payloads at load time. A ``dict`` value is a :class:`~nvalchemi.training.BaseSpec` payload captured at dump time and is deserialized with the training spec machinery (:func:`~nvalchemi.training.create_model_spec_from_json`; ``build`` resolves nested spec payloads recursively). ``hooks`` arrives as a list of payloads, each deserialized the same way. Live callables and hook instances pass through unchanged. Parameters ---------- v The raw field input. Returns ------- Any The rebuilt object(s), or ``v`` unchanged. """ if isinstance(v, dict): return create_model_spec_from_json(v).build() if isinstance(v, list): return [ create_model_spec_from_json(item).build() if isinstance(item, dict) else item for item in v ] return v @field_serializer("generator_func", "condition_func") def _serialize_callable( self, fn: Callable[..., Any] | None, info: FieldSerializationInfo ) -> dict[str, Any] | None: """Capture a callable field as a JSON-safe spec payload. The object's own ``to_spec()`` when it provides one, else a dotted-path capture of the module-level callable through the :func:`~nvalchemi._serialization._return_importable` identity factory. Lambdas, closures, and ``functools.partial`` objects carry no import path and are rejected by :func:`~nvalchemi._serialization._callable_path_of`. Fires for both ``model_dump()`` and ``model_dump_json()``. Parameters ---------- fn The live callable, or ``None``. info Field metadata (the field name labels capture errors). Returns ------- dict[str, Any] | None The serialized :class:`~nvalchemi.training.BaseSpec` payload. Raises ------ TypeError If ``fn.to_spec()`` does not return a :class:`~nvalchemi.training.BaseSpec`, or ``fn`` has no importable dotted path. """ if fn is None: return None return capture_callable_spec(fn, field_name=info.field_name).model_dump( mode="json" ) @field_serializer("hooks") def _serialize_hooks(self, hooks: list[Any]) -> list[dict[str, Any]]: """Capture each hook as a JSON-safe attribute-faithful spec payload. The payload is the hook class path plus its ``__init__`` keyword arguments, each read back from the same-named attribute (the attribute-faithful convention). Values must be JSON-serializable — keep hook state out of the constructor. Parameters ---------- hooks The live hook list. Returns ------- list[dict[str, Any]] One :class:`~nvalchemi.training.BaseSpec` payload per hook. Raises ------ TypeError If an ``__init__`` parameter cannot be read back from an attribute. """ payloads: list[dict[str, Any]] = [] for hook in hooks: cls = type(hook) kwargs: dict[str, Any] = {} for p in list(inspect.signature(cls.__init__).parameters.values())[1:]: if p.kind in ( inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD, ): continue if not hasattr(hook, p.name): raise TypeError( f"Cannot capture {cls.__name__} in a spec: __init__ " f"parameter {p.name!r} is not stored as a same-named " "attribute on the instance. Hook classes must be " "attribute-faithful to be spec-able." ) kwargs[p.name] = getattr(hook, p.name) payloads.append(create_model_spec(cls, **kwargs).model_dump(mode="json")) return payloads @field_serializer("required_inputs", "outputs") def _serialize_field_declarations( self, value: frozenset[str] | None ) -> list[str] | None: """Dump the declarations as sorted lists. Frozenset order varies between processes, so unsorted output would make two dumps of the same generator compare unequal. Parameters ---------- value The declared field set, or ``None``. Returns ------- list[str] | None The sorted declaration list, or ``None``. """ return sorted(value) if value is not None else None @model_validator(mode="after") def _default_field_declarations(self) -> AtomisticGenerator: """Default field declarations from ``generator_func`` attributes when present. Explicit constructor values always win; declarations stay ``None`` (undeclared) when the generating function carries no such attributes -- :class:`~nvalchemi.gen.pipeline.GenerationPipeline` validation then fails fast on the undeclared stage. Returns ------- AtomisticGenerator The generator with declarations defaulted. """ consumes = self.required_inputs if consumes is None: consumes = getattr(self.generator_func, "required_inputs", None) if consumes is not None: self.required_inputs = frozenset(consumes) produces = self.outputs if produces is None: produces = getattr(self.generator_func, "outputs", None) if produces is not None: self.outputs = frozenset(produces) return self @staticmethod def _check_compile_kwargs(kwargs: dict[str, Any]) -> None: """Raise ``ValueError`` for kwargs that are not ``torch.compile`` keywords. Parameters ---------- kwargs The kwargs to check against the installed ``torch.compile`` signature. Raises ------ ValueError If a key is not a keyword argument of ``torch.compile``, or is ``model`` (the compile target, filled by :meth:`compile` with the generating function). """ if not kwargs: return if "model" in kwargs: raise ValueError( "compile_kwargs must not contain 'model': compile() passes the " "generating function as the torch.compile target." ) params = inspect.signature(torch.compile).parameters valid = { name for name, param in params.items() if param.kind is inspect.Parameter.KEYWORD_ONLY } invalid = set(kwargs) - valid if invalid: raise ValueError( f"compile_kwargs {sorted(invalid)} are not keyword arguments of " f"torch.compile; valid options: {sorted(valid)}." ) @model_validator(mode="after") def _validate_compile_kwargs(self) -> AtomisticGenerator: """Check ``compile_kwargs`` against the installed ``torch.compile`` signature. Returns ------- AtomisticGenerator The validated generator. """ self._check_compile_kwargs(self.compile_kwargs) return self
[docs] def compile(self, **kwargs: Any) -> AtomisticGenerator: """Compile the generating function with ``torch.compile``. Merges *kwargs* with :attr:`compile_kwargs` (values passed here win), sets :attr:`compile_generate`, and wraps ``generator_func``. Calling again re-compiles with the new kwargs. Only the generating function is compiled; hook dispatch runs eagerly because it builds data structures and would graph-break anyway. Note the boundary: a function returning a :class:`~nvalchemi.data.Batch` builds it through pydantic, which dynamo cannot trace -- driver-level compile captures the tensor-pure prefix and breaks at materialization, and ``fullgraph=True`` cannot work there at all. For real capture, compile the model inside the generating function and leave the driver eager. Non-tensor-pure generating functions will graph-break under ``torch.compile``; compile the model inside such functions directly instead. Parameters ---------- **kwargs Forwarded to ``torch.compile``. Returns ------- AtomisticGenerator This instance, for fluent chaining. """ merged = {**self.compile_kwargs, **kwargs} self._check_compile_kwargs(merged) self.compile_kwargs = merged self.compile_generate = True self._compiled_generate = torch.compile(self.generator_func, **merged) return self
def __enter__(self) -> AtomisticGenerator: """Enter a generation session. Creates and enters a dedicated CUDA stream when the resolved device is CUDA and :attr:`dedicated_stream` is set (skipped when a pipeline has already supplied a stream), seeds the session RNG from :attr:`seed`, compiles the generating function when :attr:`compile_generate` is set, enters :func:`torch.inference_mode` when :attr:`enable_inference_mode` is set, and opens any context-manager hooks. The new stream waits on the caller's current stream at entry. Exiting does not synchronize the session stream: enqueue a ``wait_stream`` or ``synchronize`` before consuming results from a different stream. When no device resolves -- the driver has no ``device`` and the generating function declares none -- no stream is created, and the session owns only the RNG (when :attr:`seed` is set) and hook lifecycles. Returns ------- AtomisticGenerator This instance. """ if self._session_stack is not None: raise RuntimeError( "AtomisticGenerator sessions do not nest: this instance is " "already in a session (duplicate pipeline stage or a manual " "double-enter). Exit the active session first." ) stack = ExitStack() try: if self.enable_inference_mode and not torch.is_inference_mode_enabled(): # generation produces no autograd history inside a session stack.enter_context(torch.inference_mode()) if self._stream is None: device = self.device if ( device is not None and device.type == "cuda" and self.dedicated_stream ): self._stream = torch.cuda.Stream(device=device) # order the session stream after the caller's in-flight work self._stream.wait_stream(torch.cuda.current_stream(device)) self._stream_ctx = torch.cuda.stream(self._stream) stack.enter_context(self._stream_ctx) if self.seed is not None and self._session_rng is None: device = self.device rng_device = ( device if device is not None and device.type == "cuda" else "cpu" ) self._session_rng = torch.Generator(device=rng_device).manual_seed( self.seed ) if self.compile_generate and self._compiled_generate is None: self.compile() for hook in self.hooks: enter = getattr(hook, "__enter__", None) if enter is not None: enter() # hooks unwind with (None, None, None): the lifecycle convention # matches dynamics (no exception triple); close-having hooks # without __exit__ unwind through close() exit_ = getattr(hook, "__exit__", None) if exit_ is not None: stack.callback(exit_, None, None, None) else: close = getattr(hook, "close", None) if close is not None: stack.callback(close) except Exception: stack.close() self._stream = None self._stream_ctx = None self._session_rng = None raise self._session_stack = stack.pop_all() return self def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None: """Exit the session: close hooks, exit the stream, drop session RNG. Parameters ---------- exc_type, exc_val, exc_tb The active exception, if any. """ if self._session_stack is not None: self._session_stack.close() self._session_stack = None self._stream = None self._stream_ctx = None self._session_rng = None def _build_context(self, batch: Batch | None) -> GenerationContext: """Return the live per-call context built by :meth:`sample`. Hooks always see the same context object within a call, so mutations made at one stage are visible to later stages and to the core steps in between. Outside a call, a minimal context is built on demand. Parameters ---------- batch : Batch | None Current batch; used only when no per-call context is live. Returns ------- GenerationContext The live or freshly built context. """ if self._ctx is not None: return self._ctx from nvalchemi.training.distributed import get_rank return GenerationContext( batch=batch, global_rank=get_rank(None), inputs=batch, workflow=self, step_count=self.step_count, ) def _prepare_generation( self, inputs: Any, num_samples: int | None, kwargs: dict[str, Any], ) -> _PreparedGeneration: """Build and install the context, then resolve per-call generation state.""" from nvalchemi.training.distributed import get_rank ctx = GenerationContext( batch=inputs if isinstance(inputs, Batch) else None, global_rank=get_rank(None), workflow=self, inputs=inputs, step_count=self.step_count, ) self._ctx = ctx n_draws = num_samples if num_samples is not None else self.num_samples if n_draws < 1: raise ValueError(f"num_samples must be positive, got {n_draws}") # Resolve RNG: per-call override, then session, then seed-derived. rng = kwargs.pop("rng", None) if rng is None: if self._session_rng is not None: rng = self._session_rng elif self.seed is not None: device = self.device rng = torch.Generator( device=device if device is not None else "cpu" ).manual_seed(self.seed + ctx.step_count) # Resolve condition: driver's condition_func > generator_func.condition. condition = self.condition_func if condition is None: condition = getattr(self.generator_func, "condition", None) if condition is not None and callable(condition): self._call_hooks(GenerationStage.BEFORE_CONDITION, None) ctx.inputs = condition(ctx.inputs, num_samples=n_draws, rng=rng) self._call_hooks(GenerationStage.AFTER_CONDITION, None) if self.required_inputs: if ctx.inputs is None or not isinstance( ctx.inputs, (Batch, TensorDictBase, Mapping) ): raise TypeError( "AtomisticGenerator declares required_inputs=" f"{sorted(self.required_inputs)}, but the call's inputs " f"({type(ctx.inputs).__name__}) are not a " "field-addressable container (Batch, TensorDict, or a " "string-keyed mapping). Pass inputs carrying those " "fields, or fix the declaration." ) missing = [f for f in sorted(self.required_inputs) if f not in ctx.inputs] if missing: raise ValueError( "AtomisticGenerator declares required_inputs but the " f"call's inputs lack {missing}. Provide the fields in the " "inputs or in the condition step, or fix the declaration." ) return _PreparedGeneration(ctx, n_draws, rng, kwargs) def _finish_preparation( self, prepared: _PreparedGeneration | None, error: Exception | None, ) -> _PreparedGeneration: """Return prepared call state, or re-raise its preparation error.""" if error is not None: raise error if prepared is None: raise RuntimeError("generation preparation returned no call state") return prepared
[docs] def sample( self, inputs: Any = None, *, num_samples: int | None = None, **kwargs: Any, ) -> Any: """Generate samples for the given inputs. Runs the per-call pipeline shown in the module docstring: condition (only if a condition callable resolved for the call), generate on the session's CUDA stream, and the ``Batch`` path (hooks, device and field checks) when the sample is a :class:`~nvalchemi.data.Batch`. Hooks fire at the :class:`~nvalchemi.gen.stages.GenerationStage` points -- each stage only when the step it brackets ran -- and share one :class:`~nvalchemi.hooks.GenerationContext` for the whole call. Parameters ---------- inputs The input for this call -- a :class:`~nvalchemi.data.Batch`, another tensor container, or ``None`` for unconditional generation. When a condition step resolved for the call it runs on this value first and the generating function receives the conditioned result; otherwise the input is forwarded untouched. num_samples Per-call override for :attr:`num_samples`, passed straight through to the generating function. **kwargs Per-call options forwarded to the generating function (e.g. ``mask`` for inpainting). One reserved kwarg, ``rng=``, is consumed by ``sample`` itself to override the session/seeded RNG for this call. Returns ------- Any The generating function's output: a :class:`~nvalchemi.data.Batch` on the contract path -- ``AFTER_GENERATE`` hooks have run (post-filter, so possibly with fewer graphs than were sampled), and the device and declared-field checks passed. A zero-graph ``Batch`` (built via :meth:`~nvalchemi.data.Batch.empty`) passes through as-is (subsetting a batch to zero graphs still raises ``IndexError``). Any other container forfeits the ``Batch`` machinery: returned untouched, ``AFTER_GENERATE`` hooks skipped, and it cannot feed dynamics stages in a pipeline. Raises ------ TypeError If the call declares ``required_inputs`` but the inputs cannot carry fields, or ``AFTER_GENERATE`` hooks leave ``ctx.batch`` as something other than a :class:`~nvalchemi.data.Batch`. ValueError If ``num_samples`` resolves to less than 1, declared fields are missing from the inputs or the returned batch, or a device resolved (via ``device`` or ``generator_func.device``) but the returned batch lives on a different device. """ try: try: prepared = self._prepare_generation(inputs, num_samples, kwargs) except Exception as error: prepared = self._finish_preparation(None, error) else: prepared = self._finish_preparation(prepared, None) ctx = prepared.ctx gen_fn = self._compiled_generate or self.generator_func ctx.sample = gen_fn( ctx.inputs, num_samples=prepared.num_samples, rng=prepared.rng, **prepared.kwargs, ) if not isinstance(ctx.sample, Batch): # raw passthrough: AFTER_GENERATE hooks are Batch-level return ctx.sample # at this point, we should be able to treat the # sample as the batch now, ctx.batch = ctx.sample self._call_hooks(GenerationStage.AFTER_GENERATE, None) batch = ctx.batch device = self.device if ( device is not None and not torch.compiler.is_compiling() # a zero-graph batch (total rejection) carries no device state and batch.num_graphs > 0 ): batch_device = batch.device if device.type != batch_device.type or ( device.index is not None and batch_device.index is not None and device.index != batch_device.index ): raise ValueError( f"the generated batch lives on device " f"'{batch_device}', but the resolved device is " f"'{device}'. Move the batch onto the resolved device " "inside the generating function, or " "fix the device chain (AtomisticGenerator.device / " "generator_func.device)." ) if self.outputs and batch.num_graphs > 0: missing = [f for f in sorted(self.outputs) if f not in batch] if missing: raise ValueError( "AtomisticGenerator declares outputs but the " f"returned batch lacks {missing}. Add the fields in the " "generating function, or fix the " "declaration." ) return batch finally: if self._ctx is not None: self._ctx = None self.step_count += 1
def __call__(self, inputs: Any = None, **kwargs: Any) -> Any: """Syntactic sugar for :meth:`sample`. Parameters ---------- inputs The input for this call; forwarded to :meth:`sample`. **kwargs Forwarded to :meth:`sample`. Returns ------- Any The generated batch, or the raw sample when the function returns a non-``Batch`` container. """ return self.sample(inputs, **kwargs)
[docs] def stream( self, inputs: Any = None, *, max_batches: int | None = None, **kwargs: Any, ) -> Iterator[Any]: """Iterate over inputs, calling :meth:`sample` once per item. Pass any iterable of inputs, or ``None`` for repeated unconditional draws. ``stream(None)`` without ``max_batches`` is an infinite iterator. Parameters ---------- inputs Iterable of inputs, or ``None`` for unconditional draws. max_batches Stop after this many batches; ``None`` follows ``inputs``. When ``inputs`` is ``None`` and ``max_batches`` is unset the stream is unbounded. **kwargs Per-call options forwarded to :meth:`sample`. Yields ------ Any Each :meth:`sample` result exactly as produced: a :class:`~nvalchemi.data.Batch` when the function returns one, otherwise the raw sample. A function may signal total rejection with :meth:`~nvalchemi.data.Batch.empty` -- that zero-graph batch is yielded, so rejection-aware consumers should check ``num_graphs == 0``. Retrying rejected draws is the consumer's job. """ if inputs is None: inputs = itertools.repeat(None) for index, item in enumerate(inputs): if max_batches is not None and index >= max_batches: return yield self.sample(item, **kwargs)
def __iter__(self) -> Iterator[Any]: """Thin sugar for :meth:`stream` with default arguments. Warnings -------- This is an unbounded stream: ``list(gen)`` or a bare ``for`` loop never terminates. Bound it with ``stream(max_batches=...)``. Returns ------- Iterator ``self.stream()`` -- an unbounded stream of unconditional draws. """ return self.stream() def __or__(self, other: Any) -> GenerationPipeline: """Compose sequentially into a :class:`GenerationPipeline`. Mirrors :meth:`nvalchemi.dynamics.base.BaseDynamics.__or__`. (``+`` stays reserved for concurrent/fused composition, as in dynamics.) Parameters ---------- other A :class:`AtomisticGenerator`, a dynamics engine, a ``Batch -> Batch`` callable, or an existing pipeline. Returns ------- GenerationPipeline ``self`` followed by ``other`` (prepended when ``other`` is already a pipeline). """ from nvalchemi.gen.pipeline import GenerationPipeline if isinstance(other, GenerationPipeline): return GenerationPipeline(stages=[self, *other.stages]) return GenerationPipeline(stages=[self, other])