# 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.
"""
NPT (isothermal-isobaric) integrator.
Constant temperature and pressure; uses Martyna-Tobias-Klein (MTK)
barostat equations with two Nosé-Hoover chains: one coupled to
particle DOFs and one coupled to cell/barostat DOFs.
The step is split around the force/stress evaluation:
* ``pre_update``: NHC-p half → NHC-b half → baro half → force/barostat v half
→ r full → cell full
* [model evaluates F and stress at r(t+dt), h(t+dt)]
* ``post_update``: force/barostat v half → baro half → NHC-b half → NHC-p half
Per-system state: ``dt``, ``temperature``, ``pressure``,
``barostat_time``, ``thermostat_time``, barostat inertia ``W``,
``cell_velocity [M,3,3]``, particle NHC state
``nhc_eta [M,C]``, ``nhc_eta_dot [M,C]``, ``nhc_Q [M,C]``,
barostat NHC state ``nhc_b_eta [M,C]``, ``nhc_b_eta_dot [M,C]``,
``nhc_b_Q [M,C]``, and pre-allocated scratch tensors.
"""
from __future__ import annotations
import warnings
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_compute_masses
from nvalchemi.dynamics._ops.npt_nph import (
compute_barostat_mass,
compute_pressure_tensor,
nph_velocity_half_step,
npt_barostat_half_step,
npt_cell_update,
npt_position_update,
npt_thermostat_half_step,
)
from nvalchemi.dynamics._ops.thermostat_utils import compute_kinetic_energy
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__ = ["NPT"]
def _cell_dof_count(pressure_coupling: str) -> int:
"""Return the active barostat cell degrees of freedom for a mode."""
return 9 if pressure_coupling == "triclinic" else 3
def _cell_kinetic_energy(
cell_velocity: torch.Tensor,
W: torch.Tensor,
pressure_coupling: str,
cells_inv: torch.Tensor | None = None,
) -> torch.Tensor:
r"""Compute cell kinetic energy :math:`\mathrm{KE}_\mathrm{cell} = \tfrac{1}{2} W \lVert\dot\varepsilon\rVert_F^2`.
Parameters
----------
cell_velocity : torch.Tensor
Strain-rate tensor :math:`\dot\varepsilon` ``[M, 3, 3]``.
W : torch.Tensor
Barostat inertia ``[M]``.
pressure_coupling : str
One of ``"isotropic"``, ``"anisotropic"``, ``"triclinic"``.
cells_inv : torch.Tensor, optional
Deprecated; ignored. Emits ``DeprecationWarning`` when passed.
Returns
-------
torch.Tensor
Cell kinetic energy ``[M]``.
"""
if cells_inv is not None:
warnings.warn(
"_cell_kinetic_energy: cells_inv is deprecated and ignored.",
DeprecationWarning,
stacklevel=2,
)
eps_dot = cell_velocity
if pressure_coupling == "triclinic":
active = eps_dot.reshape(eps_dot.shape[0], -1)
else:
active = torch.diagonal(eps_dot, dim1=-2, dim2=-1)
return 0.5 * W * (active * active).sum(dim=-1)
[docs]
class NPT(BaseDynamics):
r"""Isothermal-isobaric (NPT) integrator via MTK barostat and NHC thermostat.
Samples the NPT ensemble. Two Nosé-Hoover chains control the
temperature: one coupled to the particle velocities and one coupled
to the barostat (cell) degrees of freedom.
Parameters
----------
model : BaseModelMixin
The neural network potential model. Must produce ``"stress"``
output in addition to forces.
dt : float or torch.Tensor
Integration timestep in femtoseconds ``[M]`` or scalar.
temperature : float or torch.Tensor
Target temperature in Kelvin ``[M]`` or scalar.
pressure : float or torch.Tensor
Target pressure in :math:`\mathrm{eV}/\mathrm{\AA}^3` (positive for
compression); the value is used directly by the barostat with no
bar/GPa conversion applied. Shape ``[M]`` (isotropic), ``[M, 3]``
(anisotropic), or ``[M, 3, 3]`` (triclinic). Scalar is broadcast to
``[M]`` isotropic. For reference,
:math:`1\,\mathrm{eV}/\mathrm{\AA}^3 \approx 1.602\times10^{6}\,\mathrm{bar} \approx 160.2\,\mathrm{GPa}`.
barostat_time : float or torch.Tensor
Barostat coupling time :math:`\tau_P` in femtoseconds ``[M]`` or scalar.
thermostat_time : float or torch.Tensor
Thermostat coupling time :math:`\tau_T` in femtoseconds ``[M]`` or scalar.
pressure_coupling : {"isotropic", "anisotropic", "triclinic"}
Pressure control mode. Default ``"isotropic"``.
chain_length : int, optional
Number of links in each Nosé-Hoover chain. 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", "stress"}``.
__provides_keys__ : set[str]
``{"positions", "velocities", "cell"}``.
"""
__needs_keys__: set[str] = {"forces", "stress"}
__provides_keys__: set[str] = {"positions", "velocities", "cell"}
# Domain-parallel intent (read by the dynamics coordinator; inert
# single-process). The barostat + particle thermostat couple to the
# mesh-global kinetic energy, kinetic pressure tensor, and DOF; the NHC
# chains + cell velocity are replicated state kept byte-identical across ranks.
__dd_thermo_kind__: str = "npt"
__dd_replicated__: tuple[str, ...] = (
"nhc_eta",
"nhc_eta_dot",
"nhc_b_eta",
"nhc_b_eta_dot",
"cell_velocity",
)
def __init__(
self,
model: BaseModelMixin,
dt: float | torch.Tensor,
temperature: float | torch.Tensor,
pressure: float | torch.Tensor,
barostat_time: float | torch.Tensor,
thermostat_time: float | torch.Tensor,
pressure_coupling: Literal[
"isotropic", "anisotropic", "triclinic"
] = "isotropic",
chain_length: int = 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._pressure_init = pressure
self._barostat_time_init = fs_to_internal_time(barostat_time)
self._thermostat_time_init = fs_to_internal_time(thermostat_time)
self.pressure_coupling = pressure_coupling
self.chain_length = chain_length
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)
# All NHC/barostat kernels expect kT in energy units (eV), not T in Kelvin.
kT = _to_per_system(self._temperature_init * KB_EV, M, dev, dtype)
pressure = _to_per_system(self._pressure_init, M, dev, dtype)
tau_p = _to_per_system(self._barostat_time_init, M, dev, dtype)
tau_t = _to_per_system(self._thermostat_time_init, M, dev, dtype)
counts = torch.bincount(batch.batch_idx, minlength=M)
num_atoms_per_system = counts.to(dtype=torch.int32, device=dev)
W = torch.zeros(M, dtype=dtype, device=dev)
compute_barostat_mass(kT, tau_p, num_atoms_per_system, W)
# Kernel emits the full ``(3N+3)·kT·τ_P²``; ``/3`` recovers the canonical
# per-DOF MTK barostat mass ``(N+1)·kT·τ_P²``.
W = W / 3
Q = nhc_compute_masses(
kT, tau_t, batch.atomic_masses, batch.batch_idx.int(), self.chain_length
)
cell_dofs = _cell_dof_count(self.pressure_coupling)
dummy_b_particles = 3 if cell_dofs == 9 else 1
dummy_b_masses = torch.ones(M * dummy_b_particles, dtype=dtype, device=dev)
dummy_b_batch = torch.arange(
M, device=dev, dtype=torch.int32
).repeat_interleave(dummy_b_particles)
Q_b = nhc_compute_masses(
kT, tau_p, dummy_b_masses, dummy_b_batch, self.chain_length
)
self._state = _make_state_batch(
{
"dt": dt,
"temperature": kT,
"pressure": pressure,
"barostat_time": tau_p,
"thermostat_time": tau_t,
"W": W,
"cell_velocity": torch.zeros(M, 3, 3, dtype=dtype, device=dev),
"num_atoms_per_system": num_atoms_per_system,
"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,
"nhc_b_eta": torch.zeros(M, self.chain_length, dtype=dtype, device=dev),
"nhc_b_eta_dot": torch.zeros(
M, self.chain_length, dtype=dtype, device=dev
),
"nhc_b_Q": Q_b,
# Pre-allocated scratch tensors; zeroed by kernel each call.
"kinetic_tensors": torch.zeros(M, 9, dtype=dtype, device=dev),
"pressure_tensors": torch.zeros(M, 9, dtype=dtype, device=dev),
"volumes": torch.zeros(M, dtype=dtype, device=dev),
},
dev,
)
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_p = _to_per_system(self._barostat_time_init, n, dev, dtype)
tau_t = _to_per_system(self._thermostat_time_init, n, dev, dtype)
approx_n_atoms = template_batch.num_nodes // template_batch.num_graphs
num_atoms_per_system = torch.full(
(n,), approx_n_atoms, dtype=torch.int32, device=dev
)
dummy_masses = template_batch.atomic_masses[:1].expand(n).contiguous()
dummy_batch_idx = torch.zeros(n, dtype=torch.int32, device=dev)
W = torch.zeros(n, dtype=dtype, device=dev)
compute_barostat_mass(kT, tau_p, num_atoms_per_system, W)
W = W / 3
Q = nhc_compute_masses(
kT[:1],
tau_t[:1],
dummy_masses[:1],
dummy_batch_idx[:1],
self.chain_length,
)
Q = Q.expand(n, -1).contiguous()
cell_dofs = _cell_dof_count(self.pressure_coupling)
dummy_b_particles = 3 if cell_dofs == 9 else 1
dummy_b_masses = torch.ones(dummy_b_particles, dtype=dtype, device=dev)
dummy_b_batch = torch.zeros(dummy_b_particles, dtype=torch.int32, device=dev)
Q_b_single = nhc_compute_masses(
kT[:1], tau_p[:1], dummy_b_masses, dummy_b_batch, self.chain_length
)
Q_b = Q_b_single.expand(n, -1).contiguous()
return _make_state_batch(
{
"dt": _to_per_system(self._dt_init, n, dev, dtype),
"temperature": kT,
"pressure": _to_per_system(self._pressure_init, n, dev, dtype),
"barostat_time": tau_p,
"thermostat_time": tau_t,
"W": W,
"cell_velocity": torch.zeros(n, 3, 3, dtype=dtype, device=dev),
"num_atoms_per_system": num_atoms_per_system,
"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_b_eta": torch.zeros(n, self.chain_length, dtype=dtype, device=dev),
"nhc_b_eta_dot": torch.zeros(
n, self.chain_length, dtype=dtype, device=dev
),
"nhc_b_Q": Q_b,
"kinetic_tensors": torch.zeros(n, 9, dtype=dtype, device=dev),
"pressure_tensors": torch.zeros(n, 9, dtype=dtype, device=dev),
"volumes": torch.zeros(n, dtype=dtype, device=dev),
},
dev,
)
def _compute_volumes(self, batch: Batch) -> torch.Tensor:
"""Compute per-system cell volumes as |det(h)|."""
return torch.linalg.det(batch.cell).abs()
def _compute_P(self, batch: Batch, volumes: torch.Tensor) -> torch.Tensor:
"""Compute the instantaneous pressure tensor."""
# batch.stress is tensile-positive Cauchy stress -W/V (eV/A^3).
# compute_pressure_tensor expects virial W (eV).
virial = -batch.stress * volumes.view(-1, 1, 1)
return compute_pressure_tensor(
batch.velocities,
batch.atomic_masses,
virial,
batch.cell,
self._state.kinetic_tensors,
self._state.pressure_tensors,
volumes,
batch.batch_idx.int(),
)
def _compute_ke(self, batch: Batch) -> torch.Tensor:
"""Compute per-system kinetic energy."""
M = batch.num_graphs
return compute_kinetic_energy(
batch.velocities,
batch.atomic_masses,
batch.batch_idx.int(),
M,
)
[docs]
def pre_update(self, batch: Batch) -> None:
"""NHC-p half → NHC-b half → baro half → force/barostat v half → r full → cell full.
Parameters
----------
batch : Batch
Current batch; *positions*, *velocities*, and *cell*
updated in-place.
"""
M = batch.num_graphs
volumes = self._compute_volumes(batch)
cells_inv = torch.linalg.inv_ex(batch.cell)[0].contiguous()
KE = self._compute_ke(batch)
# Particle thermostat half step.
npt_thermostat_half_step(
self._state.nhc_eta,
self._state.nhc_eta_dot,
KE,
self._state.temperature,
self._state.nhc_Q,
self._state.num_atoms_per_system,
self.chain_length,
self._state.dt,
)
# Scale particle velocities by exp(-eta_dot[:,0] * dt/2).
scale = torch.exp(-self._state.nhc_eta_dot[:, 0] * self._state.dt * 0.5)
batch.velocities.mul_(scale[batch.batch_idx].unsqueeze(-1))
ke_cell = _cell_kinetic_energy(
self._state.cell_velocity,
self._state.W,
self.pressure_coupling,
)
# Kernel internally computes ``N_f = 3·input``; pre-divide so the
# barostat-thermostat target matches the cell's actual DOF count
# (3 for iso/aniso, 9 for triclinic).
cell_ndof_tensor = torch.full(
(M,),
_cell_dof_count(self.pressure_coupling) // 3,
dtype=torch.int32,
device=batch.device,
)
npt_thermostat_half_step(
self._state.nhc_b_eta,
self._state.nhc_b_eta_dot,
ke_cell,
self._state.temperature,
self._state.nhc_b_Q,
cell_ndof_tensor,
self.chain_length,
self._state.dt,
)
b_scale = torch.exp(-self._state.nhc_b_eta_dot[:, 0] * self._state.dt * 0.5)
self._state.cell_velocity.mul_(b_scale.view(M, 1, 1))
P_inst = self._compute_P(batch, volumes)
KE = self._compute_ke(batch)
# Cell damping is the explicit ``b_scale`` step above; the barostat
# half-step itself carries no thermostat drag.
npt_barostat_half_step(
self._state.cell_velocity,
P_inst,
self._state.pressure,
volumes,
self._state.W,
KE,
self._state.num_atoms_per_system,
self._state.dt,
)
# Force + barostat-strain velocity half step. Particle NHC scaling is
# applied as the separate Trotter operator above, so use the no-drag
# NPH primitive here.
nph_velocity_half_step(
batch.velocities,
batch.atomic_masses,
batch.forces,
self._state.cell_velocity,
volumes,
self._state.num_atoms_per_system,
self._state.dt,
batch.batch_idx.int(),
cells_inv,
self.pressure_coupling,
)
npt_position_update(
batch.positions,
batch.velocities,
batch.cell,
self._state.cell_velocity,
self._state.dt,
cells_inv,
batch.batch_idx.int(),
)
npt_cell_update(
batch.cell,
self._state.cell_velocity,
self._state.dt,
)
[docs]
def post_update(self, batch: Batch) -> None:
"""Force/barostat v half → baro half → NHC-b half → NHC-p half.
Parameters
----------
batch : Batch
Current batch; *velocities* updated in-place.
"""
M = batch.num_graphs
volumes = self._compute_volumes(batch)
cells_inv = torch.linalg.inv_ex(batch.cell)[0].contiguous()
# Force + barostat-strain velocity half step only; particle NHC scaling
# closes the split below.
nph_velocity_half_step(
batch.velocities,
batch.atomic_masses,
batch.forces,
self._state.cell_velocity,
volumes,
self._state.num_atoms_per_system,
self._state.dt,
batch.batch_idx.int(),
cells_inv,
self.pressure_coupling,
)
P_inst = self._compute_P(batch, volumes)
KE = self._compute_ke(batch)
npt_barostat_half_step(
self._state.cell_velocity,
P_inst,
self._state.pressure,
volumes,
self._state.W,
KE,
self._state.num_atoms_per_system,
self._state.dt,
)
ke_cell = _cell_kinetic_energy(
self._state.cell_velocity,
self._state.W,
self.pressure_coupling,
)
cell_ndof_tensor = torch.full(
(M,),
_cell_dof_count(self.pressure_coupling) // 3,
dtype=torch.int32,
device=batch.device,
)
npt_thermostat_half_step(
self._state.nhc_b_eta,
self._state.nhc_b_eta_dot,
ke_cell,
self._state.temperature,
self._state.nhc_b_Q,
cell_ndof_tensor,
self.chain_length,
self._state.dt,
)
b_scale = torch.exp(-self._state.nhc_b_eta_dot[:, 0] * self._state.dt * 0.5)
self._state.cell_velocity.mul_(b_scale.view(M, 1, 1))
# Particle thermostat half step.
KE = self._compute_ke(batch)
npt_thermostat_half_step(
self._state.nhc_eta,
self._state.nhc_eta_dot,
KE,
self._state.temperature,
self._state.nhc_Q,
self._state.num_atoms_per_system,
self.chain_length,
self._state.dt,
)
scale = torch.exp(-self._state.nhc_eta_dot[:, 0] * self._state.dt * 0.5)
batch.velocities.mul_(scale[batch.batch_idx].unsqueeze(-1))