Low-impact development

Use unit.update(**changes) to edit a subcatchment's configured LidUnit properties together. Every optional LID-control layer also has update(**changes), and individual property assignments use the same atomic native operation. Invalid scalar values fail immediately. The next start() checks process, group, and subcatchment relationships together.

from swmmrs import Simulation

with Simulation("model.inp", "model.rpt") as simulation:
    unit = simulation.subcatchments["S-1"].lid_units[0]
    unit.update(
        area=500.0,
        full_width=25.0,
        initial_saturation=0.20,
        routes_to_pervious=True,
        drain_destination=simulation.nodes["J-1"],
    )

    control = unit.control
    surface = control.surface
    if surface is not None:
        surface.update(thickness=0.25, roughness=0.15, slope=0.01)
        surface.roughness = 0.20  # Scalar assignment uses the same update approach.

The solver handles reads, value conversion, relationship identity, allowed lifecycle states, and atomic updates. Derived layer values and runtime snapshots are read-only. Keeping a view of an optional layer does not keep the layer in existence: access raises StaleViewError while that layer is absent.

from swmmrs import Simulation, StaleViewError

with Simulation("model.inp", "model.rpt") as simulation:
    control = simulation.lid_controls["BIORETENTION"]
    soil = control.soil
    if soil is not None:  # Layers depend on the configured LID process.
        soil.update(porosity=0.45, field_capacity=0.20, wilting_point=0.10)

    try:
        if soil is not None:
            print(soil.thickness)
    except StaleViewError:
        # Reacquire the optional slot after configuration changes.
        soil = control.soil

Stable LID declarations are writable only while the simulation is Open or Ended; every LID write is rejected while Running. Requested routes_to_pervious and implicit drain intent remain visible while dirty, while prepared alpha, overflow, bottom width, and runtime snapshots continue to represent the last successful preparation or run.

from swmmrs import Simulation

with Simulation("model.inp", "model.rpt") as simulation:
    unit = simulation.subcatchments["S-1"].lid_units[0]
    unit.update(routes_to_pervious=True, drain_destination=None)
    assert unit.routes_to_pervious is True  # Requested intent is visible while dirty.

    simulation.start()
    surface = unit.control.surface
    if surface is not None:
        print(surface.alpha, surface.immediate_overflow)  # Prepared, read-only values.
    print(unit.bottom_width)  # Prepared unit geometry is also read-only.

    while simulation.step() is not None:
        runtime = unit.snapshot()  # Owned point-in-time runtime values.
        print(runtime)

    simulation.end()
    unit.area = 450.0  # Stable declarations are writable again in Ended.

Typed, generation-bound views over configured SWMM project objects.

All view instances retain the simulation and project generation that created them. They validate that identity before accessing native state, so retained views cannot silently address a subsequently reopened project.

CLASS	DESCRIPTION
`LidControl`	Expose the configured layers of one generation-bound LID control.
`LidSurfaceLayer`	Expose one configured LID surface layer.
`LidSoilLayer`	Expose one configured LID soil layer.
`LidStorageLayer`	Expose one configured LID storage layer.
`LidPavementLayer`	Expose one configured LID pavement layer.
`LidDrainLayer`	Expose one configured LID drain layer.
`LidDrainageMatLayer`	Expose one configured LID drainage-mat layer.
`LidUnitCollection`	Provide indexed access to a subcatchment's LID units.
`LidUnit`	Expose one LID unit owned by a subcatchment.

LidControl


              flowchart TD
              swmmrs.objects.LidControl[LidControl]
              swmmrs.objects._base._LiveView[_LiveView]

                              swmmrs.objects._base._LiveView --> swmmrs.objects.LidControl
                


              click swmmrs.objects.LidControl href "" "swmmrs.objects.LidControl"
              click swmmrs.objects._base._LiveView href "" "swmmrs.objects._base._LiveView"

Expose the configured layers of one generation-bound LID control.

A layer property returns None when that layer is not part of the control's configured LID process.

