As a first step, iFlow reads the input file (Fig. a) and compiles a list of the modules. In order to determine the order in which to call these modules, iFlow needs information on the input required and output returned by each module. This information is documented in a registry file (Fig. b), which is provided with the modules and does not need to be given on input. The call stack is made by matching the output provided by each module to the input required by the other modules, such that the required input is available at the moment a module is called.

The input file lists four modules with a specific task each: RegularGrid for making a grid, Geometry2DV for setting the model geometry, Hydrolead for computing the leading-order hydrodynamics and KEFitted as turbulence closure. At the end, the input file lists the variables that are required by the user, e.g. for saving or plotting; here these variables are the leading-order velocity u0 and eddy viscosity Av (more information on these variables and the underlying equations will be provided in Sects.  and ). The registry file (Fig. b) contains the same modules with their input and output variables. Using the registry file, iFlow assesses that the outputs of the Hydrolead module, u0, and of KEFitted, Av are needed to obtain the required variables. iFlow then constructs the call stack by determining the modules needed in order to run Hydrolead and KEFitted. Focussing on Hydrolead, it follows from the registry that this module requires nine input variables. These variables may be provided in the input file, by the output of other modules or in a configuration file (not shown here; see the manual for details). Three of these input variables, A0, phase0 and Q0, are provided in the input file, while the other six follow from the output of other modules. By matching all the input for and output of the four modules, iFlow constructs the call stack depicted in Fig. c.

The call stack shows a loop between Hydrolead and KEFitted, which is necessary as both require each other's output as input. This interdependency is resolved by defining KEFitted as an iterative module. Behind the keyword inputInit in the registry of KEFitted it can be seen that this module does not require the flow velocity u0, computed by Hydrolead, for its first run. In subsequent runs of the iteration, u0 is required. iFlow recognizes the interdependency and constructs the smallest possible iteration loop, here involving the two interdependent modules only. The number of iterations follows dynamically from a convergence criterion that is implemented in the KEFitted iterative module.

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 DataContainer in the iFlow core. It collects the module's output upon completion and handles the input data requests by each module; see Fig. c. To simplify the interchangeability of modules and the analysis of data, the DataContainer supports various data types and data decompositions, as is discussed more elaborately below.

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, Geometry2DV sets a constant depth H, which is saved as a scalar value (see also Fig. c). Other implementations of the depth allow for depths varying over the horizontal x coordinate according to prescribed analytical functions or data on a grid. This difference in the way the depth is prescribed should not influence the functioning of other modules. The DataContainer allows this by providing a uniform interface to all data types. This means that there is one command for a module to retrieve H (or any other variable) regardless of the underlying data type. The DataContainer handles this command based on the data type. For example, the RegularGrid module requests H on grid points. If H is stored as a scalar, the DataContainer automatically extends this scalar value to all requested points. If H is stored as an analytical function description, this function is evaluated at the grid points. Data stored on numerical grids may as well be used as input to analytical functions. If the numerical data are requested at other coordinates than the grid points, the DataContainer automatically interpolates these data to the requested coordinates. Similarly, a module can access the derivative of a variable. iFlow sees whether an analytical function or numerical data for this derivative is provided and, if not, will automatically perform numerical differentiation.

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.  for the hydrodynamics and sediment dynamics modules. Within iFlow's philosophy, it should be possible to interchange these modules with others that do not make decompositions or make decompositions in different components, without affecting other modules. The DataContainer supports this using sub-variables. This is illustrated in Fig. c for the flow velocity variable u0. This has contributions induced by the tide and by the river discharge, such that the sum of both yields the total flow velocity u0. The KEFitted turbulence model does not require this decomposition and does not necessarily need to be aware that such a decomposition exists. It can therefore simply request u0 and iFlow will automatically sum the tide and river contributions. Alternatively a module may request a list of all the sub-variables of u0 and request each of these contributions separately.

