Skip to content

Link

Source-generated reference for link configuration, controls, results, and statistics. See Configure a model, Runtime forcings, and Collect results for workflows.

Owner-bound link from simulation.links.get(id). No public subtype subclasses. Reads are detached; configuration is available in healthy states. Wrong-kind operations reject without changing the model. Statistics require an active run.

Properties

id

readonly id: string;

Canonical configured link ID.

Methods

results()

results(): Promise<LinkResults>;

Read hydraulics in running, complete, or ended.

Returns

Promise<LinkResults>

Detached current link results.

configuration()

configuration(): Promise<LinkConfiguration>;

Read common and kind-specific declarations in any healthy owner state.

Returns

Promise<LinkConfiguration>

Detached configuration, including cross-section and optional inlet.

configure()

configure(patch: LinkPatch): Promise<void>;

Atomically update declarations in open or ended; accepted writes return ended to open.

Parameters
Parameter Type Description
patch LinkPatch Sparse common/subtype fields; invalid fields or a wrong-kind subtype reject the whole patch.
Returns

Promise<void>

Resolves after all fields are accepted.

setTargetSetting()

setTargetSetting(setting: number): Promise<void>;

Change the target opening or pump speed in running; native control rules may change it later.

Parameters
Parameter Type Description
setting number Finite dimensionless factor. Non-pumps clamp to [0, 1]; pumps clamp at zero and may exceed one.
Returns

Promise<void>

Resolves after setting the target.

setFlowLimit()

setFlowLimit(flowLimit: number): Promise<void>;

Set a persistent flow limit in open, running, or ended.

Parameters
Parameter Type Description
flowLimit number Limit in project flow units.
Returns

Promise<void>

Resolves after the forcing is updated.

quality()

quality(): Promise<LinkQuality>;

Read quality in running, complete, or ended.

Returns

Promise<LinkQuality>

Detached pollutant-aligned concentrations and transported loads.

overridePollutantConcentrations()

overridePollutantConcentrations(values: Record<string, number>): Promise<void>;

Queue sparse overrides for the next quality step in running; they expire after that step.

Parameters
Parameter Type Description
values Record<string, number> Pollutant-ID concentration map in configured concentration units.
Returns

Promise<void>

Resolves after valid IDs and concentrations are queued.

externalPollutantMassFlux()

externalPollutantMassFlux(): Promise<Record<string, number>>;

Read persistent pollutant mass fluxes in open, running, or ended.

Returns

Promise<Record<string, number>>

Pollutant-ID map in configured mass-flux units.

externalPollutantMassFluxValue()

externalPollutantMassFluxValue(pollutantId: string): Promise<number>;

Read one persistent mass flux in open, running, or ended.

Parameters
Parameter Type Description
pollutantId string Configured pollutant ID.
Returns

Promise<number>

Value in configured pollutant mass-flux units; unknown IDs reject.

updateExternalPollutantMassFlux()

updateExternalPollutantMassFlux(values: Record<string, number>, replace?: boolean): Promise<void>;

Update persistent mass fluxes in open, running, or ended. Nonzero flux requires a non-dummy conduit; other kinds accept only an all-zero clear.

Parameters
Parameter Type Default value Description
values Record<string, number> undefined Pollutant-ID map in configured mass-flux units.
replace boolean false Defaults to false: merge. True replaces the whole map, resetting omitted IDs to zero.
Returns

Promise<void>

Resolves after the atomic update.

statistics()

statistics(): Promise<LinkStatistics>;

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

Returns

Promise<LinkStatistics>

Detached link statistics.

pumpStatistics()

pumpStatistics(): Promise<PumpStatistics>;

Read pump-only cumulative statistics in running or complete.

Returns

Promise<PumpStatistics>

Detached pump statistics; non-pump calls reject.

inlet()

inlet(): Promise<InletConfiguration | null>;

Read the inlet placement in any healthy owner state.

Returns

Promise<InletConfiguration | null>

Detached inlet configuration, or null when absent.

inletResults()

inletResults(): Promise<InletResults | null>;

Read inlet results in running, complete, or ended.

Returns

Promise<InletResults | null>

Detached current inlet values, or null when no inlet is configured.

updateInlet()

updateInlet(patch: InletPatch): Promise<void>;

Update persistent inlet controls in open, running, or ended.

Parameters
Parameter Type Description
patch InletPatch Sparse clogging percentage and/or flow limit; omission retains a value.
Returns

