Source code for nvalchemi.dynamics.strategy

# 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.
"""Declarative strategies that construct and run dynamics engines."""

from __future__ import annotations

from collections.abc import Mapping, Sequence
from typing import Annotated, Any, TypeAlias

import torch
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator

from nvalchemi._serialization import (
    SerializableOptionalClass,
    _extract_init_kwargs_from_attrs,
)
from nvalchemi.data import Batch
from nvalchemi.dynamics.base import BaseDynamics
from nvalchemi.hooks._protocol import Hook
from nvalchemi.models.base import BaseModelMixin
from nvalchemi.specs import BaseSpec, create_model_spec, create_model_spec_from_json

__all__ = ["DynamicsStrategy"]

# Strictly positive scalar integer
PositiveInt: TypeAlias = Annotated[int, Field(strict=True, gt=0)]


def _constructor_spec(component: Any) -> Any:
    """Build a reconstructible spec from a component's constructor state."""
    checkpoint_spec = getattr(component, "checkpoint_spec", None)
    if callable(checkpoint_spec):
        spec = checkpoint_spec()
        if spec is not None:
            if not isinstance(spec, BaseSpec):
                raise TypeError(
                    "checkpoint_spec() must return a BaseSpec or None; got "
                    f"{type(spec).__name__}."
                )
            return spec

    kwargs = _extract_init_kwargs_from_attrs(component)
    for name, value in list(kwargs.items()):
        if isinstance(value, torch.nn.Module):
            kwargs[name] = _constructor_spec(value)
    return create_model_spec(type(component), **kwargs)


def _component_spec_dict(component: Any, *, label: str) -> dict[str, Any]:
    """Serialize one reconstructible runtime component to a JSON dictionary."""
    try:
        return _constructor_spec(component).model_dump(mode="json")
    except (AttributeError, TypeError, ValueError) as exc:
        raise ValueError(
            f"Cannot serialize {label} {type(component).__name__}: {exc}"
        ) from exc


def _build_spec_component(raw: Any, *, label: str) -> Any:
    """Build one runtime component from a serialized constructor spec."""
    if not isinstance(raw, Mapping):
        raise ValueError(
            f"from_spec_dict: {label} must be a constructor-spec mapping; "
            f"got {type(raw).__name__}."
        )
    try:
        return create_model_spec_from_json(dict(raw)).build()
    except (AttributeError, TypeError, ValueError) as exc:
        raise ValueError(f"from_spec_dict: cannot rebuild {label}: {exc}") from exc