The DataContainer as an interface for different data types and decompositions of data thus ensures that modules with different (e.g. analytical and numerical) solution methods can be used together. Additionally, a module can easily be replaced by a different module that results in the same output variables through other processes, without requiring any changes to other modules.

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, general, analytical2DV, numerical2DV and semi_analytical2DV, containing auxiliary modules and modules using analytical, numerical or semi-analytical (i.e. largely analytical, with numerical components) solution methods respectively. All included standard modules and the location where they can be found are listed in Table .

A short introduction to many of these modules is provided in Sects. –. Section  introduces the standard module for geometry and grid. The standard modules for hydrodynamics and sediment dynamics are introduced in Sect. . A short explanation of other modules related to salinity, turbulence, reference level and sensitivity analyses is given in Sect. .

The water motion is described by the Reynolds-averaged width-averaged shallow water equations that solve for the water level elevation ζ(x,t), horizontal velocity u(x,z,t) and vertical velocity w(x,z,t). Here, t denotes time. We neglect the effects of Coriolis and assume that density variations are small compared to the average density, allowing for the Boussinesq approximation. The resulting momentum equation reads e.g. ut+uux+wuz=-gζx-g∫zR+ζρxρ0dz̃+Avuzz. Here, g is the acceleration of gravity, ρ is the density with reference density ρ0 and the vertical eddy viscosity is denoted by Av. The subscripts x, z and t in the equations denote derivatives with respect to these dimensions. The background horizontal eddy viscosity Ah has been neglected. The momentum equation has a no-stress boundary condition at the free surface and a partial slip condition at the bed Avuz=0at z=R+ζ,Avuz=sfuat z=-H. The parameter sf denotes the partial slip roughness coefficient. For sf→∞, the partial slip condition reduces to a no-slip condition u=0. The partial slip law becomes a quadratic bottom friction law if sf is made dependent on the local velocity (see also Sect. ).

In addition we use the width-averaged, depth-integrated continuity equation, which reads ζt+1BB∫-HR+ζudzx=0 with boundary conditions ζ=Aat x=0,B∫-HR+ζudz=-Qat x=L. Here A=A(t) is the time-dependent tidal forcing at the seaward boundary and Q is the river discharge imposed on the landward boundary. Finally the width-averaged continuity equation reads wz+1BBux=0, with a non-permeability condition at the bed w+uHx=0at z=-H.

The sediment dynamics is described by the width-averaged sediment mass balance equation, which solves for the sediment concentration c(x,z,t) in the model domain. The sediment is assumed to consist of non-cohesive, fine particles that have a uniform grain size (i.e. constant settling velocity) and are transported primarily as suspended load. At the surface we do not allow for transport of sediment through the water surface and at the bottom we assume that the diffusive flux equals the erosion flux E. The resulting equation is e.g. ct+ucx+wcz=wscz+1B(BKhcx)x+(Kvcz)z, with vertical boundary conditions wsc+Kvcz-Khcxζx=0at z=R+ζ,-Kvcz-KhcxHx=Eat z=-H.

In Eq. (), ws is the settling velocity and Kh and Kv are the horizontal and vertical eddy diffusivity. Boundary condition  is valid under the assumption that Hx is much smaller than one. We assume that Kv is related to the vertical eddy viscosity coefficient Av as Kv=Av/σρ, where σρ is the Prandtl–Schmidt number that converts viscosity to diffusivity. The erosion flux E is related to the so-called reference concentration c⋆ through E=wsc⋆. In turn, the reference concentration is defined as c⋆(x,t)=ρsτb(x,t)ρ0g′dsa(x), where ρs is the density of sediment, τb(x,t)=ρ0Avuz is the bed shear stress (again assuming Hx≪1), g′=g(ρs-ρ0)/ρ0 is the reduced gravity, ds is the mean grain size, and a(x) is the availability of easily erodible fine sediment.

