Skip to content

Subcatchment

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

LID units

LID usage and layer contracts have their own LID reference. See Configure specialized definitions for an example.

Subcatchment

Subcatchment handle owned by one Simulation. Worker reads return detached values; use configure only in open or ended.

Properties

id

readonly id: string;

Canonical configured subcatchment ID.

lidUnits

readonly lidUnits: LidUnitCollection;

Asynchronously indexed LID usages belonging to this subcatchment.

Methods

results()

results(): Promise<SubcatchmentResults>;

Read current runoff results in running, complete, or ended.

Returns

Promise<SubcatchmentResults>

Detached result record in project units.

lidSnapshot()

lidSnapshot(): Promise<SubcatchmentLidSnapshot>;

Read aggregate LID-group results in running or complete, before end().

Returns

Promise<SubcatchmentLidSnapshot>

Detached aggregate LID results.

Throws

A solver error when this subcatchment has no LID group.

configuration()

configuration(): Promise<SubcatchmentConfiguration>;

Read declarations in any healthy owner state.

Returns

Promise<SubcatchmentConfiguration>

Detached configuration with canonical relationship IDs.

configure()

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

Atomically update declarations in open or ended; preparation-sensitive edits return the owner to open.

Parameters
Parameter Type Description
patch SubcatchmentPatch Sparse project-unit declarations. Null removes optional relationships; supplied buildup/coverage maps replace those complete maps.
Returns

Promise<void>

Resolves after all supplied fields are accepted; rejected patches apply no fields.

precipitationScaleFactors()

precipitationScaleFactors(): Promise<SubcatchmentPrecipitationScaleFactors>;

Read persistent precipitation multipliers in a healthy owner state.

Returns

Promise<SubcatchmentPrecipitationScaleFactors>

Dimensionless rainfall and snowfall factors.

rainScaleFactor()

rainScaleFactor(): Promise<number>;

Read the persistent dimensionless rainfall multiplier; initially 1.

Returns

Promise<number>

snowScaleFactor()

snowScaleFactor(): Promise<number>;

Read the persistent dimensionless snowfall multiplier; initially 1.

Returns

Promise<number>

setPrecipitationScaleFactors()

setPrecipitationScaleFactors(rainfall: number, snowfall: number): Promise<void>;

Replace persistent precipitation multipliers in open, running, or ended.

Parameters
Parameter Type Description
rainfall number Finite nonnegative rainfall multiplier.
snowfall number Finite nonnegative snowfall multiplier.
Returns

Promise<void>

Resolves after both values are accepted; values persist until replaced.

externalForcing()

externalForcing(): Promise<SubcatchmentExternalForcing>;

Read persistent external rainfall/snowfall additions in a healthy owner state.

Returns

Promise<SubcatchmentExternalForcing>

Rates in in/h or mm/h, initially zero.

externalRainfall()

externalRainfall(): Promise<number>;

Read the persistent external rainfall addition in in/h or mm/h.

Returns

Promise<number>

setExternalRainfall()

setExternalRainfall(value: number): Promise<void>;

Replace the persistent rainfall addition in open, running, or ended.

Parameters
Parameter Type Description
value number Finite nonnegative rate in in/h or mm/h; zero clears the addition.
Returns

Promise<void>

externalSnowfall()

externalSnowfall(): Promise<number>;

Read the persistent external snowfall addition in in/h or mm/h.

Returns

Promise<number>

setExternalSnowfall()

setExternalSnowfall(value: number): Promise<void>;

Replace the persistent snowfall addition in open, running, or ended.

Parameters
Parameter Type Description
value number Finite nonnegative rate in in/h or mm/h; zero clears the addition.
Returns

Promise<void>

quality()

quality(): Promise<SubcatchmentQuality>;

Read pollutant-aligned quality results in running, complete, or ended.

Returns

Promise<SubcatchmentQuality>

Detached concentrations and loads in configured pollutant units.

