Source code for nvalchemi.models._derivatives

# 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.

"""Private graph-preserving derivative execution helpers."""

from __future__ import annotations

from collections.abc import Iterator
from contextlib import AbstractContextManager, contextmanager, nullcontext
from dataclasses import dataclass
from functools import partial
from types import TracebackType
from typing import TYPE_CHECKING, Any, Literal, Self

import torch
from torch import Tensor

from nvalchemi.data import Batch
from nvalchemi.data.level_storage import effective_dtype

if TYPE_CHECKING:
    from nvalchemi.models.base import BaseModelMixin

_DerivativeOperation = Literal["hvp", "dense_hessian"]
_DerivativeStrategy = Literal["loop", "vmap"]
_DerivativeExecutionKind = Literal["local", "distributed"]


class DerivativeNotSupported(NotImplementedError):
    """A model or execution context does not support a derivative request.

    Attributes
    ----------
    model_name : str
        Name of the model wrapper rejecting the request.
    operation : {"hvp", "dense_hessian"}
        Derivative operation requested by the caller.
    execution : {"local", "distributed"}
        Execution context in which the request was made.
    strategy : {"loop", "vmap"} or None
        Dense-Hessian strategy, or ``None`` for HVP requests.
    reason : str
        Explanation of why the request is unsupported.
    """

    def __init__(
        self,
        *,
        model_name: str,
        operation: _DerivativeOperation,
        execution: _DerivativeExecutionKind,
        strategy: _DerivativeStrategy | None,
        reason: str,
    ) -> None:
        """Initialize a contextual derivative capability error.

        Parameters
        ----------
        model_name : str
            Name of the model wrapper rejecting the request.
        operation : {"hvp", "dense_hessian"}
            Derivative operation requested by the caller.
        execution : {"local", "distributed"}
            Execution context in which the request was made.
        strategy : {"loop", "vmap"} or None
            Dense-Hessian strategy, or ``None`` for HVP requests.
        reason : str
            Explanation of why the request is unsupported.
        """
        self.model_name = model_name
        self.operation = operation
        self.execution = execution
        self.strategy = strategy
        self.reason = reason
        strategy_text = strategy if strategy is not None else "none"
        super().__init__(
            f"{model_name} does not support derivative operation '{operation}' "
            f"for execution='{execution}', strategy='{strategy_text}': {reason}"
        )

    def __reduce__(self) -> tuple[Any, tuple[Any, ...]]:
        """Reconstruct the exception from its contextual fields when unpickled."""
        return (
            partial(
                type(self),
                model_name=self.model_name,
                operation=self.operation,
                execution=self.execution,
                strategy=self.strategy,
                reason=self.reason,
            ),
            (),
        )


_CONFIG_OVERRIDE_UNSET = object()


@contextmanager
def _temporary_model_config(
    model: BaseModelMixin,
    *,
    active_outputs: Any = _CONFIG_OVERRIDE_UNSET,
    gradient_keys: Any = _CONFIG_OVERRIDE_UNSET,
) -> Iterator[None]:
    """Temporarily override selected config fields and restore their objects."""
    config = model.model_config
    saved: dict[str, Any] = {}
    try:
        if active_outputs is not _CONFIG_OVERRIDE_UNSET:
            saved["active_outputs"] = config.active_outputs
            config.active_outputs = active_outputs
        if gradient_keys is not _CONFIG_OVERRIDE_UNSET:
            saved["gradient_keys"] = config.gradient_keys
            config.gradient_keys = gradient_keys
        yield
    finally:
        for key, value in saved.items():
            setattr(config, key, value)


