Source code for nvalchemi.dynamics.integrators.nvt_nose_hoover

# 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.
"""
NVT integrator via Nosé-Hoover chain (NHC) thermostat.

The NHC thermostat is deterministic, time-reversible, and ergodic.
It uses Yoshida-Suzuki factorization with the Martyna-Tobias-Klein
(MTK) equations.

The step is split around the force evaluation:

* ``pre_update``:  NHC half → v half kick → r full step
* [model evaluates F(r(t+dt))]
* ``post_update``: v half kick → NHC half

Per-system state: ``dt``, ``temperature``, ``thermostat_time``,
chain positions ``nhc_eta [M, C]``, chain velocities ``nhc_eta_dot [M, C]``,
chain masses ``nhc_Q [M, C]``, and NHC scratch tensors
``nhc_ke2 [M]``, ``nhc_total_scale [M]``, ``nhc_step_scale [M]``,
``nhc_dt_chain [M]``.

References
----------
Martyna, Tobias, Klein (1994); Tuckerman et al. (2006).
"""

from __future__ import annotations

from collections.abc import Mapping
from typing import TYPE_CHECKING, Any, Literal

import torch

from nvalchemi.data import Batch
from nvalchemi.dynamics._ops._bridge import _make_state_batch, _to_per_system
from nvalchemi.dynamics._ops.nose_hoover import (
    nhc_chain_update,
    nhc_compute_masses,
    nhc_position_update,
    nhc_velocity_half_step,
)
from nvalchemi.dynamics._units import KB_EV, fs_to_internal_time
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__ = ["NVTNoseHoover"]