runoffPollutantConcentration()

runoffPollutantConcentration(): Promise<Readonly<Record<string, number>>>;

Read runoff concentrations keyed by pollutant ID in running, complete, or ended; values use configured concentration units.

Returns

Promise<Readonly<Record<string, number>>>

pondedPollutantConcentration()

pondedPollutantConcentration(): Promise<Readonly<Record<string, number>>>;

Read ponded-water concentrations keyed by pollutant ID in running, complete, or ended; values use configured concentration units.

Returns

Promise<Readonly<Record<string, number>>>

pollutantBuildup()

pollutantBuildup(): Promise<Readonly<Record<string, number>>>;

Read current buildup keyed by pollutant ID in running, complete, or ended; values use configured pollutant load units.

Returns

Promise<Readonly<Record<string, number>>>

pollutantTotalLoad()

pollutantTotalLoad(): Promise<Readonly<Record<string, number>>>;

Read cumulative washoff keyed by pollutant ID in running, complete, or ended; values use configured pollutant load units.

Returns

Promise<Readonly<Record<string, number>>>

namedSettings()

namedSettings(kind: SubcatchmentNamedSettingsKind): Promise<Readonly<Record<string, number>>>;

Read configured loading or coverage in a healthy owner state.

Parameters
Parameter Type Description
kind SubcatchmentNamedSettingsKind loading for pollutant buildup; coverage for land-use fractions.
Returns

Promise<Readonly<Record<string, number>>>

Detached canonical-ID map in pollutant load units or area fractions, respectively.

namedSetting()

namedSetting(kind: SubcatchmentNamedSettingsKind, name: string): Promise<number>;

Read one named declaration in a healthy owner state.

Parameters
Parameter Type Description
kind SubcatchmentNamedSettingsKind Loading or coverage selector.
name string Configured pollutant ID or land-use ID, respectively.
Returns

Promise<number>

Initial load or coverage fraction for the selected definition.

updateNamedSettings()

updateNamedSettings(
   kind: SubcatchmentNamedSettingsKind, 
   values: SubcatchmentNamedValues, 
   replace?: boolean
): Promise<void>;

Atomically update loading or coverage in open or ended; accepted declaration edits return the owner to open.

Parameters
Parameter Type Default value Description
kind SubcatchmentNamedSettingsKind undefined Loading or coverage selector.
values SubcatchmentNamedValues undefined Configured pollutant-ID/load or land-use-ID/fraction map.
replace boolean false False by default merges supplied entries; true clears omitted entries to zero.
Returns

Promise<void>

Resolves after the update is accepted.

clearNamedSettings()

clearNamedSettings(kind: SubcatchmentNamedSettingsKind): Promise<void>;

Clear every entry in one named declaration family in open or ended.

Parameters
Parameter Type Description
kind SubcatchmentNamedSettingsKind Loading or coverage selector.
Returns

Promise<void>

initialBuildup()

initialBuildup(): Promise<Readonly<Record<string, number>>>;

Read configured initial buildup by pollutant ID in a healthy owner state; values use pollutant load units.

Returns

Promise<Readonly<Record<string, number>>>

updateInitialBuildup()

updateInitialBuildup(values: SubcatchmentNamedValues, replace?: boolean): Promise<void>;

Update configured initial buildup in open or ended.

Parameters
Parameter Type Default value Description
values SubcatchmentNamedValues undefined Canonical pollutant-ID map in configured load units.
replace boolean false False by default merges; true clears omitted pollutants to zero.
Returns

Promise<void>

clearInitialBuildup()

clearInitialBuildup(): Promise<void>;

Clear configured initial buildup in open or ended.

Returns

Promise<void>

coverageFractions()

coverageFractions(): Promise<Readonly<Record<string, number>>>;

Read configured land-use area fractions by ID in a healthy owner state.

Returns

Promise<Readonly<Record<string, number>>>

