nvalchemi.dynamics.hooks.StabilityMonitor#

class nvalchemi.dynamics.hooks.StabilityMonitor(*, frequency=1, stage=DynamicsStage.AFTER_STEP, timestep_fs=None, include_kinetic=True, warmup_steps=0, divergence=None, aggregate='max', stop_on_composition_change=True)[source]#

Dynamics hook recording energy and momentum along a trajectory.

A stability monitor records the total energy and momentum of a trajectory and reports how well the run conserves them. Register it on a BaseDynamics run like any observation hook, then call metrics() once the run is over. Unlike EnergyDriftMonitorHook, which compares one live value against a threshold, this hook keeps the whole series on the host as float64, one small tensor per firing. For a long run, raise frequency rather than record every step.

Parameters:
  • frequency (int, optional) – Record every frequency steps. The dynamics hook registry applies this gating. Default 1.

  • stage (Enum, optional) – Stage to record at. Default AFTER_STEP.

  • timestep_fs (float | None, optional) – Integration timestep in femtoseconds, which turns per-step drift into a per-nanosecond rate. Default None.

  • include_kinetic (bool, optional) – Add the kinetic energy to the potential energy before measuring drift. This is what makes the metric meaningful for NVE. Default True.

  • warmup_steps (int, optional) – Discard every firing before this step count, as read from the propagator’s own step counter. A run seeded from frames that are not equilibria of the propagated potential needs this equilibration window, because a fit that includes the relaxation reports it as drift. Default 0.

  • divergence (Callable[[Batch], Bool[Tensor, "G"]] | None, optional) – Predicate that flags the graphs that have diverged, evaluated at every firing after the warmup. The first firing that flags any graph is recorded as first_divergence_step and stops the series, so the metrics describe the trajectory up to the divergence. Default None (nonfinite_graph_mask(), which flags a non-finite position or force).

  • aggregate ({"max", "mean"}, optional) – Reduction across graphs for the drift, fluctuation, excursion, and momentum figures: the worst graph, or the mean over graphs. Default "max".

  • stop_on_composition_change (bool, optional) – Stop recording with a warning when the system_id in a slot changes while the batch keeps its shape. That is what an inflight refill with an equal-size system looks like. False keeps recording through such a refill. A change in the batch’s graph count or per-graph atom counts always stops the series, because the per-graph arrays could no longer be stacked. Default True.

Raises:

ValueError – If aggregate is not one of the two reductions.

Examples

>>> from nvalchemi.dynamics.hooks import StabilityMonitor
>>> monitor = StabilityMonitor(frequency=10, timestep_fs=1.0, warmup_steps=100)
>>> dynamics.register_hook(monitor)
>>> dynamics.run(batch)
>>> monitor.metrics().energy_drift_per_atom_per_ns
0.0042

Notes

Every sample is formed from the batch’s own energy, velocities, and atomic_masses. A batch built from geometry alone gains its energy on the propagator’s first compute(), which allocates the output fields the batch arrived without, so a firing inside a run always finds one. A batch fired outside a run has no model outputs and is refused.

Momentum is conserved only by an integrator that conserves it. Under a stochastic thermostat, max_momentum_drift describes the bath, and no acceptance bar should be set on it.

Recording stops with a warning as soon as the batch composition changes. A change means a different graph count, different per-graph atom counts, or a different system_id in the slots (unless stop_on_composition_change is off). A propagator that graduates systems mid-run is therefore scored on the segment before the first graduation. A sampler-seeded batch carries status, so its dispatches come with an active_graph_mask; the monitor records as long as that mask keeps every graph active. Like EnergyDriftMonitorHook, it does not yet support a dispatch in which some graphs are inactive, whose per-graph series would have to be tracked per system.

metrics()[source]#

Return the drift and conservation metrics of the recorded series.

The call stacks the recorded samples and fits a rate over them. It refuses a series too short to fit. Call it once the run is over; a call made mid-run scores only the segment recorded so far.

Returns:

Metrics over every recorded sample.

Return type:

StabilityMetrics

Raises:

ValueError – If fewer than two samples were recorded, or if every sample landed on the same step so no rate can be formed.