Promise<void>

Resolves after the update is accepted.

FunctionalOutletRating

Power-law outlet rating in native project head/flow units.

Properties

Property Modifier Type Description
kind readonly "functional" Power-law rating discriminator.
coefficient readonly number Discharge coefficient in the rating's native units.
exponent readonly number Head/depth exponent.
headBasis readonly OutletHeadBasis Whether the rating uses depth or head difference.

TabularOutletRating

Curve-based outlet rating using a configured curve identity.

Properties

Property Modifier Type Description
kind readonly "tabular" Curve-based rating discriminator.
curve readonly string Canonical rating-curve ID.
headBasis readonly OutletHeadBasis Whether the rating uses depth or head difference.

CircularCrossSection

Circular conduit section.

Properties

Property Modifier Type Description
kind readonly "circular" Circular section discriminator.
diameter readonly number Diameter in project length units (ft or m).

StandardCrossSection

Standard SWMM section; geometry interpretation depends on the shape.

Properties

Property Modifier Type Description
kind readonly "standard" Standard section discriminator.
shape readonly StandardCrossSectionShape Native standard shape name.
geometry readonly readonly [number, number, number, number] Four native geometry parameters; dimensional entries use project length units.
culvertCode readonly number Native culvert inlet-control code.

CustomCrossSection

Custom section backed by a configured shape.

Properties

Property Modifier Type Description
kind readonly "custom" Custom section discriminator.
shape readonly string Canonical custom-shape ID.
fullDepth readonly number Full depth in project length units.
culvertCode readonly number Native culvert inlet-control code.

IrregularCrossSection

Irregular section backed by a configured transect.

Properties

Property Modifier Type Description
kind readonly "irregular" Irregular section discriminator.
transect readonly string Canonical transect ID.
culvertCode readonly number Native culvert inlet-control code.

StreetCrossSection

Street section backed by a configured street definition.

Properties

Property Modifier Type Description
kind readonly "street" Street section discriminator.
street readonly string Canonical street ID.
culvertCode readonly number Native culvert inlet-control code.

InletConfiguration

Detached inlet placement; link.inlet() returns null when none is configured.

Properties

Property Modifier Type Description
count readonly number Number of inlet units.
percentClogged readonly number Clogging percentage.
flowLimit readonly number Inlet flow limit in project flow units.
localDepression readonly number Local depression in project length units.
localWidth readonly number Local width in project length units.
design readonly string Canonical inlet-design ID.

InletPatch

Sparse persistent inlet-control update; omission retains a value.

Properties

Property Modifier Type Description
percentClogged? readonly number Clogging percentage.
flowLimit? readonly number Inlet flow limit in project flow units.

InletResults

Detached current inlet results.

Properties

Property Modifier Type Description
flowFactor readonly number Dimensionless inlet flow factor.
capturedFlow readonly number Captured flow in project flow units.
backflow readonly number Backflow in project flow units.
backflowRatio readonly number Dimensionless backflow ratio.

ConduitConfiguration

Conduit-specific declarations.

Properties

Property Modifier Type Description
kind readonly "conduit" Conduit subtype discriminator.
length readonly number Conduit length in ft or m.
roughness readonly number Conduit roughness in native solver units.
barrels readonly number Number of parallel barrels.
crossSection readonly CrossSection | null Cross-section declaration, or null.

PumpConfiguration

Pump-specific declarations.

Properties

Property Modifier Type Description
kind readonly "pump" Pump subtype discriminator.
curve readonly string | null Canonical pump-curve ID, or null for ideal operation.
initialSetting readonly number Initial dimensionless pump setting.
startupDepth readonly number Startup depth in ft or m.
shutoffDepth readonly number Shutoff depth in ft or m.

OrificeConfiguration

Orifice-specific declarations.

Properties

Property Modifier Type Description
kind readonly "orifice" Orifice subtype discriminator.
orificeKind readonly OrificeKind Side or bottom opening.
dischargeCoefficient readonly number Native orifice discharge coefficient.
openingTimeHours readonly number Full opening time in hours.

WeirConfiguration

Weir-specific declarations.

Properties