updateCoverageFractions()

updateCoverageFractions(values: SubcatchmentNamedValues, replace?: boolean): Promise<void>;

Update land-use coverage in open or ended.

Parameters
Parameter Type Default value Description
values SubcatchmentNamedValues undefined Canonical land-use-ID map of area fractions, not percentages.
replace boolean false False by default merges; true clears omitted land uses to zero.
Returns

Promise<void>

clearCoverageFractions()

clearCoverageFractions(): Promise<void>;

Clear all land-use coverage declarations in open or ended.

Returns

Promise<void>

externalPollutantBuildupIncrement()

externalPollutantBuildupIncrement(): Promise<Readonly<Record<string, number>>>;

Read persistent external buildup increments in open, running, or ended; values are loads applied on runoff updates, not concentrations.

Returns

Promise<Readonly<Record<string, number>>>

externalPollutantBuildupIncrementValue()

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

Read one persistent buildup increment in open, running, or ended.

Parameters
Parameter Type Description
pollutantId string Configured pollutant ID.
Returns

Promise<number>

External increment in that pollutant's load units.

updateExternalPollutantBuildupIncrement()

updateExternalPollutantBuildupIncrement(values: SubcatchmentPollutantValues, replace?: boolean): Promise<void>;

Update persistent buildup increments in open, running, or ended.

Parameters
Parameter Type Default value Description
values SubcatchmentPollutantValues undefined Configured pollutant-ID map of finite nonnegative increments in pollutant load units.
replace boolean false False by default merges; true clears omitted pollutants to zero.
Returns

Promise<void>

Resolves after the update; increments persist until explicitly replaced or cleared.

clearExternalPollutantBuildupIncrement()

clearExternalPollutantBuildupIncrement(): Promise<void>;

Clear all persistent buildup increments in open, running, or ended.

Returns

Promise<void>

statistics()

statistics(): Promise<SubcatchmentStatistics>;

Read cumulative statistics in running or complete, before end().

Returns

Promise<SubcatchmentStatistics>

Detached runoff statistics in project units.


SubcatchmentOutlet

Configured runoff destination.

Properties

Property Modifier Type Description
kind readonly OutKind Receiving node or subcatchment family.
id readonly string Canonical configured receiving ID.

HortonInfiltrationSettings

Horton infiltration declarations.

Properties

Property Modifier Type Description
kind readonly "horton" Infiltration-model discriminator.
initialRate readonly number Initial infiltration rate in in/h or mm/h.
minimumRate readonly number Minimum infiltration rate in in/h or mm/h.
decayCoefficient readonly number Decay coefficient in inverse hours.
dryingTimeDays readonly number Time to dry soil fully, in days.
maximumInfiltration readonly number | null Maximum cumulative infiltration in in or mm; null means no limit.

ModifiedHortonInfiltrationSettings

Modified Horton infiltration declarations.

Properties

Property Modifier Type Description
kind readonly "modified_horton" Infiltration-model discriminator.
initialRate readonly number Initial infiltration rate in in/h or mm/h.
minimumRate readonly number Minimum infiltration rate in in/h or mm/h.
decayCoefficient readonly number Decay coefficient in inverse hours.
dryingTimeDays readonly number Time to dry soil fully, in days.
maximumInfiltration readonly number | null Maximum cumulative infiltration in in or mm; null means no limit.

GreenAmptInfiltrationSettings

Green-Ampt infiltration declarations.

Properties

Property Modifier Type Description
kind readonly "green_ampt" Infiltration-model discriminator.
suctionHead readonly number Wetting-front suction head in in or mm.
hydraulicConductivity readonly number Saturated hydraulic conductivity in in/h or mm/h.
initialMoistureDeficit readonly number Initial moisture deficit fraction.

ModifiedGreenAmptInfiltrationSettings

Modified Green-Ampt infiltration declarations.

Properties