@dataclass(frozen=True, slots=True)
class _DerivativeRequest:
    """Describe one contextual second-order derivative request."""

    operation: _DerivativeOperation
    execution: _DerivativeExecutionKind
    strategy: _DerivativeStrategy | None

    def __post_init__(self) -> None:
        """Validate the request before capability checks or model execution."""
        if self.operation not in {"hvp", "dense_hessian"}:
            raise ValueError(
                f"operation must be 'hvp' or 'dense_hessian', got {self.operation!r}"
            )
        if self.execution not in {"local", "distributed"}:
            raise ValueError(
                f"execution must be 'local' or 'distributed', got {self.execution!r}"
            )
        if self.strategy not in {None, "loop", "vmap"}:
            raise ValueError(
                f"strategy must be None, 'loop', or 'vmap', got {self.strategy!r}"
            )
        if self.operation == "hvp" and self.strategy is not None:
            raise ValueError("HVP requests must not specify a strategy")
        if self.operation == "dense_hessian" and self.strategy is None:
            raise ValueError(
                "Dense-Hessian requests must specify strategy='loop' or 'vmap'"
            )


@dataclass(slots=True)
class _DerivativeGraph:
    """Graph-connected state yielded while derivative preparation is active.

    ``data`` is the private working batch when the graph came from a model
    forward and ``None`` when the caller supplied the energy.
    """

    data: Batch | None
    positions: Tensor
    energy: Tensor


def _validate_hessian_vector(vector: Tensor, positions: Tensor) -> Tensor:
    """Validate one position-space vector against a reference tensor."""
    if not isinstance(vector, Tensor):
        raise TypeError(
            f"Hessian vector must be a torch.Tensor, got {type(vector).__name__}"
        )
    if not vector.is_floating_point():
        raise TypeError(
            f"Hessian vector must have a floating-point dtype, got {vector.dtype}"
        )
    if vector.shape != positions.shape:
        raise ValueError(
            "Hessian vector must have the same shape as positions "
            f"{tuple(positions.shape)}, got {tuple(vector.shape)}"
        )
    if vector.dtype != positions.dtype:
        raise ValueError(
            "Hessian vector must have the same dtype as positions "
            f"{positions.dtype}, got {vector.dtype}"
        )
    if vector.device != positions.device:
        raise ValueError(
            "Hessian vector must be on the same device as positions "
            f"{positions.device}, got {vector.device}"
        )
    return vector


def _position_gradient(graph: _DerivativeGraph) -> Tensor:
    """Construct the retained first position derivative for an HVP graph."""
    with torch.inference_mode(False), torch.enable_grad():
        gradient = torch.autograd.grad(
            graph.energy.sum(),
            graph.positions,
            create_graph=True,
            retain_graph=True,
            allow_unused=True,
        )[0]
        if gradient is None:
            raise RuntimeError(
                "Derivative energy is not connected to the position leaf"
            )

        if graph.positions.numel() == 0:
            return gradient
        if not gradient.requires_grad:
            raise RuntimeError(
                "First position derivative does not retain a differentiable graph"
            )

        # A first derivative can depend on model parameters but not on positions.
        # A connected zero Hessian returns zeros; a disconnected derivative returns None.
        probe = torch.autograd.grad(
            gradient,
            graph.positions,
            grad_outputs=torch.ones_like(gradient),
            retain_graph=True,
            allow_unused=True,
        )[0]
        if probe is None:
            raise RuntimeError(
                "First position derivative is not connected to the position leaf"
            )
    return gradient


