# 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.
"""Per-path energy statistics shared by reaction-path dynamics methods."""
from __future__ import annotations
from dataclasses import dataclass
from enum import Enum
import torch
from torch import Tensor
from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.dynamics.mep.path_ops.torch_paths import path_energy_stats
from nvalchemi.dynamics.mep.validate import validate_paths
from nvalchemi.hooks import DynamicsContext
[docs]
@dataclass(frozen=True)
class PathEnergyStats:
"""Preallocated energy statistics for a grouped path batch.
Attributes
----------
endpoint_reference_energy : Tensor
Smaller endpoint energy for each path, shape ``(num_paths,)``.
highest_interior_energy : Tensor
Maximum interior-image energy for each path, shape ``(num_paths,)``.
highest_interior_image_idx : Tensor
Packed image index attaining ``highest_interior_energy`` for each path,
shape ``(num_paths,)``. The tensor has dtype ``torch.int32``. Ties
select the first interior image. Unlike
:attr:`PathDiagnostics.highest_interior_image_idx
<nvalchemi.dynamics.mep.hooks.PathDiagnostics.highest_interior_image_idx>`,
this index is batch-global rather than path-local.
"""
endpoint_reference_energy: Tensor
highest_interior_energy: Tensor
highest_interior_image_idx: Tensor
[docs]
class PathEnergyStatsHook:
"""Compute reusable energy statistics for each path after model evaluation.
Register this hook before other hooks such as climbing-image selection,
path-force construction, and diagnostics. It prepares persistent buffers at
:attr:`DynamicsStage.ON_ADMISSION` and refreshes them from ``batch.energy``
at :attr:`DynamicsStage.AFTER_COMPUTE`.
Pass this same registered instance to downstream hooks that consume the
statistics. They should call :meth:`get_stats` after this hook has run for
the current evaluation. In eager execution, :meth:`get_stats` raises if the
energy tensor has changed since the statistics were refreshed. This check is
skipped during compilation because tensor mutation versions are private eager
metadata, so compiled hooks must still be registered in execution order.
The hook prepares its own int32 path offsets during ``ON_ADMISSION`` so it
can be used independently of path-force hooks.
"""
# Multi-stage dispatch is defined by `_runs_on_stage()`.
stage = None
frequency = 1
def __init__(self) -> None:
"""Initialize an unprepared path-energy statistics hook."""
self._stats: PathEnergyStats | None = None
self._path_ptr: Tensor
self._energy_update_token: tuple[Tensor, int, int] | None = None
def _runs_on_stage(self, stage: Enum) -> bool:
"""Return whether to prepare or refresh path-energy statistics."""
return stage in {
DynamicsStage.ON_ADMISSION,
DynamicsStage.AFTER_COMPUTE,
}
@torch.compiler.disable
def _prepare_batch(self, ctx: DynamicsContext) -> None:
"""Validate paths and allocate per-path output buffers.
Compilation is disabled because validation, shape-dependent tensor
allocation, and mutation of hook-owned Python state introduce graph
breaks. This path runs only during admission.
"""
batch = ctx.batch
validate_paths(batch)
self._energy_update_token = None
num_paths = batch.group_layout.num_groups
dtype = batch.positions.dtype
device = batch.device
self._stats = PathEnergyStats(
endpoint_reference_energy=torch.empty(
num_paths, dtype=dtype, device=device
),
highest_interior_energy=torch.empty(num_paths, dtype=dtype, device=device),
highest_interior_image_idx=torch.empty(
num_paths, dtype=torch.int32, device=device
),
)
self._path_ptr = batch.group_layout.group_ptr.to(torch.int32).contiguous()
@staticmethod
def _get_energy_update_token(ctx: DynamicsContext) -> tuple[Tensor, int, int]:
"""Identify the current energy tensor and its latest in-place update."""
energy = ctx.batch.energy
if torch.is_inference(energy):
raise RuntimeError(
"PathEnergyStatsHook cannot validate freshness for an inference "
"tensor because inference tensors do not track mutation versions"
)
return energy, energy._version, ctx.step_count
[docs]
def get_stats(self, ctx: DynamicsContext) -> PathEnergyStats:
"""Return statistics computed for the current energy evaluation.
Parameters
----------
ctx : DynamicsContext
Context containing the energy tensor whose statistics are needed.
Returns
-------
PathEnergyStats
Current per-path energy statistics.
Raises
------
RuntimeError
If the hook has not prepared its buffers at ``ON_ADMISSION``, has
not refreshed them for the current energy tensor update, or cannot
validate an inference tensor's mutation version.
"""
if self._stats is None:
raise RuntimeError(
"PathEnergyStatsHook must run at ON_ADMISSION before get_stats"
)
if not torch.compiler.is_compiling():
current_energy, current_version, current_step = (
self._get_energy_update_token(ctx)
)
token = self._energy_update_token
if (
token is None
or token[0] is not current_energy
or token[1] != current_version
or token[2] != current_step
):
raise RuntimeError(
"PathEnergyStatsHook statistics are stale for the current "
"energy evaluation; register and run PathEnergyStatsHook "
"before its consumers at AFTER_COMPUTE"
)
return self._stats
def __call__(self, ctx: DynamicsContext, stage: DynamicsStage) -> None:
"""Prepare buffers or refresh them based on the current image energies.
This hook intentionally ignores ``ctx.active_graph_mask`` because it only
computes statistics on energies. Downstream consumers can separately enforce
active-path ownership when mutating dynamics state.
"""
batch = ctx.batch
if stage == DynamicsStage.ON_ADMISSION:
self._prepare_batch(ctx)
return
if stage != DynamicsStage.AFTER_COMPUTE:
return
stats = self._stats
if stats is None:
raise RuntimeError(
"PathEnergyStatsHook must run at ON_ADMISSION before AFTER_COMPUTE"
)
path_ptr = self._path_ptr
path_energy_stats(
batch.energy.squeeze(-1).contiguous(),
path_ptr,
stats.endpoint_reference_energy,
stats.highest_interior_energy,
stats.highest_interior_image_idx,
)
# Tensor mutation versions are private eager metadata. Reading them while
# compiling creates guards and prevents stable CUDA-graph replay.
if not torch.compiler.is_compiling():
self._energy_update_token = self._get_energy_update_token(ctx)