Property Modifier Type Description
kind readonly "modified_green_ampt" Infiltration-model discriminator.
suctionHead readonly number Wetting-front suction head in in or mm.
hydraulicConductivity readonly number Saturated hydraulic conductivity in in/h or mm/h.
initialMoistureDeficit readonly number Initial moisture deficit fraction.

CurveNumberInfiltrationSettings

Curve-number infiltration declarations.

Properties

Property Modifier Type Description
kind readonly "curve_number" Infiltration-model discriminator.
curveNumber readonly number Dimensionless runoff curve number.
dryingTimeDays readonly number Time to dry soil fully, in days.

SubcatchmentInfiltrationPatch

Sparse infiltration update. Supply fields appropriate to the selected model; incompatible fields are rejected.

Properties

Property Modifier Type Description
kind? readonly InfilKind Model selector; omission retains the configured model.
initialRate? readonly number Initial infiltration rate in in/h or mm/h.
minimumRate? readonly number Minimum infiltration rate in in/h or mm/h.
decayCoefficient? readonly number Decay coefficient in inverse hours.
dryingTimeDays? readonly number Time to dry soil fully, in days.
maximumInfiltration? readonly number | null Maximum cumulative infiltration in in or mm; null means no limit.
suctionHead? readonly number Wetting-front suction head in in or mm.
hydraulicConductivity? readonly number Saturated hydraulic conductivity in in/h or mm/h.
initialMoistureDeficit? readonly number Initial moisture deficit fraction.
curveNumber? readonly number Dimensionless runoff curve number.

SubcatchmentGroundwaterConfiguration

Detached groundwater declarations in project units.

Properties

Property Modifier Type Description
aquifer readonly string Canonical configured aquifer ID.
node readonly string Canonical receiving node ID.
surfaceElevation readonly number Surface elevation in ft or m.
groundwaterCoefficient readonly number Groundwater-flow equation coefficient in project units.
groundwaterExponent readonly number Groundwater-flow equation exponent.
surfaceCoefficient readonly number Surface-water equation coefficient in project units.
surfaceExponent readonly number Surface-water equation exponent.
interactionCoefficient readonly number Groundwater/surface-water interaction coefficient in project units.
fixedSurfaceDepth readonly number Fixed receiving-node surface depth in ft or m.
bottomElevation readonly number Aquifer bottom elevation in ft or m.
waterTableElevation readonly number Initial water-table elevation in ft or m.
upperMoisture readonly number Initial upper-zone moisture fraction.

SubcatchmentGroundwaterPatch

Sparse groundwater update; omission retains a field in an existing declaration.

Properties

Property Modifier Type Description
aquifer? readonly string Canonical configured aquifer ID.
node? readonly string Canonical receiving node ID.
surfaceElevation? readonly number Surface elevation in ft or m.
groundwaterCoefficient? readonly number Groundwater-flow equation coefficient in project units.
groundwaterExponent? readonly number Groundwater-flow equation exponent.
surfaceCoefficient? readonly number Surface-water equation coefficient in project units.
surfaceExponent? readonly number Surface-water equation exponent.
interactionCoefficient? readonly number Groundwater/surface-water interaction coefficient in project units.
fixedSurfaceDepth? readonly number Fixed receiving-node surface depth in ft or m.
bottomElevation? readonly number Aquifer bottom elevation in ft or m.
waterTableElevation? readonly number Initial water-table elevation in ft or m.
upperMoisture? readonly number Initial upper-zone moisture fraction.

SubcatchmentPatch

Atomic sparse configuration update; omitted fields retain their declarations.

Properties

