Simulation

Source-generated reference for simulation ownership, advancement, files, and scenario operations. See Run a model for workflows.

Hotstarts, checkpoints, and forks

See the continuation guide for choosing a mechanism. The method and bundle contracts are generated below.

Simulation

One isolated project, worker pool, and in-memory file system. Open with open, not the private constructor, and always await close. Handles and collections share this owner's lifecycle. Only one iterator or manual advancement may own the solver; result reads and allowed controls can run between observations. Records already returned remain usable after close.

Implements

AsyncIterable<ModelTime>
AsyncDisposable

Properties

nodes

readonly nodes: NodeCollection;

Configured-order node handles and aligned snapshot reads.

links

readonly links: LinkCollection;

Configured-order link handles and aligned snapshot reads.

subcatchments

readonly subcatchments: SubcatchmentCollection;

Configured-order subcatchment handles and aligned snapshot reads.

rainGages

readonly rainGages: RainGageCollection;

Configured-order rain-gage handles; no collection snapshot API.

options

readonly options: SimulationOptionsView;

Stable model-option view, distinct from worker creation options.

pollutants

readonly pollutants: ObjectCollection<Definition>;

Pollutant identities; definition editing is not exposed.

landUses

readonly landUses: ObjectCollection<Definition>;

Land-use identities.

timePatterns

readonly timePatterns: ObjectCollection<Definition>;

Time-pattern identities.

curves

readonly curves: ObjectCollection<Definition>;

Curve identities.

timeSeries

readonly timeSeries: ObjectCollection<Definition>;

Time-series identities; data editing is not exposed.

controls

readonly controls: ObjectCollection<Definition>;

Control-rule identities.

transects

readonly transects: ObjectCollection<Definition>;

Transect identities.

aquifers

readonly aquifers: ObjectCollection<Aquifer>;

Editable aquifer definitions.

snowmeltSets

readonly snowmeltSets: ObjectCollection<SnowmeltParameterSet>;

Editable snowmelt parameter sets.

shapes

readonly shapes: ObjectCollection<Definition>;

Custom cross-section shape identities.

streets

readonly streets: ObjectCollection<Definition>;

Street identities.

inletDesigns

readonly inletDesigns: ObjectCollection<Definition>;

Inlet-design identities.

ammModels

readonly ammModels: ObjectCollection<AmmModel>;

Editable AMM definitions; node assignments are separate.

unitHydrographs

readonly unitHydrographs: ObjectCollection<UnitHydrograph>;

Editable RTK definitions; RDII assignments are separate.

lidControls

readonly lidControls: ObjectCollection<LidControl>;

Editable LID-control layers; unit placements belong to subcatchments.

Methods

open()

static open(
   input: FileContents, 
   files?: Readonly<Record<string, FileContents>>, 
   options?: SimulationOptions
): Promise<Simulation>;

Parse an INP in a new independent worker.

Parameters

Parameter	Type	Description
`input`	`FileContents`	INP contents, never a host path.
`files`	`Readonly`<`Record`<`string`, `FileContents`>>	Supporting-file contents keyed by INP-relative paths; defaults to an empty record.
`options`	`SimulationOptions`	Worker URL and thread capacity; defaults to an empty record.

Returns

Promise<Simulation>

An owner in open; close it when finished.

Throws

Rejects malformed input, invalid thread capacity, unavailable runtime prerequisites, or solver parse failures.

resume()

static resume(checkpoint: CheckpointBundle, options?: SimulationOptions): Promise<Simulation>;

Restore a checkpoint in an independent worker without rerunning the model.

Parameters

Parameter	Type	Description
`checkpoint`	`CheckpointBundle`	Complete bundle, including manifest sidecars and dependencies.
`options`	`SimulationOptions`	Worker creation options (the second argument); defaults to an empty record.

Returns

Promise<Simulation>

An independent owner; no worker or mutable state is shared with the source.

Throws

Rejects unsupported, corrupt, mismatched, or incomplete checkpoint bundles.

getState()

getState(): Promise<SimulationState>;

