nvalchemi.training.ValidationLoop

class nvalchemi.training.ValidationLoop(*, validation_data, config, device, model=None, models=None, loss_fn=None, loss_target_assembler=assemble_loss_targets, validation_fn=None, inference_model=None, autocast=None, grad_enabled=None, distributed_manager=None, step_count=0, epoch=0)

Context-manager orchestrator for a single validation pass.

ValidationLoop encapsulates the full validation lifecycle — setup, per-batch forward + loss accumulation, distributed summary reduction, sink writes, and teardown — in a single reusable object.

Two construction paths are supported:

• Standalone via __init__(): caller provides all dependencies explicitly. No strategy or hook scanning.

• Strategy-integrated via from_training_strategy(): reads capabilities through strategy introspection and holds a live reference for counter/model access during execute().

Usage:

with ValidationLoop.from_training_strategy(strategy) as loop:
    summary = loop.execute()

Parameters:

• validation_data (Iterable[Batch]) – Re-iterable object yielding validation batches.

• config (ValidationConfig) – Validation configuration.

• device (torch.device) – Primary device for the validation pass.

• model (nn.Module | None) – Single model for single-model validation. Mutually exclusive with models.

• models (dict[str, nn.Module] | None) – Named models for named-model validation. Mutually exclusive with model.

• loss_fn (ComposedLossFunction | None) – Validation loss function. Falls back to config.loss_fn when None.

• validation_fn (Callable[..., Any] | None) – Validation forward callable. Required in standalone mode.

• inference_model (nn.Module | nn.ModuleDict | None) – Optional EMA/inference model to swap in during validation.

• autocast (Callable[[], AbstractContextManager[None]] | None) – Precision context factory. None uses contextlib.nullcontext() and precision label "float32".

• grad_enabled (bool | None) – Autograd policy. None infers from config.grad_mode and loss_fn.requires_eval_grad().

• distributed_manager (Any | None) – Optional distributed manager for all-reduce and barrier ops.

• step_count (int) – Optimizer step counter for sink metadata.

• epoch (int) – Epoch counter for sink metadata.

• loss_target_assembler (LossTargetAssemblyProtocol)

Raises:

ValueError – When both or neither of model/models are supplied, or when required arguments (loss_fn, validation_fn) are missing.

execute()

Run the validation loop over all batches and return the summary.

Iterates validation_data, runs the forward pass and loss computation per batch, invokes the optional per-batch callback, accumulates results, computes the distributed-reduced summary, and returns the summary dictionary.

Returns:

The local validation summary outside distributed execution, or the distributed-reduced summary on every distributed rank.

Return type:

dict[str, Any]

Raises:

• RuntimeError – When called outside the context manager.

• ValueError – When validation_data produces no batches.

classmethod from_training_strategy(strategy, config=None)

Build a ValidationLoop from a TrainingStrategy.

Reads capabilities through the strategy’s introspection methods and holds a live reference for counter/model access during execute().

Parameters:

• strategy (TrainingStrategy) – The training strategy owning the validation pass.

• config (ValidationConfig | None) – Override validation config. None uses strategy.validation_config.

Returns:

A loop instance ready to be used as a context manager.

Return type:

ValidationLoop

Raises:

RuntimeError – When strategy.validation_config is None and no config override is provided.