Semi distributed model
This section describes semi-distributed hydraulic models and their connection to the Hydraulic Module of floodam.building.
Concept
In hydraulic modelling, three main levels of spatial representation are generally distinguished:
- Distributed models: which resolve flow equations in a continuous spatial domain (e.g. 2D shallow-water models). Demanding significant computational resources and detailed input data.
- Lumped models: which treat the whole system as a single storage with no internal spatial variability. Simplifying representation but potentially sacrificing accuracy.
- Semi-distributed models: which divide the domain into interconnected sub-units (control volumes) where mass and energy balances are solved individually. It is a more pragmatic approach to balancing model complexity and computational efficiency.
The compute_hydraulic() function implements a semi-distributed, time-dependent approach to simulate flood propagation inside buildings. Each control volume (room) evolves dynamically over time according to mass balance equations, using an adaptive time step that maintains numerical stability.
Each room acts as an elementary control volume with a known geometry (surface, ceiling height, volume curve), while openings represent the hydraulic connections between these volumes or between a room and the outside environment.
The temporal evolution of water level in each room results from the conservation of mass:
\[A_{i} \frac{dz_{i}}{dt} = \sum_j Q_{ij}\]
where \(A_{i}\) is the wetted surface of room \(i\) and \(Q_{ij}\) is the flow rate exchanged with adjacent rooms or boundaries through openings \(j\). For merged rooms, the effective storage area can vary with level, so the model uses a volume curve to track the correct room volume as water rises. ## Representation in the Model
In practice, the room and opening data frames form a hydraulic network:
- Nodes → rooms (control volumes)
- Edges → openings (hydraulic links)
Each opening connects two nodes, the up and down sides, and its discharge is computed according to the head difference using the weir or gate laws described in the flow equations chapter.
The resulting system is thus a graph of lumped elements where the water level in each node evolves over time according to the balance of inflows and outflows.
Adaptive Time Step Control
To ensure numerical stability and conserve water volume accurately, the model uses an adaptive time step mechanism (dt_adj).
At each iteration, the function evaluates whether any room is about to become empty (outflow exceeds the available volume).
If this occurs, the time step is automatically reduced so that the next update brings the room exactly to zero volume, avoiding negative storage values.
This approach combines the efficiency of a fixed maximum time step (dt_max) with the robustness of an event-driven adjustment.
As a result, the simulation remains both stable and physically consistent, even when large differences in water level or highly unbalanced flows occur between rooms.