ATTRIBUTE	DESCRIPTION
`drain`	Return the configured underdrain layer, if present. TYPE: `LidDrainLayer \| None`
`drainage_mat`	Return the configured drainage-mat layer, if present. TYPE: `LidDrainageMatLayer \| None`
`pavement`	Return the configured pavement layer, if present. TYPE: `LidPavementLayer \| None`
`soil`	Return the configured soil layer, if present. TYPE: `LidSoilLayer \| None`
`storage`	Return the configured storage layer, if present. TYPE: `LidStorageLayer \| None`
`surface`	Return the configured surface layer, if present. TYPE: `LidSurfaceLayer \| None`

drain `property`

drain: LidDrainLayer | None

Return the configured underdrain layer, if present.

drainage_mat `property`

drainage_mat: LidDrainageMatLayer | None

Return the configured drainage-mat layer, if present.

pavement `property`

pavement: LidPavementLayer | None

Return the configured pavement layer, if present.

soil `property`

soil: LidSoilLayer | None

Return the configured soil layer, if present.

storage `property`

storage: LidStorageLayer | None

Return the configured storage layer, if present.

surface `property`

surface: LidSurfaceLayer | None

Return the configured surface layer, if present.

LidSurfaceLayer


              flowchart TD
              swmmrs.objects.LidSurfaceLayer[LidSurfaceLayer]
              swmmrs.objects._lids._LidLayer[_LidLayer]

                              swmmrs.objects._lids._LidLayer --> swmmrs.objects.LidSurfaceLayer
                


              click swmmrs.objects.LidSurfaceLayer href "" "swmmrs.objects.LidSurfaceLayer"
              click swmmrs.objects._lids._LidLayer href "" "swmmrs.objects._lids._LidLayer"

Expose one configured LID surface layer.