[docs] class DynamicsStrategy(BaseModel): """Base class for declarative, serializable dynamics strategies. A strategy stores the configuration needed to construct a dynamics engine. By default, each :meth:`run` constructs a fresh engine. Set ``cache_engine`` to continue the same simulation with its engine state preserved across runs. :meth:`to_spec_dict` represents hooks as reconstructible constructor specs while the live model remains a runtime dependency. When restoring with :meth:`from_spec_dict`, ``model=`` supplies that dependency and ``extra_hooks=`` appends runtime hooks. Parameters ---------- model : BaseModelMixin Potential model used by the dynamics engine. engine : type of BaseDynamics or None, optional Engine class for the default :meth:`build_engine` implementation. Serialized as an importable dotted path. ``None`` requires an override. engine_kwargs : dict of str to Any, optional Additional engine constructor arguments. ``model``, ``hooks``, and ``n_steps`` are supplied by the strategy. n_steps : int or None, optional Default number of dynamics steps. ``None`` delegates termination to the constructed engine. extra_hooks : sequence of Hook or None, optional Ordered runtime hooks added to the constructed engine. cache_engine : bool, optional Reuse the first engine built by :meth:`run` to continue the same simulation, preserving optimizer or thermostat state and step counts. Defaults to ``False``. Cached runtime state is excluded from strategy specs. """ model_config = ConfigDict( arbitrary_types_allowed=True, extra="forbid", validate_assignment=False, revalidate_instances="never", ) model: BaseModelMixin = Field( exclude=True, description=( "Live potential model used by the dynamics engine; excluded from " "strategy serialization." ), ) engine: SerializableOptionalClass = Field( default=None, description=( "Dynamics engine class for the default builder; None requires a " "build_engine override. Round-trips via an importable dotted path." ), ) engine_kwargs: dict[str, Any] = Field( default_factory=dict, description="Additional keyword arguments forwarded to the engine constructor.", ) n_steps: PositiveInt | None = Field( default=None, description="Default dynamics step limit, or None for no fixed limit.", ) extra_hooks: list[Hook] = Field( default_factory=list, exclude=True, description=( "Runtime hooks represented by ordered constructor specs during strategy " "serialization." ), ) cache_engine: bool = Field( default=False, description="Reuse the engine and its runtime state across run() calls.", ) _engine: BaseDynamics | None = PrivateAttr(default=None) @field_validator("engine") @classmethod def _validate_engine(cls, value: type | None) -> type[BaseDynamics] | None: """Require a dynamics engine subclass when a class is configured.""" if value is not None and not issubclass(value, BaseDynamics): raise TypeError("engine must subclass BaseDynamics") return value @field_validator("extra_hooks", mode="before") @classmethod def _normalize_extra_hooks(cls, value: Any) -> list[Hook]: """Convert an optional hook sequence to a new list.""" if value is None: return [] if isinstance(value, (str, bytes)) or not isinstance(value, Sequence): raise TypeError("extra_hooks must be a sequence of Hook objects or None") return list(value)
[docs] def build_engine(self) -> BaseDynamics: """Construct a fresh dynamics engine. The default builds one engine from :attr:`engine` and :meth:`build_hooks`. Override for multi-engine or multi-stage strategies. Returns ------- BaseDynamics Newly constructed engine configured by this strategy. Raises ------ NotImplementedError If no engine class is configured and this method is not overridden. """ if self.engine is None: raise NotImplementedError( f"{type(self).__name__} must set `engine=` or override build_engine()" ) return self.engine( model=self.model, hooks=self.build_hooks(), n_steps=self.n_steps, **self.engine_kwargs, )
[docs] def build_hooks(self) -> list[Hook]: """Build the ordered hook list for the default engine builder. Returns ------- list of Hook A new list containing the configured extra hooks. Override to add strategy-specific hooks. """ return list(self.extra_hooks)
[docs] def run( self, batch: Batch, n_steps: int | None = None, ) -> Batch: """Run an engine on ``batch``, reusing it when caching is enabled. With ``cache_engine=False``, every call builds a fresh engine. With ``cache_engine=True``, only the first call builds an engine, and later calls reuse its state and original configuration to continue the same simulation. Optimizer or thermostat state and step counts are retained. The caller must keep the batch's system/group membership and ordering, device, and dtype aligned with the cached engine's state. Compatibility is not validated automatically, and changing the batch does not reset engine state. Use ``cache_engine=False`` for independent simulations. Parameters ---------- batch : Batch Atomic systems to update in place. n_steps : int or None, optional Per-run step-limit override. ``None`` uses :attr:`n_steps`. Returns ------- Batch The input batch after dynamics updates. """ if self.cache_engine: if self._engine is None: self._engine = self.build_engine() engine = self._engine else: engine = self.build_engine() result = engine.run(batch, n_steps=n_steps) if result is None: raise RuntimeError( f"{type(self).__name__} unexpectedly completed without a result batch" ) return result
[docs] def to_spec_dict(self) -> dict[str, Any]: """Serialize declarative strategy fields to a JSON-ready dictionary. Hooks are represented by constructor specs. The live model, cached engine, and mutable hook state are not included. Subclasses with arbitrary configuration objects must provide Pydantic serializers or override this method. Returns ------- dict[str, Any] JSON-ready strategy configuration. """ spec = self.model_dump(mode="json") spec["extra_hook_specs"] = [ _component_spec_dict(hook, label=f"hook at index {index}") for index, hook in enumerate(self.extra_hooks) ] return spec
[docs] @classmethod def from_spec_dict( cls, spec: Mapping[str, Any], *, model: BaseModelMixin, extra_hooks: Sequence[Hook] | None = None, ) -> DynamicsStrategy: """Rebuild a strategy from :meth:`to_spec_dict` output. Parameters ---------- spec : mapping of str to Any JSON-decoded strategy configuration. model : BaseModelMixin Weighted potential model to attach to the restored strategy. extra_hooks : sequence of Hook or None, optional Runtime hooks appended after hooks rebuilt from serialized specs. Returns ------- DynamicsStrategy Freshly validated strategy instance. """ if not isinstance(spec, Mapping): raise TypeError("spec must be a mapping") data = dict(spec) runtime_fields = {"model", "extra_hooks"} & data.keys() if runtime_fields: names = ", ".join(sorted(runtime_fields)) raise ValueError(f"spec cannot contain runtime-only fields: {names}") raw_hook_specs = data.pop("extra_hook_specs", []) if not isinstance(raw_hook_specs, list): raise ValueError( "from_spec_dict: extra_hook_specs must be a list of constructor specs." ) hooks: list[Hook] = [] for index, raw_hook_spec in enumerate(raw_hook_specs): hook = _build_spec_component( raw_hook_spec, label=f"extra_hook_specs[{index}]", ) if not isinstance(hook, Hook): raise TypeError( f"from_spec_dict: extra_hook_specs[{index}] built " f"{type(hook).__name__}, expected Hook." ) hooks.append(hook) data["model"] = model data["extra_hooks"] = [*hooks, *(extra_hooks or [])] return cls.model_validate(data)