# 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.
"""Sequential composition of generators and other batch-processing stages.
A :class:`GenerationPipeline` is a thin orchestrator: it folds a
conditioning input through an ordered list of stages -- generators, dynamics
engines, or any ``Batch -> Batch`` callable -- mirroring the dynamics
``|`` sugar (:meth:`nvalchemi.dynamics.base.BaseDynamics.__or__` builds a
``DistributedPipeline``; here ``AtomisticGenerator.__or__`` builds a
``GenerationPipeline``).
Examples
--------
::
pipe = gen_a | gen_b | optimizer
out = pipe(inputs) # one fold through the stages
for batch in pipe.stream(inputs): # lazy per-item fold
...
Semantics:
* **Stage 1 consumes the user's ``inputs``** (its generating function owns
conditioning); every later stage maps Batch -> Batch.
* **1:1 cardinality** per stage: filters may shrink a batch; nothing fans
out. An all-false filter can use :meth:`~nvalchemi.data.Batch.empty_like`
to retain materialized schema and capacities; ordinary empty Batch indexing
still raises ``IndexError``.
* **Empty batches short-circuit**: when a stage yields a zero-graph Batch,
remaining stages are skipped for that item and the empty Batch is returned
as-is. ``DeduplicateHook`` uses ``Batch.empty_like`` for an all-false mask.
* **Non-``Batch`` outputs are terminal-only**: a generating function returning
a non-``Batch`` container passes it through raw, so such a stage can only
be last (or feed plain callables); a dynamics stage fed a non-``Batch``
raises ``TypeError`` at the boundary (skipped under ``torch.compile``).
* **Per-stage hooks**: each :class:`~nvalchemi.gen.generator.AtomisticGenerator`
stage keeps its own hooks and
:class:`~nvalchemi.hooks.GenerationContext`; the pipeline passes only
the batch between stages.
* **Sessions and compile**: ``with pipe:`` creates one dedicated CUDA
stream (when the first AtomisticGenerator stage's resolved device is CUDA)
shared by every AtomisticGenerator stage that opts in -- sequential stages
serialize on it with no cross-stream sync. :meth:`compile` compiles each
AtomisticGenerator stage's generating function (non-AtomisticGenerator stages are
skipped); there is no whole-fold compile, since the Batch
plumbing between stages would graph-break for no real capture.
"""
from __future__ import annotations
import inspect
import itertools
import warnings
from collections.abc import Iterator, Mapping, Sequence
from contextlib import ExitStack, nullcontext
from typing import Any
import torch
from pydantic import (
BaseModel,
ConfigDict,
Field,
field_serializer,
field_validator,
model_validator,
)
from nvalchemi._serialization import capture_callable_spec
from nvalchemi.data import Batch
from nvalchemi.gen.generator import AtomisticGenerator
from nvalchemi.training import create_model_spec_from_json
__all__ = ["GenerationPipeline"]
[docs]
class GenerationPipeline(BaseModel):
"""Sequential composition of generation and batch-processing stages.
Attributes
----------
stages
Ordered pipeline stages: :class:`~nvalchemi.gen.generator.AtomisticGenerator`
instances, dynamics engines, or ``Batch -> Batch`` callables.
Notes
-----
**Field-contract validation.** Every ``AtomisticGenerator`` stage must declare
``required_inputs`` / ``outputs`` (set on the AtomisticGenerator directly
or defaulted from the generating function's attributes); construction
raises otherwise. For each adjacent AtomisticGenerator -> AtomisticGenerator link,
the downstream stage's ``required_inputs`` must be covered by the upstream
stage's ``outputs``: the dynamics link contract
(AIMNet2 ``charges`` -> Ewald) applied to generation. Authors of custom
generating functions own keeping their stage's declaration in sync with
what the function actually writes. Non-AtomisticGenerator stages carry no
declarations and are not validated (their outputs are unknown at
construction).
The first stage's ``required_inputs`` describe its *conditioning* input
and are not validated (the pipeline cannot know what a user's ``inputs``
carries).
**Sessions and compile.** ``GenerationPipeline`` is a context manager:
entry creates one dedicated CUDA stream (when the first
:class:`~nvalchemi.gen.generator.AtomisticGenerator` stage's resolved device
is CUDA) and shares it with every stage that follows the ``_stream``
convention -- AtomisticGenerator stages with ``dedicated_stream`` set,
and any other stage that accepts a pre-set stream (dynamics engines and
fused stages honor it) -- then enters each stage's own session.
**Stage calling convention.** A stage with a ``run`` method (a dynamics
engine or a fused stage) is driven to completion with
``stage.run(batch, **kwargs)`` -- its own hooks fire inside its loop.
Any other stage is called as ``stage(batch, **kwargs)``. A dynamics
stage must carry its own exit criterion (convergence or ``n_steps``);
the fold offers no step budget of its own.
"""
model_config = ConfigDict(arbitrary_types_allowed=True)
stages: list[Any] = Field(
min_length=1,
description=(
"Ordered stages: Generators, dynamics engines, or Batch -> Batch callables."
),
)
@model_validator(mode="after")
def _validate_links(self) -> GenerationPipeline:
"""Validate declarations and adjacent AtomisticGenerator stages.
Returns
-------
GenerationPipeline
The validated pipeline.
Raises
------
ValueError
If an AtomisticGenerator stage lacks field declarations, or a
stage's ``required_inputs`` are not covered by the immediately
upstream AtomisticGenerator's ``outputs``.
"""
for index, stage in enumerate(self.stages):
if not callable(stage) and not hasattr(stage, "run"):
raise TypeError(
f"Pipeline stage {index} has type {type(stage).__name__}: stages "
"must be AtomisticGenerator instances, dynamics engines, or "
"Batch -> Batch callables."
)
if not isinstance(stage, AtomisticGenerator):
continue
consumes = stage.required_inputs
produces = stage.outputs
if consumes is None or produces is None:
missing = []
if consumes is None:
missing.append("required_inputs")
if produces is None:
missing.append("outputs")
fn = stage.generator_func
name = getattr(fn, "__name__", None) or type(fn).__name__
raise ValueError(
f"Pipeline stage {index} ({name}) is missing declarations: "
f"{', '.join(missing)}. Set them on the AtomisticGenerator or "
"on the generating function."
)
prev = self.stages[index - 1] if index > 0 else None
if isinstance(prev, AtomisticGenerator):
# Validated non-None on the previous iteration.
produced = prev.outputs or frozenset()
missing = set(consumes) - set(produced)
if missing:
raise ValueError(
f"Pipeline stage {index} consumes fields "
f"{sorted(missing)} that the upstream stage does not "
"produce (outputs="
f"{sorted(produced)}). Fix the "
"declarations or insert a stage that writes them."
)
return self
[docs]
def model_post_init(self, __context: Any) -> None:
"""Initialize session state."""
self._stream: torch.cuda.Stream | None = None
self._stream_ctx: Any = None
self._session_stack: ExitStack | None = None
[docs]
def compile(self, **kwargs: Any) -> GenerationPipeline:
"""Compile every AtomisticGenerator stage's generating function.
Per-stage compilation (see :meth:`AtomisticGenerator.compile`); non-AtomisticGenerator
stages are skipped. There is no whole-fold compile: the
Batch plumbing and hook dispatch between stages would graph-break for
no real capture. (Cross-stage tensor fusion is a separate research
item.)
Parameters
----------
**kwargs
Forwarded to each stage's :meth:`AtomisticGenerator.compile`.
Returns
-------
GenerationPipeline
This instance, for fluent chaining.
"""
for stage in self.stages:
if isinstance(stage, AtomisticGenerator):
stage.compile(**kwargs)
return self
@field_validator("stages", mode="before")
@classmethod
def _deserialize_stages(cls, v: Any) -> Any:
"""Rebuild serialized stage payloads to live stages.
A dict with a ``cls_path`` key is a captured callable payload
(dotted-path or factory capture) and deserializes through the
training spec machinery; any other dict is a serialized
:class:`~nvalchemi.gen.generator.AtomisticGenerator` and revalidates as
one. Live stages pass through unchanged.
Parameters
----------
v
The raw ``stages`` input.
Returns
-------
Any
The stages list with payloads rebuilt, or ``v`` unchanged when
not a list.
"""
if not isinstance(v, list):
return v
out: list[Any] = []
for item in v:
if isinstance(item, dict):
if "cls_path" in item:
out.append(create_model_spec_from_json(item).build())
else:
out.append(AtomisticGenerator.model_validate(item))
else:
out.append(item)
return out
@field_serializer("stages")
def _serialize_stages(self, stages: list[Any]) -> list[dict[str, Any]]:
"""Capture each stage as a JSON-safe nested payload.
:class:`~nvalchemi.gen.generator.AtomisticGenerator` stages serialize via
their own dump; any other stage (a plain ``Batch -> Batch``
callable) is captured by dotted import path through the
:func:`~nvalchemi._serialization._return_importable` identity
factory, or via the object's own ``to_spec()`` when it provides one.
Callable *instances* (e.g. dynamics engines) carry no import path
and are rejected. Fires for both ``model_dump()`` and
``model_dump_json()``.
Parameters
----------
stages
The live stages list.
Returns
-------
list[dict[str, Any]]
One payload per stage: a nested AtomisticGenerator dump, or a
:class:`~nvalchemi.training.BaseSpec` payload carrying
``cls_path``.
Raises
------
TypeError
If a stage's ``to_spec()`` does not return a
:class:`~nvalchemi.training.BaseSpec`, or the stage has no
importable dotted path.
"""
payloads: list[dict[str, Any]] = []
for stage in stages:
if isinstance(stage, AtomisticGenerator):
payloads.append(stage.model_dump(mode="json"))
continue
spec = capture_callable_spec(stage, field_name="stage")
payloads.append(spec.model_dump(mode="json"))
return payloads
def _infer_device(self) -> torch.device | None:
"""Read the bound device from the first AtomisticGenerator stage.
Returns
-------
torch.device | None
The construction-bound device, or ``None`` when the first
AtomisticGenerator stage is unmanaged or no such stage exists.
"""
for stage in self.stages:
if isinstance(stage, AtomisticGenerator):
return stage.device
return None
def __enter__(self) -> GenerationPipeline:
"""Enter a pipeline session: one CUDA stream shared across stages.
Creates one dedicated CUDA stream (when the first AtomisticGenerator
stage's resolved device is CUDA) and waits it on the caller's current
stream, shares it with every stage that follows the ``_stream``
convention -- AtomisticGenerator stages with ``dedicated_stream`` set
whose resolved device matches, and any other stage accepting a pre-set
stream (dynamics engines and fused stages honor it) -- then enters each
stage's own session. The pipeline never enters
:func:`torch.inference_mode` itself; generator stages manage their own.
Stages that provide a ``run`` method can require autograd. If the
caller wraps the pipeline in ``torch.no_grad``, the pipeline will not
disable that context.
Exiting does not synchronize the session stream: enqueue a
``wait_stream`` or ``synchronize`` before consuming results from a
different stream.
Returns
-------
GenerationPipeline
This instance.
"""
if self._session_stack is not None:
raise RuntimeError(
"GenerationPipeline sessions do not nest: this instance is "
"already in a session. Exit the active session first."
)
stack = ExitStack()
try:
device = self._infer_device()
if device is not None and device.type == "cuda":
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)
entered: set[int] = set()
for stage in self.stages:
if id(stage) in entered:
# the fold may call one stage object twice; its session
# lifecycle enters and exits once
continue
if isinstance(stage, AtomisticGenerator):
if stage.dedicated_stream and (
self._stream is None
or stage.device in (None, self._stream.device)
):
stage._stream = self._stream
stage.__enter__()
# stages unwind with (None, None, None): the lifecycle
# convention matches dynamics (no exception triple)
stack.callback(stage.__exit__, None, None, None)
entered.add(id(stage))
elif hasattr(stage, "__enter__"):
# Offer the shared stream to any stage that follows the
# ``_stream`` convention (dynamics engines, fused stages),
# but only when the stage lives on the stream's device.
if hasattr(stage, "_stream"):
stage_device = getattr(stage, "device", None)
if self._stream is None or stage_device in (
None,
self._stream.device,
):
stage._stream = self._stream
stage.__enter__()
stack.callback(stage.__exit__, None, None, None)
entered.add(id(stage))
except Exception:
stack.close()
self._stream = None
self._stream_ctx = 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: exit each AtomisticGenerator stage, then the stream.
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
def __call__(
self,
inputs: Any = None,
*,
stage_kwargs: Mapping[str, Any]
| Sequence[Mapping[str, Any] | None]
| None = None,
) -> Any:
"""Fold ``inputs`` through the stages.
Parameters
----------
inputs
Input for the first stage (a
:class:`~nvalchemi.data.Batch`, another tensor container, or
``None``).
stage_kwargs
Per-call keyword arguments addressed to stages: a single mapping
stretches across every stage (for homogeneous pipelines), or a
sequence of one mapping (or ``None``) per stage -- its length
must match the number of stages. Generator stages accept their
usual call options (``num_samples``, ``rng``, generating-function
options); a stage with a ``run`` method is driven with
``stage.run(batch, **kwargs)`` (e.g. ``{"n_steps": 200}``).
Returns
-------
Any
The final stage's output -- a :class:`~nvalchemi.data.Batch`,
unless the terminal stage is a mapping-less generator (raw
sample). If a stage yields a zero-graph Batch, remaining stages
are skipped and it is returned as-is.
Raises
------
ValueError
If ``stage_kwargs`` is a sequence whose length differs from the
number of stages.
"""
if stage_kwargs is None:
per_stage: list[dict[str, Any]] = [{} for _ in self.stages]
elif isinstance(stage_kwargs, Mapping):
# Copy per stage: stages may pop keys from their kwargs.
per_stage = [dict(stage_kwargs) for _ in self.stages]
else:
if len(stage_kwargs) != len(self.stages):
raise ValueError(
f"stage_kwargs must have one entry per stage "
f"({len(self.stages)}), got {len(stage_kwargs)}."
)
per_stage = [{} if kw is None else dict(kw) for kw in stage_kwargs]
from nvalchemi.dynamics.base import (
BaseDynamics, # lazy: keeps gen's import light
)
result: Any = inputs
for index, (stage, kwargs) in enumerate(
zip(self.stages, per_stage, strict=True)
):
if isinstance(result, Batch) and result.num_graphs == 0:
break
run = getattr(stage, "run", None)
if kwargs:
try:
params = inspect.signature(
run if run is not None else stage
).parameters.values()
except (TypeError, ValueError):
pass_kwargs = kwargs # unsignatureable: pass through, loudly
else:
if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in params):
pass_kwargs = kwargs
else:
accepted = {p.name for p in params}
pass_kwargs = {k: v for k, v in kwargs.items() if k in accepted}
dropped = sorted(kwargs.keys() - accepted)
if dropped:
warnings.warn(
f"Pipeline stage {index} ({type(stage).__name__}) "
f"ignores unsupported stage_kwargs {dropped}: they "
"match no parameter.",
UserWarning,
stacklevel=2,
)
else:
pass_kwargs = kwargs
if run is None:
result = stage(result, **pass_kwargs)
continue
if not isinstance(result, Batch):
if not torch.compiler.is_compiling() and isinstance(
stage, BaseDynamics
):
raise TypeError(
f"Pipeline stage {index} ({type(stage).__name__}) runs dynamics "
f"and requires a Batch input, but the previous stage produced "
f"{type(result).__name__}. A generating function feeding "
"dynamics must return a Batch (the documented output "
"contract); adjust the previous stage to return one."
)
result = run(result, **pass_kwargs)
continue
# The clone gives the next stage fresh tensors.
# A clone created under ``torch.inference_mode`` is still an
# inference tensor that blocks autograd. The code disables
# inference mode first so autograd can track the new tensors.
# The clone does not remove existing gradient history.
# A generator stage that feeds dynamics must produce tensors
# without gradient tracking.
with (
torch.inference_mode(False)
if torch.is_inference_mode_enabled()
else nullcontext()
):
result = result.clone()
result = run(result, **pass_kwargs)
return result
[docs]
def stream(
self,
inputs: Any = None,
*,
max_batches: int | None = None,
stage_kwargs: Mapping[str, Any]
| Sequence[Mapping[str, Any] | None]
| None = None,
) -> Iterator[Any]:
"""Stream pipeline outputs, mirroring :meth:`AtomisticGenerator.stream`.
One fold per input item; ``inputs`` is the data source.
Parameters
----------
inputs
Iterable of inputs, or ``None`` for repeated unconditional draws.
max_batches
Cap on batches yielded (``None`` means unbounded).
stage_kwargs
Per-call options addressed to stages, forwarded to
:meth:`__call__` on every fold.
Yields
------
Any
One output per fold, exactly as produced.
"""
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(item, stage_kwargs=stage_kwargs)
def __or__(self, other: Any) -> GenerationPipeline:
"""Append a stage, returning a new pipeline.
Parameters
----------
other
A stage to append (AtomisticGenerator, dynamics engine, or callable).
Returns
-------
GenerationPipeline
A pipeline of ``self.stages`` followed by ``other``.
"""
if isinstance(other, GenerationPipeline):
return GenerationPipeline(stages=[*self.stages, *other.stages])
return GenerationPipeline(stages=[*self.stages, other])