The dimensionless sediment availability function a(x) describes how the sediment is distributed over the system. This function is unknown and can be determined by imposing the so-called morphodynamic equilibrium condition . This condition implies that the total amount of sediment in the estuary varies on a timescale that is much longer than the timescale at which the easily erodible sediment is redistributed over the system. In other words, it is assumed that the amount of sediment in the system is a constant, and we will look for the equilibrium distribution of this sediment in the estuary. Equilibrium in this context means that there is a balance between the tidally averaged erosion and deposition at the bottom or, equivalently, that the tidally averaged transport of sediment is divergence free. The latter is described by the morphodynamic equilibrium condition B∫-HR+ζ(uc-Khcx)dzx=0, where uc is the advective sediment transport and Khcx is the diffusive sediment transport. As a boundary condition to this expression it is prescribed that the upstream river carries negligibly little sediment, so that there is no sediment influx from the landward boundary at x=L. The resulting morphodynamic equilibrium condition can be written as B∫-HR+ζ(uc-Khcx)dz=0. This implies no net (i.e. tidally averaged) transport of sediment in the entire domain. As the concentration c in Eq. () depends on the availability a(x), the above condition is an equation for a. This determines the availability up to a constant factor a*, which should be prescribed on input. This factor determines the total amount of sediment in the system. As the amount of sediment in the system directly affects the concentration in the water column, the absolute magnitude of the concentration may be calibrated directly by changing a*. The relevant result of the sediment model therefore consists of the relative differences between concentrations at different locations along the estuary instead of the absolute magnitude of the concentration.

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 leading-order terms. Terms that are significantly smaller than these leading-order terms will be further categorized according to their relative importance. The most dominant terms, after separating leading-order terms, are called first-order terms. This categorization continues, with all terms of second or higher order generally referred to here as higher-order terms.

The scaling requires four crucial assumptions. Firstly we assume ε=ζH≪1, i.e. the ratio of the typical water level amplitude to the depth is much smaller than unity. The small parameter ε is used to define of which order a term is. A term is defined to be of first order if its typical relative magnitude is of order ε compared to the leading-order terms. Similarly, an nth-order term is of order εn with respect to the leading-order terms.

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 uux+wuz in Eq. () and ucx+wcz in Eq. () scale with ε. It is found that, by these two assumptions, the leading-order equations are all linear, while all non-linearities in the velocity, concentration and water level elevation only appear as first-order or higher-order effects.

Thirdly, it is assumed that the horizontal density gradient is small. More precisely, the internal Froude number should be of order ε or, equivalently, ρxLtide/ρ0 should be of order ε2, where Ltide is the length of tidal influence. As a consequence, the baroclinic pressure term g∫zR+ζρxρ0dz̃ in Eq. () is of order ε.

Finally, the horizontal diffusion term Khcxx is assumed to be of order ε2.

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 u, w, ζ an c are written as an asymptotic series ordered in the small parameter ε, i.e. u=u0+u1+u2+…,w=w0+w1+w2+…,ζ=ζ0+ζ1+ζ2+…,c=c0+c1+c2+…, where [⋅]0 denotes a quantity at leading order, [⋅]1 denotes a quantity of order ε, [⋅]2 order ε2, etc. In addition, the eddy viscosity and diffusivity, density, tidal forcing, river discharge and fall velocity are written as similar series. These series are substituted into the equations. The resulting equations are still equivalent to the original system of equations. The analysis up to this point has merely identified what terms in the equations are of leading and higher orders.