METHOD	DESCRIPTION
`update`	Commit requested layer values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`alpha`	Return the derived surface runoff coefficient in project units. TYPE: `float`
`immediate_overflow`	Return whether ponded surface water overflows without delay. TYPE: `bool`
`roughness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`side_slope`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`slope`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`thickness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`vegetation_volume_fraction`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`

alpha `property`

alpha: float

Return the derived surface runoff coefficient in project units.

immediate_overflow `property`

immediate_overflow: bool

Return whether ponded surface water overflows without delay.

roughness `property` `writable`

roughness: float

Setter lifecycle: OPEN, ENDED.

side_slope `property` `writable`

side_slope: float

Setter lifecycle: OPEN, ENDED.

slope `property` `writable`

slope: float

Setter lifecycle: OPEN, ENDED.

thickness `property` `writable`

thickness: float

Setter lifecycle: OPEN, ENDED.

vegetation_volume_fraction `property` `writable`

vegetation_volume_fraction: float

Setter lifecycle: OPEN, ENDED.

update

update(**changes: object) -> None

Commit requested layer values atomically in OPEN or ENDED.

Intrinsic scalar errors fail immediately. Coupled layer, process, and LID-group relationships are validated during the next start().

LidSoilLayer


              flowchart TD
              swmmrs.objects.LidSoilLayer[LidSoilLayer]
              swmmrs.objects._lids._LidLayer[_LidLayer]

                              swmmrs.objects._lids._LidLayer --> swmmrs.objects.LidSoilLayer
                


              click swmmrs.objects.LidSoilLayer href "" "swmmrs.objects.LidSoilLayer"
              click swmmrs.objects._lids._LidLayer href "" "swmmrs.objects._lids._LidLayer"

Expose one configured LID soil layer.

METHOD	DESCRIPTION
`update`	Commit requested layer values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`conductivity_slope`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`field_capacity`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`porosity`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`saturated_conductivity`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`suction_head`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`thickness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`wilting_point`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`

conductivity_slope `property` `writable`

conductivity_slope: float

Setter lifecycle: OPEN, ENDED.

field_capacity `property` `writable`

field_capacity: float

Setter lifecycle: OPEN, ENDED.

porosity `property` `writable`

porosity: float

Setter lifecycle: OPEN, ENDED.

saturated_conductivity `property` `writable`

saturated_conductivity: float

Setter lifecycle: OPEN, ENDED.

suction_head `property` `writable`

suction_head: float

Setter lifecycle: OPEN, ENDED.

thickness `property` `writable`

thickness: float

Setter lifecycle: OPEN, ENDED.

wilting_point `property` `writable`

wilting_point: float

Setter lifecycle: OPEN, ENDED.

update

update(**changes: object) -> None

Commit requested layer values atomically in OPEN or ENDED.

Intrinsic scalar errors fail immediately. Coupled layer, process, and LID-group relationships are validated during the next start().

LidStorageLayer


              flowchart TD
              swmmrs.objects.LidStorageLayer[LidStorageLayer]
              swmmrs.objects._lids._LidLayer[_LidLayer]

                              swmmrs.objects._lids._LidLayer --> swmmrs.objects.LidStorageLayer
                


              click swmmrs.objects.LidStorageLayer href "" "swmmrs.objects.LidStorageLayer"
              click swmmrs.objects._lids._LidLayer href "" "swmmrs.objects._lids._LidLayer"

Expose one configured LID storage layer.

METHOD	DESCRIPTION
`update`	Commit requested layer values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`clogging_factor`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`saturated_conductivity`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`thickness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`void_ratio`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`

clogging_factor `property` `writable`

clogging_factor: float

Setter lifecycle: OPEN, ENDED.

saturated_conductivity `property` `writable`

saturated_conductivity: float

Setter lifecycle: OPEN, ENDED.

thickness `property` `writable`

thickness: float

Setter lifecycle: OPEN, ENDED.

void_ratio `property` `writable`

void_ratio: float

Setter lifecycle: OPEN, ENDED.

update

update(**changes: object) -> None

Commit requested layer values atomically in OPEN or ENDED.

Intrinsic scalar errors fail immediately. Coupled layer, process, and LID-group relationships are validated during the next start().

LidPavementLayer


              flowchart TD
              swmmrs.objects.LidPavementLayer[LidPavementLayer]
              swmmrs.objects._lids._LidLayer[_LidLayer]

                              swmmrs.objects._lids._LidLayer --> swmmrs.objects.LidPavementLayer
                


              click swmmrs.objects.LidPavementLayer href "" "swmmrs.objects.LidPavementLayer"
              click swmmrs.objects._lids._LidLayer href "" "swmmrs.objects._lids._LidLayer"

Expose one configured LID pavement layer.

METHOD	DESCRIPTION
`update`	Commit requested layer values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`clogging_factor`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`impervious_fraction`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`regeneration_fraction`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`regeneration_interval`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `timedelta`
`saturated_conductivity`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`thickness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`void_ratio`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`

clogging_factor `property` `writable`

clogging_factor: float

Setter lifecycle: OPEN, ENDED.

impervious_fraction `property` `writable`

impervious_fraction: float

Setter lifecycle: OPEN, ENDED.

regeneration_fraction `property` `writable`

regeneration_fraction: float

Setter lifecycle: OPEN, ENDED.

regeneration_interval `property` `writable`

regeneration_interval: timedelta

Setter lifecycle: OPEN, ENDED.

saturated_conductivity `property` `writable`

saturated_conductivity: float

Setter lifecycle: OPEN, ENDED.

thickness `property` `writable`

thickness: float

Setter lifecycle: OPEN, ENDED.

void_ratio `property` `writable`

void_ratio: float

Setter lifecycle: OPEN, ENDED.

update

update(**changes: object) -> None

Commit requested layer values atomically in OPEN or ENDED.

Intrinsic scalar errors fail immediately. Coupled layer, process, and LID-group relationships are validated during the next start().

LidDrainLayer


              flowchart TD
              swmmrs.objects.LidDrainLayer[LidDrainLayer]
              swmmrs.objects._lids._LidLayer[_LidLayer]

                              swmmrs.objects._lids._LidLayer --> swmmrs.objects.LidDrainLayer
                


              click swmmrs.objects.LidDrainLayer href "" "swmmrs.objects.LidDrainLayer"
              click swmmrs.objects._lids._LidLayer href "" "swmmrs.objects._lids._LidLayer"

Expose one configured LID drain layer.

METHOD	DESCRIPTION
`update`	Commit requested layer values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`close_head`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`coefficient`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`control_curve`	Return the configured underdrain control curve, if one is assigned. TYPE: `Curve \| None`
`delay`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `timedelta`
`exponent`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`offset`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`open_head`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`

