Source code for nvalchemi.dynamics.integrators.nvt_langevin

# 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 BAOAB Langevin dynamics.

The BAOAB splitting scheme samples the canonical (NVT) ensemble and
provides excellent configurational sampling accuracy while remaining
simple to implement.

The step is split around the force evaluation:

* ``pre_update``:   B-A-O-A — half kick, drift, Ornstein-Uhlenbeck,
                               drift
* [model evaluates F(r(t+dt))]
* ``post_update``:  B         — final half velocity kick

Reference: Leimkuhler & Matthews, *BAOAB algorithm* (2012).
"""

from __future__ import annotations

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

import torch

from nvalchemi.data import Batch
from nvalchemi.dynamics._ops._bridge import _make_state_batch, _to_per_system
from nvalchemi.dynamics._ops.langevin import langevin_finalize, langevin_half_step
from nvalchemi.dynamics._units import (
    KB_EV,
    fs_to_internal_time,
    per_fs_to_internal_rate,
)
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__ = ["NVTLangevin"]


[docs] class NVTLangevin(BaseDynamics): r"""NVT integrator via BAOAB Langevin dynamics. Samples the canonical ensemble via a stochastic Ornstein-Uhlenbeck process that acts as an exact thermostat. 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. friction : float or torch.Tensor Langevin friction coefficient :math:`\gamma` in ``1/fs`` ``[M]`` or scalar. Controls thermostat coupling strength. random_seed : int, optional Global RNG seed for the stochastic O step. Default 42. 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"} def __init__( self, model: BaseModelMixin, dt: float | torch.Tensor, temperature: float | torch.Tensor, friction: float | torch.Tensor, random_seed: int = 42, 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._friction_init = per_fs_to_internal_rate(friction) self._random_seed = random_seed @property def random_seed(self) -> int: """Base seed of the thermostat noise, which every step offsets by ``step_count``.""" return self._random_seed @random_seed.setter def random_seed(self, value: int) -> None: """Move the noise onto another stream from the next step on.""" self._random_seed = value def _init_state(self, batch: Batch) -> None: M = batch.num_graphs dev = batch.device dtype = batch.positions.dtype # The Warp kernel expects kT in energy units (eV), not T in Kelvin. kT_init = self._temperature_init * KB_EV self._state = _make_state_batch( { "dt": _to_per_system(self._dt_init, M, dev, dtype), "temperature": _to_per_system(kT_init, M, dev, dtype), "friction": _to_per_system(self._friction_init, M, dev, dtype), }, dev, )
[docs] def apply_per_system_params( self, params: Mapping[str, torch.Tensor], batch: Batch ) -> None: """Rebind each walker's target temperature and rescale its velocities. Langevin has no thermostat memory to transform — its noise amplitude is read from the per-system ``temperature`` every step — so the rebinding is the target update plus the velocity rescaling that keeps the kinetic energy consistent with the new target. Velocities scale by ``sqrt(T_new / T_old)``, in the same call, because the two together are the indivisible change. 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( "NVTLangevin.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 with torch.no_grad(): state.temperature.copy_(new_kT.reshape(state.temperature.shape)) self._rescale_velocities(torch.sqrt(new_kT / old_kT), batch)
def _make_new_state(self, n: int, template_batch: Batch) -> Batch: dev = template_batch.device dtype = template_batch.positions.dtype kT_init = self._temperature_init * KB_EV return _make_state_batch( { "dt": _to_per_system(self._dt_init, n, dev, dtype), "temperature": _to_per_system(kT_init, n, dev, dtype), "friction": _to_per_system(self._friction_init, n, dev, dtype), }, dev, )
[docs] def pre_update(self, batch: Batch) -> None: """BAOAB pre-force half: B-A-O-A sequence. Parameters ---------- batch : Batch Current batch; *positions* and *velocities* updated in-place. """ langevin_half_step( batch.positions, batch.velocities, batch.forces, batch.atomic_masses, self._state.dt, self._state.temperature, self._state.friction, self._random_seed + self.step_count, batch.batch_idx.int(), )
[docs] def post_update(self, batch: Batch) -> None: """BAOAB post-force final B step. Parameters ---------- batch : Batch Current batch; *velocities* updated in-place. """ langevin_finalize( batch.velocities, batch.forces, batch.atomic_masses, self._state.dt, batch.batch_idx.int(), )