Source code for nvalchemi.models.gen.base

# 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.
"""Model-side generative API: config and mixin.

This is the *non-energy* counterpart to
:class:`~nvalchemi.models.base.BaseModelMixin`. Where ``BaseModelMixin`` is
MLIP/energy-oriented (energy, forces, stress, neighbor lists, autograd,
pipeline composition), a generative model owns a family-specific sampling
procedure (a diffusion sampler's loop, a GAN decoder pass, a packing or
population loop) and shares none of that energy machinery. The two are
kept separate: a generative model builds on this mixin, not
``BaseModelMixin``.

Two pieces live here:

* :class:`GenerativeModelConfig` — a pydantic config schema describing a
  generative model's capability surface: batch-field declarations and
  prediction-output keys. It is set as ``self.model_config``
  in a wrapper's ``__init__``, mirroring the ``BaseModelMixin`` pattern (the
  config lives with the model, not on the
  :class:`~nvalchemi.gen.generator.AtomisticGenerator`).
* :class:`GenerativeModelMixin` — the model mixin providing
  ``forward`` (raw output) and ``adapt_output`` (raw -> :class:`ModelOutputs`).
  It owns no conditioning, scheduler, sampler, or guidance.
"""

from __future__ import annotations

import abc
from collections import OrderedDict
from collections.abc import Mapping
from typing import Annotated, Any

from pydantic import BaseModel, ConfigDict, Field
from torch import Tensor

from nvalchemi._typing import ModelOutputs
from nvalchemi.data import AtomicData, Batch

__all__ = [
    "GenerativeModelConfig",
    "GenerativeModelMixin",
]