def _gradient_vector_product(
    outputs: Tensor,
    positions: Tensor,
    grad_outputs: Tensor,
    *,
    is_grads_batched: bool,
    create_graph: bool = False,
) -> Tensor:
    """Differentiate a gradient view against positions for one or many seeds.

    The product is detached unless ``create_graph`` is set, in which case the
    single-seed path keeps it attached to the energy graph. The batched path
    only produces detached products, so requesting a graph there is refused.
    """
    if is_grads_batched and create_graph:
        raise ValueError("create_graph is not supported with is_grads_batched=True")
    with torch.inference_mode(False), torch.enable_grad():
        if positions.numel() == 0:
            shape = (
                (grad_outputs.shape[0], *positions.shape)
                if is_grads_batched
                else positions.shape
            )
            return positions.new_empty(shape)
        if not outputs.requires_grad:
            raise RuntimeError(
                "First position derivative does not retain a differentiable graph"
            )

        if is_grads_batched:

            def _single_product(seed: Tensor) -> Tensor:
                product = torch.autograd.grad(
                    outputs,
                    positions,
                    grad_outputs=seed,
                    create_graph=False,
                    retain_graph=True,
                    allow_unused=False,
                )[0]
                return product

            return torch.vmap(_single_product)(grad_outputs.detach()).detach()

        product = torch.autograd.grad(
            outputs,
            positions,
            grad_outputs=grad_outputs.detach(),
            create_graph=create_graph,
            retain_graph=True,
            allow_unused=False,
        )[0]
        return product if create_graph else product.detach()


@dataclass(frozen=True, slots=True)
class _ValidatedDenseHessianRequest:
    """Dense Hessian inputs validated before any model evaluation."""

    positions: Tensor
    num_nodes: list[int]
    strategy: _DerivativeStrategy
    row_chunk_size: int | None

    @classmethod
    def build(
        cls,
        batch: Batch,
        strategy: Any,
        row_chunk_size: Any,
    ) -> _ValidatedDenseHessianRequest:
        """Validate dense-Hessian inputs before any model evaluation."""
        if not isinstance(batch, Batch):
            raise TypeError(f"batch must be a Batch, got {type(batch).__name__}")
        if strategy not in ("loop", "vmap"):
            raise ValueError(f"strategy must be 'loop' or 'vmap', got {strategy!r}")
        if row_chunk_size is not None:
            if not isinstance(row_chunk_size, int) or isinstance(row_chunk_size, bool):
                raise TypeError("row_chunk_size must be a positive integer or None")
            if row_chunk_size <= 0:
                raise ValueError("row_chunk_size must be positive")

        positions = getattr(batch, "positions", None)
        if not isinstance(positions, Tensor):
            raise RuntimeError("Dense Hessians require tensor positions")
        if positions.ndim != 2 or positions.shape[1] != 3:
            raise ValueError(
                "Dense Hessian positions must have shape [total_atoms, 3], "
                f"got {tuple(positions.shape)}"
            )

        atomic_numbers = getattr(batch, "atomic_numbers", None)
        if not isinstance(atomic_numbers, Tensor):
            raise RuntimeError("Dense Hessians require tensor atomic_numbers")
        if atomic_numbers.ndim != 1:
            raise ValueError(
                "Dense Hessian atomic_numbers must have shape [total_atoms], "
                f"got {tuple(atomic_numbers.shape)}"
            )

        num_nodes = batch.num_nodes_list
        expected_atoms = sum(num_nodes)
        if positions.shape[0] != expected_atoms:
            raise ValueError(
                "Dense Hessian positions length must match active atom segmentation "
                f"{expected_atoms}, got {positions.shape[0]}"
            )
        if atomic_numbers.shape[0] != expected_atoms:
            raise ValueError(
                "Dense Hessian atomic_numbers length must match active atom "
                f"segmentation {expected_atoms}, got {atomic_numbers.shape[0]}"
            )

        schema = batch.get_level_schema()
        schema.add_product_level("atom_atom", left="atoms", right="atoms")
        field_group = schema.attr_to_group.get("hessian")
        if field_group is not None and field_group != "atom_atom":
            raise ValueError(
                f"Field 'hessian' must belong to level 'atom_atom', not '{field_group}'"
            )
        declared_dtype = schema.dtypes.get("hessian")
        if declared_dtype is not None:
            expected_dtype = effective_dtype(declared_dtype)
            if isinstance(expected_dtype, str):
                raise ValueError(
                    f"Field 'hessian' has unsupported declared dtype '{declared_dtype}'"
                )
            if expected_dtype != positions.dtype:
                raise ValueError(
                    "Field 'hessian' has declared dtype "
                    f"{declared_dtype}, expected {positions.dtype}"
                )

        if "hessian" in batch:
            hessian = batch["hessian"]
            expected_shape = (sum(count * count for count in num_nodes), 3, 3)
            if tuple(hessian.shape) != expected_shape:
                raise ValueError(
                    f"Existing 'hessian' field must have shape {expected_shape}, "
                    f"got {tuple(hessian.shape)}"
                )
            if hessian.dtype != positions.dtype:
                raise ValueError(
                    "Existing 'hessian' field must have dtype "
                    f"{positions.dtype}, got {hessian.dtype}"
                )

        return cls(
            positions=positions,
            num_nodes=num_nodes,
            strategy=strategy,
            row_chunk_size=row_chunk_size,
        )


