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 (_ConvergenceCriterion | list[_ConvergenceCriterion] | dict | list[dict] | None)

• 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,
... )

evaluate(batch)

Evaluate all criteria and return indices of converged samples.

Pre-allocates a (N_criteria, B) boolean tensor, evaluates each criterion to fill one row, then AND-reduces across criteria. Returns the integer indices of converged samples, or None if no samples have converged.

Parameters:

batch (Batch) – The current batch of atomic data.

Returns:

1-D integer tensor of converged sample indices, or None if no samples satisfy all criteria.

Return type:

torch.Tensor | None

classmethod from_fmax(threshold=0.05, source_status=None, target_status=None, frequency=1)

Create a forces-based convergence hook (fmax-compatible).

This is a convenience constructor for backward compatibility with the original convergence_fmax parameter.

Parameters:

• threshold (float, optional) – Maximum force threshold. Default 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.

Returns:

Hook with a single forces-based (max force norm) criterion.

Return type:

ConvergenceHook

classmethod from_forces(threshold, frequency=1, source_status=None, target_status=None)

Construct from force-norm threshold (reads ‘forces’ key, norm reduction).

Parameters:

• threshold (float) – Force threshold; systems with max force norm <= threshold are converged.

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

• source_status (int | None, optional) – Status code that eligible systems must have. Default None (any status).

• target_status (int | None, optional) – Status code to assign to converged systems. Default None (no status change).

Returns:

Hook that evaluates max per-atom force norm against threshold.

Return type:

ConvergenceHook

property num_criteria: int

Return the number of individual criteria.