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,
    resume_from: str | None = None,
    dir: str | os.PathLike[str] | None = None,
    fork_from: str | None = None,
    fork_step: int | None = None,
    metric_aliases: dict[str, str] | None = None,
    allow_val_change: bool = False,
    **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 or supplied through resume_from after restoring external state.

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

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.
• resume_from — Canonical run ID restored from external durable state, such as a training checkpoint. This resumes that run even when the local run-data directory is missing. Cannot be combined with resume or fork_from, and is unavailable in offline mode.
• 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. This must be the canonical SimpCat run ID.
• fork_step — Step to fork from. The new run’s step counter starts here. Defaults to the parent run’s latest step when omitted.
• metric_aliases — Per-run metric alias map {alternate: canonical}. At read time an aliased metric name is treated as its canonical name when comparing runs; entries override the project-level alias map (managed with simpcat alias). No value may itself appear as a key (resolution is a single lookup, never a chain), and alternate names must be printable ASCII, not start with $, and not be __proto__ (they are stored as record keys). Forked runs inherit the parent run’s aliases with these entries as overrides; inherited entries that would conflict (form a chain with an entry in this map, or overflow the 200-entry cap) are dropped and reported as a run warning. On resume, passing a map replaces the stored one (an explicit {} clears it); omitting the argument keeps it.
• allow_val_change — Allow resume to silently overwrite stored config values. By default, resuming with a config value that differs from the stored one keeps the new value but emits a warning and a run diagnostic suggesting fork_from for a clean branch.

Raises

• TypeError — If id= or unknown keyword arguments are passed.
• ValueError — If resume arguments conflict, resume_from is invalid, or metric_aliases is malformed (non-string names, self-mappings, chained aliases, or too many entries).