specsr.runtime

Environment-variable overrides for the training scripts.

The SR1 and SR2 training scripts carry their hyperparameters in a literal dict with no command-line interface, so there was no way to run them briefly. That makes an overnight chain risky: a typo or a missing checkpoint in stage 3 only surfaces hours in, after stages 1 and 2 have already burned the night.

This module lets any stage be run in a shortened form through exactly the same code path, driven by environment variables so no call site has to change:

SPECSR_EPOCHS

Override the epoch count.

SPECSR_LIMIT_TRAIN_BATCHES / SPECSR_LIMIT_VAL_BATCHES

Stop each epoch after this many batches. This is what makes a smoke run take seconds rather than an hour — an epoch over the DR4 product is ~1,300 steps.

SPECSR_OUT_DIR

Redirect checkpoints and artefacts, so a smoke run cannot overwrite real weights.

SPECSR_DATASET

Override the dataset path.

SPECSR_WANDB_MODE

Set to disabled or offline for smoke runs that should not create cloud runs.

A smoke run must exercise the real code path. Reimplementing a shortened version of the loop would test the reimplementation, not the thing that runs overnight.

Functions

apply_env_overrides(config)	Return config with environment overrides applied.
describe_overrides()	One-line summary of active overrides, for logging at stage start.
env_int(name[, default])
is_smoke_run()	True when any batch limit is set, i.e. this is not a full run.
limit_batches(loader[, limit, kind])	Yield at most limit batches from loader.
resolve_dataset(default)	Return SPECSR_DATASET if set, else default.
wandb_mode([default])	W&B mode, overridable via SPECSR_WANDB_MODE.

specsr.runtime.apply_env_overrides(config)

Return config with environment overrides applied.

Called immediately after a stage builds its config dict and before that dict reaches W&B, so the run record shows what actually ran.

Parameters:

config (dict[str, Any])

Return type:

dict[str, Any]

specsr.runtime.limit_batches(loader, limit=None, *, kind='train')

Yield at most limit batches from loader.

limit defaults to SPECSR_LIMIT_TRAIN_BATCHES or SPECSR_LIMIT_VAL_BATCHES depending on kind. With no limit set this is a transparent pass-through, so wrapping a loop costs nothing in a real run.

Parameters:

• loader (Iterable)

• limit (int | None)

• kind (str)

Return type:

Iterator

specsr.runtime.is_smoke_run()

True when any batch limit is set, i.e. this is not a full run.

Return type:

bool

specsr.runtime.env_int(name, default=None)

Parameters:

• name (str)

• default (int | None)

Return type:

int | None

specsr.runtime.describe_overrides()

One-line summary of active overrides, for logging at stage start.

Return type:

str

specsr.runtime.resolve_dataset(default)

Return SPECSR_DATASET if set, else default.

The SR1 and SR2 scripts hold their dataset path in a local variable rather than in the config dict, so apply_env_overrides() never reached it. That was not cosmetic: a preflight check could validate one dataset while the stage silently trained on another, which a smoke run caught doing exactly that — validating DR4 and then training on DR3.

The resolved path is echoed on a machine-readable line so the chain script can assert every stage agrees on the dataset. A stage training on the wrong product is invisible in the metrics and expensive to discover late.

Parameters:

default (str)

Return type:

str

specsr.runtime.wandb_mode(default='online')

W&B mode, overridable via SPECSR_WANDB_MODE.

Smoke runs set this to offline so rehearsals do not litter the project with cloud runs that look like real experiments.

Parameters:

default (str)

Return type:

str