[docs] class NVTNoseHoover(BaseDynamics): r"""NVT integrator via Nosé-Hoover chain (NHC) thermostat. Deterministic extended-Lagrangian thermostat that rigorously samples the canonical ensemble for ergodic systems. Parameters ---------- model : BaseModelMixin The neural network potential model. dt : float or torch.Tensor Integration timestep in femtoseconds ``[M]`` or scalar. temperature : float or torch.Tensor Target temperature in Kelvin ``[M]`` or scalar. thermostat_time : float or torch.Tensor Thermostat coupling time :math:`\tau_T` in femtoseconds ``[M]`` or scalar. Controls how tightly the thermostat couples to the system; typical values are 10–100 :math:`\times \Delta t`. chain_length : int, optional Number of links in the Nosé-Hoover chain. Default 3. yoshida_order : int, optional Order of the Yoshida-Suzuki integrator. Must be 3 or 5. Default 3. n_steps : int, optional Total steps for :meth:`run`. hooks : list[Hook], optional Initial hooks. convergence_hook : ConvergenceHook or dict, optional Convergence criterion. **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"} # Domain-parallel intent (read by the dynamics coordinator; inert # single-process). This integrator couples its thermostat to the mesh-global # kinetic energy + DOF; its NHC controller state is replicated and kept # byte-identical across ranks. __dd_thermo_kind__: str = "nhc" __dd_replicated__: tuple[str, ...] = ("nhc_eta", "nhc_eta_dot") def __init__( self, model: BaseModelMixin, dt: float | torch.Tensor, temperature: float | torch.Tensor, thermostat_time: float | torch.Tensor, chain_length: int = 3, yoshida_order: Literal[3, 5] = 3, 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 = fs_to_internal_time(dt) self._temperature_init = temperature self._thermostat_time_init = fs_to_internal_time(thermostat_time) self.chain_length = chain_length self.yoshida_order = yoshida_order def _init_state(self, batch: Batch) -> None: M = batch.num_graphs dev = batch.device dtype = batch.positions.dtype dt = _to_per_system(self._dt_init, M, dev, dtype) # NHC kernels expect kT in energy units (eV), not T in Kelvin. kT = _to_per_system(self._temperature_init * KB_EV, M, dev, dtype) tau = _to_per_system(self._thermostat_time_init, M, dev, dtype) # Compute chain masses using the actual per-atom masses and batch index. Q = nhc_compute_masses( kT, tau, batch.atomic_masses, batch.batch_idx.int(), self.chain_length ) # Compute per-system ndof as a float tensor (required by nhc_chain_update). counts = torch.bincount(batch.batch_idx, minlength=M) nhc_ndof = (counts * 3).to(dtype=dtype, device=dev) self._state = _make_state_batch( { "dt": dt, "temperature": kT, "thermostat_time": tau, "nhc_ndof": nhc_ndof, "nhc_eta": torch.zeros(M, self.chain_length, dtype=dtype, device=dev), "nhc_eta_dot": torch.zeros( M, self.chain_length, dtype=dtype, device=dev ), "nhc_Q": Q, # Scratch tensors for NHC chain update. "nhc_ke2": torch.zeros(M, dtype=dtype, device=dev), "nhc_total_scale": torch.zeros(M, dtype=dtype, device=dev), "nhc_step_scale": torch.zeros(M, dtype=dtype, device=dev), "nhc_dt_chain": torch.zeros(M, dtype=dtype, device=dev), }, dev, )
[docs] def apply_per_system_params( self, params: Mapping[str, torch.Tensor], batch: Batch ) -> None: """Rebind target temperature, chain masses, and velocities together. Unlike Langevin, a Nosé-Hoover chain carries memory: the chain masses ``Q`` are proportional to ``kT tau^2`` and the chain velocities ``eta_dot`` are conjugate to them. Rebinding the target without transforming both leaves the thermostat driving toward the old temperature and breaks detailed balance, so all four move together: * ``temperature`` takes the new ``kT``. * ``Q`` scales by ``kT_new / kT_old``, preserving ``Q ∝ kT tau^2``. * ``eta_dot`` scales by ``sqrt(kT_old / kT_new)``, which keeps the chain kinetic energy ``Q eta_dot^2 / 2`` invariant under the mass change rather than injecting or removing thermostat energy. * atomic velocities scale by ``sqrt(kT_new / kT_old)``. ``eta`` itself is a position-like variable and is left untouched. Parameters ---------- params : Mapping[str, torch.Tensor] Must contain ``"temperature"`` in Kelvin per graph, shape ``[B]``. batch : Batch The live batch; ``velocities`` is modified in place. Raises ------ RuntimeError If called before the integrator state exists. KeyError If *params* names something this integrator cannot rebind. """ state = getattr(self, "_state", None) if state is None: raise RuntimeError( "NVTNoseHoover.apply_per_system_params: integrator state is " "not initialised; run or prime the dynamics first." ) temperature = self._validated_temperature(params, state.temperature) old_kT = state.temperature.reshape(-1).clone() new_kT = temperature * KB_EV ratio = new_kT / old_kT with torch.no_grad(): state.temperature.copy_(new_kT.reshape(state.temperature.shape)) state.nhc_Q.mul_(ratio.reshape(-1, 1)) state.nhc_eta_dot.mul_(torch.rsqrt(ratio).reshape(-1, 1)) self._rescale_velocities(torch.sqrt(ratio), batch)
def _make_new_state(self, n: int, template_batch: Batch) -> Batch: dev = template_batch.device dtype = template_batch.positions.dtype kT = _to_per_system(self._temperature_init * KB_EV, n, dev, dtype) tau = _to_per_system(self._thermostat_time_init, n, dev, dtype) # Approximate Q with a reasonable default using a dummy batch. dummy_masses = ( template_batch.atomic_masses[:n].contiguous() if template_batch.atomic_masses.shape[0] >= n else template_batch.atomic_masses ) dummy_batch_idx = torch.zeros( dummy_masses.shape[0], dtype=torch.int32, device=dev ) Q = nhc_compute_masses( kT[:1], tau[:1], dummy_masses, dummy_batch_idx, self.chain_length ) Q = Q.expand(n, -1).contiguous() approx_n_atoms = template_batch.num_nodes // template_batch.num_graphs nhc_ndof = torch.full((n,), approx_n_atoms * 3, dtype=dtype, device=dev) return _make_state_batch( { "dt": _to_per_system(self._dt_init, n, dev, dtype), "temperature": kT, "thermostat_time": tau, "nhc_ndof": nhc_ndof, "nhc_eta": torch.zeros(n, self.chain_length, dtype=dtype, device=dev), "nhc_eta_dot": torch.zeros( n, self.chain_length, dtype=dtype, device=dev ), "nhc_Q": Q, "nhc_ke2": torch.zeros(n, dtype=dtype, device=dev), "nhc_total_scale": torch.zeros(n, dtype=dtype, device=dev), "nhc_step_scale": torch.zeros(n, dtype=dtype, device=dev), "nhc_dt_chain": torch.zeros(n, dtype=dtype, device=dev), }, dev, )
[docs] def pre_update(self, batch: Batch) -> None: """NHC half-step → velocity half-kick → position full-step. Parameters ---------- batch : Batch Current batch; *positions* and *velocities* updated in-place. """ nhc_chain_update( batch.velocities, batch.atomic_masses, self._state.nhc_eta, self._state.nhc_eta_dot, self._state.nhc_Q, self._state.temperature, self._state.dt, self._state.nhc_ndof, self._state.nhc_ke2, self._state.nhc_total_scale, self._state.nhc_step_scale, self._state.nhc_dt_chain, batch.batch_idx.int(), ) nhc_velocity_half_step( batch.velocities, batch.forces, batch.atomic_masses, self._state.dt, batch.batch_idx.int(), ) nhc_position_update( batch.positions, batch.velocities, self._state.dt, batch.batch_idx.int(), )
[docs] def post_update(self, batch: Batch) -> None: """Velocity half-kick → NHC half-step (symmetric closure). Parameters ---------- batch : Batch Current batch; *velocities* updated in-place. """ nhc_velocity_half_step( batch.velocities, batch.forces, batch.atomic_masses, self._state.dt, batch.batch_idx.int(), ) nhc_chain_update( batch.velocities, batch.atomic_masses, self._state.nhc_eta, self._state.nhc_eta_dot, self._state.nhc_Q, self._state.temperature, self._state.dt, self._state.nhc_ndof, self._state.nhc_ke2, self._state.nhc_total_scale, self._state.nhc_step_scale, self._state.nhc_dt_chain, batch.batch_idx.int(), )