Property Modifier Type Description
kind readonly "weir" Weir subtype discriminator.
weirKind readonly WeirKind Weir geometry.
dischargeCoefficient readonly number Native weir discharge coefficient.
endDischargeCoefficient readonly number Native end-discharge coefficient.
endContractions readonly number Number of end contractions.
canSurcharge readonly boolean Whether the weir may surcharge.
roadwayWidth readonly number Roadway width in ft or m.
roadwaySurface readonly RoadSurface Roadway surface classification.
coefficientCurve readonly string | null Canonical coefficient-curve ID, or null.

OutletConfiguration

Outlet-specific declarations.

Properties

Property Modifier Type Description
kind readonly "outlet" Outlet subtype discriminator.
rating readonly OutletRating Functional or tabular rating.

LinkConfiguration

Detached read-only common, subtype, cross-section, and inlet declarations.

Properties

Property Modifier Type Description
kind readonly LinkKind Configured link family.
tag readonly string Object tag.
inletNode readonly string Canonical configured inlet-node ID.
outletNode readonly string Canonical configured outlet-node ID.
flowDirection readonly number Solver direction relative to configured orientation.
length readonly number | null Conduit length in ft or m; null for other kinds.
slope readonly number | null Conduit slope ratio; null for other kinds.
fullDepth readonly number Full hydraulic depth in ft or m.
fullFlow readonly number Full-flow capacity in project flow units.
includedInReport readonly boolean Selection for detailed reporting.
inletOffset readonly number Inlet offset in project length units.
outletOffset readonly number Outlet offset in project length units.
initialFlow readonly number Initial flow in project flow units.
flowLimit readonly number Persistent flow limit in project flow units; set with Link.setFlowLimit.
inletLossCoefficient readonly number Dimensionless inlet loss coefficient.
outletLossCoefficient readonly number Dimensionless outlet loss coefficient.
averageLossCoefficient readonly number Dimensionless average loss coefficient.
seepageRate readonly number Seepage rate in in/h or mm/h.
hasFlapGate readonly boolean Flap-gate flag.
subtype readonly LinkSubtypeConfiguration Kind-tagged subtype record.
crossSection readonly CrossSection | null Convenience alias for conduit declarations; null for other link families.
inlet readonly InletConfiguration | null Inlet placement, or null when absent.

ConduitPatch

Sparse conduit update; omitted fields retain their values.

Properties

Property Modifier Type Description
length? readonly number Conduit length in ft or m.
roughness? readonly number Conduit roughness in native solver units.
barrels? readonly number Number of parallel barrels.

PumpPatch

Sparse pump update; omission retains a field.

Properties

Property Modifier Type Description
curve? readonly string | null Omit to preserve; null switches to ideal operation.
initialSetting? readonly number Initial dimensionless pump setting.
startupDepth? readonly number Startup depth in ft or m.
shutoffDepth? readonly number Shutoff depth in ft or m.

OrificePatch

Sparse orifice update; omission retains a field.

Properties

Property Modifier Type Description
orificeKind? readonly OrificeKind Side or bottom opening.
dischargeCoefficient? readonly number Native orifice discharge coefficient.
openingTimeHours? readonly number Full opening time in hours.

WeirPatch

Sparse weir update; omission retains a field.

Properties

Property Modifier Type Description
weirKind? readonly WeirKind Weir geometry.
dischargeCoefficient? readonly number Native weir discharge coefficient.
endDischargeCoefficient? readonly number Native end-discharge coefficient.
endContractions? readonly number Number of end contractions.
canSurcharge? readonly boolean Whether the weir may surcharge.
roadwayWidth? readonly number Roadway width in ft or m.
roadwaySurface? readonly RoadSurface Roadway surface classification.
coefficientCurve? readonly string | null Omit to preserve; null clears the optional coefficient curve.

OutletPatch

Sparse outlet update; omission retains its rating.

Properties

Property Modifier Type Description
rating? readonly OutletRatingPatch Replacement rating declaration.

LinkPatch

Sparse atomic link declaration update. Omitted fields retain their values; derived fields are not writable.

Properties

Property Modifier Type Description
tag? readonly string Object tag.
inletNode? readonly string Canonical configured inlet-node ID.
outletNode? readonly string Canonical configured outlet-node ID.
inletOffset? readonly number Inlet offset in project length units.
outletOffset? readonly number Outlet offset in project length units.
includedInReport? readonly boolean Selection for detailed reporting.
initialFlow? readonly number Initial flow in project flow units.
inletLossCoefficient? readonly number Dimensionless inlet loss coefficient.
outletLossCoefficient? readonly number Dimensionless outlet loss coefficient.
averageLossCoefficient? readonly number Dimensionless average loss coefficient.
seepageRate? readonly number Seepage rate in in/h or mm/h.
hasFlapGate? readonly boolean Flap-gate flag.
crossSection? readonly CrossSectionPatch Replacement conduit cross-section.
subtype? readonly LinkSubtypePatch Sparse kind-tagged subtype update; cannot change link family.

