Source code for nvalchemi.dynamics.optimizers.fire2

# 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.
"""
FIRE2 and FIRE2+variable-cell geometry optimizers.

FIRE2 (Shuang et al., 2020) improves on FIRE with better restart
conditions and a modified velocity-mixing rule.

* ``FIRE2``            — fixed-cell coordinate optimizer.
* ``FIRE2VariableCell`` — variable-cell optimizer.

Both classes delegate to ``fire2_step_coord`` and
``fire2_step_coord_cell`` from :mod:`nvalchemiops.torch.fire2`, which
wrap the full FIRE2 step (MD integration + mixing).  The step is
therefore placed entirely in ``pre_update``; ``post_update`` is a no-op.

FIRE2 uses different hyperparameter names from FIRE:

* ``delaystep``   — minimum steps before adaptation (like n_min, default 60)
* ``dtgrow``      — timestep growth factor (like f_inc, default 1.05)
* ``dtshrink``    — timestep shrink factor (like f_dec, default 0.75)
* ``alphashrink`` — alpha decrease factor (like f_alpha, default 0.985)
* ``alpha0``      — initial mixing parameter (like alpha_start, default 0.09)
* ``tmax``        — maximum timestep (default 0.08)
* ``tmin``        — minimum timestep (default 0.005)
* ``maxstep``     — maximum displacement per step (default 0.1)

Per-system state: ``dt [M]``, ``alpha [M]``, ``nsteps_inc [M, int32]``.
For :class:`FIRE2VariableCell`: additionally ``cell_velocities [M,3,3]``.
"""

from __future__ import annotations

import math
from typing import TYPE_CHECKING, Any, ClassVar

import torch

from nvalchemi.data import Batch
from nvalchemi.dynamics._ops._bridge import _make_state_batch, _to_per_system
from nvalchemi.dynamics._ops.fire import fire2_step_coord, fire2_step_coord_cell
from nvalchemi.dynamics._ops.npt_nph import stress_to_cell_force
from nvalchemi.dynamics.base import BaseDynamics

if TYPE_CHECKING:
    from nvalchemi.dynamics.base import ConvergenceHook
    from nvalchemi.hooks import Hook
    from nvalchemi.models.base import BaseModelMixin

__all__ = ["FIRE2", "FIRE2VariableCell"]

_FIRE2_DEFAULTS = dict(
    delaystep=60,
    dtgrow=1.05,
    dtshrink=0.75,
    alphashrink=0.985,
    alpha0=0.09,
    tmax=0.08,
    tmin=0.005,
    maxstep=0.1,
)


def _build_state(
    n: int,
    dt: torch.Tensor,
    alpha0: float,
    dtype: torch.dtype,
    dev: torch.device,
    *,
    with_cell: bool = False,
) -> dict[str, torch.Tensor]:
    d = {
        "dt": dt,
        "alpha": torch.full((n,), alpha0, dtype=dtype, device=dev),
        "nsteps_inc": torch.zeros(n, dtype=torch.int32, device=dev),
        # Scratch buffers for FIRE2 dot-product reductions.
        "vf": torch.zeros(n, dtype=dtype, device=dev),
        "v_sumsq": torch.zeros(n, dtype=dtype, device=dev),
        "f_sumsq": torch.zeros(n, dtype=dtype, device=dev),
    }
    if with_cell:
        d["cell_velocities"] = torch.zeros(n, 3, 3, dtype=dtype, device=dev)
    return d


