Flow equations
Rooms are considered individually and we track the evolution of the water level in each one during a flood event. Conservation of mass requires:
\[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 exchanged through opening \(j\).
Openings connect rooms to each other or to the outside. Different types of openings are possible: open doors, closed doors and windows. For simplicity, all openings are represented by the same exchange law, but with geometric parameters that distinguish their behaviour. Openings are not oriented, so the exchange satisfies:
\[Q_{AB} = Q(Z_{A}, Z_{B}) = -Q(Z_{B}, Z_{A})\]
Notations
| Symbol | Description | Unit |
|---|---|---|
| \(Z_A, Z_B\) | Water levels on each side of the opening | m |
| \(Z_{am}\) | Highest water level on either side (max(Z_A, Z_B)) |
m |
| \(Z_{av}\) | Lowest water level on either side (min(Z_A, Z_B)) |
m |
| \(Z_b\) | Bottom elevation of the opening | m |
| \(Z_t\) | Top elevation of the opening | m |
| \(S\) | Wetted section of the opening | m² |
| \(Q\) | Water discharge through the opening | m³/s |
| \(g\) | Acceleration due to gravity (≈ 9.81) | m/s² |
| \(C_d\) | Discharge coefficient | — |
| \(SG(x)\) | Sign function of \(x\) | — |
Hydraulic computations
The following equations are used in the code to describe different hydraulic regimes across an opening.
No flow
When the water level is below the bottom elevation of the opening:
\[Z_{am} \le Z_{b}\]
\[Q = 0\]
There is no exchange between the rooms, so the flow is set to 0.
Weir laws
The weir law is used when the highest water level is above the bottom of the opening, but the opening is not fully drowned:
\[Z_{t} > Z_{am} \ge Z_{b}\]
Free weir law
When only the higher side of the opening is above the bottom and the lower side is below it:
\[Z_{b} \ge Z_{av}\]
\[S = L (Z_{am} - Z_{b})\] \[Q = C_{d} \sqrt{2g} S \sqrt{Z_{am} - Z_{b}}\]
Submerged weir law
When both sides of the opening are above the bottom:
\[Z_{av} > Z_{b}\]
\[S = L \left( \frac{Z_{am} - Z_{av}}{2} - Z_{b} \right)\] \[Q = C_{d} \sqrt{2g} S \sqrt{Z_{am} - Z_{av}}\]
Gate laws
Gate laws are used when the opening is overtopped by water on at least one side:
\[Z_{am} \ge Z_{t}\]
Free gate law
When the lower side is still below the top of the opening:
\[Z_{t} \ge Z_{av}\]
\[S = L (Z_{t} - Z_{b})\] \[Q = C_{d} \sqrt{2g} S \sqrt{Z_{am} - \frac{Z_{b} - Z_{t}}{2}}\]
Submerged gate law
When both sides are higher than the top of the opening:
\[Z_{av} \ge Z_{t}\]
\[S = L (Z_{t} - Z_{b})\] \[Q = C_{d} \sqrt{2g} S \sqrt{Z_{am} - Z_{av}}\]
Flow direction
Because openings are not oriented, the sign of flow is determined by the water level difference:
\[Q_{AB} = SG(Z_{A} - Z_{B}) \, Q\]
Numerical Stability and Low-Flow Conditions
The exchange equations above simulate transient water flow between rooms and boundaries. When the system approaches quasi-steady state and the head difference is very small, numerical oscillations can appear due to discrete time integration.
The model mitigates this with an adaptive time step (dt_adj). During each iteration, if a room is about to become empty, the time step is reduced so the next update brings the room exactly to zero volume instead of producing negative storage. This preserves mass balance while avoiding unstable behaviour.
If you need a more accurate representation of low-flow conditions, consider lowering the time step using the dt_max parameter. This reduces noise but increases computation time, so choose a value that balances accuracy and performance. The default time step of 0.5 s is a practical compromise for most cases.