close_head `property` `writable`

close_head: float

Setter lifecycle: OPEN, ENDED.

coefficient `property` `writable`

coefficient: float

Setter lifecycle: OPEN, ENDED.

control_curve `property`

control_curve: Curve | None

Return the configured underdrain control curve, if one is assigned.

delay `property` `writable`

delay: timedelta

Setter lifecycle: OPEN, ENDED.

exponent `property` `writable`

exponent: float

Setter lifecycle: OPEN, ENDED.

offset `property` `writable`

offset: float

Setter lifecycle: OPEN, ENDED.

open_head `property` `writable`

open_head: float

Setter lifecycle: OPEN, ENDED.

update

update(**changes: object) -> None

Commit requested layer values atomically in OPEN or ENDED.

Intrinsic scalar errors fail immediately. Coupled layer, process, and LID-group relationships are validated during the next start().

LidDrainageMatLayer


              flowchart TD
              swmmrs.objects.LidDrainageMatLayer[LidDrainageMatLayer]
              swmmrs.objects._lids._LidLayer[_LidLayer]

                              swmmrs.objects._lids._LidLayer --> swmmrs.objects.LidDrainageMatLayer
                


              click swmmrs.objects.LidDrainageMatLayer href "" "swmmrs.objects.LidDrainageMatLayer"
              click swmmrs.objects._lids._LidLayer href "" "swmmrs.objects._lids._LidLayer"

Expose one configured LID drainage-mat layer.

METHOD	DESCRIPTION
`update`	Commit requested layer values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`alpha`	Return the derived drainage-mat runoff coefficient in project units. TYPE: `float`
`roughness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`thickness`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`void_fraction`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`

alpha `property`

alpha: float

Return the derived drainage-mat runoff coefficient in project units.

roughness `property` `writable`

roughness: float

Setter lifecycle: OPEN, ENDED.

thickness `property` `writable`

thickness: float

Setter lifecycle: OPEN, ENDED.

void_fraction `property` `writable`

void_fraction: float

Setter lifecycle: OPEN, ENDED.

update

update(**changes: object) -> None

Commit requested layer values atomically in OPEN or ENDED.

Intrinsic scalar errors fail immediately. Coupled layer, process, and LID-group relationships are validated during the next start().

LidUnitCollection


              flowchart TD
              swmmrs.objects.LidUnitCollection[LidUnitCollection]

              

              click swmmrs.objects.LidUnitCollection href "" "swmmrs.objects.LidUnitCollection"

Provide indexed access to a subcatchment's LID units.

LidUnit

Expose one LID unit owned by a subcatchment.

METHOD	DESCRIPTION
`snapshot`	Copy current LID Unit runtime values in configured project units.
`update`	Commit requested LID-unit values atomically in `OPEN` or `ENDED`.

ATTRIBUTE	DESCRIPTION
`area`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`bottom_width`	Return the LID unit's bottom width in project length units. TYPE: `float`
`control`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `LidControl`
`count`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `int`
`drain_destination`	Return explicit drain intent; setter lifecycle: `OPEN`, `ENDED`. TYPE: `Node \| Subcatchment \| None`
`full_width`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`impervious_runoff_treated`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`index`	Return the generation-bound position within the owning subcatchment. TYPE: `int`
`initial_saturation`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`pervious_runoff_treated`	Setter lifecycle: `OPEN`, `ENDED`. TYPE: `float`
`routes_to_pervious`	Return requested routing intent; setter lifecycle: `OPEN`, `ENDED`. TYPE: `bool`

area `property` `writable`

area: float

Setter lifecycle: OPEN, ENDED.

bottom_width `property`

bottom_width: float

Return the LID unit's bottom width in project length units.

control `property` `writable`

control: LidControl

Setter lifecycle: OPEN, ENDED.

count `property` `writable`

count: int

Setter lifecycle: OPEN, ENDED.

drain_destination `property` `writable`

drain_destination: Node | Subcatchment | None

