Iber v3. Reference manual and GUI. 1D shallow flows calculation module


<!-- metadata commented in wiki content


==Iber v3. Reference manual and GUI. 1D shallow flows calculation module==

Marcos Sanz-Ramos<sup>1</sup>, Danial Dehghan-Souraki<sup>1</sup>, Ernest Bladé<sup>1</sup>

<sup>1</sup>Flumen Institute, Universitat Politècnica de Catalunya (UPC - Barcelona TECH) – International Centre of Numerical Methods in Engineering (CIMNE), 08034 Barcelona, Spain

''Correspondence to'': [mailto:marcos.sanz-ramos@upc.edu marcos.sanz-ramos@upc.edu]

<span id='_Toc203976053'></span>
-->

==Abstract==

Iber is a two-dimensional hydraulic model for the simulation of free surface flow in rivers and estuaries, and the simulation of environmental processes in fluvial hydraulics. Since the release of the first version of Iber, which included a hydrodynamic calculation engine fully coupled with sediment transport processes and turbulence, it has evolved to become a free surface flow modelling tool for highly complex environmental processes. This document presents the developments made for version 3, specifically, for the new calculation module for the simulation of one-dimensional shallow flows called Iber-1D. The nature of this module enhances the current capabilities of the urban drainage model (Iber-UD) and homogenises the code both sewer and channel networks, but also includes particular capabilities for simulating irrigation channels (e.g., operation tools). Additionally, a calculation module for one-dimensional suspended sediment transport has been developed, being fully coupled with the hydrodynamics. The graphical user interface (GUI) has been adapted to the module's new features to achieve a simple and user-friendly workflow.

'''Keywords''': 1D flows, channel networks, sewer networks, urban drainage, sediment transport, Iber

<span id='_Toc203976054'></span>

==Resumen==

Iber es un modelo hidrodinámico bidimensional para la simulación del flujo superficial libre en ríos y estuarios, así como para la simulación de procesos ambientales en hidráulica fluvial. Desde el lanzamiento de la primera versión de Iber, que incluía un motor de cálculo hidrodinámico totalmente acoplado con los procesos de transporte de sedimentos y turbulencia, ha evolucionado hasta convertirse en una herramienta de modelado de flujo superficial libre para procesos ambientales altamente complejos. Este documento presenta los desarrollos realizados para la versión 3, específicamente para el nuevo módulo de cálculo para la simulación de flujos superficiales unidimensionales denominado Iber-1D. La naturaleza de este módulo mejora las capacidades actuales del modelo de drenaje urbano (Iber-UD) y homogeneiza el código tanto para redes de alcantarillado como de canales, e incluye además capacidades específicas para la simulación de canales de riego (por ejemplo, herramientas de operación). Asimismo, se ha desarrollado un módulo de cálculo para el transporte de sedimento en suspensión unidimensional, estando completamente acoplado con la hidrodinámica. La interfaz gráfica de usuario (GUI) se ha adaptado a las nuevas características del módulo para lograr un flujo de trabajo sencillo e intuitivo.

'''Palabras clave''': flujos 1D, redes de canales, redes de alcantarillas, drenaje urbano, transporte de sedimentos, Iber

<br/>

<span id='_Toc203976056'></span>

==1 Introduction==