The perturbation approach is illustrated here for the momentum and depth-averaged continuity equations for the hydrodynamics, which may be used to compute u and ζ. A first approximation of the equations for the hydrodynamics can be made by neglecting all terms of first and higher orders. The leading-order momentum equation is formulated as ut0=-gζx0+Av0uz0z with boundary conditions Av0uz0=0at z=R,Av0uz0=sfu0at z=-H. The leading-order depth-averaged continuity equation reads ζt0+1BB∫-HRu0dzx=0 with boundary conditions ζ0=A0︸tideat x=0,B∫-HRu0dz=Q0︸riverat x=L. Compared to the original equations, these leading-order equations omit the non-linear advection, density forcing and all occurrences of ζ in the integration boundaries. These terms feature in the first- and higher-order equations. As a result the leading-order equations have become linear and contain two forcing terms, which are named in the equation: the tidal forcing and river discharge. The linearity is a powerful property, as it allows for applying the principle of superposition. This means that the effect of each of the tidal forcing and river discharge may be evaluated separately and independently and may be summed to obtain the total solution. This is the principle that allows iFlow to make a decomposition of the physics into the responsible forcing mechanisms.

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 u1 and ζ1. The first-order momentum equation is given by ut1+u0ux0+w0uz0︸advection=-gζx1-g∫zRρx0ρ0dz̃︸density+Av0uz1z+Av1uz0z︸eddy visc., with boundary conditions Av0uz1=-Av0uz1zζ0︸vel.-dep. asym.-Av1uz0︸eddy visc.at z=R,Av0uz1=sfu1-Av0uz1︸eddy visc.at z=-H. The first-order depth-averaged continuity equation reads ζt1+1BB∫-HRu1dz+Buz=R0ζ0︸tidal return flowx=0 with boundary conditions ζ1=A1︸tideat x=0,B∫-HRu1dz=Q1︸river-Buz=R0ζ0︸tidal return flowat x=L. The forcing terms to these first-order equations are defined as the known terms that do not depend on u1 or ζ1 and are again marked by a name in the equation. The forcing mechanisms are the first-order tidal forcing A1 at the entrance, first-order river discharge Q1, the density forcing and linear estimates of the non-linearities acting on the flow. These non-linearities include the effects of momentum advection, the tidal return flow and velocity–depth asymmetry. The tidal return flow is the flow that compensates for the mass transport due to correlations between the tidal velocity and surface variation. The velocity–depth asymmetry accounts for the effect that the velocity profile differs between ebb and flood due to different water levels. Finally, temporal or spatial variations of the leading-order eddy viscosity may be included at first order, so that the interactions between these variations and the leading-order flow appear as a forcing at the first order. Note that some of these mechanisms appear in multiple places in the equations. As the equations are again linear, the principle of superposition allows iFlow to compute the effect of each of these forcing mechanisms separately and independently and sum them to obtain the total result. All forcing mechanisms to the leading- and first-order equations are summarized in Table .

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 E0. This erosion rate involves the leading-order bed shear stress τb0, which is derived from the leading-order velocity. The leading-order concentration thus is the concentration locally resuspended by the leading-order tide. The first-order equation describes a similar balance between vertical diffusion and the settling of sediment, but is forced by different components. Firstly, it is forced at the bed by the first-order erosion rate E1, which represents the erosion due to the first-order bed shear stress. This involves the first-order velocity and therefore the flow caused by all mechanisms that act on the first-order hydrodynamics. Secondly, the first-order balance is forced by horizontal sediment advection ucx+wcz, which results in what is known as spatial settling lag effects . Thirdly, the first-order balance involves a forcing from the covariance between the sediment concentration and the surface elevation. Finally, if the eddy diffusivity and fall velocity have first-order contributions, their covariances with the leading-order concentration appear as first-order effects as well. All forcing mechanisms on the leading- and first-order sediment balances are summarized in Table . Similar to the hydrodynamics, all the contributions to the sediment concentration by different forcing terms can be evaluated separately and independently due to the principle of superposition. The ordered sediment equations are described in the manuals.

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 M2 tide and its overtides, as these are the most common. In general, one can choose any single tidal base mode and its overtides in the model. The solution to the non-linear system of equations also consists of a sub-tidal component, the M2 tide and possibly infinitely many overtidal components. As the sediment dynamics is forced by the hydrodynamics, the sediment concentration is described by the same components. This means that the solution can be written as a sum of the sub-tidal component and these tidal constituents. However, instead of accounting for infinitely many components, the signal is truncated after p components, where p can be chosen arbitrarily. As an example, for the velocity u0 we then write u0=∑n=0pReu^n0eniωt, where u^n0 is the complex amplitude of the nth component of u0, where n=0 denotes the sub-tidal component, n=1 the M2 component, n=2 the M4 component, etc. A similar decomposition is made for all quantities that vary on the tidal timescale.

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 , also see the manual on the semi-analytical model implementation. If these assumptions do not hold, the matrix-solution procedure suggested by is followed, also see the manual on the numerical model implementation.

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 standard forcing assumptions. These are the same as in e.g. and are the following:

the leading-order hydrodynamics is only forced by an M2 constituent;

Under these assumptions the leading-order hydrodynamics describes the linear propagation of the M2 tide and only consists of an M2 frequency. The first-order hydrodynamics consists of a sub-tidal component forced by the river discharge and an M4 component forced by the external tidal forcing. The density-induced flow and non-linear components appearing at first order are also described by sub-tidal and M4 components. The first-order flow therefore describes the sources of tidal asymmetry, both caused by external forcing and internal generation.

Assuming the standard forcing assumptions hold, the leading-order sediment dynamics contains the sub-tidal, M4, M8, etc. components. The first-order sediment dynamics conversely contains the M2, M6, M10, etc. components. In many examples, the leading-order and first-order concentrations are truncated after the M4 tidal component. This is because the higher harmonics beyond the M4 component are unimportant for the net transport of sediment and are therefore of less interest.

The main advantage of the standard forcing assumptions is their effect on the morphodynamic equilibrium condition, Eq. (). This forms a sub-tidal balance of sediment transport terms at second order, which reads B∫-HRu0c1+u1c0+uriver1criver–river2-Khcx0-Khcriver–river,x2dz+uz=R0cz=R0ζ0=0.

We can distinguish between three types of transport terms. The first describes the covariance between the velocity and concentration, i.e. 〈∫-H0ucdz〉. The dominant covariance terms that result in a sub-tidal transport are 〈∫-HRu0c1dz〉 and 〈∫-HRu1c0dz〉. The term u0c1 only generates a sub-tidal transport due to the covariance between the leading-order M2 flow and M2 variation of the first-order concentration. The term u1c0 generates transport due to M4–M4 covariance and the product of both sub-tidal contributions. As the model computes the effect of different physical mechanisms contributing to u1 and c1 (see Table ), the transport terms can be subdivided further into the transport caused by particular physical mechanisms. This way, we obtain a subdivision of 〈∫-H0u1c0dz〉, with components named after the different contributions to u1. Likewise, the components in the subdivision of 〈∫-H0u0c1dz〉 are named after the contributions to c1. One exception to this is the “erosion” contribution to c1, which is again subdivided further into the u1 velocity contributions that cause the erosion.

In addition to these terms, the model includes the sub-tidal transport by 〈∫-HRuriver1criver–river2dz〉, i.e. the covariance between the river-induced velocity and the river-induced sediment resuspension. This transport is a fourth-order term according to the scaling and therefore formally does not belong in this balance. However, it typically becomes the dominant term near the end of the tidal influence where all tidally induced transport mechanisms vanish. It is therefore an important mechanism to avoid an unrealistically high degree of sediment trapping at the upstream boundary.

The second type of transport term is the covariance between the velocity, concentration and the varying water surface elevation, with dominant contribution u0c0ζ0. No further subdivision of this term can be made. This term represents the drift of sediment with the moving surface and is largely compensated for by the tidal return flow, which is part of 〈∫-HRucdz〉. Therefore we will consider the transport due to this drift and the tidal return flow together as one term under the name “tidal return flow”.

