The iFlow modelling framework is a width-averaged model for the systematic analysis of the water motion and sediment transport processes in estuaries and tidal rivers. The distinctive solution method, a mathematical perturbation method, used in the model allows for identification of the effect of individual physical processes on the water motion and sediment transport and study of the sensitivity of these processes to model parameters. This distinction between processes provides a unique tool for interpreting and explaining hydrodynamic interactions and sediment trapping. iFlow also includes a large number of options to configure the model geometry and multiple choices of turbulence and salinity models. Additionally, the model contains auxiliary components, including one that facilitates easy and fast sensitivity studies.

iFlow has a modular structure, which makes it easy to include, exclude or change individual model components, called modules. Depending on the required functionality for the application at hand, modules can be selected to construct anything from very simple quasi-linear models to rather complex models involving multiple non-linear interactions. This way, the model complexity can be adjusted to the application. Once the modules containing the required functionality are selected, the underlying model structure automatically ensures modules are called in the correct order. The model inserts iteration loops over groups of modules that are mutually dependent. iFlow also ensures a smooth coupling of modules using analytical and numerical solution methods. This way the model combines the speed and accuracy of analytical solutions with the versatility of numerical solution methods.

In this paper we present the modular structure, solution method and two examples of the use of iFlow. In the examples we present two case studies, of the Yangtze and Scheldt rivers, demonstrating how iFlow facilitates the analysis of model results, the understanding of the underlying physics and the testing of parameter sensitivity. A comparison of the model results to measurements shows a good qualitative agreement.

iFlow is written in Python and is available as open source code under the LGPL license.

The dynamics of estuaries and tidal rivers is
characterized by the complex
interplay of mutually interacting processes related to the water motion (i.e.
tidal propagation, river run-off), salinity and sediment dynamics, transport
of nutrients and bathymetric changes. In many estuaries and tidal rivers
these processes are subject to constant change due to human interventions,
such as dredging and canalization, or to natural changes, such as sea level
rise or changing river discharge. These changes may lead to practical
problems. Focussing on the hydrodynamics and sediment dynamics, examples are
increasing risks of flooding related to tidal amplification or reflection

A wide range of process-based models has contributed to the present-day
understanding of flow and transport processes. These models range from linear
one-dimensional along-channel models to non-linear three-dimensional
numerical models. One way of classifying models is to describe their position
in the spectrum ranging from

The aim of the iFlow modelling framework is to combine the strengths of both
approaches identified above, that is, to represent some of the complex
processes and interactions contained in complex models while retaining the
ability to analyse these processes and study their sensitivity. iFlow is
a width-averaged model for hydrodynamics and sediment transport processes in
single-branch estuaries and tidal rivers, focussing on global estuarine
processes. Within this context, the model is able to cover a wide range of
complexity, reaching out to both the idealized and complex model types. This
requires a structured and systematic approach. This approach starts from the
exploratory model of

iFlow currently includes several modules that allow for the computation of
the flow and suspended sediment transport. Most of these modules focus on
identifying the effect of individual processes and to this end use
a perturbation approach. This approach has been successfully applied before
in the context of estuarine research by e.g.

Summarizing, the iFlow philosophy revolves around three central ideas:

the model is easily extendible by new processes;

the model allows for the combination of different solution methods for different processes, including analytical and numerical solution methods;

it is possible to identify the effects of individual physical forcing mechanisms and interactions.

This paper is structured into three main parts. Firstly,
Sect.

In order to satisfy the three criteria set in the introduction (extendibility, interchangeability and ease of analysis), the structure of iFlow has to be modular. Modules are separate model entities that implement certain physical processes or perform auxiliary tasks, such as plotting or initiating a sensitivity study. A module may use any approach to obtain the required variables, for example solving a set of equations, loading measured or modelled data from a file or even linking to another modelling suite. Modules are code-independent, meaning that the interaction between different modules is only on input and output level, not on code level. This allows an independent development of modules by different developers while ensuring seamless interaction between different modules. It also allows easy interchangeability of modules that compute the same variables but that differ in the physical processes taken into account or the type of implementation used.

Depending on the problem at hand, users can select which variables to save,
which physical processes to include and which auxiliary tasks to perform by
selecting a set of modules. These modules are listed in an

