Validation

ValidationConfig configures strategy-owned validation passes; ValidationLoop is the reusable loop that the strategy drives, and that you can also run standalone. Neither performs a backward pass or optimizer step — validation runs the forward and loss only, then reduces per-batch results across ranks.

See also

• Training update hooks — AFTER_VALIDATION stage and update hooks.

• Training — validation configuration patterns and customization.

Training vs validation

Aspect	Training step	Validation pass
Backward / optimizer step	Yes	No — forward + loss only
Module mode	train()	eval() by default (set_eval), restored afterward
Autograd	Always on	Driven by grad_mode
Weights	Live training weights	Live, or the EMA / inference slot (use_ema)
Per-batch output	Loss for the update	Accumulated into a reduced summary
Gradient buffers	Updated in place	Snapshotted, cleared, restored

ValidationConfig

Field	Type	Description
validation_data	collections.abc.Iterable[nvalchemi.data.batch.Batch]	Re-iterable container (e.g. list, DataLoader, Dataset) yielding Batch instances. The strategy re-iterates this on every validation pass; one-shot generators and bare iterators are rejected at construction time.
validation_fn	collections.abc.Callable[..., typing.Any] | None	Validation forward callable. None means use the strategy’s training_fn with the same single-model or named-model call convention.
loss_fn	nvalchemi.training.losses.composition.ComposedLossFunction | None	Validation loss function. None means use the strategy’s loss_fn. Leaf losses are auto-normalized to a ComposedLossFunction via as_composed_loss().
every_n_epochs	int | None	Run validation after every n-th completed epoch. Mutually exclusive with every_n_steps.
every_n_steps	int | None	Run validation after every n-th completed optimizer step. Mutually exclusive with every_n_epochs.
grad_mode	typing.Literal['auto', 'enabled', 'disabled']	Autograd policy during validation. "auto" enables gradients when any loss component has requires_eval_grad=True and disables them when all components report False.
set_eval	<class 'bool'>	If True, set validation modules to eval mode and restore their original training modes afterward.
use_ema	typing.Literal['auto', 'always', 'never']	Whether the strategy’s inference_model slot (populated by EMA) should replace live training weights for validation.
use_mixed_precision	typing.Literal['auto', 'always', 'never']	Whether to reuse a registered MixedPrecisionHook autocast context for validation inference.
batch_callback	nvalchemi.training._validation.BatchValidationCallback | None	Optional user-supplied callable invoked once per validation batch with the batch, predictions, and per-batch loss output. Use it to stream per-sample diagnostics to a custom logging or storage backend. None disables per-batch callbacks. For epoch-level (summary) logging, register a hook on the AFTER_VALIDATION stage and read ctx.validation instead.
name	<class 'str'>	Name stored in the validation summary dictionary.

Assign to strategy.validation_config to enable strategy-owned validation:

from nvalchemi.training import TrainingStrategy, ValidationConfig

strategy = TrainingStrategy(...)
strategy.validation_config = ValidationConfig(
    validation_data=val_data,
    every_n_epochs=1,
)
strategy.run(train_loader)

validation_data must be a re-iterable container (list, DataLoader, Dataset); one-shot generators are rejected at construction time.

Standalone validation

ValidationLoop is a context manager — call execute() inside the with block; training modes and gradient buffers are snapshotted and restored on exit, even on exception:

from nvalchemi.training import ValidationConfig, ValidationLoop

config = ValidationConfig(validation_data=val_data, loss_fn=loss_fn)
loop = ValidationLoop(
    validation_data=val_data,
    config=config,
    device=device,
    model=model,
    validation_fn=validation_fn,
)
with loop as active:
    summary = active.execute()

The returned summary matches ctx.validation / strategy.last_validation during integrated training: total_loss, per-component totals, batch and sample counts, model_source, precision, and distributed_reduced.

API reference

ValidationConfig	Configuration for strategy-owned validation passes.
ValidationLoop	Context-manager orchestrator for a single validation pass.
BatchValidationCallback	Protocol for an optional per-batch validation callback.