The final type of transport terms are the terms involving the horizontal eddy diffusivity, 〈Khcx0〉 and 〈Khcriver–river,x2〉. It is assumed that the horizontal diffusivity is constant in time, so that the term Khcx1 is zero-averaged over the tide. The diffusive transport thus describes horizontal background diffusion of the tide- and river-induced resuspended sediment. Physically, this background diffusion is caused by unresolved flows such as lateral circulation.

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 and uses fully analytical formulations for the vertical velocity and sediment profiles, but uses a numerical method to solve for the water level elevation. This solution method is fast and accurate, but may only be applied if the forcing satisfies certain conditions. The required conditions are the standard forcing assumptions above, together with the requirement that the eddy viscosity, eddy diffusivity and fall velocity are uniform over the water column.

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 M2 tide. These tidal constituents may be imposed at either the leading or the first order depending on the situation. The river flow may additionally be imposed at the leading order, if appropriate. The eddy viscosity, eddy diffusivity, partial slip parameter and fall velocity are also allowed to vary in time at leading or first order. This means that the numerical model may be used with the same restrictions as the semi-analytical method, but these restrictions may be relaxed for further functionality. This is at the cost of potentially larger computational times and lower accuracy, depending on the numerical grid resolution. An overview of the differences between the restrictions in the semi-analytical and numerical methods is provided in Table .

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 M6–M6 covariance between the velocity and concentration. When a sub-tidal or M4 velocity is entered at the leading-order velocity, e.g. through the river discharge or externally prescribed M4 tide, the covariance between the leading-order velocity and concentration, 〈∫-H0u0c0dz〉, yields a sub-tidal contribution. According to the scaling, this contribution dominates over all transport contributions in Eq. (), so that those contributions should no longer be considered. The term 〈∫-H0u0c0dz〉 in the new balance can again be subdivided according to the physical mechanisms that contribute to the velocity and concentration. However, the balance now only concerns the leading-order velocity and concentration, for which the model computes only one or two contributions (see Table ). The subdivision of the transport therefore leads to much fewer terms and typically provides less insight into the underlying physics.

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 ), referred to as the turbulence model. The simplest turbulence model available is implemented in the TurbulenceUniform module and assumes a vertically uniform eddy viscosity and constant partial slip roughness parameter, which may only vary with the depth , according to Av=Av0H+RH(x=0)m,sf=sf,0H+RH(x=0)n, with Av0, sf,0, m and n provided as input to the model. The input parameters Av0 and sf,0 may include time-variations (in combination with the numerical hydrodynamics only). This turbulence model is the usually chosen highly simplified turbulence model and was applied in several studies, including , and . However, showed that multiple values of the calibration parameters Av0 and sf,0 result in equivalent results. Therefore there is a degree of arbitrariness to the calibration parameters in this turbulence model.

In order to resolve this arbitrariness, iFlow includes a set of modules named KEFitted. These models depend only on one calibration parameter and include more physical dependencies of the eddy viscosity. These KEFitted turbulence modules define parametrizations for Av and sf derived by fitting the results of a one-dimensional numerical model with k-ε closure for a large number of barotropic tidal model configurations. The turbulence closures provide a number of options. The most important option is the choice of roughness parameter to provide on input. If the roughness parameter sf,0 is provided, the turbulence model uses the relation Av=0.5sf(H+R+ζ),sf=sf,0H+RH(x=0)n. This model only has the calibration parameter sf,0 and requires a choice for n. It thus eliminates the need to calibrate Av0 and m. To leading order, because it is assumed that ζ≪H+R, this model is the same as Eqs. ()–() with m=1+n and Av0=0.5sf(H(x=0))m. This model is recommended over Eqs. ()–(), as it only has a single calibration parameter and thus leads to a definite best calibration parameter setting. However, note that this relation is derived for a unidirectional flow and its is assumed that any flow in another direction does not affect this relation.

Alternatively, the KEFitted turbulence models may be provided with a roughness parameter z00*. The formulations for the eddy viscosity and partial slip roughness then read as Av=αu*(H+R+ζ)f1(z0*),sf=βu*f2(z0*),z0*=z00*H+RH(x=0)n, where u* is the bed friction velocity, which may be related to the depth-averaged velocity (see ). The parameters z00* and n should be provided as input, and α, β, f1(z0*) and f2(z0*) are known hard-coded parameters and functions obtained by fitting results of the k-ε model (see the manual for details). This model therefore also contains only one calibration parameter z00* and requires a choice for n. These formulations relate the vertically uniform eddy viscosity and partial slip parameter to the local bed shear stress velocity and water depth. As a result, the bottom boundary condition for the hydrodynamic Eq. () has become a quadratic friction law. This model introduces non-linearity, as there now is a mutual relation between the flow velocity and the water surface elevation on the one hand and eddy viscosity and the partial slip parameter on the other hand. This non-linearity is resolved by an iteration loop over the turbulence and hydrodynamic modules, which is automatically constructed by the iFlow core as exemplified in Sect. . Due to the non-linearity, this model introduces more complexity compared to the previous models and is therefore only recommended when the case at hand requires this complexity, for example because of large variations in u* in space or time. An example of this is given in Sect. .