Basic example of input

As a first step, iFlow reads the input file (Fig.

The input file lists four modules with a specific task each:

The call stack shows a loop between

As a consequence of the way that iFlow constructs the call stack, the model will not use modules that are not needed to compute the required variables. A notification of this is given when running a simulation. Similarly, a notification is given if the call stack cannot be completed, because certain input variables are missing.

The example discussed here can easily be extended, e.g. by adding modules for computing additional variables or by adding auxiliary modules for saving the output or plotting it. To allow for more flexibility, the input and output files allow for a number of additional options that are beyond the scope of this paper, such as submodules and input-dependent output requirements. Details on this are provided in the iFlow manual in the Supplement.

After construction of the call stack, the modules are called sequentially in
the determined order. As modules are required to be code-independent, they
are not allowed to communicate directly with each other. Instead, the iFlow
core regulates the distribution of the required input data and collection of
the resulting output. The management of these data is facilitated by the

Different modules used within one simulation can have widely different
degrees of complexity and are allowed to use different solution methods.
Therefore the requested input and resulting output data can be of different
types, including scalars, multi-dimensional arrays and analytical function
descriptions. In our example,

Since iFlow is designed to improve the understanding of physical processes,
modules may offer decompositions of data into contributions resulting from
different physical components. The method of decomposition is the
responsibility of individual modules. An example of this using the
perturbation method will be discussed in Sect.

The

The iFlow modelling framework includes a number of standard modules that may
be used to simulate and analyse the water motion and sediment dynamics in
estuaries and tidal rivers. Together, the standard modules provide a full
model for hydrodynamics and sediment dynamics that may be used in different
combinations to model various levels of complexity. The modules are organized
into four packages,

A short introduction to many of these modules is provided in
Sects.

The iFlow core has a flexible definition of the model dimensions that allows
for anything from one-dimensional to three-dimensional models. In this paper
we will discuss the standard modules in iFlow version 2.4, which are only for
a two-dimensional width-averaged (2DV) model. The along-channel axis is
defined as the

Model domain. The model is two-dimensional in the along-channel
(

List of modules included in iFlow version 2.4.

Flow diagram outlining the main steps taken in the derivation of the implemented equations for hydrodynamics and sediment dynamics. The fully non-linear width-averaged equations are taken through several steps of analysis to reduce the complexity of the system. Then, two implementations of this reduced system are made, each with their own advantages and disadvantages.

The surface level relative to

As discussed in Sect.

The standard modules for computing the hydrodynamics and sediment dynamics fit particularly well in the iFlow philosophy as they allow for a separate analysis of the physical contributions to the total result. These analysis properties result from the perturbation approach that is used to solve the continuity, momentum and sediment balances.

The steps taken in the perturbation analysis are listed in
Fig.

The water motion is described by the Reynolds-averaged width-averaged shallow
water equations that solve for the water level elevation

In addition we use the width-averaged, depth-integrated continuity equation,
which reads

The sediment dynamics is described by the width-averaged sediment mass
balance equation, which solves for the sediment concentration

In Eq. (

The dimensionless sediment availability function

The first step in the perturbation approach is the scaling of the equations.
This approach uses a systematic mathematical procedure to determine the
relative importance of the different terms in the equations for water motion
and sediment dynamics. The most dominant terms will be called

The scaling requires four crucial assumptions. Firstly we assume

Secondly, it is assumed that the typical tidal wave length and the typical
length-scale of bathymetric variations are of the same order of magnitude as
the length of tidal influence into the estuary. This implies that sudden
local bathymetric variations are not allowed. Rather, bathymetric changes
should be smooth over the length of the estuary. Likewise, the method is
restricted to long waves, such as tides. Short waves, such as wind waves, are
not accounted for. As a consequence of this assumption, the non-linear
advection term

Thirdly, it is assumed that the horizontal density gradient is small. More
precisely, the internal Froude number should be of order

Finally, the horizontal diffusion term

Instead of neglecting first- and higher-order non-linear effects, as is done
in conventional linearization techniques, the perturbation approach expands
these non-linearities into a series of linear estimates. To this end, the
solution variables

The perturbation approach is illustrated here for the momentum and
depth-averaged continuity equations for the hydrodynamics, which may be used
to compute

Separate forcing mechanisms to the water and sediment motion and the order at which these mechanisms appear.

An improved approximation of the solution results from constructing the
balance of first-order terms. Again focussing on the momentum and
depth-averaged continuity equations, these consist of a linear set of
equations for

A similar approach for the sediment balance also results in linear equations
at the leading and first order, forced by different physical mechanisms. The
leading-order sediment balance describes a local balance between vertical
turbulent mixing and the settling of sediment. It is forced at the bed, where
sediment is locally resuspended by the leading-order erosion flux

Similar to the approach outlined above for the first-order terms, higher-order approximations of both the hydrodynamics and sediment dynamics can be made by composing a balance of the terms on second, third and higher orders. It is assumed that all external forcing terms (i.e. external tidal forcing, river discharge) act on the leading and first orders. The second and higher orders therefore only contain estimates of non-linear interactions of lower order contributions. The sum of all estimates of the non-linear terms at all orders should return the total solution to the original non-linear system of equations. If the scaling assumptions are satisfied, it follows that the contributions at higher order rapidly become smaller. The solutions at leading and first order then provide a fairly accurate estimate of the total solution. The higher-order systems are nevertheless useful in cases where the scaling assumptions are only marginally satisfied or when studying a particular process that involves a non-linear interaction that appears at higher order.

The external forcing of the hydrodynamics in iFlow consists of a sub-tidal
flow and a limited number of tidal constituents. In the remainder of this
paper we will assume that these tidal constituents are the

As a consequence of this harmonic decomposition, the equations are solved for each frequency component. This eliminates the need to solve the equations by time-stepping. This is a major advantage when computing (dynamic) equilibrium states of the hydrodynamics and sediment concentration, as iFlow can compute these states immediately. This is in contrast to time-stepping models, which often need many time steps and a large computational time to go from an initial state to the equilibrium state.

Details of the equations per frequency component can be found in the manuals.
For the case where the leading-order eddy viscosity, eddy diffusivity,
partial slip parameter and fall velocity are constant in time, this procedure
is the same as in

Under certain assumptions about the external forcing, the resulting frequency
components of the solutions form an especially well-analysable set. We will
call these assumptions the

the leading-order hydrodynamics is only forced by an

the first-order is forced only by an

the river discharge only appears at first order;

the eddy viscosity and partial slip parameter do not vary on the tidal timescale;

the fall velocity and eddy diffusivity do not vary on the tidal timescale; and

the leading-order density variation only contains a sub-tidal and

Under these assumptions the leading-order hydrodynamics describes the linear
propagation of the

Assuming the standard forcing assumptions hold, the leading-order sediment
dynamics contains the sub-tidal,

The main advantage of the standard forcing assumptions is their effect on the
morphodynamic equilibrium condition, Eq. (

We can distinguish between three types of transport terms. The first
describes the covariance between the velocity and concentration, i.e.

In addition to these terms, the model includes the sub-tidal transport by

The second type of transport term is the covariance between the velocity,
concentration and the varying water surface elevation, with dominant
contribution

The final type of transport terms are the terms involving the horizontal eddy
diffusivity,

Under the standard assumptions, the morphodynamic equilibrium condition thus
yields an extensive set of sediment transport terms, which together should
sum to zero. By investigating the separate transport terms, it can be
inferred which of these mechanisms promote sediment export and which promote
sediment import. An example of this is provided in
Sect.

The iFlow hydrodynamics and sediment dynamics modules offer two ways of
solving the equations: semi-analytical and numerical. The semi-analytical
method follows

Allowed forcing and turbulence options in the semi-analytical and numerical solution methods.

The numerical method was introduced, because the assumptions on the forcing
in the semi-analytical method can be too restrictive for specific
applications. The numerical method allows for arbitrary vertical profiles of
the eddy viscosity, eddy diffusivity and fall velocity. The numerical method
also allows for releasing the standard forcing assumptions. It allows any
number of tidal constituents as long as they are overtides of a base
component, often the

Some of the additional functionality of the numerical method affects the
sediment transport balance. The possible addition of more harmonic components
leads to additional transport terms, such as a transport contribution due to
the

The choice to keep a simulation within the restrictions of the semi-analytical method or to extend it to the full possibilities of the numerical method thus has a direct effect on the ability to analyse the results. This is an example of the classical trade-off between model complexity and ability to analyse the results as was mentioned in the introduction. A major strength of iFlow is that it offers one software environment where one can experiment with the degree of complexity required for a simulation for a specific application.

iFlow provides a number of modules to parametrize the eddy viscosity and
roughness parameter (see also Table

In order to resolve this arbitrariness, iFlow includes a set of modules named

Alternatively, the

iFlow implements four modules that implement the above

Finally, the

The iFlow standard modules include two types of salinity models: diagnostic
(i.e. prescribed) and prognostic (i.e. resolved). The diagnostic modules
prescribe a sub-tidal vertically uniform (well-mixed) salinity that varies in
the along-channel direction. The

The prognostic salinity model (modules

The hydrodynamic module relies on the water depth being positive and much
larger than the time varying surface elevation (see assumption 1 in
Sect.

The river-induced set-up is estimated numerically using the leading-order
momentum and depth-averaged continuity equations, assuming it is purely
forced by a constant discharge

The reference level still depends on the eddy viscosity. If a

iFlow's standard sensitivity analysis module

Modules used in two stages of the case studies, put into the correct order and including iteration loops over groups of modules.

The use of a 2DV perturbation approach for hydrodynamics or sediment dynamics
similar to iFlow's semi-analytical method has been demonstrated before by
e.g.

Here, iFlow is applied to two case studies. The aim of these cases is to show
the application of iFlow, demonstrate ways it can be used to analyse the
results and qualitatively compare the model results to measurements. While
this aim requires discussing some of the physical mechanisms observed in the
model, these physical mechanisms are not the focus of this section. The first
case study is an assessment of hydrodynamic effects of the river discharge on
the tidal propagation in the Yangtze River, China. This case demonstrates
some of the advanced hydrodynamic settings in iFlow, including the use of the
reference level, leading-order river discharge and velocity-dependent eddy
viscosity. Due to the inclusion of the leading-order river discharge, this
can only be done using the numerical implementation of the modules in iFlow.
The calibration of this model is also demonstrated. The second case study
presents an assessment of the estuarine turbidity maximum (ETM) in the
Scheldt River estuary. Here, we will use the standard assumptions on the
forcing (see Sect.

As a result of iFlow's flexible modular structure, the modules used are
different from application to application. The modules used in the two
applications presented below are shown in
Fig.

The tidal part of the Yangtze River in China stretches from its mouth near
Shanghai approximately to Datong, 560

The tidal Yangtze River. Adapted from

Cost function that measures the error between the measurements of
the water level amplitude and model results for a range of values of the
calibration parameter

Measurements of the width-averaged bed level and near-surface width are
provided by

We will distinguish between two forcing conditions: wet and dry season
conditions. For both we will assume average tidal conditions, for which the
primary forcing components are a leading-order

Water level amplitude

The model is calibrated by adjusting the roughness parameter

The resulting water level amplitude and phase are plotted in
Fig.

Water level amplitude for the Yangtze case when the computation of
the reference level is omitted. The figure shows results for a dry season
situation (solid line and dots) and a wet season situation (dashed line and
crosses); see Fig.

We will demonstrate how the model can be used to uncover the main processes
that cause the differences in tidal propagation between the dry and wet
seasons. The non-linear first-order processes that involve tide–river
interactions are advection, tidal return flow and velocity–depth asymmetry.
Through the perturbation method, these processes can be inferred directly
from the model results. The correction to the

The model is rerun without the reference level module (i.e.

The effect of the river flow on the eddy viscosity and partial slip parameter
can be assessed by switching off the dependency of these quantities on the
river flow. The

Water level amplitude for the Yangtze case when the effect of the
river discharge on the eddy viscosity and partial slip parameter is omitted.
The figure shows results for a dry season situation (solid line and dots) and
a wet season situation (dashed line and crosses); see
Fig.

The Scheldt River estuary.

Tidally averaged sediment concentration for summer and winter conditions. Parameter values corresponding to the Scheldt Estuary.

The tidal Scheldt River, situated in the south-west of the Netherlands and
north-west of Belgium, runs from its mouth in the North Sea to a set of locks
and sluices near Ghent, 160

The model is forced by a leading-order

The river discharge varies over the seasons, with an average summer discharge
of 30

The model for the Scheldt Estuary is calibrated by tuning the partial slip
roughness parameter

The five most important tidally averaged sediment transport contributions, rescaled with the maximum transport. Negative values indicate export, while positive values indicate import. Total net transport of all terms added yields zero. The scaled tidally averaged depth-averaged sediment concentration (grey dashed line) is plotted in the background for reference. Parameter values corresponding to the Scheldt Estuary.

Using the above parameter values and settings we compute the tidally averaged
sediment concentration for average summer and winter conditions; see
Fig.

In order to further investigate the underlying physical mechanisms of the ETM
dynamics in the Scheldt Estuary, we look closer at the individual processes
that contribute to the sediment transport. As explained in
Sect.

To illustrate iFlow's capacity to easily perform an extensive sensitivity
analysis, we further analyse the influence of the external

We have demonstrated that iFlow provides a flexible and versatile modular environment for modelling flows and sediment transport in estuaries and tidal rivers. The model focusses on idealized approaches that allow the systematic analysis of physical processes and the sensitivity of these processes to model parameters. Due to the modular nature, iFlow offers a software environment where users can easily adjust the processes included in a simulation, thereby allowing users to adjust the degree of complexity, computational time and ability to analyse the results to a specific application. The iFlow core supports these adjustments by automatically taking care of the communication between modules, order of modules and smooth coupling of modules that use different solution methods. iFlow version 2.4 additionally includes a number of standard modules especially designed to analyse individual processes affecting the flow and sediment transport.

Sensitivity of the location of the ETM to varying external

This has been illustrated in two applications of iFlow to the study of non-linear hydrodynamic interactions in the Yangtze River and sediment trapping mechanisms in the Scheldt River. By a systematic approach of switching particular processes on and off and by the decomposition of the results according the underlying physical processes, the model allows for a unique insight into the physics of these systems. As iFlow allows for a quick set-up and calibration of a model and quick sensitivity study, the model is especially well suited to gain a first insight into the essential processes of a system and response of the system to changes. The comparison of the model results with observations in these systems should be mainly interpreted qualitatively, focussing on the relative importance of processes, behaviour and sensitivity. Nevertheless, in the shown applications, there is a good quantitative correspondence between the model result and observations considering the degree of schematization in the model.

Both case studies used different modules and interactions, so that the model complexity suits the analysis relevant to the application. This extendibility, interchangeability and ease of analysis form the main ideas of iFlow. These ideas are reflected in the architecture of the modular set-up, data management and the modules offered within this version of the model. Wrapped around this is a set of tools and modules to support input, output and visualization of the results to make the model user-friendly.

As the structure of iFlow can be adapted and modules can be added easily by
new users, there is no such thing as a single iFlow model. Also, the provided
default modules for hydrodynamics, turbulence and sediment dynamics may be
replaced if this is useful for a particular application. For example, these
modules may be replaced by a coupling to a complex model

The future ambitions for the model involve further developments of modules for turbulence and morphology and for the transport of sediment, salinity and nutrients. Users are encouraged to contribute to this development by developing and sharing modules or sharing model applications.

When using iFlow in any scientific publication, technical report or otherwise formal writing, authors are strongly requested to cite this paper and mention the name iFlow.

The iFlow code is property of the Flemish Dutch Scheldt Committee (VNSC) and is licensed under LGPL (GNU Lesser General Public License). In summary, this means that the code is open source and may be used freely for non-commercial and commercial purposes. Any alterations to the existing iFlow source code (core and modules) must be licensed under LGPL as well and are therefore open source. However, new modules or a coupling between iFlow and other software may be published under a different licence. Nevertheless, users of iFlow are encouraged to make their own developed modules and model applications open source as well.

iFlow is written in Python 2.7 and the code is available through GitHub
(

The authors declare that they have no conflict of interest.

The development of iFlow is funded by VNSC (