nvalchemi.dynamics.NVTNoseHoover#

class nvalchemi.dynamics.NVTNoseHoover(model, dt, temperature, thermostat_time, chain_length=3, yoshida_order=3, n_steps=None, hooks=None, convergence_hook=None, **kwargs)[source]#

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 \(\tau_T\) in femtoseconds [M] or scalar. Controls how tightly the thermostat couples to the system; typical values are 10–100 \(\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 run().

  • hooks (list[Hook], optional) – Initial hooks.

  • convergence_hook (ConvergenceHook or dict, optional) – Convergence criterion.

  • **kwargs – Forwarded to BaseDynamics.

__needs_keys__#

{"forces"}.

Type:

set[str]

__provides_keys__#

{"positions", "velocities"}.

Type:

set[str]

apply_per_system_params(params, batch)[source]#

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.

Return type:

None

post_update(batch)[source]#

Velocity half-kick → NHC half-step (symmetric closure).

Parameters:

batch (Batch) – Current batch; velocities updated in-place.

Return type:

None

pre_update(batch)[source]#

NHC half-step → velocity half-kick → position full-step.

Parameters:

batch (Batch) – Current batch; positions and velocities updated in-place.

Return type:

None