iFlow implements four modules that implement the above KEFitted relations. The KEFittedLead, KEFittedFirst and KEFittedHigher modules make an ordering of the above equations to determine the leading-order, first-order and higher-order eddy viscosity and partial slip parameter. The KEFittedTruncated module uses the sum of all computed orders of the velocity and water surface elevation to compute a total eddy viscosity and roughness parameter without ordering (i.e. a truncation method).

Finally, the TurbulenceParabolic turbulence model is similar to Eqs. ()–(), but assumes the eddy viscosity to have a parabolic profile in the vertical direction. This turbulence model assumes sf→∞, so that the bottom boundary condition for the hydrodynamics reduces to a no-slip law. The roughness is instead described by a roughness height z0. The formulations for Av and z0 read as Av=Av0H+RH(x=0)m(zs*-z*)(z0*+z*+1),z0=z0*H+RH(x=0)n+1. The parameters Av0 and z0*=z0(x=0)/H(x=0), m and n are provided as input, z*=z/(H+R) and the dimensionless surface roughness zs* is determined by the model such that Av equals 10-6 m2 s-1 at the surface, i.e. approximately the molecular viscosity. The parabolic eddy viscosity profile represents a more realistic shape in barotropic flows and therefore results in more realistically shaped velocity profiles. However, this model faces a similar degree of arbitrariness in the choice of Av0 and z0* as in Eqs. ()–() and may only be used in combination with the numerical solution method.

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 SalinityHyperbolicTangent module formulates this as (see also ) s=ssea21-tanh⁡x-xcxL and SalinityExponential formulates this as s=sseaexp⁡-xLs.

The prognostic salinity model (modules SalinityLead, SalinityFirst) follows work done by and . The model is based on the perturbation approach, where it is assumed that the leading-order salinity consists of a sub-tidal vertically uniform (well-mixed) salinity. Vertical and temporal variations of the salinity appear at higher orders. For more information we refer to .

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 model fails or becomes inaccurate if the bottom lies above or close to MSL. In many cases this problem can be resolved by the iFlow ReferenceLevel module. This module computes a quick estimate of the sub-tidal water level elevation based on the river-induced set-up. This is often sufficient, because the river is often the dominant flow term in the most upstream reach, where the bottom level is highest.

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 Q and the resulting water level elevation is given by R. These equations read as -gRx+Avuzz=0,B∫-HRudz=Q. This system is non-linear in R as the integral in the second equation contains R in the integration boundary and u, which depends on R according to the first equation. Nevertheless, the system can be solved without iterating by starting at the mouth and working upstream. At the mouth (x=0), R=0 by definition. Therefore Rx can be computed from the above system of equations. The value of R at the next grid point x=Δx follows from a simple first-order routine: R(Δx)=R(0)+Rx(0)Δx. The total reference level follows by repeating this procedure for all horizontal grid cells. More accurate computations of the river-induced set-up follow from the hydrodynamic modules, so that the relatively low numerical accuracy of the reference level computation will not reduce the precision of the overall result.

The reference level still depends on the eddy viscosity. If a KEFitted turbulence model is used, the eddy viscosity in turn depends on the reference level. To resolve this interdependency efficiently, without needing to iterate between the turbulence model and reference level module, the KEFitted turbulence models have a built-in routine to compute the reference level. Therefore, the ReferenceLevel module can be omitted when the KEFitted module is used.

iFlow's standard sensitivity analysis module Sensitivity provides a powerful analysis tool, by easily allowing a user perform a full model simulation for various values of one or more input variables. On input, the user provides the names of the variables to loop over, as well as a list with the values for these variables. A final input parameter indicates whether all combinations of parameter values should be tested or whether the values of all variables should be changed simultaneously. The iFlow core then automatically decides which modules should be included in the loop and runs these modules for all prescribed parameter settings, saving the results to a file after each loop. The sensitivity analysis is therefore a general tool that may be combined with any set of modules to loop over any set of variables and values. An example of the use of the sensitivity module is given in the model evaluation in Sect. .