Numerical modelling of channel networks, whether it be sewers or irrigation canals, is particularly relevant to properly characterize the propagation of free surface and pressurized flows. Despite Iber already has a one-dimensional module [<span id='cite-_Bib001'></span>[[#_Bib001|1]],<span id='cite-_Bib002'></span>[[#_Bib002|2]]], it is oriented to simulate coupled urban pluvial floods using numerical techniques and a workflow not fully coupled with the rest of [https://www.iberaula.es/53/iber-model/modules modules of Iber]. This fact limited its application to particular cases and made it impossible to consider transport processes.

Iber-1D raises, based on Iber [<span id='cite-_Bib003'></span>[[#_Bib003|3]]], as a depth-averaged one-dimensional hydrodynamic numerical tool to simulate free and pressurized flows in channels networks, fully coupled with suspended sediment transport process. Using the classical and robust numerical scheme of Roe (hydrodynamics) and the sediment transport equations (suspended load), together with the Exner equation to update bed elevation, the code was refactored and unified to ensure the same flow behaviour in 1D and 2D simulations in equal geometry discretization. This not only resulted in good interaction between Iber-1D and the other calculation modules, but also a significant improvement in the performance of the hydrodynamic module with accelerations greater than 2x was achieved (reaching values up to 22x in complex channel networks).

The common applications of Iber-1D are the numerical modelling of sewer networks (urban drainage) and channel networks (irrigation), but also it is an incipient tool to simulate propagation processes in such computational domains where the flow is mainly 1D. To that end, new cross-sections were included besides a particular way to calculate the Rouse profile in suspended sediment transport modelling, which notably improve the numerical performance properly maintaining the accuracy of the numerical tool.

<span id='_Toc203976057'></span>

==2 Graphical user interface of Iber-1D==

<span id='_Toc203976058'></span>

===2.1 Generalities===

The current version of Iber-1D is fully integrated into Iber. Thus, the same properties, options and main workflow used in Iber also applies to Iber-1D. Only particular characteristics of this module are described below. Further information can be found in the Iber v3 Refence manual [<span id='cite-_Bib004'></span>[[#_Bib004|4]]].

It is worth noticing that Iber-1D works as fully coupled one-dimensional hydrodynamic module together with the classical two-dimensional hydrodynamic module of Iber. Thus, the user can choose if 1D, 2D or 1D/2D simulation is carried out. Flow exchange between 1D/2D and 2D/1D domains are possible through options of the urban drainage module Iber-UD [<span id='cite-_Bib001'></span>[[#_Bib001|1]],<span id='cite-_Bib002'></span>[[#_Bib002|2]]]. Additionally, this new module presents relevant improvement: it is fully coupled with the suspended sediment transport module of Iber [<span id='cite-_Bib005'></span>[[#_Bib005|5]],<span id='cite-_Bib006'></span>[[#_Bib006|6]],<span id='cite-_Bib007'></span>[[#_Bib007|7]]]. Future interactions with other modules are not discarded.

<span id='_Toc203976059'></span>

===2.2 Particularities===

Iber-1D, as for the rest of modules, must be activated. The activation of Iber-1D can be done by:

:* The menu '''Iber tools >> Plug-ins'''…

:* The shortcut  [[Image:Draft_Sanz-Ramos_817161369-image1.png|12px]] (located on the left side of the interface, by default)

Once selected ‘1D/2D flow’ as a module, and then applied, the interface will be adapted to this new hydrodynamic module oriented to simulate 1D flows. Currently, Iber-1D acts as the base module to compute hydrodynamics in one-dimensional networks (geometry definition), being coupled with Hydrological Process and Urban Drainage modules to compute urban pluvial floods and with Sediment Transport module (Figure 1).

{| style="width: 100%;margin: 1em auto 0.1em auto;border-collapse: collapse;" 
|-
|  style="text-align: center;width: 33%;"|[[Image:Draft_Sanz-Ramos_817161369-image2.png|186px]] 
|  style="text-align: center;width: 33%;"|[[Image:Draft_Sanz-Ramos_817161369-image3.png|186px]] 
|  style="text-align: center;width: 33%;"|[[Image:Draft_Sanz-Ramos_817161369-image4.png|186px]] 
|-
|  style="text-align: center;"|(a)
|  style="text-align: center;"|(b)
|  style="text-align: center;"|(c)
|}


<span id='_Hlk202869113'></span><span style="text-align: center; font-size: 75%;">'''Fig. 1. Plug-ins window. When selecting 1D/2D flow module (a), it serves as the basis Sediment transport module (b) and for Urban Drainage and Hydrological processes modules (c).'''</span>

Particularly, the 1D module possibilities the simulation of free (channel network) and pressurized flows (sewer network, e.g., Iber-UD), but also integrates the capability of simulating 1D, 2D or 1D/2D flows together. These features can be enabled/disabled through '''Data >> Problem data''' menu, the tab “1D/2D flow” containing the kind of flow to simulate. Also for hydrodynamics, the network can be defined manually or automatically by importing a shapefile (if the attribute table contains the properties of each condition, it will be automatically assigned). The geometry characteristics can be defined through '''Data >> 1D network >> Network definition '''menu (Figure 2).

{| style="width: 100%;margin: 1em auto 0.1em auto;border-collapse: collapse;" 
|-
|  style="text-align: center;width: 33%;"|[[Image:Draft_Sanz-Ramos_817161369-image5.png|186px]] 
|  style="text-align: center;width: 33%;"|[[Image:Draft_Sanz-Ramos_817161369-image6.png|186px]] 
|  style="text-align: center;width: 33%;"|[[Image:Draft_Sanz-Ramos_817161369-image7.png|186px]] 
|-
|  style="text-align: center;"|(a)
|  style="text-align: center;"|(b)
|  style="text-align: center;"|(c)
|}


<span style="text-align: center; font-size: 75%;">'''Fig. 2. Entities definition. Junctions (a), Network (b) and 2D areas (c).'''</span>

The main difference with the classical hydrodynamic modelling using Iber, a two-dimensional numerical tool, is the that the computational domain discretises channels as lines and junctions as points both containing cross-section information. Additionally, as well as for the Urban Drainage module of Iber [<span id='cite-_Bib004'></span>[[#_Bib004|4]]], there are 2D areas that are only connected to 1D domain.

<span id='_Toc203976064'></span>

==3 Governing equations==

This section is a brief description of the governing equations of Iber-1D. Further details about this hydrodynamic module and the numerical scheme used to solve the equations can be found in Aragón-Hernández [<span id='cite-_Bib001'></span>[[#_Bib001|1]]], as well as in the Reference Manual of the version 3 of Iber [<span id='cite-_Bib004'></span>[[#_Bib004|4]]].

===3.1 Hydrodynamic module===

====3.1.1 Network====

The hydrodynamic module solves the depth-averaged shallow water equations or one-dimensional Saint-Venant equations in the channel/sewer network, which are a hyperbolic system of partial differential equations and can be written, in conservative form, as in Equation <span id='cite-_Ref202869890'></span>[[#_Ref202869890|(1)]].

{| class="formulaSCP" style="width: 100%;border-collapse: collapse;width: 100%;text-align: center;" 
|-
| 
{| style="text-align: center;margin:auto;width: 100%;"
|-
| <math>\begin{matrix}\frac{\partial A}{\partial t}+\frac{\partial Q}{\partial x}=0\\\frac{\partial Q}{\partial t}+\frac{\partial }{\partial x}\left( \frac{{Q}^{2}}{A}+g{I}_{1}\right) =g{I}_{2}+gA\left( {S}_{0}-{S}_{f}\right) \end{matrix}</math>
|}
|  style="text-align: center;width: 5px;text-align: right;white-space: nowrap;"|<span id='_Ref202869890'></span>(1)
|}


where <math display="inline">A</math> is the wetted area, <math display="inline">Q</math> is the discharge, <math display="inline">g</math> is the gravitational acceleration, <math display="inline">{S}_{o}</math> is the is the bed slope, and <math display="inline">{S}_{f}</math> is the friction slope. The terms <math display="inline">{I}_{1}</math> and <math display="inline">{I}_{2}</math> represent the hydrostatic pressure force integral and the pressure force component due to longitudinal variations in channel width, respectively. The current sections implemented in Iber-1D are circular, rectangular and trapezoidal. Future versions will implement further cross-sections type.

====3.1.2 Junctions====

Any channel/sewer network needs the definition of junctions that connects different channels/pipes allowing the flow propagation over the entire network. The junction is modelled as a storage volume where the conservation of mass is enforced, being the momentum preserved or not. Unlike simple point-node approximations, this approach accounts for the finite surface area of the junction, allowing for a more physical representation of the flow dynamics. Thus, a particularized numerical scheme is used since more than 2 channels/pipes can be connect into a junction, converging or diverging the flow, which is similar than the one used by the two-dimensional hydrodynamic module of Iber.

====3.1.3 Channel operation tools====

Hydraulic structures like gates and weirs are modelled as internal singularities where the standard momentum equation is replaced by specific discharge laws. Beside the wide extended equations to simulate weirs, gates, gate-weirs and local losses, Iber-1D implements an additional operation tool called “Flux limiter”. This option limits the flow transferred between elements, causing flow accumulation upstream when the discharge arriving to the internal condition is greater than the defined value.

===3.2 Sediment transport module===

<span id='_Toc176677472'></span><span id='_Toc203976067'></span>The developed suspended sediment transport module, explicitly coupled through bed evolution using the Exner equation, solves the depth-averaged convection-diffusion equation, and can be expressed as follows:

{| class="formulaSCP" style="width: 100%;margin: 1em auto 0.1em auto;width: 100%;text-align: center;" 
|-
| 
{| style="text-align: center;margin:auto;width: 100%;"
|-
| <math>\frac{\partial AC}{\partial t}+\frac{\partial QC}{\partial x}=\frac{\partial }{\partial x}\left( A\Gamma \frac{\partial C}{\partial x}\right) +</math><math>\left( E-D\right)</math> 
|}
|  style="text-align: center;width: 5px;text-align: right;white-space: nowrap;"|<span id='_Ref202871261'></span>(2)
|}


where <math display="inline">C</math> is the depth-averaged sediment concentration, <math display="inline">\Gamma</math>  is the molecular diffusion coefficient, <math display="inline">E</math> is the source term related to the erosion process, and <math display="inline">D</math> is the source term related to the deposition process.

For calculating the erosion and deposition term <math display="inline">\left( E-\right. </math><math>\left. D\right)</math> , the same transport equations already used by Iber have been implemented in Iber-1D: van Rijn (1987), Smith-McLean (1977), Ariathurai-Arulanandan (1978), and Ariathurai-Arulanandan-López (2024), which is an adaptation of the previous equation that allows for modification of the minimum and maximum erosion rate ( <math display="inline">E</math>) and erosion stress.

Coupling with the hydrodynamic module is achieved using the Exner equation, which is used to update the bottom elevation after evaluating the <math display="inline">\left( E-\right. </math><math>\left. D\right)</math>  term. If this term is positive, the bottom tends to erode; conversely, if this term is negative, the bed tends to settle. The Exner equation can be expressed as follows:

{| class="formulaSCP" style="width: 100%;margin: 1em auto 0.1em auto;width: 100%;text-align: center;" 
|-
| 
{| style="text-align: center;margin:auto;width: 100%;"
|-
| <math>\left( 1-p\right) \frac{\partial {z}_{b}}{\partial t}+\frac{\partial {Q}_{s}}{\partial x}=</math><math>\left( D-E\right)</math> 
|}
|  style="text-align: center;width: 5px;text-align: right;white-space: nowrap;"|(3)
|}


where <math display="inline">p</math> represents the porosity of the sedimented material, <math display="inline">{z}_{b}</math> is the bed elevation, <math display="inline">{Q}_{s}</math> is solid discharge.

<span id='_Hlk164577115'></span>

====3.2.1 Suspended sediment transport models====

The term that expresses the suspension and sedimentation of sediment particles <math display="inline">\left( D-\right. </math><math>\left. E\right)</math>  is evaluated through the empirical equations of van Rijn [<span id='cite-_Bib008'></span>[[#_Bib008|8]]], Smith-McLean [<span id='cite-_Bib009'></span>[[#_Bib009|9]]], Ariathurai-Arulanandan [<span id='cite-_Bib010'></span>[[#_Bib010|10]]], and Ariathurai-Arulanandan-López [<span id='cite-_Bib011'></span>[[#_Bib011|11]]].

====3.2.2 Settling velocity====

Iber-1D, as in Iber, uses the equation proposed by van Rijn to compute the settling velocity ( <math display="inline">{W}_{s}</math>) of a particular sediment size. This expression is split in 3 equations depending on the diameter of the sediment:

{| class="formulaSCP" style="width: 100%;margin: 1em auto 0.1em auto;width: 100%;text-align: center;" 
|-
| 
{| style="text-align: center;margin:auto;width: 100%;"
|-
| <math>\begin{matrix}{D}_{50}<0.1\, mm&\rightarrow &{W}_{s}=\frac{Rg{D}_{50}^{2}}{18\nu }\\{0.1\leq D}_{50}\leq 1\, mm&\rightarrow &{W}_{s}=\frac{10\nu }{{D}_{50}}\left( \sqrt{\frac{1+0.01Rg{D}_{50}^{3}}{{\nu }^{2}}}\right) \\{D}_{50}>1\, mm&\rightarrow &{W}_{s}=1.1\sqrt{Rg{D}_{50}}\end{matrix}</math>
|}
|  style="text-align: center;width: 5px;text-align: right;white-space: nowrap;"|(4)
|}


where <math display="inline">{D}_{50}</math> is characteristic diameter of the sediment particles, <math display="inline">g</math> is the gravitational acceleration, <math display="inline">R</math> is submerged relative density, and <math display="inline">\nu</math>  is the water kinematic viscosity.

====3.2.3 Vertical distribution of the sediment concentration====

Generally, the suspended sediment concentration on a water current is not homogeneous in vertical neither in horizontal directions. Iber-1D assumes homogeneous distribution of the sediment concentration for the whole section, but it implements the Rouse profile [<span id='cite-_Bib012'></span>[[#_Bib012|12]]] to compute the sediment concentration from the depth-averaged sediment concentration ( <math display="inline">C</math>):

{| class="formulaSCP" style="width: 100%;margin: 1em auto 0.1em auto;width: 100%;text-align: center;" 
|-
| 
{| style="text-align: center;margin:auto;width: 100%;"
|-
| <math>C={C}_{0}{\left( \frac{{z}_{0}\left( h-z\right) }{z\left( h-{z}_{0}\right) }\right) }^{\frac{{W}_{s}}{0.4{u}^{\ast }}}</math>
|}
|  style="text-align: center;width: 5px;text-align: right;white-space: nowrap;"|(5)
|}


where <math display="inline">{C}_{0}</math> is the sediment concentration at <math display="inline">{z}_{0}</math>, assumed to be an elevation near the bed, and <math display="inline">{u}^{\ast }</math> is the bed friction velocity computed as <math display="inline">\sqrt{\frac{{\tau }_{b}}{\rho }}</math>, being the bed shear stress and the fluid density respectively.

<span id='_Toc203976080'></span>

==4 Results==

Another particularity of this calculation module relay in how the results are shown. All results, both hydrodynamic and sediment transport, of Iber-1D are stored in the same analysis as for 2D, but specifying with “1D” at the end of the results name. Thus, two type of results exists: 1D in lines (network) and 2D in points (junctions).

Both results can be personalized through the particular options of the GUI of Iber, GiD. The size of point and line mesh elements can be modified in Utilities >> Preferences menu, particularly in Postprocess > Mesh element. Point elements must be shown using the “Points” and “Point bound” style of the Global settings (Windows >> View style). Line elements can be shown all styles except “Points” and “Point bound”, being Body-type those allows representing the mesh size properly. Figure 3 shows some examples of results visualization configuration.

{| style="width: 100%;margin: 1em auto 0.1em auto;border-collapse: collapse;" 
|-
|  style="text-align: center;width: 50%;"|[[Image:Draft_Sanz-Ramos_817161369-image8.png|270px]] 
|  style="text-align: center;width: 50%;"|[[Image:Draft_Sanz-Ramos_817161369-image9.png|270px]] 
|-
|  style="text-align: center;"|(a1)
|  style="text-align: center;"|(b1)
|-
|  style="text-align: center;width: 50%;"|[[Image:Draft_Sanz-Ramos_817161369-image10.png|270px]] 
|  style="text-align: center;width: 50%;"|[[Image:Draft_Sanz-Ramos_817161369-image11.png|270px]] 
|-
|  style="text-align: center;"|(a2)
|  style="text-align: center;"|(b2)
|}


<span style="text-align: center; font-size: 75%;">'''Fig. 3. Results style configuration. Line mesh elements with a size of 1 (a1) and 30 (a2). Point mesh elements with a size of 3 (b1) and 30 (b2).'''</span>

A particular result of 1D sediment transport is the one called “Total sediment mass (Sups seds) 1D (kg)” that accounts for the total amount of sediments that passes through a line element.

<br/>

<span id='_Toc203976081'></span>

==References==

<span id='_Bib001'></span>
[1] J.L. Aragón-Hernández, Modelación numérica integrada de los procesos hidráulicos en el drenaje urbano, PhD thesis. Barcelona, mayo de 2013, Universitat Politècnica de Catalunya, 2013.

<span id='_Bib002'></span>
[2] J.Á. Aranda, C. Beneyto, M. Sánchez-Juny, E. Bladé, Efficient Design of Road Drainage Systems, Water (Basel). 13 (2021) 1661. [https://doi.org/10.3390/w13121661. https://doi.org/10.3390/w13121661.]

<span id='_Bib003'></span>
[3] E. Bladé, L. Cea, G. Corestein, E. Escolano, J. Puertas, E. Vázquez-Cendón, J. Dolz, A. Coll, Iber: herramienta de simulación numérica del flujo en ríos, Revista Internacional de Métodos Numéricos Para Cálculo y Diseño En Ingeniería 30 (2014) 1–10. [https://doi.org/10.1016/j.rimni.2012.07.004. https://doi.org/10.1016/j.rimni.2012.07.004.]

<span id='_Bib004'></span>
[4] M. Sanz-Ramos, L. Cea, E. Bladé, D. López-Gómez, E. Sañudo, G. Corestein, G. García-Alén, J. Aragón-Hernández, Iber v3. Reference manual and user’s interface of the new implementations, CIMNE, 2022. [https://doi.org/10.23967/iber.2022.01. https://doi.org/10.23967/iber.2022.01.]

<span id='_Bib005'></span>
[5] E. Bladé, M. Sánchez‐Juny, M. Arbat, J. Dolz, Computational Modeling of Fine Sediment Relocation Within a Dam Reservoir by Means of Artificial Flood Generation in a Reservoir Cascade, Water Resour. Res. 55 (2019) 3156–3170. [https://doi.org/10.1029/2018WR024434. https://doi.org/10.1029/2018WR024434.]

<span id='_Bib006'></span>
[6] D. López-Gómez, M. De Blas-Moncalvillo, M. Castejón-Zapata, Á. Gassó-Sánchez, E. Bladé, M. Sanz-Ramos, D. Dehghan-Souraki, L. Garrote-de Marco, D. Santillán-Sánchez, J.M. Soria-García, J. San Román-Saldaña, R. Galván-Plaza, M.Á. García-Vera, J. Sánchez-Martínez, Análisis del transporte de sedimentos en el curso bajo del río Ebro mediante modelización numérica de una avenida controlada, Ingeniería Del Agua 28 (2024) 246–262. [https://doi.org/10.4995/ia.2024.21768. https://doi.org/10.4995/ia.2024.21768.]

<span id='_Bib007'></span>
[7] D. Dehghan-Souraki, D. López-Gómez, E. Bladé-Castellet, A. Larese, M. Sanz-Ramos, Optimizing sediment transport models by using the Monte Carlo simulation and deep neural network (DNN): A case study of the Riba-Roja reservoir, Environmental Modelling & Software 175 (2024) 105979. [https://doi.org/10.1016/j.envsoft.2024.105979. https://doi.org/10.1016/j.envsoft.2024.105979.]

<span id='_Bib008'></span>
[8] L.C. van Rijn, Sediment Transport, Part I: Bed Load Transport, Journal of Hydraulic Engineering 110 (1984) 1431–1456. [https://doi.org/10.1061/ https://doi.org/10.1061/](ASCE)0733-9429(1984)110:10(1431).

<span id='_Bib009'></span>
[9] J.D. Smith, S.R. McLean, Spatially averaged flow over a wavy surface, J. Geophys. Res. 82 (1977) 1735–1746. [https://doi.org/10.1029/JC082i012p01735. https://doi.org/10.1029/JC082i012p01735.]

<span id='_Bib010'></span>
[10] R. Ariathurai, K. Arulanandan, Erosion rates of cohesive soils, Journal of the Hydraulics Division 104 (1978) 279–283.

<span id='_Bib011'></span>
[11] D. López-Gómez, M. De Blas-Moncalvillo, V. Cuéllar-Moro, Herramientas para la gestión sostenible de la sedimentación en el embalse de Marmolejo (España), Ingeniería Del Agua 28 (2024) 1–16. [https://doi.org/10.4995/ia.2024.20376. https://doi.org/10.4995/ia.2024.20376.]

<span id='_Bib012'></span>
[12] H. Rouse, Modern conceptions of the mechanics of turbulence, Transactions American Society of Civil Engineers 102 (1937) 463–543.

 &nbsp;