# 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.
"""Nudged elastic band strategy."""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from copy import deepcopy
from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal, Self
from pydantic import (
BaseModel,
ConfigDict,
Field,
field_serializer,
field_validator,
model_validator,
)
from nvalchemi._serialization import SerializableClass
from nvalchemi.dynamics.base import (
BaseDynamics,
ConvergenceHook,
DynamicsStage,
FusedStage,
)
from nvalchemi.dynamics.hooks import FreezeAtomsHook, LoggingHook
from nvalchemi.dynamics.mep.hooks import (
ClimbingImageSelectionHook,
NEBForceHook,
PathDiagnosticsHook,
PathEnergyStatsHook,
)
from nvalchemi.dynamics.mep.neb_configs import (
ConstantSpringConfig,
NEBMethod,
SpringConfig,
TorchNEBMethod,
)
from nvalchemi.dynamics.optimizers.fire2 import FIRE2
from nvalchemi.dynamics.strategy import (
DynamicsStrategy,
PositiveInt,
_build_spec_component,
_component_spec_dict,
)
from nvalchemi.hooks import Hook
if TYPE_CHECKING:
from nvalchemi.models.base import BaseModelMixin
__all__ = ["ClimbingImageConfig", "NEB"]
[docs]
class ClimbingImageConfig(BaseModel):
"""Configure climbing-image NEB activation."""
model_config = ConfigDict(frozen=True, extra="forbid")
mode: Literal["after_regular", "immediate"] = Field(
default="after_regular",
description=(
"Activate climbing forces after regular NEB convergence or from "
"the initial evaluation."
),
)
selection: Literal["fixed", "dynamic"] = Field(
default="fixed",
description=(
"Keep the initially selected climbing image or reselect the "
"highest-energy image after every evaluation."
),
)
regular_fmax: float | None = Field(
default=None,
gt=0,
description=(
"Force threshold for entering the climbing stage; None uses the "
"final NEB fmax. Only valid with mode='after_regular'."
),
)
max_regular_steps: PositiveInt | None = Field(
default=None,
description=(
"Per-path step budget for regular NEB. When reached, the path enters "
"the climbing-image stage even if the regular-stage convergence "
"criterion has not been satisfied. None waits for regular-stage "
"convergence, subject to the overall NEB.n_steps limit. "
"Only valid with mode='after_regular'. "
),
)
max_climbing_steps: PositiveInt | None = Field(
default=None,
description="Per-path step budget for climbing-image optimization.",
)
@field_validator("regular_fmax", mode="before")
@classmethod
def _validate_regular_fmax(cls, value: Any) -> float | None:
"""Validate and normalize the regular-stage convergence threshold."""
if value is None:
return None
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise TypeError("regular_fmax must be a number")
if value <= 0:
raise ValueError("regular_fmax must be positive")
return float(value)
@model_validator(mode="after")
def _validate_regular_stage_options(self) -> Self:
"""Restrict regular-stage options to staged climbing strategies."""
if self.mode != "after_regular" and self.regular_fmax is not None:
raise ValueError("regular_fmax is only valid with mode='after_regular'")
if self.mode != "after_regular" and self.max_regular_steps is not None:
raise ValueError(
"max_regular_steps is only valid with mode='after_regular'"
)
return self
_NEB_MANAGED_OPTIMIZER_KWARGS = {
"by_group",
"convergence_hook",
"hooks",
"model",
"n_steps",
"reprime_on_entry",
}
_NEB_FIRE2_DEFAULTS = {
"dt": 0.04,
"maxstep": 0.1,
"delaystep": 20,
"dtgrow": 1.1,
"dtshrink": 0.5,
"alphashrink": 0.99,
"alpha0": 0.25,
"tmax": 0.055,
"tmin": 0.0075,
}
[docs]
class NEB(DynamicsStrategy):
"""Run regular or climbing-image nudged elastic band optimization.
Every graph in the input batch is one path image, and its group layout
identifies complete paths. The strategy builds a group-aware
:class:`~nvalchemi.dynamics.FusedStage` containing one or two
optimizer stages.
Attributes
----------
convergence_hook : ConvergenceHook or None
Optional override for the final or only optimizer stage. When provided,
it takes precedence over ``fmax``. Otherwise, :meth:`build_engine`
constructs the force criterion from ``fmax``. Overrides must use the
standard hook type with ``frequency=1``.
regular_convergence_hook : ConvergenceHook or None
Optional override for the preliminary stage of an ``after_regular`` run.
When provided, it takes precedence over ``climbing.regular_fmax`` and
``fmax``. Otherwise, :meth:`build_engine` constructs the force
criterion from those thresholds. It has the same type and frequency
constraints and is otherwise ignored.
"""
model_config = ConfigDict(validate_assignment=True)
spring: float | SpringConfig = Field(
default=0.1,
description="Spring configuration used by the shared NEB force hook.",
)
method: str | NEBMethod | TorchNEBMethod = Field(
default="improved_tangent",
description=(
"Method for computing NEB forces: 'improved_tangent', custom Warp "
"equations, or a Torch callable. 'improved_tangent' is equivalent "
"to NEBMethod() without overrides."
),
)
climbing: ClimbingImageConfig | None = Field(
default=None,
description="Climbing-image configuration; None runs regular NEB only.",
)
optimizer: SerializableClass = Field(
default=FIRE2,
frozen=True,
description=(
"Optimizer class used by internal stages. Must subclass BaseDynamics "
"and support fixed-cell, group-aware updates through the FusedStage "
"contract. Cannot be reassigned after construction."
),
)
optimizer_kwargs: dict[str, Any] = Field(
default_factory=dict,
description=(
"Keyword arguments forwarded to each internal optimizer stage. "
"When using FIRE2, NEB-tuned defaults are applied to unspecified "
"parameters."
),
)
fmax: float = Field(
default=0.05,
gt=0,
description=(
"Force threshold for convergence of the final or only stage; ignored "
"when convergence_hook is provided."
),
)
endpoint_mode: Literal["fixed", "relaxed"] = Field(
default="fixed",
description="Whether path endpoint coordinates remain fixed or are relaxed.",
)
fixed_atom_indices: dict[int, tuple[int, ...]] | None = Field(
default=None,
description=(
"Mapping from path indices to atom indices held fixed in every image "
"of that path."
),
)
diagnostics_log_path: Path | None = Field(
default=None,
description=(
"CSV output path for per-path diagnostics. None disables both path "
"diagnostics and their logging hook."
),
)
diagnostics_frequency: PositiveInt = Field(
default=1,
description="Step frequency for computing and logging per-path diagnostics.",
)
compile: bool = Field(
default=False,
strict=True,
description="Compile the fused NEB step with torch.compile.",
)
compile_kwargs: dict[str, Any] = Field(
default_factory=dict,
description="Keyword arguments forwarded to torch.compile.",
)
neighbor_hooks: list[Hook] | None = Field(
default=None,
exclude=True,
description=(
"Neighbor-list hooks for the fused NEB engine. None uses hooks "
"generated by model.make_neighbor_hooks()."
),
)
convergence_hook: ConvergenceHook | None = Field(
default=None,
exclude=True,
description="Final-stage convergence override; takes precedence over fmax.",
)
regular_convergence_hook: ConvergenceHook | None = Field(
default=None,
exclude=True,
description=(
"Preliminary-stage convergence override; takes precedence over "
"climbing.regular_fmax and fmax."
),
)
@field_validator("engine", mode="before")
@classmethod
def _reject_engine(cls, value: Any) -> None:
"""Reject engine overrides because NEB constructs its own fused engine."""
if value is not None:
raise ValueError("NEB does not accept engine; use optimizer instead")
return None
@field_validator("engine_kwargs")
@classmethod
def _reject_engine_kwargs(cls, value: dict[str, Any]) -> dict[str, Any]:
"""Reject engine arguments that NEB's custom builder would ignore."""
if value:
raise ValueError(
"NEB does not accept nonempty engine_kwargs; use optimizer_kwargs instead"
)
return value
@field_validator("fmax", mode="before")
@classmethod
def _validate_fmax(cls, value: Any) -> float:
"""Validate and normalize the convergence threshold."""
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise TypeError("fmax must be a number")
if value <= 0:
raise ValueError("fmax must be positive")
return float(value)
@field_validator("compile", mode="before")
@classmethod
def _validate_boolean_options(cls, value: Any) -> bool:
"""Reject integer coercion for the compile option."""
if not isinstance(value, bool):
raise TypeError("compile must be boolean")
return value
@field_validator("optimizer_kwargs", mode="before")
@classmethod
def _normalize_optimizer_kwargs(cls, value: Any) -> dict[str, Any]:
"""Normalize optimizer keyword arguments."""
if value is None:
normalized: dict[str, Any] = {}
elif isinstance(value, dict):
normalized = dict(value)
else:
raise TypeError("optimizer_kwargs must be a dictionary or None")
reserved = _NEB_MANAGED_OPTIMIZER_KWARGS & normalized.keys()
if reserved:
names = ", ".join(sorted(reserved))
raise ValueError(
f"optimizer_kwargs cannot override NEB-managed keys: {names}"
)
return normalized
@field_validator("neighbor_hooks", mode="before")
@classmethod
def _normalize_neighbor_hooks(cls, value: Any) -> list[Hook] | None:
"""Validate and copy explicit neighbor hooks, preserving ``None`` to use
model-generated hooks."""
if value is None:
return None
if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
raise TypeError("neighbor_hooks must be a sequence of Hook objects or None")
hooks = list(value)
if any(not isinstance(hook, Hook) for hook in hooks):
raise TypeError("neighbor_hooks must contain only Hook objects")
return hooks
@staticmethod
def _validate_convergence_hook(value: Any) -> None:
"""Validate one convergence override at engine build time."""
if not isinstance(value, ConvergenceHook):
raise TypeError(
"NEB convergence overrides must be ConvergenceHook instances"
)
if type(value) is not ConvergenceHook:
raise TypeError("NEB convergence overrides do not support hook subclasses")
if value.frequency != 1:
raise ValueError("NEB convergence overrides must use frequency=1")
if value.source_status is not None or value.target_status is not None:
raise ValueError(
"NEB convergence hooks cannot set source_status or target_status; "
"NEB manages stage migration"
)
if not value.by_group:
raise ValueError("NEB convergence hooks must use by_group=True")
@field_validator("compile_kwargs", mode="before")
@classmethod
def _normalize_compile_kwargs(cls, value: Any) -> dict[str, Any]:
"""Own compile kwargs while accepting ``None`` as the default."""
if value is None:
return {}
if not isinstance(value, dict):
raise TypeError("compile_kwargs must be a dictionary or None")
return dict(value)
@field_validator("fixed_atom_indices", mode="before")
@classmethod
def _validate_fixed_atom_indices(cls, value: Any) -> Any:
"""Normalize the per-path fixed-atom mapping."""
if value is None:
return None
if not isinstance(value, Mapping):
raise TypeError(
"fixed_atom_indices must map path indices to atom-index sequences"
)
try:
normalized = {
path_index: tuple(atom_indices)
for path_index, atom_indices in value.items()
}
except TypeError as exc:
raise TypeError(
"fixed_atom_indices values must be sequences of integers"
) from exc
if any(
isinstance(path_index, bool) or not isinstance(path_index, int)
for path_index in normalized
):
raise TypeError("fixed_atom_indices keys must be integer path indices")
if any(
isinstance(atom_index, bool) or not isinstance(atom_index, int)
for atom_indices in normalized.values()
for atom_index in atom_indices
):
raise TypeError("fixed_atom_indices values must contain only integers")
return normalized
@field_validator("spring", mode="before")
@classmethod
def _validate_spring(cls, value: Any) -> Any:
"""Validate spring policies and restore serialized recipes."""
if isinstance(value, dict) and value.get("type") == "constant":
if set(value) != {"type", "value"}:
raise ValueError("constant spring spec must contain type and value")
value = ConstantSpringConfig(value["value"])
elif isinstance(value, dict) and value.get("type") == "custom":
if set(value) != {"type", "spec"}:
raise ValueError("custom spring spec must contain type and spec")
value = _build_spec_component(value["spec"], label="custom spring")
if not isinstance(value, SpringConfig):
raise TypeError(
"custom spring spec must build a SpringConfig; got "
f"{type(value).__name__}"
)
if isinstance(value, bool):
raise TypeError("spring must be a number or implement SpringConfig")
if isinstance(value, (int, float)):
ConstantSpringConfig(value)
return float(value)
if not isinstance(value, SpringConfig):
raise TypeError("spring must be a number or implement SpringConfig")
return value
@field_serializer("spring", when_used="json")
def _serialize_spring(self, spring: float | SpringConfig) -> float | dict[str, Any]:
"""Serialize numeric, constant, and custom spring configurations."""
if isinstance(spring, (int, float)):
return float(spring)
if isinstance(spring, ConstantSpringConfig):
return {"type": "constant", "value": spring.value}
return {
"type": "custom",
"spec": _component_spec_dict(spring, label="custom spring"),
}
@field_validator("method", mode="before")
@classmethod
def _restore_method(cls, value: Any) -> Any:
"""Restore Warp equations or a Torch method from its constructor spec."""
if isinstance(value, str) and value.startswith(
("stored_tangent|", "gram_stats|")
):
return NEBMethod.from_key(value)
if isinstance(value, Mapping) and value.get("type") == "torch":
if set(value) != {"type", "spec"}:
raise ValueError("Torch NEB method spec must contain type and spec")
method = _build_spec_component(value["spec"], label="Torch NEB method")
if not isinstance(method, TorchNEBMethod):
raise TypeError(
"Torch NEB method spec must build a callable; got "
f"{type(method).__name__}"
)
return method
return value
@field_serializer("method", when_used="json")
def _serialize_method(
self, method: str | NEBMethod | TorchNEBMethod
) -> str | dict[str, Any]:
"""Serialize named, Warp-equation, or Torch NEB methods."""
if isinstance(method, str):
return method
if isinstance(method, NEBMethod):
return method.to_key()
return {
"type": "torch",
"spec": _component_spec_dict(method, label="Torch NEB method"),
}
@model_validator(mode="after")
def _validate_optimizer(self) -> NEB:
"""Validate the optimizer class and apply its NEB defaults."""
if not issubclass(self.optimizer, BaseDynamics):
raise TypeError("optimizer must be a BaseDynamics subclass")
if self.optimizer is FIRE2:
for name, value in _NEB_FIRE2_DEFAULTS.items():
self.optimizer_kwargs.setdefault(name, value)
return self
def _build_convergence_hook(
self,
*,
fmax: float,
regular_stage: bool,
) -> ConvergenceHook:
"""Resolve the group-aware convergence hook for one optimizer stage."""
template = (
self.regular_convergence_hook if regular_stage else self.convergence_hook
)
if template is None:
return ConvergenceHook.from_fmax(threshold=fmax, by_group=True)
self._validate_convergence_hook(template)
return deepcopy(template)
def _build_path_hooks(self, *, climbing_status: int | None) -> list[Hook]:
"""Build the shared ordered path hook stack."""
energy_stats = PathEnergyStatsHook()
hooks: list[Hook] = [energy_stats]
if climbing_status is not None:
config = self.climbing
if config is None:
raise RuntimeError("climbing stage requires climbing configuration")
hooks.append(
ClimbingImageSelectionHook(
energy_stats_hook=energy_stats,
selection=config.selection,
# Fused hooks receive the union mask, so restrict selection
# to the climbing-stage status.
status_code=climbing_status,
)
)
hooks.append(
NEBForceHook(
energy_stats_hook=energy_stats,
spring=self.spring,
method=self.method,
endpoint_mode=self.endpoint_mode,
fixed_atom_indices=self.fixed_atom_indices,
)
)
if self.endpoint_mode == "fixed" or self.fixed_atom_indices:
hooks.append(
FreezeAtomsHook(
mask_key="neb_fixed_node_mask",
zero_velocities=("velocities" in self.optimizer.__provides_keys__),
)
)
if self.diagnostics_log_path is not None:
diagnostics_hook = PathDiagnosticsHook(
energy_stats_hook=energy_stats,
frequency=self.diagnostics_frequency,
)
hooks.extend(
[
diagnostics_hook,
LoggingHook(
stage=DynamicsStage.ON_GRADUATE,
backend="csv",
frequency=self.diagnostics_frequency,
log_path=self.diagnostics_log_path,
custom_scalars={
"fmax": (
lambda _ctx: diagnostics_hook.get_diagnostics().fmax
),
"energy_barrier": (
lambda _ctx: (
diagnostics_hook.get_diagnostics().energy_barrier
)
),
"highest_interior_image_idx": (
lambda _ctx: (
diagnostics_hook.get_diagnostics().highest_interior_image_idx
)
),
"path_length": (
lambda _ctx: (
diagnostics_hook.get_diagnostics().path_length
)
),
},
by_group=True,
),
]
)
return hooks
[docs]
def build_engine(self) -> FusedStage:
"""Construct a fresh fused optimizer.
Returns
-------
FusedStage
Group-aware one- or two-stage optimizer strategy.
"""
optimizer_kwargs = {
**self.optimizer_kwargs,
"model": self.model,
"by_group": True,
}
if self.climbing is not None and self.climbing.mode == "after_regular":
climbing_status = 1
regular_fmax = (
self.fmax
if self.climbing.regular_fmax is None
else self.climbing.regular_fmax
)
stages = [
(
0,
self.optimizer(
**optimizer_kwargs,
n_steps=self.climbing.max_regular_steps,
convergence_hook=self._build_convergence_hook(
fmax=regular_fmax,
regular_stage=True,
),
),
),
(
1,
self.optimizer(
**optimizer_kwargs,
n_steps=self.climbing.max_climbing_steps,
convergence_hook=self._build_convergence_hook(
fmax=self.fmax,
regular_stage=False,
),
reprime_on_entry=True,
),
),
]
else:
climbing_status = 0 if self.climbing is not None else None
stages = [
(
0,
self.optimizer(
**optimizer_kwargs,
n_steps=(
None
if self.climbing is None
else self.climbing.max_climbing_steps
),
convergence_hook=self._build_convergence_hook(
fmax=self.fmax,
regular_stage=False,
),
),
)
]
neighbor_hooks = (
self.model.make_neighbor_hooks()
if self.neighbor_hooks is None
else self.neighbor_hooks
)
fused_hooks = [
*neighbor_hooks,
*self._build_path_hooks(climbing_status=climbing_status),
*self.build_hooks(),
]
return FusedStage(
sub_stages=stages,
n_steps=self.n_steps,
by_group=True,
hooks=fused_hooks,
compile_step=self.compile,
compile_kwargs=dict(self.compile_kwargs),
device_type=stages[0][1].device_type,
)
[docs]
def to_spec_dict(self) -> dict[str, Any]:
"""Serialize NEB configuration and convergence hooks."""
spec = super().to_spec_dict()
spec["neighbor_hook_specs"] = (
None
if self.neighbor_hooks is None
else [
_component_spec_dict(hook, label=f"neighbor hook at index {index}")
for index, hook in enumerate(self.neighbor_hooks)
]
)
for field_name in ("convergence_hook", "regular_convergence_hook"):
hook = getattr(self, field_name)
spec[f"{field_name}_spec"] = (
None if hook is None else _component_spec_dict(hook, label=field_name)
)
return spec
[docs]
@classmethod
def from_spec_dict(
cls,
spec: Mapping[str, Any],
*,
model: BaseModelMixin,
extra_hooks: Sequence[Hook] | None = None,
) -> Self:
"""Rebuild NEB configuration, including convergence hooks."""
if not isinstance(spec, Mapping):
raise TypeError("spec must be a mapping")
data = dict(spec)
raw_neighbor_hook_specs = data.pop("neighbor_hook_specs", None)
if raw_neighbor_hook_specs is not None:
if not isinstance(raw_neighbor_hook_specs, list):
raise ValueError(
"from_spec_dict: neighbor_hook_specs must be null or a list "
"of constructor specs."
)
data["neighbor_hooks"] = [
_build_spec_component(
raw_hook_spec,
label=f"neighbor hook at index {index}",
)
for index, raw_hook_spec in enumerate(raw_neighbor_hook_specs)
]
fixed_atom_indices = data.get("fixed_atom_indices")
if isinstance(fixed_atom_indices, Mapping):
data["fixed_atom_indices"] = {
int(path_index)
if isinstance(path_index, str) and path_index.lstrip("-").isdigit()
else path_index: atom_indices
for path_index, atom_indices in fixed_atom_indices.items()
}
for field_name in ("convergence_hook", "regular_convergence_hook"):
if field_name in data:
raise ValueError(f"spec cannot contain runtime field: {field_name}")
raw_spec = data.pop(f"{field_name}_spec", None)
if raw_spec is None:
continue
hook = _build_spec_component(raw_spec, label=f"{field_name}_spec")
if not isinstance(hook, ConvergenceHook):
raise TypeError(
f"{field_name}_spec built {type(hook).__name__}, expected "
"ConvergenceHook"
)
data[field_name] = hook
rebuilt = super().from_spec_dict(
data,
model=model,
extra_hooks=extra_hooks,
)
if not isinstance(rebuilt, cls):
raise RuntimeError(f"Expected {cls.__name__}, got {type(rebuilt).__name__}")
return rebuilt