Skip to content
Simpcat Simpcat Simpcat

simpcat.init()

simpcat.init(
    project: str | None = None,
    name: str | None = None,
    config: dict[str, Any] | None = None,
    mode: str | None = None,
    auto_expire_seconds: int | None = None,
    tags: dict[str, str] | None = None,
    notes: str | None = None,
    group: str | None = None,
    job_type: str | None = None,
    system_metrics: bool = True,
    system_metrics_interval: float = 15.0,
    capture_output: bool = False,
    resume: str | bool | None = None,
    dir: str | os.PathLike[str] | None = None,
    fork_from: str | None = None,
    fork_step: int | None = None,
    **kwargs: Any
) -> Run | NoOpRun

Initialize a new run.

Auto-finishes any previously active run. Returns a NoOpRun when mode=“disabled”.

SimpCat assigns run IDs. Passing id= is unsupported; resume reuses the run ID recorded in run.json under the run-data directory.

After calling init(), the active run is also accessible via module-level attributes: simpcat.run, simpcat.config, simpcat.summary, and simpcat.dir.

Parameters

Section titled “Parameters”
  • project — Project name. Defaults to “default”.
  • name — Run display name. Auto-generated if not provided.
  • config — Initial hyperparameter dict, accessible as run.config.
  • mode — Set to “disabled” to return a NoOpRun that discards all data.
  • auto_expire_seconds — If set, the run auto-expires after this many seconds.
  • tags — Dict of key-value tags for filtering runs.
  • notes — Free-text description of the run.
  • group — Group name for organizing related runs.
  • job_type — Job type label (e.g. “train”, “eval”).
  • system_metrics — Collect CPU/memory/GPU metrics in background. Default True.
  • system_metrics_interval — Seconds between system metric samples. Default 15.0.
  • capture_output — Capture stdout/stderr to files/output.log. Default False.
  • resume — Resume mode — omitted/None defaults to auto-resume from run.json in the run-data directory. True/“allow” tries resume and creates if missing, “must” fails if missing, “never” fails if the run already exists, “auto” reads run.json explicitly, and False forces a fresh run and writes the new id to run.json. Env var: SIMPCAT_RESUME.
  • dir — Directory for local simpcat run data. SimpCat stores run state and run directories under dir/simpcat. Defaults to ./.simpcat.
  • fork_from — Canonical run document ID to fork from. Must be paired with fork_step. This must be the canonical SimpCat run ID.
  • fork_step — Step to fork from. The new run’s step counter starts here.

Raises

Section titled “Raises”
  • TypeError — If id= or unknown keyword arguments are passed.