LinkQuality

Detached quality arrays in pollutant-ID order, using configured concentration/load units.

Properties

Property Modifier Type Description
pollutantIds readonly readonly string[] Canonical pollutant IDs defining array order.
concentrations readonly readonly number[] Current link concentrations.
reactorConcentrations readonly readonly number[] Current reactor concentrations.
totalLoads readonly readonly number[] Cumulative transported pollutant loads.

LinkQualitySnapshot

Detached pollutant-major quality matrices: [pollutantIndex][objectIndex], in configured units.

Properties

Property Modifier Type Description
objectIds readonly readonly string[] Canonical link IDs defining inner-row order.
pollutantIds readonly readonly string[] Canonical pollutant IDs defining outer-row order.
concentrations readonly readonly (readonly number[])[] Pollutant-major matrices; each inner row follows objectIds.
reactorConcentrations readonly readonly (readonly number[])[] Reactor concentrations in configured concentration units.
totalLoads readonly readonly (readonly number[])[] Transported loads in configured pollutant load units.

LinkStatistics

Detached cumulative link statistics for the current run.

Properties

Property Modifier Type Description
maximumFlow readonly number Maximum flow in project flow units.
maximumFlowTime readonly string Timezone-free ModelTime string of maximum flow.
maximumVelocity readonly number Maximum velocity in ft/s or m/s.
maximumDepth readonly number Maximum depth in ft or m.
maximumStreetFillFraction readonly number | null Maximum street fill fraction; null without a street section.
timeNormalFlowSeconds readonly number Normal-flow duration in seconds.
timeInletControlSeconds readonly number Inlet-control duration in seconds.
timeSurchargedSeconds readonly number Surcharge duration in seconds.
timeFullUpstreamSeconds readonly number Duration full at the upstream end, in seconds.
timeFullDownstreamSeconds readonly number Duration full at the downstream end, in seconds.
timeFullFlowSeconds readonly number Full-flow duration in seconds.
timeCapacityLimitedSeconds readonly number Capacity-limited duration in seconds.
timeInFlowClassSeconds readonly readonly number[] Seven seconds-valued durations: dry, upstream dry, downstream dry, subcritical, supercritical, upstream critical, downstream critical.
timeCourantCriticalSeconds readonly number Courant-critical duration in seconds.
flowTurns readonly number Flow-reversal count.
flowTurnSign readonly number Flow-reversal sign.

PumpStatistics

Detached pump-only cumulative statistics.

Properties

Property Modifier Type Description
timeUtilizedSeconds readonly number Pump utilization time in seconds.
minimumFlow readonly number Minimum pumped flow in project flow units.
averageFlow readonly number Average pumped flow in project flow units.
maximumFlow readonly number Maximum pumped flow in project flow units.
pumpedVolume readonly number Pumped volume in project volume units.
energyConsumed readonly number Energy consumed in native pump-report energy units.
offCurveLowSeconds readonly number Time below the pump curve in seconds.
offCurveHighSeconds readonly number Time above the pump curve in seconds.
startupCount readonly number Number of pump startups.
periodCount readonly number Number of statistical observation periods.

LinkStatisticsSnapshot

Detached cumulative columns in object-ID order; units match LinkStatistics.

Properties