def _dense_hessian_blocks(
    graph: _DerivativeGraph,
    gradient: Tensor,
    num_nodes: list[int],
    *,
    strategy: _DerivativeStrategy,
    row_chunk_size: int | None,
) -> list[Tensor]:
    """Materialize detached within-system Hessian blocks from one graph."""
    blocks: list[Tensor] = []
    atom_start = 0
    with torch.inference_mode(False), torch.enable_grad():
        for atom_count in num_nodes:
            atom_stop = atom_start + atom_count
            row_count = 3 * atom_count
            if row_count == 0:
                blocks.append(graph.positions.new_empty((0, 0, 3, 3)).detach())
                atom_start = atom_stop
                continue

            local_gradient = gradient[atom_start:atom_stop]
            chunk_size = row_count if row_chunk_size is None else row_chunk_size
            row_chunks: list[Tensor] = []
            for row_start in range(0, row_count, chunk_size):
                row_stop = min(row_start + chunk_size, row_count)
                if strategy == "vmap":
                    rows = torch.arange(
                        row_start,
                        row_stop,
                        device=graph.positions.device,
                    )
                    seeds = graph.positions.new_zeros(
                        (row_stop - row_start, atom_count, 3)
                    )
                    seeds[
                        torch.arange(rows.shape[0], device=rows.device),
                        torch.div(rows, 3, rounding_mode="floor"),
                        torch.remainder(rows, 3),
                    ] = 1
                    products = _gradient_vector_product(
                        local_gradient,
                        graph.positions,
                        seeds,
                        is_grads_batched=True,
                    )
                    row_chunks.append(products[:, atom_start:atom_stop].clone())
                else:
                    loop_rows: list[Tensor] = []
                    for row in range(row_start, row_stop):
                        seed = torch.zeros_like(local_gradient)
                        seed.reshape(-1)[row] = 1
                        product = _gradient_vector_product(
                            local_gradient,
                            graph.positions,
                            seed,
                            is_grads_batched=False,
                        )
                        loop_rows.append(product[atom_start:atom_stop].clone())
                    row_chunks.append(torch.stack(loop_rows, dim=0))

            rows = torch.cat(row_chunks, dim=0)
            block = (
                rows.reshape(atom_count, 3, atom_count, 3)
                .permute(0, 2, 1, 3)
                .contiguous()
                .detach()
            )
            blocks.append(block)
            atom_start = atom_stop
    return blocks


def _attach_hessian_blocks(
    batch: Batch,
    blocks: list[Tensor],
    *,
    dtype: torch.dtype,
) -> None:
    """Prepare and install canonical Hessian blocks as one Batch update."""
    schema = batch.get_level_schema()
    schema.add_product_level("atom_atom", left="atoms", right="atoms")
    group_name, blocks = batch._validate_add_key_request(
        "hessian",
        blocks,
        level="atom_atom",
        overwrite=True,
        dtype=dtype,
        payload_shape=(3, 3),
        schema=schema,
    )
    prepared = batch._prepare_product_field(
        "hessian",
        blocks,
        group_name,
        schema=schema,
        dtype=dtype,
        payload_shape=(3, 3),
    )
    candidate_schema, groups, data_updates = prepared
    batch._install_level_schema(
        candidate_schema,
        groups=groups,
        data_updates=data_updates,
    )