Return explicit drain intent; setter lifecycle: OPEN, ENDED.

None requests an implicit drain that follows the prospective subcatchment outlet during Configuration Preparation.

full_width `property` `writable`

full_width: float

Setter lifecycle: OPEN, ENDED.

impervious_runoff_treated `property` `writable`

impervious_runoff_treated: float

Setter lifecycle: OPEN, ENDED.

index `property`

index: int

Return the generation-bound position within the owning subcatchment.

initial_saturation `property` `writable`

initial_saturation: float

Setter lifecycle: OPEN, ENDED.

pervious_runoff_treated `property` `writable`

pervious_runoff_treated: float

Setter lifecycle: OPEN, ENDED.

routes_to_pervious `property` `writable`

routes_to_pervious: bool

Return requested routing intent; setter lifecycle: OPEN, ENDED.

Preparation can force the native effective value off while a subcatchment has no pervious area without overwriting this request.

snapshot

snapshot() -> LidUnitSnapshot

Copy current LID Unit runtime values in configured project units.

update

update(**changes: object) -> None

Commit requested LID-unit values atomically in OPEN or ENDED.

Intrinsic errors fail immediately. Group area, capture, routing, drain, infiltration, and subcatchment relationships are prepared at start().

Low-impact development

LidControl

drain property

drainage_mat property

pavement property

soil property

storage property

surface property

LidSurfaceLayer

alpha property

immediate_overflow property

roughness property writable

side_slope property writable

slope property writable

thickness property writable

vegetation_volume_fraction property writable

update

LidSoilLayer

conductivity_slope property writable

field_capacity property writable

porosity property writable

saturated_conductivity property writable

suction_head property writable

thickness property writable

wilting_point property writable

update

LidStorageLayer

clogging_factor property writable

saturated_conductivity property writable

thickness property writable

void_ratio property writable

update

LidPavementLayer

clogging_factor property writable

impervious_fraction property writable

regeneration_fraction property writable

regeneration_interval property writable

saturated_conductivity property writable

thickness property writable

void_ratio property writable

update

LidDrainLayer

close_head property writable

coefficient property writable

control_curve property

delay property writable

exponent property writable

offset property writable

open_head property writable

update

LidDrainageMatLayer

alpha property

roughness property writable

thickness property writable

void_fraction property writable

update

LidUnitCollection

LidUnit

area property writable

bottom_width property

control property writable

count property writable

drain_destination property writable

full_width property writable

impervious_runoff_treated property writable

index property

initial_saturation property writable

pervious_runoff_treated property writable

routes_to_pervious property writable

snapshot

update

drain `property`

drainage_mat `property`

pavement `property`

soil `property`

storage `property`

surface `property`

alpha `property`

immediate_overflow `property`

roughness `property` `writable`

side_slope `property` `writable`

slope `property` `writable`

thickness `property` `writable`

vegetation_volume_fraction `property` `writable`

conductivity_slope `property` `writable`

field_capacity `property` `writable`

porosity `property` `writable`

saturated_conductivity `property` `writable`

suction_head `property` `writable`

thickness `property` `writable`

wilting_point `property` `writable`

clogging_factor `property` `writable`

saturated_conductivity `property` `writable`

thickness `property` `writable`

void_ratio `property` `writable`

clogging_factor `property` `writable`

impervious_fraction `property` `writable`

regeneration_fraction `property` `writable`

regeneration_interval `property` `writable`

saturated_conductivity `property` `writable`

thickness `property` `writable`

void_ratio `property` `writable`

close_head `property` `writable`

coefficient `property` `writable`

control_curve `property`

delay `property` `writable`

exponent `property` `writable`

offset `property` `writable`

open_head `property` `writable`

alpha `property`

roughness `property` `writable`

thickness `property` `writable`

void_fraction `property` `writable`

area `property` `writable`

bottom_width `property`

control `property` `writable`

count `property` `writable`

drain_destination `property` `writable`

full_width `property` `writable`

impervious_runoff_treated `property` `writable`

index `property`

initial_saturation `property` `writable`

pervious_runoff_treated `property` `writable`

routes_to_pervious `property` `writable`