Property Modifier Type Description
tag? readonly string User tag; an empty string clears it.
area? readonly number Drainage area in acres for US projects or hectares for SI projects.
imperviousFraction? readonly number Impervious area fraction, 0–1.
zeroImperviousFraction? readonly number Fraction of impervious area without depression storage, 0–1.
width? readonly number Characteristic runoff width in ft or m.
slope? readonly number Surface slope as a fraction, not percent.
imperviousRoughness? readonly number Impervious Manning roughness coefficient.
perviousRoughness? readonly number Pervious Manning roughness coefficient.
imperviousDepressionStorage? readonly number Impervious depression storage in in or mm.
perviousDepressionStorage? readonly number Pervious depression storage in in or mm.
curbLength? readonly number Curb length in ft or m.
includedInReport? readonly boolean Whether this subcatchment is selected for reporting.
rainGage? readonly string Canonical configured rain-gage ID.
outlet? readonly SubcatchmentOutlet Canonical runoff destination.
infiltration? readonly SubcatchmentInfiltrationPatch Sparse infiltration parameters matching the selected model.
groundwater? readonly SubcatchmentGroundwaterPatch | null Omit to preserve; null removes the groundwater declaration.
snowpack? readonly string | null Omit to preserve; null removes the snowpack relationship.
initialBuildup? readonly Readonly<Record<string, number>> Replace the complete configured pollutant buildup map.
coverageFractions? readonly Readonly<Record<string, number>> Replace the complete configured land-use coverage map.

SubcatchmentConfiguration

Detached subcatchment declarations; runtime precipitation scales are also exposed for inspection.

Properties

Property Modifier Type Description
tag readonly string User tag; an empty string clears it.
rainScaleFactor readonly number Dimensionless rainfall multiplier; edited through setPrecipitationScaleFactors.
snowScaleFactor readonly number Dimensionless snowfall multiplier; edited through setPrecipitationScaleFactors.
area readonly number Drainage area in acres for US projects or hectares for SI projects.
rainGage readonly string Canonical configured rain-gage ID.
includedInReport readonly boolean Whether this subcatchment is selected for reporting.
width readonly number Characteristic runoff width in ft or m.
slope readonly number Surface slope as a fraction, not percent.
curbLength readonly number Curb length in ft or m.
imperviousFraction readonly number Impervious area fraction, 0–1.
zeroImperviousFraction readonly number Fraction of impervious area without depression storage, 0–1.
imperviousRoughness readonly number Impervious Manning roughness coefficient.
perviousRoughness readonly number Pervious Manning roughness coefficient.
imperviousDepressionStorage readonly number Impervious depression storage in in or mm.
perviousDepressionStorage readonly number Pervious depression storage in in or mm.
outlet readonly SubcatchmentOutlet Canonical runoff destination.
infiltration readonly | SubcatchmentInfiltrationConfiguration | null Model-specific infiltration declarations, or null when absent.
groundwater readonly | SubcatchmentGroundwaterConfiguration | null Groundwater declarations, or null when absent.
snowpack readonly string | null Canonical snowmelt parameter-set ID, or null.
initialBuildup readonly Readonly<Record<string, number>> Configured pollutant-ID map of initial buildup in pollutant load units.
coverageFractions readonly Readonly<Record<string, number>> Configured land-use-ID map of area fractions, 0–1.

SubcatchmentQuality

Detached pollutant results; all arrays follow pollutantIds.

Properties

Property Modifier Type Description
pollutantIds readonly readonly string[] Canonical pollutant IDs in configured order.
runoffConcentrations readonly readonly number[] Runoff concentrations in each pollutant's configured concentration units.
pondedConcentrations readonly readonly number[] Ponded-water concentrations in configured concentration units.
buildupLoads readonly readonly number[] Current buildup in each pollutant's load units.
totalWashoffLoads readonly readonly number[] Cumulative washoff in each pollutant's load units.

SubcatchmentQualitySnapshot

Detached pollutant-major matrices: outer rows follow pollutantIds, inner columns follow objectIds.

Properties