[docs] class HessianOperator: """Matrix-free Hessian for repeated products at one geometry. Obtain an operator through :meth:`~nvalchemi.models.base.BaseModelMixin.prepare_hessian`, which runs its own energy-only forward on an independent batch snapshot, or through :meth:`from_energy`, which differentiates an energy the caller already computed. Its :meth:`matvec` method computes ``(d^2 E / dR^2) @ v`` from a retained autograd graph. Keep model parameters, buffers, execution mode, and pipeline wiring unchanged while the operator is active. Call :meth:`close` or use a context manager to release the graph. """ def __init__( self, context: AbstractContextManager[_DerivativeGraph], ) -> None: """Enter a prepared derivative context and retain its first gradient.""" self._context: AbstractContextManager[_DerivativeGraph] | None = context self._graph: _DerivativeGraph | None = None self._gradient: Tensor | None = None self._closed = True try: graph = context.__enter__() except BaseException: self._context = None raise try: gradient = _position_gradient(graph) except BaseException as exc: try: context.__exit__(type(exc), exc, exc.__traceback__) finally: self._context = None raise self._graph = graph self._gradient = gradient self._closed = False
[docs] @classmethod def from_energy(cls, energy: Tensor, positions: Tensor) -> HessianOperator: """Build an operator from an energy the caller already computed. The energy must carry an autograd graph back to ``positions``, as the output of a forward pass run with ``positions.requires_grad`` enabled does. Nothing is re-evaluated: the operator retains the caller's graph, so products taken with ``create_graph=True`` stay attached to whatever produced the energy, including the model parameters and any DDP wrapper whose forward computed it. Parameters ---------- energy : torch.Tensor Floating tensor whose sum is differentiated, typically of shape ``(num_graphs, 1)``. positions : torch.Tensor Floating tensor with ``requires_grad`` enabled that the energy was computed from, on the same device as ``energy``. Returns ------- HessianOperator Active operator over the supplied graph. Raises ------ TypeError If either argument is not a floating-point tensor. ValueError If ``positions`` does not require gradients or the tensors are on different devices. RuntimeError If ``energy`` carries no autograd graph, or its first position derivative is not connected to ``positions``. Examples -------- >>> import torch >>> from nvalchemi.models import HessianOperator >>> batch.positions.requires_grad_(True) # doctest: +SKIP >>> energy = model(batch)["energy"] # doctest: +SKIP >>> with HessianOperator.from_energy(energy, batch.positions) as op: # doctest: +SKIP ... product = op.matvec(torch.randn_like(batch.positions)) Notes ----- No wrapper capability check runs on this path, because no wrapper is involved: the caller vouches that the graph behind ``energy`` is twice differentiable. An energy whose first derivative does not depend on the positions, such as one linear in them, is refused rather than given a zero Hessian, as :meth:`BaseModelMixin.prepare_hessian <nvalchemi.models.base.BaseModelMixin.prepare_hessian>` does. """ for name, value in (("energy", energy), ("positions", positions)): if not isinstance(value, Tensor): raise TypeError( f"{name} must be a torch.Tensor, got {type(value).__name__}" ) if not value.is_floating_point(): raise TypeError( f"{name} must have a floating-point dtype, got {value.dtype}" ) if not positions.requires_grad: raise ValueError("positions must have requires_grad enabled") if energy.device != positions.device: raise ValueError( "energy must be on the positions device " f"{positions.device}, got {energy.device}" ) if not energy.requires_grad or energy.grad_fn is None: raise RuntimeError( "Derivative energy must retain a graph connected to the position leaf" ) graph = _DerivativeGraph(data=None, positions=positions, energy=energy) return cls(nullcontext(graph))
[docs] def matvec(self, vector: Tensor, *, create_graph: bool = False) -> Tensor: """Multiply the retained Hessian by one position-space vector. Parameters ---------- vector : torch.Tensor Floating tensor matching the prepared positions in shape, dtype, and device. create_graph : bool, optional Keep the product attached to the energy graph, and through it to the model parameters, so a loss can backpropagate through the product. Default ``False`` returns a detached product. Returns ------- torch.Tensor Hessian-vector product aligned with the prepared positions. Raises ------ RuntimeError If the operator has been closed. TypeError If the vector is not a floating-point tensor. ValueError If shape, dtype, or device does not match the prepared positions. """ if self._closed: raise RuntimeError("HessianOperator is closed") graph = self._graph gradient = self._gradient if graph is None or gradient is None: raise RuntimeError("HessianOperator has no active derivative graph") validated = _validate_hessian_vector(vector, graph.positions) return _gradient_vector_product( gradient, graph.positions, validated, is_grads_batched=False, create_graph=create_graph, )
[docs] def close(self) -> None: """Release the retained derivative graph; repeated calls are harmless.""" if self._closed: return context = self._context self._closed = True self._gradient = None self._graph = None self._context = None if context is not None: context.__exit__(None, None, None)
def __enter__(self) -> Self: """Return this active operator without rebuilding its graph.""" if self._closed: raise RuntimeError("HessianOperator is closed") return self def __exit__( self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, ) -> None: """Close the operator without suppressing an active exception.""" self.close()
@contextmanager def _prepare_derivative_graph( model: BaseModelMixin, batch: Batch, request: _DerivativeRequest, ) -> Iterator[_DerivativeGraph]: """Yield independent data and a connected energy graph for derivatives.""" if not isinstance(batch, Batch): raise TypeError(f"batch must be a Batch, got {type(batch).__name__}") if request.execution != "local": raise DerivativeNotSupported( model_name=type(model).__name__, operation=request.operation, execution=request.execution, strategy=request.strategy, reason="distributed second-order derivatives are not supported", ) model._validate_derivative_request(request) graph: _DerivativeGraph | None = None working_batch: Batch | None = None positions: Tensor | None = None energy: Tensor | None = None try: with torch.inference_mode(False), torch.enable_grad(): working_batch = batch.clone() for key, value in list(working_batch): if isinstance(value, Tensor): working_batch[key] = value.detach() stored_positions = getattr(working_batch, "positions", None) if not isinstance(stored_positions, Tensor): raise RuntimeError( "Derivative graph preparation requires tensor positions" ) if not stored_positions.is_floating_point(): raise TypeError( "Derivative positions must have a floating-point dtype, " f"got {stored_positions.dtype}" ) positions = stored_positions.detach().clone().requires_grad_(True) working_batch["positions"] = positions model._copy_derivative_runtime_data(batch, working_batch) with _temporary_model_config( model, active_outputs={"energy"}, gradient_keys={"positions"}, ): candidate_energy = model._derivative_energy(working_batch) if not isinstance(candidate_energy, Tensor): raise RuntimeError( "Derivative energy must be a torch.Tensor, " f"got {type(candidate_energy).__name__}" ) expected_shape = (working_batch.num_graphs, 1) if tuple(candidate_energy.shape) != expected_shape: raise RuntimeError( "Derivative energy must have shape " f"{expected_shape}, got {tuple(candidate_energy.shape)}" ) if candidate_energy.device != positions.device: raise RuntimeError( "Derivative energy must be on the positions device " f"{positions.device}, got {candidate_energy.device}" ) if not candidate_energy.is_floating_point(): raise RuntimeError( "Derivative energy must have a floating-point dtype, " f"got {candidate_energy.dtype}" ) if not candidate_energy.requires_grad or candidate_energy.grad_fn is None: raise RuntimeError( "Derivative energy must retain a graph connected to the position leaf" ) energy = candidate_energy graph = _DerivativeGraph( data=working_batch, positions=positions, energy=energy, ) yield graph finally: graph = None energy = None positions = None working_batch = None