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
BaseDynamicsrun like any observation hook, then callmetrics()once the run is over. UnlikeEnergyDriftMonitorHook, 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, raisefrequencyrather than record every step.- Parameters:
frequency (int, optional) – Record every
frequencysteps. The dynamics hook registry applies this gating. Default1.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_stepand stops the series, so the metrics describe the trajectory up to the divergence. DefaultNone(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_idin a slot changes while the batch keeps its shape. That is what an inflight refill with an equal-size system looks like.Falsekeeps 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. DefaultTrue.
- Raises:
ValueError – If
aggregateis 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, andatomic_masses. A batch built from geometry alone gains itsenergyon the propagator’s firstcompute(), 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_driftdescribes 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_idin the slots (unlessstop_on_composition_changeis off). A propagator that graduates systems mid-run is therefore scored on the segment before the first graduation. A sampler-seeded batch carriesstatus, so its dispatches come with anactive_graph_mask; the monitor records as long as that mask keeps every graph active. LikeEnergyDriftMonitorHook, 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:
- Raises:
ValueError – If fewer than two samples were recorded, or if every sample landed on the same step so no rate can be formed.