Property Modifier Type Description
objectIds readonly readonly string[] Canonical link IDs in requested order.
maximumFlow readonly readonly number[] Maximum flow in project flow units.
maximumFlowTime readonly readonly string[] Timezone-free ModelTime string of maximum flow.
maximumVelocity readonly readonly number[] Maximum velocity in ft/s or m/s.
maximumDepth readonly readonly number[] Maximum depth in ft or m.
maximumStreetFillFraction readonly readonly (number | null)[] Maximum street fill fraction; null without a street section.
timeNormalFlowSeconds readonly readonly number[] Normal-flow duration in seconds.
timeInletControlSeconds readonly readonly number[] Inlet-control duration in seconds.
timeSurchargedSeconds readonly readonly number[] Surcharge duration in seconds.
timeFullUpstreamSeconds readonly readonly number[] Duration full at the upstream end, in seconds.
timeFullDownstreamSeconds readonly readonly number[] Duration full at the downstream end, in seconds.
timeFullFlowSeconds readonly readonly number[] Full-flow duration in seconds.
timeCapacityLimitedSeconds readonly readonly number[] Capacity-limited duration in seconds.
timeInFlowClassSeconds readonly readonly (readonly number[])[] Object-major matrix: one row per link, seven durations in FlowClass order.
timeCourantCriticalSeconds readonly readonly number[] Courant-critical duration in seconds.
flowTurns readonly readonly number[] Flow-reversal count.
flowTurnSign readonly readonly number[] Flow-reversal sign.

LinkResults

Detached current link hydraulics from link.results(), not a historical series.

Properties

Property Modifier Type Description
setting readonly number Current opening or pump-speed factor.
targetSetting readonly number Target opening or pump-speed factor; native control rules may change it.
timeOpenSeconds readonly number Open duration in seconds.
timeClosedSeconds readonly number Closed duration in seconds.
flow readonly number Signed flow in configured orientation, in project flow units.
depth readonly number Water depth in ft or m.
velocity readonly number Velocity magnitude in ft/s or m/s.
topWidth readonly number | null Conduit surface width in ft or m; null for other link kinds.
volume readonly number Stored water volume in ft³ or m³.
capacity readonly number Conduit capacity ratio, or non-conduit setting.
upstreamSurfaceArea readonly number Upstream surface area in ft² or m².
downstreamSurfaceArea readonly number Downstream surface area in ft² or m².
froudeNumber readonly number Dimensionless Froude number.

OutletRating

type OutletRating = 
  | FunctionalOutletRating
  | TabularOutletRating;

Functional or tabular outlet rating, discriminated by kind.

OutletRatingPatch

type OutletRatingPatch = 
  | {
  kind: "functional";
  coefficient: number;
  exponent: number;
  headBasis?: OutletHeadBasis;
}
  | {
  kind: "tabular";
  curve: string;
  headBasis?: OutletHeadBasis;
};

Replacement outlet rating; omitted head basis defaults to depth, not the previous declaration's value.

Union Members

Type Literal

{
  kind: "functional";
  coefficient: number;
  exponent: number;
  headBasis?: OutletHeadBasis;
}
kind
readonly kind: "functional";

Power-law rating discriminator.

coefficient
readonly coefficient: number;

Discharge coefficient in the rating's native units.

exponent
readonly exponent: number;

Head/depth exponent.

headBasis?
readonly optional headBasis?: OutletHeadBasis;

Depth or head-difference basis; defaults to depth.

Type Literal

{
  kind: "tabular";
  curve: string;
  headBasis?: OutletHeadBasis;
}
kind
readonly kind: "tabular";

Curve-based rating discriminator.

curve
readonly curve: string;

Canonical rating-curve ID.

headBasis?
readonly optional headBasis?: OutletHeadBasis;

Depth or head-difference basis; defaults to depth.

CrossSection

type CrossSection = 
  | CircularCrossSection
  | StandardCrossSection
  | CustomCrossSection
  | IrregularCrossSection
  | StreetCrossSection;

Detached conduit section selected by kind; absent sections are represented by null on the containing record.

CrossSectionPatch

type CrossSectionPatch = 
  | Omit<CircularCrossSection, "culvertCode">
  | Omit<StandardCrossSection, "culvertCode"> & object
  | Omit<CustomCrossSection, "culvertCode"> & object
  | Omit<IrregularCrossSection, "culvertCode"> & object
  | Omit<StreetCrossSection, "culvertCode"> & object;

Replacement cross-section declaration. Non-circular variants accept an optional culvert code.

LinkSubtypeConfiguration

type LinkSubtypeConfiguration = 
  | ConduitConfiguration
  | PumpConfiguration
  | OrificeConfiguration
  | WeirConfiguration
  | OutletConfiguration;

Kind-tagged link declarations; configuring a subtype cannot change the link's family.

LinkSubtypePatch

type LinkSubtypePatch = 
  | object & ConduitPatch
  | object & PumpPatch
  | object & OrificePatch
  | object & WeirPatch
  | object & OutletPatch;

Select the existing link family and patch only its writable subtype fields.