Read native lifecycle state, including after cleanup.

Returns

Promise<SimulationState>

The current state, or closed after close completes.

info()

info(): Promise<SimulationInfo>;

Read model identities, units, solver build, effective threads, and schedule while healthy.

Returns

Promise<SimulationInfo>

Detached model information.

status()

status(): Promise<SimulationStatus>;

Read lifecycle and progress before close.

Returns

Promise<SimulationStatus>

Detached status; unavailable after cleanup.

updateSchedule()

updateSchedule(patch: SchedulePatch): Promise<void>;

Update calendar boundaries in open or ended; accepted edits return ended to open.

Parameters

Parameter	Type	Description
`patch`	`SchedulePatch`	Sparse timezone-free schedule. Omitted times retain their values.

Returns

Promise<void>

Resolves after the schedule update is accepted.

ammAssignments()

ammAssignments(): Promise<readonly AmmAssignment[]>;

Read the complete AMM node-assignment list.

Returns

Promise<readonly AmmAssignment[]>

Canonical node/model IDs and areas in project land-area units.

replaceAmmAssignments()

replaceAmmAssignments(assignments: readonly AmmAssignment[]): Promise<void>;

Atomically replace all AMM assignments in open or ended; accepted edits return the owner to open.

Parameters

Parameter	Type	Description
`assignments`	readonly `AmmAssignment`[]	Complete replacement list; an empty list clears all assignments.

Returns

Promise<void>

Resolves after all assignments are accepted.

rdiiAssignments()

rdiiAssignments(): Promise<readonly RdiiAssignment[]>;

Read the complete RTK RDII assignment list.

Returns

Promise<readonly RdiiAssignment[]>

Canonical node/unit-hydrograph IDs and project land areas.

replaceRdiiAssignments()

replaceRdiiAssignments(assignments: readonly RdiiAssignment[]): Promise<void>;

Atomically replace all RTK assignments in open or ended; accepted edits return the owner to open.

Parameters

Parameter	Type	Description
`assignments`	readonly `RdiiAssignment`[]	Complete replacement list; an empty list clears all assignments.

Returns

Promise<void>

Resolves after all assignments are accepted.

useHotstart()

useHotstart(input: FileContents | null): Promise<void>;

Configure hotstart input in open or ended; accepted edits return the owner to open.

Parameters

Parameter	Type	Description
`input`	`FileContents` \| `null`	Hotstart file contents, or null to clear the configured input.

Returns

Promise<void>

Resolves after the configuration write.

saveHotstart()

saveHotstart(): Promise<Uint8Array<ArrayBufferLike>>;

Save current hydraulic state in running or complete.

Returns

Promise<Uint8Array<ArrayBufferLike>>

Caller-owned EPA hotstart bytes.

saveCheckpoint()

saveCheckpoint(): Promise<CheckpointBundle>;

Capture a quiescent running or complete owner, including validated dependencies.

Returns

Promise<CheckpointBundle>

Complete portable checkpoint bundle with manifest sidecars.

loadCheckpointState()

loadCheckpointState(checkpoint: CheckpointBundle): Promise<void>;

Stage physical and numerical checkpoint state in an open owner. Declarations, files, and persistent forcings remain those of the receiver.

Parameters

Parameter	Type	Description
`checkpoint`	`CheckpointBundle`	Compatible bundle with all required dependencies.

Returns

Promise<void>

Resolves with the owner still open; state is applied by its next start.

Throws

Rejects incompatible identity, unsupported dependencies, corrupt manifests, or missing sidecars.

fork()

fork(options?: SimulationOptions): Promise<Simulation>;

Save a checkpoint and resume it in a new independent owner.

Parameters

Parameter	Type	Description
`options`	`SimulationOptions`	Worker options for the child; defaults to an empty record.

Returns

Promise<Simulation>

Independent simulation with copied run state and forcings.

start()

start(options?: RunOptions): Promise<void>;

Start an open or ended model.

Parameters

Parameter	Type	Description
`options`	`RunOptions`	Run options; `saveResults` defaults to true.

Returns

