nvalchemi-reporting

nvalchemi Reporting

Overview

Use reporting for curated workflow summaries and dashboards. Use logging for direct event records such as per-system dynamics rows. See docs/userguide/reporting.md, docs/userguide/training.md, docs/userguide/dynamics.md, and docs/userguide/hooks.md for full details.

from nvalchemi.hooks import (
    ReportingOrchestrator,
    RichReporter,
    TensorBoardReporter,
)
from nvalchemi.dynamics.hooks import LoggingHook

---

Choose The Layer

Use ReportingOrchestrator when the user wants progress summaries, live Rich dashboards, TensorBoard scalar snapshots, rank reductions, or one observability hook that works across training, dynamics, and custom hook-enabled workflows. ReportingOrchestrator is the hook to register with hooks=[...] or register_hook(...); RichReporter, TensorBoardReporter, and custom Reporter objects are sinks owned by that hook and are not registered directly. Workflow engines enter and close hook context managers automatically during run(), so user code should not wrap reporting hooks manually in normal cases.

Use nvalchemi.dynamics.hooks.LoggingHook when the user wants a durable per-graph dynamics event stream. It computes dynamics observables such as energy, fmax, temperature, status, and graph index, then writes one row per system to CSV, TensorBoard, or a custom writer.

Do not reuse the dynamics LoggingHook as a training logger. For training, prefer reporters unless the task explicitly requires a raw training-event log; then implement a training-specific hook with the same hook protocol.

---

Training Pattern

Attach the ReportingOrchestrator as a normal training hook. Pick stages by enum name when the code already serializes hook specs or when avoiding imports in config files. Use AFTER_OPTIMIZER_STEP for high-frequency loss and learning-rate progress, and validation stages when summaries should align with validation output.

from nvalchemi.hooks import ReportingOrchestrator, RichReporter, TensorBoardReporter
from nvalchemi.training import CheckpointHook, TrainingStrategy

reporting = ReportingOrchestrator(
    [
        TensorBoardReporter("runs/example/tensorboard"),
        RichReporter(layout="training", refresh_per_second=2.0),
    ],
    stages={"AFTER_OPTIMIZER_STEP"},
    frequency=10,
)

strategy = TrainingStrategy(
    models=model,
    optimizer_configs=optimizer_config,
    loss_fn=loss_fn,
    hooks=[
        reporting,
        CheckpointHook("runs/example/checkpoints", epoch_interval=1),
    ],
    num_epochs=20,
)

strategy.run(train_loader)