# 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.
"""Climbing-image selection for nudged elastic band dynamics."""
from __future__ import annotations
from enum import Enum
from typing import Literal
import torch
from nvalchemi.dynamics.base import DynamicsStage
from nvalchemi.dynamics.mep.hooks.path_energy_stats import PathEnergyStatsHook
from nvalchemi.dynamics.mep.neb_ops.modes import CLIMBING_NEB, REGULAR_NEB
from nvalchemi.hooks import DynamicsContext
[docs]
class ClimbingImageSelectionHook:
"""Select the highest-energy interior image in each NEB path.
Register this hook after its shared :class:`PathEnergyStatsHook` and before
:class:`NEBForceHook`. Fixed selection chooses a climber when each path first
becomes active and retains it, while dynamic selection refreshes climbing
images after every model evaluation.
Parameters
----------
energy_stats_hook : PathEnergyStatsHook
Shared path-energy statistics hook registered before this hook.
selection : {"fixed", "dynamic"}, optional
Whether to retain the initial selection or refresh it after every model
evaluation. Default is ``"fixed"``.
status_code : int or None, optional
When registered on a :class:`~nvalchemi.dynamics.FusedStage`, restrict
selection or reselection to paths whose graph status equals this value.
Existing climbing modes persist after a status change. ``None`` relies
only on the context's active mask. Default is ``None``.
frequency : int, optional
Apply the hook every ``frequency`` dynamics steps. Default is ``1``.
Attributes
----------
stage : DynamicsStage
Hook stage, :attr:`DynamicsStage.AFTER_COMPUTE`.
Notes
-----
This hook requires dynamics configured with ``by_group=True``. Group-aware
status transitions keep both ``active_graph_mask`` and ``status`` uniform
within each NEB path, so their graph-level masks can be applied directly.
"""
stage = DynamicsStage.AFTER_COMPUTE
def __init__(
self,
*,
energy_stats_hook: PathEnergyStatsHook,
selection: Literal["fixed", "dynamic"] = "fixed",
status_code: int | None = None,
frequency: int = 1,
) -> None:
"""Initialize the climbing-image selection hook.
Raises
------
TypeError
If the statistics hook or frequency has an unsupported type.
ValueError
If the selection policy is unknown or frequency is not positive.
"""
if not isinstance(energy_stats_hook, PathEnergyStatsHook):
raise TypeError("energy_stats_hook must be a PathEnergyStatsHook")
if selection not in {"fixed", "dynamic"}:
raise ValueError("selection must be 'fixed' or 'dynamic'")
if status_code is not None:
if isinstance(status_code, bool) or not isinstance(status_code, int):
raise TypeError("status_code must be an integer or None")
if status_code < 0:
raise ValueError("status_code must be non-negative")
if isinstance(frequency, bool) or not isinstance(frequency, int):
raise TypeError(
f"frequency must be an integer; got {type(frequency).__name__}"
)
if frequency < 1:
raise ValueError("frequency must be positive")
self.energy_stats_hook = energy_stats_hook
self.selection = selection
self.status_code = status_code
self.frequency = frequency
self._initialized_graphs: torch.Tensor | None = None
self._fixed_selection_complete = False
def _runs_on_stage(self, stage: Enum) -> bool:
"""Return whether to initialize state or select climbing images."""
return stage in {
DynamicsStage.ON_ADMISSION,
DynamicsStage.AFTER_COMPUTE,
}
[docs]
def on_register(self, workflow: object) -> None:
"""Require group-aware dynamics for climbing-image selection.
Parameters
----------
workflow : object
Workflow on which this hook is being registered.
Raises
------
ValueError
If the workflow does not enable group-aware dynamics.
"""
if not getattr(workflow, "by_group", False):
raise ValueError(
"ClimbingImageSelectionHook requires dynamics configured "
"with by_group=True"
)
def __call__(self, ctx: DynamicsContext, stage: DynamicsStage) -> None:
"""Update image force modes from the current path-energy statistics."""
if stage == DynamicsStage.ON_ADMISSION:
if self.selection == "fixed":
# Without an active mask, all paths initialize together. This flag lets
# subsequent fixed-selection calls return immediately.
self._fixed_selection_complete = False
# In :class:`~nvalchemi.dynamics.FusedStage`, paths may become active on
# different iterations. Track initialization per graph, while grouped dynamics
# keeps this mask uniform within each path, avoiding a reduction and rebroadcast.
self._initialized_graphs = torch.zeros(
ctx.batch.num_graphs,
dtype=torch.bool,
device=ctx.batch.device,
)
return
if stage != DynamicsStage.AFTER_COMPUTE:
return
if (
self.selection == "fixed"
and ctx.active_graph_mask is None
and self.status_code is None
and self._fixed_selection_complete
):
return
batch = ctx.batch
if "force_mode" not in batch:
raise RuntimeError(
"ClimbingImageSelectionHook requires NEB force-mode preparation. "
"Dispatch NEBForceHook or a similar hook at ON_ADMISSION first"
)
force_mode = batch.force_mode
active_mask = (
torch.ones_like(force_mode, dtype=torch.bool)
if ctx.active_graph_mask is None
else ctx.active_graph_mask
)
if self.status_code is not None:
if "status" not in batch:
raise RuntimeError(
"ClimbingImageSelectionHook requires batch.status when "
"status_code is set"
)
status = batch.status
if status.dim() == 2:
status = status.squeeze(-1)
status = status[: batch.num_graphs]
active_mask = active_mask & (status == self.status_code)
if self.selection == "fixed":
if self._initialized_graphs is None:
raise RuntimeError(
"ClimbingImageSelectionHook must run at ON_ADMISSION before "
"fixed climbing-image selection"
)
# Select only active graphs whose fixed climber has not been initialized.
active_mask = active_mask & ~self._initialized_graphs
# Clear stale selections before this hook selects a climber.
climbing_mask = force_mode == CLIMBING_NEB
climbing_mask.logical_and_(active_mask)
force_mode.masked_fill_(climbing_mask, REGULAR_NEB)
# Mark the selected image for each path
stats = self.energy_stats_hook.get_stats(ctx)
selected_images = stats.highest_interior_image_idx.long()
selected_graph_mask = torch.zeros_like(force_mode, dtype=torch.bool)
selected_graph_mask.scatter_(
0, selected_images, torch.ones_like(selected_images, dtype=torch.bool)
)
selected_graph_mask.logical_and_(active_mask)
force_mode.masked_fill_(selected_graph_mask, CLIMBING_NEB)
if self.selection == "fixed":
self._initialized_graphs.logical_or_(active_mask)
if (
ctx.active_graph_mask is None
and self.status_code is None
and not torch.compiler.is_compiling()
):
self._fixed_selection_complete = True