Property Modifier Type Description
objectIds readonly readonly string[] Selected canonical subcatchment IDs in requested order.
pollutantIds readonly readonly string[] Canonical pollutant IDs in configured order.
runoffConcentrations readonly readonly (readonly number[])[] Runoff concentrations in configured pollutant concentration units.
pondedConcentrations readonly readonly (readonly number[])[] Ponded concentrations in configured pollutant concentration units.
buildupLoads readonly readonly (readonly number[])[] Current buildup in configured pollutant load units.
totalWashoffLoads readonly readonly (readonly number[])[] Cumulative washoff in configured pollutant load units.

SubcatchmentStatistics

Detached cumulative runoff statistics, available before end().

Properties

Property Modifier Type Description
precipitation readonly number Total precipitation depth in in or mm.
runonVolume readonly number Total runon volume in ft³ or m³.
evaporationVolume readonly number Total evaporated volume in ft³ or m³.
infiltrationVolume readonly number Total infiltrated volume in ft³ or m³.
runoffVolume readonly number Total runoff volume in ft³ or m³.
maximumRunoff readonly number Maximum runoff rate in project flow units.
imperviousRunoffVolume readonly number Impervious runoff volume in ft³ or m³.
perviousRunoffVolume readonly number Pervious runoff volume in ft³ or m³.

SubcatchmentStatisticsSnapshot

Detached statistics arrays, all aligned to objectIds.

Properties

Property Modifier Type Description
objectIds readonly readonly string[] Selected canonical subcatchment IDs in requested order.
precipitation readonly readonly number[] Total precipitation depth in in or mm.
runonVolume readonly readonly number[] Total runon volume in ft³ or m³.
evaporationVolume readonly readonly number[] Total evaporated volume in ft³ or m³.
infiltrationVolume readonly readonly number[] Total infiltrated volume in ft³ or m³.
runoffVolume readonly readonly number[] Total runoff volume in ft³ or m³.
maximumRunoff readonly readonly number[] Maximum runoff rate in project flow units.
imperviousRunoffVolume readonly readonly number[] Impervious runoff volume in ft³ or m³.
perviousRunoffVolume readonly readonly number[] Pervious runoff volume in ft³ or m³.

SubcatchmentPrecipitationScaleFactors

Persistent dimensionless precipitation multipliers; both initially default to 1.

Properties

Property Modifier Type Description
rainfall readonly number Rainfall multiplier.
snowfall readonly number Snowfall multiplier.

SubcatchmentExternalForcing

Persistent external precipitation additions in in/h or mm/h; initially zero.

Properties

Property Modifier Type Description
rainfall readonly number External rainfall rate.
snowfall readonly number External snowfall rate.

SubcatchmentResults

Detached current subcatchment runoff values, available while results exist.

Properties

Property Modifier Type Description
rainfall readonly number Rainfall rate in in/h or mm/h.
evaporation readonly number Evaporation rate in in/day or mm/day.
infiltration readonly number Infiltration rate in in/h or mm/h.
runon readonly number Runon in project flow units.
runoff readonly number Runoff in project flow units.
snowDepth readonly number Snow depth in inches or millimetres.

SubcatchmentInfiltrationConfiguration

type SubcatchmentInfiltrationConfiguration = 
  | HortonInfiltrationSettings
  | ModifiedHortonInfiltrationSettings
  | GreenAmptInfiltrationSettings
  | ModifiedGreenAmptInfiltrationSettings
  | CurveNumberInfiltrationSettings;

Detached infiltration declarations, narrowed by kind.


SubcatchmentNamedSettingsKind

type SubcatchmentNamedSettingsKind = "loading" | "coverage";

Select initial pollutant buildup (loading) or land-use area fractions (coverage).


SubcatchmentNamedValues

type SubcatchmentNamedValues = Readonly<Record<string, number>>;

Canonical pollutant-ID/load or land-use-ID/fraction map, as selected by the operation.


SubcatchmentPollutantValues

type SubcatchmentPollutantValues = Readonly<Record<string, number>>;

Canonical pollutant-ID map; values use the operation's concentration or load units.