[docs] class FIRE2(BaseDynamics): """Fixed-cell FIRE2 geometry optimizer. Parameters ---------- model : BaseModelMixin The neural network potential model. dt : float or torch.Tensor Initial adaptive timestep ``[M]`` or scalar. With ``by_group=True``, ``M`` is the number of graph groups rather than the number of graphs. delaystep : int Minimum steps before adaptation. Default 60. dtgrow : float Timestep growth factor. Default 1.05. dtshrink : float Timestep shrink factor. Default 0.75. alphashrink : float Alpha decrease factor. Default 0.985. alpha0 : float Initial mixing parameter. Default 0.09. tmax : float Maximum timestep. Default 0.08. tmin : float Minimum timestep. Default 0.005. maxstep : float Maximum displacement per step. Default 0.1. n_steps : int, optional Total steps for :meth:`run`. hooks : list[Hook], optional Initial hooks. convergence_hook : ConvergenceHook or dict, optional Convergence criterion. by_group : bool, optional If True, update each group of graphs as a single unit, sharing the adaptive timestep, mixing parameter, and adaptation counters across the graphs in that group. Requires a valid layout set with ``batch.set_group_layout()``. A configured convergence hook must use the same ``by_group`` setting. Default False. Forwarded through ``**kwargs`` to :class:`~nvalchemi.dynamics.base.BaseDynamics`. **kwargs Forwarded to :class:`~nvalchemi.dynamics.base.BaseDynamics`. Attributes ---------- __needs_keys__ : set[str] ``{"forces"}``. __provides_keys__ : set[str] ``{"positions", "velocities"}``. """ __needs_keys__: set[str] = {"forces"} __provides_keys__: set[str] = {"positions", "velocities"} samples_equilibrium: ClassVar[bool] = False """A relaxation descends to a minimum rather than sampling an ensemble.""" def __init__( self, model: BaseModelMixin, dt: float | torch.Tensor, delaystep: int = _FIRE2_DEFAULTS["delaystep"], dtgrow: float = _FIRE2_DEFAULTS["dtgrow"], dtshrink: float = _FIRE2_DEFAULTS["dtshrink"], alphashrink: float = _FIRE2_DEFAULTS["alphashrink"], alpha0: float = _FIRE2_DEFAULTS["alpha0"], tmax: float = _FIRE2_DEFAULTS["tmax"], tmin: float = _FIRE2_DEFAULTS["tmin"], maxstep: float = _FIRE2_DEFAULTS["maxstep"], n_steps: int | None = None, hooks: list[Hook] | None = None, convergence_hook: ConvergenceHook | dict | None = None, **kwargs: Any, ) -> None: super().__init__( model=model, n_steps=n_steps, hooks=hooks, convergence_hook=convergence_hook, **kwargs, ) self._dt_init = dt self.delaystep = delaystep self.dtgrow = dtgrow self.dtshrink = dtshrink self.alphashrink = alphashrink self.alpha0 = alpha0 self.tmax = tmax self.tmin = tmin self.maxstep = maxstep def _init_state(self, batch: Batch) -> None: M = self._num_update_units(batch) dev = batch.device dtype = batch.positions.dtype dt = _to_per_system(self._dt_init, M, dev, dtype) self._state = _make_state_batch( _build_state(M, dt, self.alpha0, dtype, dev), dev, ) def _make_new_state(self, n: int, template_batch: Batch) -> Batch: dev = template_batch.device dtype = template_batch.positions.dtype dt = _to_per_system(self._dt_init, n, dev, dtype) return _make_state_batch( _build_state(n, dt, self.alpha0, dtype, dev), dev, )
[docs] def pre_update(self, batch: Batch) -> None: """Full FIRE2 step using current forces. Parameters ---------- batch : Batch Current batch; *positions* and *velocities* updated in-place. """ # Detach positions to avoid "non-leaf .grad accessed" warning from # wp.from_torch. FIRE2 does not use autograd; in-place updates # still apply to the batch's underlying storage. fire2_step_coord( batch.positions.detach(), batch.velocities, batch.forces, self._update_idx(batch), self._state.alpha, self._state.dt, self._state.nsteps_inc, vf=self._state.vf, v_sumsq=self._state.v_sumsq, f_sumsq=self._state.f_sumsq, delaystep=self.delaystep, dtgrow=self.dtgrow, dtshrink=self.dtshrink, alphashrink=self.alphashrink, alpha0=self.alpha0, tmax=self.tmax, tmin=self.tmin, maxstep=self.maxstep, )
[docs] def post_update(self, batch: Batch) -> None: """No-op; forces from new positions are used on the next step."""
[docs] class FIRE2VariableCell(BaseDynamics): """Variable-cell FIRE2 geometry optimizer. Simultaneously relaxes atomic coordinates and the simulation cell using the FIRE2 algorithm with cell-force derived from the model's stress tensor. Parameters ---------- model : BaseModelMixin The neural network potential model. Must produce ``"stress"``. dt : float or torch.Tensor Initial adaptive timestep ``[M]`` or scalar. delaystep : int Minimum steps before adaptation. Default 60. dtgrow : float Timestep growth factor. Default 1.05. dtshrink : float Timestep shrink factor. Default 0.75. alphashrink : float Alpha decrease factor. Default 0.985. alpha0 : float Initial mixing parameter. Default 0.09. tmax : float Maximum timestep. Default 0.08. tmin : float Minimum timestep. Default 0.005. maxstep : float Maximum displacement per step. Default 0.1. n_steps : int, optional Total steps for :meth:`run`. hooks : list[Hook], optional Initial hooks. convergence_hook : ConvergenceHook or dict, optional Convergence criterion. cell_force_scale : float Multiplier on the atom count normalizing stress-derived cell forces; raise it to move the cell less per step. Read every step. Default 1.0. **kwargs Forwarded to :class:`~nvalchemi.dynamics.base.BaseDynamics`. Attributes ---------- __needs_keys__ : set[str] ``{"forces", "stress"}``. __provides_keys__ : set[str] ``{"positions", "velocities", "cell"}``. """ __needs_keys__: set[str] = {"forces", "stress"} __provides_keys__: set[str] = {"positions", "velocities", "cell"} samples_equilibrium: ClassVar[bool] = False """A relaxation descends to a minimum rather than sampling an ensemble.""" def __init__( self, model: BaseModelMixin, dt: float | torch.Tensor, delaystep: int = _FIRE2_DEFAULTS["delaystep"], dtgrow: float = _FIRE2_DEFAULTS["dtgrow"], dtshrink: float = _FIRE2_DEFAULTS["dtshrink"], alphashrink: float = _FIRE2_DEFAULTS["alphashrink"], alpha0: float = _FIRE2_DEFAULTS["alpha0"], tmax: float = _FIRE2_DEFAULTS["tmax"], tmin: float = _FIRE2_DEFAULTS["tmin"], maxstep: float = _FIRE2_DEFAULTS["maxstep"], n_steps: int | None = None, hooks: list[Hook] | None = None, convergence_hook: ConvergenceHook | dict | None = None, *, cell_force_scale: float = 1.0, **kwargs: Any, ) -> None: if not math.isfinite(cell_force_scale) or cell_force_scale <= 0: raise ValueError( f"cell_force_scale must be finite and positive; got {cell_force_scale}" ) super().__init__( model=model, n_steps=n_steps, hooks=hooks, convergence_hook=convergence_hook, **kwargs, ) self._dt_init = dt self.delaystep = delaystep self.dtgrow = dtgrow self.dtshrink = dtshrink self.alphashrink = alphashrink self.alpha0 = alpha0 self.tmax = tmax self.tmin = tmin self.maxstep = maxstep self.cell_force_scale = cell_force_scale def _init_state(self, batch: Batch) -> None: if self.by_group: raise NotImplementedError( "FIRE2VariableCell does not support by_group=True because cell " "degrees of freedom remain graph-level." ) M = batch.num_graphs dev = batch.device dtype = batch.positions.dtype dt = _to_per_system(self._dt_init, M, dev, dtype) self._state = _make_state_batch( _build_state(M, dt, self.alpha0, dtype, dev, with_cell=True), dev, ) def _make_new_state(self, n: int, template_batch: Batch) -> Batch: dev = template_batch.device dtype = template_batch.positions.dtype dt = _to_per_system(self._dt_init, n, dev, dtype) return _make_state_batch( _build_state(n, dt, self.alpha0, dtype, dev, with_cell=True), dev, )
[docs] def pre_update(self, batch: Batch) -> None: """Full FIRE2 variable-cell step using current forces and stress. Parameters ---------- batch : Batch Current batch; *positions*, *velocities*, and *cell* updated in-place. """ volumes = torch.linalg.det(batch.cell).abs() # batch.stress is tensile-positive Cauchy stress -W/V (eV/A^3). stress_sigma = batch.stress cell_force = stress_to_cell_force(stress_sigma, batch.cell, volumes) fire2_step_coord_cell( batch.positions.detach(), batch.velocities, batch.forces, batch.cell.detach(), self._state.cell_velocities, cell_force, batch.batch_idx.int(), self._state.alpha, self._state.dt, self._state.nsteps_inc, vf=self._state.vf, v_sumsq=self._state.v_sumsq, f_sumsq=self._state.f_sumsq, delaystep=self.delaystep, dtgrow=self.dtgrow, dtshrink=self.dtshrink, alphashrink=self.alphashrink, alpha0=self.alpha0, tmax=self.tmax, tmin=self.tmin, maxstep=self.maxstep, cell_force_scale=self.cell_force_scale, )
[docs] def post_update(self, batch: Batch) -> None: """No-op; forces from new positions are used on the next step."""