[docs] class GenerativeModelConfig(BaseModel): """Pydantic config schema for a generative (non-energy) model. A :class:`GenerativeModelConfig` is the contract between a generative model wrapper and the rest of nvalchemi. Every :class:`GenerativeModelMixin` subclass must set a ``self.model_config`` instance in its ``__init__`` (no class-level default, so each wrapper owns its own config object — mirroring :class:`~nvalchemi.models.base.BaseModelMixin`). The base schema holds only the three capability fields below. Models with model-specific runtime fields should subclass it (e.g. ``class ClariConfig(GenerativeModelConfig): temperature: float = 1.0``) — the mixin's ``isinstance`` enforcement accepts subclasses. Attributes ---------- required_inputs Batch fields the model's conditioning reads (empty means unconditional). Declared here so a :class:`~nvalchemi.gen.pipeline.GenerationPipeline` can validate stage links at construction; a generator writes *something* by definition, so declarations are required, not optional. outputs Batch fields the model's generated output carries (written or forwarded). Distinct namespace from :attr:`prediction_outputs`, which keys ``ModelOutputs`` (e.g. ``"flow"``), not batch fields. prediction_outputs Output keys the model predicts (e.g. ``{"flow"}``). ``None`` defaults to ``{"flow"}`` at use time. Examples -------- >>> from nvalchemi.models.gen.base import GenerativeModelConfig >>> cfg = GenerativeModelConfig( ... required_inputs=frozenset({"positions", "atomic_numbers"}), ... outputs=frozenset({"positions", "atomic_numbers", "cell"}), ... ) >>> cfg.prediction_outputs is None True Notes ----- ``extra="forbid"``: unknown constructor keywords raise :class:`pydantic.ValidationError`, matching the :class:`~nvalchemi.models.base.ModelConfig` pattern. """ model_config = ConfigDict(extra="forbid") required_inputs: Annotated[ frozenset[str], Field( description=( "Batch fields the model's conditioning reads (empty = " "unconditional). Required: feeds GenerationPipeline link " "validation." ) ), ] outputs: Annotated[ frozenset[str], Field( description=( "Batch fields the model's generated output carries " "(written or forwarded). Required: feeds GenerationPipeline " "link validation." ) ), ] prediction_outputs: Annotated[ set[str] | None, Field( default=None, description=( "Output keys the model predicts (e.g. {'flow'}). None " "defaults to {'flow'} at use time." ), ), ] = None
[docs] class GenerativeModelMixin(abc.ABC): """Mixin class for models designed for generative workflows. This is the counterpart to :class:`~nvalchemi.models.base.BaseModelMixin`. It mirrors the two-step output pattern — ``forward`` returns raw output, :meth:`adapt_output` structures it into :class:`ModelOutputs` — with none of the energy machinery (no neighbor lists, no autograd plumbing). Concrete implementations must provide: - ``model_config`` attribute — a :class:`GenerativeModelConfig` (or a subclass of it) set in ``__init__`` (enforced by :meth:`__init_subclass__`). - :meth:`forward` — raw model output for one forward call. The mixin provides defaults for: - :meth:`adapt_output`: maps raw output to :class:`ModelOutputs`, keyed by :attr:`GenerativeModelConfig.prediction_outputs` (defaulting to ``{"flow"}``). ``forward`` / :meth:`adapt_output` are the model-side contract: the :class:`~nvalchemi.gen.generator.AtomisticGenerator` never reads them; the generating function calls them. Materialization and conditioning belong to the procedure, so the mixin defines neither. A model may define a ``to_batch(sample, cond_batch=None) -> Batch`` helper for its generating function to call (the demos do); nothing in the framework looks for it. Classes using this mixin do not own the generation process: that lives with the :class:`~nvalchemi.gen.generator.GeneratingFunction` (driven by the :class:`~nvalchemi.gen.generator.AtomisticGenerator`); the model is what the function samples from. """ model_config: GenerativeModelConfig # model_config must be set as an instance attribute in each subclass # __init__: self.model_config = GenerativeModelConfig(...). There is # intentionally NO class-level default (see BaseModelMixin for the same # rationale). __init_subclass__ wraps __init__ to enforce this at # construction time. def __init_subclass__(cls, **kwargs: Any) -> None: """Hook applied to every concrete subclass at class-creation time. Wraps the subclass ``__init__`` so that after construction, ``self.model_config`` is verified to exist and be a :class:`GenerativeModelConfig`. This catches the common mistake of forgetting to set ``model_config`` with a clear error instead of a late ``AttributeError`` deep in a forward pass. Parameters ---------- **kwargs Forwarded to the superclass hook. """ super().__init_subclass__(**kwargs) # Inject extra_repr onto the concrete class so it takes precedence over # ``nn.Module.extra_repr`` (which precedes this mixin in the MRO when a # wrapper is declared as ``class W(nn.Module, GenerativeModelMixin)``). if "extra_repr" not in cls.__dict__: cls.extra_repr = GenerativeModelMixin._config_extra_repr if "__init__" in cls.__dict__: import functools original_init = cls.__init__ @functools.wraps(original_init) def _checked_init(self: Any, *args: Any, **kw: Any) -> None: original_init(self, *args, **kw) cfg = getattr(self, "model_config", None) if not isinstance(cfg, GenerativeModelConfig): raise TypeError( f"{type(self).__name__}.__init__() must set " f"self.model_config = GenerativeModelConfig(...). " f"See GenerativeModelMixin docstring for details." ) cls.__init__ = _checked_init # type: ignore[attr-defined]
[docs] def adapt_output(self, raw: Any, data: AtomicData | Batch) -> ModelOutputs: """Map raw model output to :class:`ModelOutputs`. The default builds an :class:`OrderedDict` keyed by :attr:`GenerativeModelConfig.prediction_outputs` (defaulting to ``{"flow"}``). A dict-like ``raw`` fills matching keys; a single :class:`~torch.Tensor` is placed under the ``"flow"`` key (or the single configured key). Parameters ---------- raw Raw output from :meth:`forward`. data Source structure data (for context/metadata). Returns ------- ModelOutputs ``OrderedDict`` with the active prediction outputs. """ keys = self.model_config.prediction_outputs or {"flow"} output: ModelOutputs = OrderedDict((k, None) for k in sorted(keys)) if isinstance(raw, Mapping): for key in output: if key in raw: output[key] = raw[key] elif isinstance(raw, Tensor): key = "flow" if "flow" in output else next(iter(output)) output[key] = raw return output
@staticmethod def _config_extra_repr(self: Any) -> str: """Format the generative config for ``nn.Module.__repr__``. Parameters ---------- self The wrapper instance (injected onto concrete subclasses). Returns ------- str A short summary of the declared batch-field contracts. """ cfg = getattr(self, "model_config", None) if not isinstance(cfg, GenerativeModelConfig): return "model_config=<not set>" consumes = ", ".join(sorted(cfg.required_inputs)) produces = ", ".join(sorted(cfg.outputs)) return f"required_inputs={{{consumes}}}, outputs={{{produces}}}"