Lightning Integration

SimpCatLogger is a PyTorch Lightning Logger that sends metrics to Simpcat. It’s a drop-in replacement for WandbLogger.

Prerequisites

SimpCatLogger requires lightning, which is already installed in any Lightning-based training environment. No special extras needed — just pip install simpcat.

Basic usage

from simpcat import SimpCatLogger
import lightning as L

logger = SimpCatLogger(project="my-project", name="experiment-1")
trainer = L.Trainer(logger=logger, max_epochs=10)
trainer.fit(model, datamodule)

The logger automatically:

• Creates a run on trainer.fit()
• Logs all training/validation metrics
• Records hyperparameters via log_hyperparams()
• Keeps the run open across Lightning stages such as validate(), fit(), and test()
• Stores local SimpCat state under save_dir/simpcat when save_dir is provided, otherwise under the default .simpcat/ run-data directory

Run lifecycle

Lightning calls logger finalization hooks after each trainer entrypoint, not only when the whole experiment is done. SimpCatLogger therefore does not finish the SimpCat run from Lightning finalization. The run is finished when you call simpcat.finish() / run.finish(), or automatically when the Python process exits.

This lets one run cover multi-stage workflows:

trainer.validate(model, datamodule=datamodule)
trainer.fit(model, datamodule=datamodule)
trainer.test(model, datamodule=datamodule)

If you want deterministic cleanup before process exit, own the run explicitly and finish it after all Lightning stages and manual logging are complete:

run = simpcat.init(project="my-project", name="experiment-1")
logger = SimpCatLogger(run=run)

trainer = L.Trainer(logger=logger)
trainer.fit(model, datamodule)

run.finish("finished")

Sharing a run with simpcat.init()

If you need access to the run object (e.g. to log media), create it first and pass it in:

import simpcat
from simpcat import SimpCatLogger

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

# Log media directly
simpcat.log({"sample": simpcat.Audio(audio, sample_rate=22050)})

# Pass run to Lightning
logger = SimpCatLogger(run=run)
trainer = L.Trainer(logger=logger)
trainer.fit(model, datamodule)

Auto-expiring runs

logger = SimpCatLogger(project="my-project", auto_expire_seconds=3600)

Additional parameters

SimpCatLogger also accepts:

• save_dir — Optional directory for run data. When provided, reusing the same save_dir with default auto-resume reuses the run id in save_dir/simpcat/run.json. When omitted, SimpCat uses the default .simpcat/ run-data directory.
• mode — Reporter mode ("online", "offline", or "disabled"). When "disabled", creates a NoOpRun that discards all data.

Distributed training

SimpCatLogger automatically detects distributed training and only logs on rank 0 (using LOCAL_RANK or RANK env vars). Other ranks use a NoOpRun that discards all data. Setting mode="disabled" also creates a NoOpRun.