Promise<void>

Resolves after solver initialization succeeds.

step()

step(): Promise<string | null>;

Advance one routing step in a started run, without an active iterator.

Returns

Promise<string | null>

New model time, or null at natural completion.

stride()

stride(seconds: number, strict?: boolean): Promise<string | null>;

Advance an observation interval in a started run.

Parameters

Parameter	Type	Default value	Description
`seconds`	`number`	`undefined`	Positive 32-bit integer interval in seconds.
`strict`	`boolean`	`true`	Defaults to true: land exactly on the boundary. False allows whole-step overshoot.

Returns

Promise<string | null>

New model time, or null at natural completion.

[asyncIterator]()

asyncIterator: AsyncGenerator<string, void, unknown>;

Automatic start and routing-step advancement; exhaustion retains final statistics.

Returns

AsyncGenerator<string, void, unknown>

The same async generator as steps with default options.

Implementation of

AsyncIterable.[asyncIterator]

steps()

steps(options?: StepOptions): AsyncGenerator<string, void, unknown>;

Iterate observations, lazily starting open or ended owners on the first next(). Early exit releases advancement ownership, leaving the run available to finish or resume.

Parameters

Parameter	Type	Description
`options`	`StepOptions`	Observation/run options; routing-step cadence, strict boundaries, and retained results by default.

Returns

AsyncGenerator<string, void, unknown>

Generator of observation times. Natural exhaustion leaves final statistics available.

Throws

Rejects invalid intervals/flags or competing advancement/finalization.

terminate()

terminate(): void;

End active iteration at its next observation boundary, without closing the owner.

Returns

void

Immediately; the iterator performs the end operation at its next boundary.

Throws

Synchronously throws LifecycleError if no iterator owns advancement.

node()

node(id: string): Promise<NodeResults>;

Direct node result read retained for prototype callers; requires results to be available.

Parameters

Parameter	Type	Description
`id`	`string`	Node ID resolved in the worker, not by a local collection lookup.

Returns

Promise<NodeResults>

Detached node hydraulics; unknown IDs reject the promise.

link()

link(id: string): Promise<LinkResults>;

Direct link result read retained for prototype callers.

Parameters

Parameter	Type	Description
`id`	`string`	Link ID resolved in the worker.

Returns

Promise<LinkResults>

Detached link hydraulics; unknown IDs reject the promise.

setNodeExternalInflow()

setNodeExternalInflow(id: string, flow: number): Promise<void>;

Direct equivalent of nodes.get(id).setExternalInflow(flow).

Parameters

Parameter	Type	Description
`id`	`string`	Node ID resolved in the worker.
`flow`	`number`	Persistent additive inflow in project flow units.

Returns

Promise<void>

Resolves after updating the forcing in open, running, or ended.

setLinkTargetSetting()

setLinkTargetSetting(id: string, setting: number): Promise<void>;

Direct equivalent of links.get(id).setTargetSetting(setting); requires running.

Parameters

Parameter	Type	Description
`id`	`string`	Link ID resolved in the worker.
`setting`	`number`	Dimensionless opening or pump speed factor.

Returns

Promise<void>

Resolves after updating the target; unknown IDs reject the promise.

statistics()

statistics(): Promise<SimulationStatistics>;

Read system statistics in running or complete, before ending the run.

Returns

Promise<SimulationStatistics>

Detached cumulative totals, continuity balances, and routing diagnostics.

finish()

finish(): Promise<RunResults>;

End the run, write requested reports, and finalize binary output; safe to repeat in ended. Supports partial runs and retains the owner for result reads and reruns.

Returns

Promise<RunResults>

Finalized report and caller-owned output bytes; output is empty with saveResults: false.

run()

run(options?: RunOptions): Promise<RunResults>;

Start, run to completion, and finalize with one worker request.

Parameters

Parameter	Type	Description
`options`	`RunOptions`	Run options; `saveResults` defaults to true.

Returns

Promise<RunResults>

Finalized files, retaining the owner in ended until closed or reused.

end()

end(): Promise<void>;

