Logging Metrics

Basic logging

Pass a dictionary of metric names to scalar values:

simpcat.log({"train/loss": 0.5, "train/acc": 0.85})

Each log() call with commit=True advances the global step counter. When commit is not specified, it defaults to True when no explicit step is provided, and False when step is given. Metrics appear as time-series charts in the web UI.

Explicit steps

Override the auto-incrementing step:

simpcat.log({"val/loss": 0.3}, step=100)

Buffered logging

Use commit=False to accumulate metrics across multiple calls, then flush with commit=True:

simpcat.log({"train/loss": 0.5}, commit=False)
simpcat.log({"train/acc": 0.85}, commit=True)  # both metrics sent at this step

This is useful when different metrics are computed in different parts of your training loop.

Custom x-axes

By default, all metrics use the global step as the x-axis. Use define_metric() to plot a metric against a different axis:

simpcat.define_metric("val/loss", step_metric="epoch")

for epoch in range(10):
    simpcat.log({"epoch": epoch, "val/loss": validate()})

Now val/loss charts use epoch as the x-axis instead of the global step.

Summary aggregation

Control how a metric is summarized in the run table:

simpcat.define_metric("val/loss", summary="min")
simpcat.define_metric("val/acc", summary="max")
simpcat.define_metric("train/loss", summary="last")

Valid summary types: "min", "max", "last", "mean", "best".

Histograms

Log distribution data using simpcat.Histogram:

import numpy as np
import simpcat

run = simpcat.init(project="my-project")

# From a sequence (auto-binned)
weights = model.layer.weight.detach().cpu().numpy().ravel()
simpcat.log({"weights": simpcat.Histogram(weights)})

# Control the number of bins
simpcat.log({"activations": simpcat.Histogram(activations, num_bins=128)})

# From a pre-computed numpy histogram
counts, bin_edges = np.histogram(data, bins=50)
simpcat.log({"custom": simpcat.Histogram(np_histogram=(counts, bin_edges))})

Histograms are displayed as bar charts in the web UI. Max 512 bins.

System metrics

By default, simpcat.init() starts a background thread that logs system metrics every 15 seconds under the sys/ prefix. Metrics collected (when dependencies are available):

• CPU/memory/disk (requires psutil): sys/cpu_percent, sys/memory_used_gb, sys/memory_total_gb, sys/memory_percent, sys/disk_used_gb, sys/disk_percent
• GPU (requires pynvml): sys/gpu.{i}.utilization, sys/gpu.{i}.memory_utilization, sys/gpu.{i}.memory_used_gb, sys/gpu.{i}.memory_total_gb, sys/gpu.{i}.temperature, sys/gpu.{i}.power_w

If neither psutil nor pynvml is installed, system metrics collection is silently skipped.

Disable or adjust:

simpcat.init(project="my-project", system_metrics=False)

# Or change the interval
simpcat.init(project="my-project", system_metrics_interval=30.0)