Simulation checkpoints and forks

Simulation Checkpoints preserve a fuller swmmrs continuation boundary than an EPA hotstart. Use them to resume a running owner in another process, create an independent in-process branch, or import physical state into a compatible open receiver.

These operations are distinct from save_hotstart() and use_hotstart(), which read and write EPA's .hsf format.

Choose an operation

Save, fork, and resume operate at quiescent RUNNING or COMPLETE boundaries. They may be called between iterator advances after next() returns.

What each mechanism restores

The three durable mechanisms answer different modeling questions. In the table, source means that the value recorded at the saved boundary is restored; receiver means that the newly opened model keeps or initializes its own value. Selected means that the artifact carries only the listed state, not the complete state of that subsystem.

The matrix describes the current swmmrs contracts rather than every byte in a live process. Raw file handles, buffers, worker threads, and scratch workspaces are never serialized; Resume rebuilds them from durable state. EPA Hotstart has limited count and flow-unit checks, Enhanced Hotstart performs strict receiver compatibility and scalar-domain checks, and Resume validates the complete checkpoint artifact set.

Save and resume

from pathlib import Path

from swmmrs import Simulation

checkpoint = Path("continuation/state.json")

source = Simulation("model.inp", "source.rpt", "source.out")
source.start()
source.step()
source.save_checkpoint(checkpoint)

resumed = Simulation.resume(
    checkpoint,
    "resumed.rpt",
    "resumed.out",
)

# Both owners are independent and continue from the saved boundary.
source_time = source.step()
resumed_time = resumed.step()

for simulation in (source, resumed):
    simulation.end()
    simulation.close()

Published generation-addressed sidecars are immutable. Saving again to the same manifest destination atomically replaces that manifest with a new generation; use a unique manifest path for every boundary that must remain retained. resume() requires fresh report and output destinations and rejects collisions before publishing an owner.

Fork an in-process scenario

fork() avoids a durable round trip and preserves the source owner's prepared configuration coordinator and editable declarations:

from swmmrs import Simulation

source = Simulation("model.inp", "baseline.rpt", "baseline.out")
source.start()
source.step()

child = source.fork("scenario.rpt", "scenario.out")
child.links["GATE"].target_setting = 0.5

while source.step() is not None:
    pass
while child.step() is not None:
    pass

for simulation in (source, child):
    simulation.end()
    simulation.report()
    simulation.close()

Source and child do not share hydraulic state. Give every owner unique mutable artifact paths.

Load physical state into an open receiver

Use State Load when the receiver must keep its parsed configuration and later support declaration editing:

from swmmrs import Simulation

receiver = Simulation("compatible.inp", "receiver.rpt", "receiver.out")
receiver.load_checkpoint_state("continuation/state.json")

# Classified warm state is staged now. Receiver forcing and input processors
# remain authoritative when normal startup initializes the new run.
receiver.start()
while receiver.step() is not None:
    pass
receiver.end()
receiver.report()
receiver.close()

The receiver must be OPEN and structurally compatible. State Load stages dirty receiver declarations without mutation and accepts them only when they leave State Load structure and scalar interpretation unchanged. It validates the imported physical values, commits preparation and the classified physical/numerical subset together, and retains a pending copy so start() can reapply it after processor initialization.

The receiver keeps its dates, all persistent-forcing families, configured inputs and their progress, iterator cadence, fresh statistics/accounting, output history, and parsed declarations. Checkpoint sidecars are not read. Source rain/RDII progress and residual source-input response are not imported. Enhanced Hotstart makes no first-step or whole-run equality promise with Checkpoint Resume, even when receiver forcing, dates, and inputs match.

Prefer to complete preparation-dependent edits before loading. If you make one while warm state is pending, the edit is accepted but start() reports that the pending State Load is stale. Call load_checkpoint_state() again to prepare the receiver and revalidate the import. Persistent-forcing and metadata-only updates do not stale the pending warm state.

Editable declarations after durable resume

Checkpoint format 1.2 preserves the source owner's editable declarations and warning baseline as an authenticated payload. The full-resume fingerprint binds that payload to the checkpoint's canonical state; do not copy configuration between manifests, even if the models appear structurally compatible. After resume(), you can finish and end the restored run, make stable edits, and start a fully prepared rerun. State Load remains different: it keeps the open receiver's parsed declarations.

Artifacts and failures

A Simulation Checkpoint is not one opaque file. The JSON manifest identifies immutable sidecars for active report/output prefixes and generated resources, and validated external dependencies for immutable inputs. Do not move, replace, or edit members independently.

Publication is atomic from the caller's perspective: the manifest appears only after its complete generation is usable. Resume and fork preflight all requested destinations. Destination and preflight failures publish no partial owner and leave the source unchanged. An operational failure while flushing source-owned resources can establish FAILED, even though no child or partial destination is published.

ValidationError reports Python/path alias mistakes known before native resource planning; LifecycleError reports an invalid owner state; SolverError reports non-fresh destinations, integrity or compatibility failures, capture, resource validation, and publication failures. See Errors and recovery.