End a running or complete run without detailed report tables.

Returns

Promise<void>

Resolves after flushing output/summary statistics and entering ended.

finalizeReport()

finalizeReport(): Promise<void>;

Append and flush only the runtime footer in ended, once, even without saved results. JavaScript exposes this before close removes its in-memory files; Python report paths survive close.

Returns

Promise<void>

Resolves after the footer is flushed, without detailed report tables.

report()

report(): Promise<void>;

Generate requested detailed report tables and footer in ended, once.

Returns

Promise<void>

Resolves after flushing the report.

Throws

Rejects when the run did not retain binary results.

resetSolver()

resetSolver(): Promise<void>;

Discard run/results/output state in open or ended without reparsing the INP. Retains declarations and persistent forcings; clears staged checkpoint state.

Returns

Promise<void>

Resolves with the owner in open.

sleepWorkers()

sleepWorkers(): Promise<void>;

Put active Dynamic Wave workers to sleep; requires running.

Returns

Promise<void>

Resolves after the power-state operation; lifecycle state is unchanged.

readFile()

readFile(name: string): Promise<Uint8Array<ArrayBufferLike>>;

Copy a project or generated file before close; does not flush or finalize a run.

Parameters

Parameter	Type	Description
`name`	`string`	Path in the worker's project file system, not a host path.

Returns

Promise<Uint8Array<ArrayBufferLike>>

Caller-owned bytes. Call finish first for finalized report/output files.

close()

close(): Promise<void>;

Release the project, workers, and in-memory files. Repeated calls share cleanup.

Returns

Promise<void>

Resolves when cleanup finishes; all owner-bound handles then become unusable.

[asyncDispose]()

asyncDispose: Promise<void>;

Await resource cleanup for await using.

Returns

Promise<void>

The same cleanup promise as close.

Implementation of

AsyncDisposable.[asyncDispose]

CheckpointBundle

Transferable bytes and files captured at one quiescent simulation boundary.

Properties

Property	Modifier	Type	Description
`format`	`readonly`	`"swmmrs.checkpoint.bundle"`	Bundle format identifier.
`version`	`readonly`	`1`	Supported bundle format version.
`root`	`readonly`	`string`	Isolated solver root used for manifest paths; never use it as a host path.
`manifestPath`	`readonly`	`string`	Manifest path relative to `root`.
`manifest`	`readonly`	`Uint8Array`	Canonical core checkpoint JSON, untouched by the binding.
`files`	`readonly`	`Readonly`<`Record`<`string`, `Uint8Array`>>	Manifest sidecars and validated external dependencies, keyed relative to `root`.

ScenarioMethod

type ScenarioMethod = keyof ScenarioOperations;

Low-level scenario operation names; prefer the methods on Simulation for execution.

ScenarioArgs

type ScenarioArgs<K extends ScenarioMethod> = ScenarioOperations[K]["args"];

Argument tuple for a low-level scenario operation.

Type Parameters

Type Parameter	Description
`K` extends `ScenarioMethod`	Scenario operation name.

ScenarioResult

type ScenarioResult<K extends ScenarioMethod> = ScenarioOperations[K]["result"];

Resolved result type for a low-level scenario operation.

Type Parameters

Type Parameter	Description
`K` extends `ScenarioMethod`	Scenario operation name.

runSwmm()

function runSwmm(
   input: FileContents, 
   files?: Readonly<Record<string, FileContents>>, 
   options?: SimulationOptions & RunOptions
): Promise<RunResults>;

Open, run, finalize, and close one INP model. Also exported as the package default.

Parameters

Parameter	Type	Description
`input`	`FileContents`	INP contents, never a host path.
`files`	`Readonly`<`Record`<`string`, `FileContents`>>	Supporting-file contents keyed by INP-relative paths; defaults to an empty record.
`options`	`SimulationOptions` & `RunOptions`	Worker and run options; retained results by default.

Returns

Promise<RunResults>

Finalized report and caller-owned binary output after cleanup.

Throws

Preserves the run error if cleanup also fails, attaching the secondary failure as cleanupError.