nvalchemi.dynamics.ConvergenceHook

class nvalchemi.dynamics.ConvergenceHook(criteria=None, source_status=None, target_status=None, frequency=1)

Hook that evaluates composable convergence criteria and optionally migrates converged samples between pipeline stages.

Wraps one or more _ConvergenceCriterion instances and combines their results with AND semantics: a sample is converged only when every criterion is satisfied.

When source_status and target_status are both provided, the hook also performs status migration — updating batch.status for converged samples that match source_status. This enables the single-loop execution strategy used by FusedStage.

When used as a standalone convergence detector (both source_status and target_status are None), call evaluate() directly or let BaseDynamics use it via _check_convergence.

Parameters:

• criteria (list[_ConvergenceCriterion])

• source_status (int | None)

• target_status (int | None)

• frequency (int)

criteria

The individual convergence criteria.

Type:

list[_ConvergenceCriterion]

frequency

Execute every N steps.

Type:

int

stage

The stage at which this hook fires (AFTER_STEP).

Type:

DynamicsStage

source_status

Status code of samples to check for convergence. None disables status migration.

Type:

int | None

target_status

Status code to assign to converged samples. None disables status migration.

Type:

int | None

Examples

>>> # Backward-compatible fmax-only hook
>>> hook = ConvergenceHook.from_fmax(0.05)
>>> converged = hook.evaluate(batch)

>>> # Multi-criteria hook for FusedStage with status migration
>>> hook = ConvergenceHook(
...     criteria=[
...         {"key": "forces", "threshold": 0.05, "reduce_op": "norm", "reduce_dims": -1},
...         {"key": "energy_change", "threshold": 1e-6},
...     ],
...     source_status=0,
...     target_status=1,
... )

__init__(criteria=None, source_status=None, target_status=None, frequency=1)

Initialize the convergence hook.

Parameters:

• criteria (_ConvergenceCriterion | list[...] | dict | list[dict] | None) – Convergence criterion specification(s). Dicts are validated and converted to _ConvergenceCriterion instances. If None, defaults to a single forces-based criterion (max per-atom force norm) with threshold 0.05.

• source_status (int | None, optional) – Status code to check. None disables status migration.

• target_status (int | None, optional) – Status code to assign on convergence. None disables status migration.

• frequency (int, optional) – Execute every N steps. Default 1.

Return type:

None

Methods

__init__([criteria, source_status, ...])	Initialize the convergence hook.
evaluate(batch)	Evaluate all criteria and return indices of converged samples.
from_fmax([threshold, source_status, ...])	Create a forces-based convergence hook (fmax-compatible).
from_forces(threshold[, frequency, ...])	Construct from force-norm threshold (reads 'forces' key, norm reduction).

Attributes

num_criteria

Return the number of individual criteria.