nvalchemi.dynamics.hooks.StabilityMetrics#

class nvalchemi.dynamics.hooks.StabilityMetrics(*, num_samples, first_step, last_step, energy_drift_per_atom, energy_drift_per_atom_per_step, energy_drift_per_atom_per_ns, max_momentum_drift, timestep_fs, energy_fluctuation_per_atom=None, max_energy_excursion_per_atom=None, first_divergence_step=None, aggregate='max')[source]#

Conservation diagnostics of one trajectory.

By default, every figure is reported for the worst graph in the batch, matching EnergyDriftMonitorHook. When the monitor was built with aggregate="mean", each is the mean over graphs instead. The per-nanosecond rate is the slope of a least-squares fit through every sample, not an endpoint difference, so a noisy series is not scored on whichever two samples bracket it. Because it is a slope, the rate reads zero for an excursion that is symmetric about the window. Read it together with energy_fluctuation_per_atom, the RMS residual about the same fit, and with max_energy_excursion_per_atom. A drift no larger than the fluctuation is a line fitted through an oscillation. Both drift figures include whatever transient the series starts with. A frame that is not equilibrated under the propagated potential relaxes during the run, and the fit reports that relaxation as drift. Give StabilityMonitor a warmup_steps window that covers the relaxation.

Parameters:
  • num_samples (int)

  • first_step (int)

  • last_step (int)

  • energy_drift_per_atom (float)

  • energy_drift_per_atom_per_step (float)

  • energy_drift_per_atom_per_ns (float | None)

  • max_momentum_drift (float)

  • timestep_fs (float | None)

  • energy_fluctuation_per_atom (float | None)

  • max_energy_excursion_per_atom (float | None)

  • first_divergence_step (int | None)

  • aggregate (Literal['max', 'mean'])

num_samples#

Recorded samples, after any discarded warmup.

Type:

int

first_step, last_step

Step counts of the first and last sample.

Type:

int

energy_drift_per_atom#

|E(t_end) - E(t_0)| / N of the worst graph, or the mean over graphs under aggregate="mean".

Type:

float

energy_drift_per_atom_per_step#

The same figure divided by the elapsed steps.

Type:

float

energy_drift_per_atom_per_ns#

Fitted drift rate in eV/atom/ns of the worst graph, or the mean over graphs under aggregate="mean". None when the monitor was given no timestep.

Type:

float | None

max_momentum_drift#

Largest deviation of a graph’s total momentum from its initial value, for the worst graph or as the mean over graphs under aggregate="mean".

Type:

float

timestep_fs#

Timestep the rates were derived with.

Type:

float | None

energy_fluctuation_per_atom#

RMS residual of a graph’s per-atom energy about the fitted line, for the worst graph or as the mean over graphs under aggregate="mean". None only when rebuilt from an export written before this field existed.

Type:

float | None

max_energy_excursion_per_atom#

Largest |E(t) - E(t_0)| / N a graph reached, for the worst graph or as the mean over graphs under aggregate="mean". None only when rebuilt from an older export.

Type:

float | None

first_divergence_step#

Step count of the first firing at which the monitor’s divergence predicate flagged a graph. The series stopped at that step. None when no graph diverged.

Type:

int | None

aggregate#

Reduction across graphs used to form the drift, fluctuation, excursion, and momentum figures.

Type:

Literal[“max”, “mean”]

model_config = {'extra': 'forbid', 'frozen': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].