Welcome to XBeach’s documentation!¶

Contents:

User manual¶

Introduction¶

XBeach is an open-source numerical model which is originally developed to simulate hydrodynamic and morphodynamic processes and impacts on sandy coasts with a domain size of kilometers and on the time scale of storms. Since then, the model has been applied to other types of coasts and purposes.

The model includes the hydrodynamic processes of short wave transformation (refraction, shoaling and breaking), long wave (infragravity wave) transformation (generation, propagation and dissipation), wave-induced setup and unsteady currents, as well as overwash and inundation. The morphodynamic processes include bed load and suspended sediment transport, dune face avalanching, bed update and breaching. Effects of vegetation and of hard structures have been included. The model has been validated with a series of analytical, laboratory and field test cases using a standard set of parameter settings.

XBeach has two modes: a hydrostatic and a non-hydrostatic mode. In the hydrostatic mode, the short wave amplitude variation is solved separately from the long waves, currents and morphological change. This saves considerable computational time, with the expense that the phase of the short waves is not simulated. A more complete model is the non-hydrostatic model which solves all processes including short wave motions, but with more computational demand.

The original application, funded by the U.S. Corps of Engineers in the framework of the Morphos project and the U.S. Geological Survey, was to be able to assess hurricane impacts on sandy beaches. Since then with funding from the Dutch Public Works Department, the model has been extended, applied and validated for storm impacts on dune and urbanized coasts for the purpose of dune safety assessments. With support from the European Commission XBeach has been validated on a number of dissipative and reflective beaches bordering all regionall seas in the EU.

Beyond sandy coasts, the model has been applied to coral fringing and atoll reefs, in cooperation with and with funding by the University of Western Australia, the USGS and the Asian Development Bank. The model now also includes vegetative damping effects, with support of the U.S. Office of Naval Research.

The non-hydrostatic model has been developed initially by the TU Delft (as a prototype version of the SWASH model). For the purpose of simulating the morphodynamic processes on gravel beaches, the model was extended and validated with support from the University of Plymouth. In this mode, ship-induced waves can be simulated as well, demonstrating the flight that the model has taken since its first inception.

This development of XBeach could not have been possible without all of the above mentioned funding agencies and partners. It would also not have been possible without the enthusiastic, critical and constructive approach of all consultants, researchers, M.Sc. and Ph.D. students who have taken up XBeach, and made it into the tool that it is today.

This manual serves as an introduction to the model and a reference guide to its many functionalities, options and parameters. We sincerely hope that this document will help existing and new researchers apply the model for their purposes and advance our knowledge of coastal hydro- and morphodynamics.

Processes and model formulation¶

Domain and definitions¶

Coordinate system¶

XBeach uses a coordinate system where the computational x-axis is always oriented towards the coast, approximately perpendicular to the coastline, and the y-axis is alongshore, see Fig. 1 and Fig. 2. This coordinate system is defined in world coordinates. The grid size in x- and y-direction may be variable but the grid must be curvilinear. Alternatively, in case of a rectangular grid (a special case of a curvilinear grid) the user can provide coordinates in a local coordinate system that is oriented with respect to world coordinates (xw, yw) through an origin (xori, yori) and an orientation (alfa) as depicted in Fig. 1. The orientation is defined counter-clockwise w.r.t. the xw-axis (East).

Rectangular coordinate system of XBeach

Grid set-up¶

The grid applied is a staggered grid, where the bed levels, water levels, water depths and concentrations are defined in cell centers, and velocities and sediment transports are defined in u- and v-points, viz. at the cell interfaces. In the wave energy balance, the energy, roller energy and radiation stress are defined at the cell centers, whereas the radiation stress gradients are defined at u- and v-points.

Velocities at the u- and v-points are denoted by the output variables uu and vv respectively; velocities u and v at the cell centers are obtained by interpolation and are for output purpose only. The water level, zs, and the bed level, zb, are both defined positive upward. uv and vu are the u-velocity at the v-grid point and the v-velocity at the u-grid point respectively. These are obtained by interpolation of the values of the velocities at the four surrounding grid points.

The model solves coupled 2D horizontal equations for wave propagation, flow, sediment transport and bottom changes, for varying (spectral) wave and flow boundary conditions.

Curvilinear coordinate system of XBeach

Hydrodynamics options¶

XBeach was originally developed as a short-wave averaged but wave-group resolving model, allowing resolving the short wave variations on the wave group scale and the long waves associated with them. Since the original paper by [RRvD+09] a number of additional model options have been implemented, thereby allowing users to choose which time-scales to resolve:

Stationary wave model (keyword: wavemodel = stationary), efficiently solving wave-averaged equations but neglecting infragravity waves;
Surfbeat mode (instationary) (keyword: wavemodel = surfbeat), where the short wave variations on the wave group scale (short wave envelope) and the long waves associated with them are resolved;
Non-hydrostatic mode (wave-resolving) (keyword: wavemodel = nonh), where a combination of the non-linear shallow water equations with a pressure correction term is applied, allowing to model the propagation and decay of individual waves.

In the following these options are discussed in more detail. Important to note that all times in XBeach are prescribed on input in morphological time. If you apply a morphological acceleration factor (keyword: morfac) all input time series and other time parameters are divided internally by morfac. This way, you can specify the time series as real times, and vary the morfac without changing the rest of the input files (keyword: morfacopt = 1).

Principle sketch of the relevant wave processes

Stationary mode¶

See also

The stationary mode is implemented in mod:wave_stationary_module.

In stationary mode the wave-group variations and thereby all infragravity motions are neglected. This is useful for conditions where the incident waves are relatively small and/or short, and these motions would be small anyway. The model equations are similar to HISWA ([HBH89]) but do not include wave growth or wave period variations. Processes that are resolved are wave propagation, directional spreading, shoaling, refraction, bottom dissipation and wave breaking, and a roller model is included; these processes are usually dominant in nearshore areas of limited extent. For the breaking dissipation we use the [BHBvW98] model, which is valid for wave-averaged modeling. The radiation stress gradients from the wave and roller model force the shallow water equations, drive currents and lead to wave setdown and setup. Additionally, wind and tidal forcing can be applied.

The mean return flow due to mass flux and roller is included in the model and affects the sediment transport, leading to an offshore contribution. To balance this, effects of wave asymmetry and skewness are included as well. Bed slope effects can further modify the cross-shore behavior. A limited number of model coefficients allow the user to calibrate the profile shape resulting from these interactions.

A typical application would be to model morphological changes during moderate wave conditions, often in combination with tides. The wave boundary conditions can be specified as constant (keyword: wbctype = stat) or as a time-series of wave conditions (keyword: wbctype = stat_table). Typical examples of such model applications are given below for tombolo formation behind an offshore breakwater (left panel) and development of an ebb delta at a tidal inlet (right panel). A big advantage of the stationary XBeach wave model over other models is that the lateral boundaries are entirely without disturbance if the coast is longshore uniform near these boundaries.

Root-mean square wave height (left panels) and final bathymetry (right panels) for an offshore breakwater case (upper panels) and a tidal inlet with waves from 330 degrees (lower panels).

Surf beat mode (instationary)¶

See also

The surfbeat mode is implemented in mod:wave_instationary_module.

The short-wave motion is solved using the wave action equation which is a time-dependent forcing of the HISWA equations ([HBH89]). This equation solves the variation of short-waves envelope (wave height) on the scale of wave groups. It employs a dissipation model for use with wave groups ([Roe93][DRvD+12]) and a roller model ([Sve84][NRS90][SDeVriend94]) to represent momentum stored at the surface after breaking. These variations, through radiation stress gradients ([LHS62][LHS64]) exert a force on the water column and drive longer period waves (infragravity waves) and unsteady currents, which are solved by the nonlinear shallow water equations (e.g. [Phi77]). Thus, wave-driven currents (longshore current, rip currents and undertow), and wind-driven currents (stationary and uniform) for local wind set-up, long (infragravity) waves, and runup and rundown of long waves (swash) are included.

Using the surfbeat mode is necessary when the focus is on swash zone processes rather than time-averaged currents and setup. It is fully valid on dissipative beaches, where the short waves are mostly dissipated by the time they are near the shoreline. On intermediate beaches and during extreme events the swash motions are still predominantly in the infragravity band and so is the runup.

Under this surfbeat mode, several options are available, depending on the circumstances:

1D cross-shore; in this case the longshore gradients are ignored and the domain reduces to a single gridline (keyword: ny = 0). Within this mode the following options are available:

#. Retaining directional spreading (keyword: dtheta < thetamax – thetamin); this has a limited effect on the wave heights because of refraction, but can also allow obliquely incident waves and the resulting longshore currents;

#. Using a single directional bin (keyword: dtheta = thetamax – thetamin); this leads to perpendicular waves always and ignores refraction. If the keyword snells = 1 is applied, the mean wave direction is determined based on Snell’s law. In this case also longshore currents are generated.
2DH area; the model is solved on a curvilinear staggered grid (rectilinear is a special case). The incoming short wave energy will vary along the seaward boundary and in time, depending on the wave boundary conditions. This variation is propagated into the model domain. Within this mode the following options are available:
1. Resolving the wave refraction ’on the fly’ using the propagation in wave directional space. For large directional spreading or long distances this can lead to some smoothing of groupiness since the waves from different directions do not interfere but their energy is summed up. This option is possible for arbitrary bathymetry and any wave direction. The user must specify the width of the directional bins for the surfbeat mode (keyword: dtheta)
2. Solving the wave direction at regular intervals using the stationary solver, and then propagating the wave energy along the mean wave direction. This preserves the groupiness of the waves therefore leads to more forcing of the infragravity waves (keyword: single_dir = 1). The user must now specify a single directional bin for the instationary mode (dtheta = thetamax - thetamin) and a smaller bin size for the stationary solver (keyword: dtheta_s).
3. For schematic, longshore uniform cases the mean wave direction can also be computed using Snell’s law (keyword: snells = 1). This will then give comparable results to the single_dir option.

In the figures below some typical applications of 1D and 2D models are shown; a reproduction of a large-scale flume test, showing the ability of XBeach to model both short-wave (HF) and long-wave (LF) wave heights and velocities; and a recent 2DH simulation ([NLB+15]) of the impact of hurricane Sandy on Camp Osborne, Brick, NJ.

Computed and observed hydrodynamic parameters for test 2E of the LIP11D experiment. Top left: bed level and mean water level. Top right: measured (dots) and computed

Pre (left) and post-Sandy (right) in a three dimensional plot with both bed and water levels as simulated by XBeach ([NLB+15])

Non-hydrostatic mode (wave resolving)¶

See also

The non-hydrostatic mode is implemented in mod:nonh_module.

For non-hydrostatic XBeach calculations (keyword: wavemodel = nonh) depth-averaged flow due to waves and currents are computed using the non-linear shallow water equations, including a non-hydrostatic pressure. The depth-averaged normalized dynamic pressure ( $q$ ) is derived in a method similar to a one-layer version of the SWASH model ([ZSS11]). The depth averaged dynamic pressure is computed from the mean of the dynamic pressure at the surface and at the bed by assuming the dynamic pressure at the surface to be zero and a linear change over depth.

Under these formulations dispersive behavior is added to the long wave equations and the model can be used as a short-wave resolving model. Wave breaking is implemented by disabling the non-hydrostatic pressure term when waves exceed a certain steepness, after which the bore-like breaking implicit in the momentum-conserving shallow water equations takes over.

In case the non-hydrostatic mode is used, the short wave action balance is no longer required. This saves computation time. However, in the wave-resolving mode we need much higher spatial resolution and associated smaller time steps, making this mode much more computationally expensive than the surfbeat mode.

The main advantages of the non-hydrostatic mode are that the incident-band (short wave) runup and overwashing are included, which is especially important on steep slopes such as gravel beaches. Another advantage is that the wave asymmetry and skewness are resolved by the model and no approximate local model or empirical formulation is required for these terms. Finally, in cases where diffraction is a dominant process, wave-resolving modeling is needed as it is neglected in the short wave averaged mode. The XBeach-G formulations for gravel beaches ([MMP+14]) are based on the non-hydrostatic mode. Although sandy morphology can be simulated using the wave-resolving mode, it has not been extensively validated and it is likely that changes in the sediment transport formulations will be implemented in the near future.

An interesting recent application that has been validated for a number of cases concerns the modeling of primary waves generated by large ships, see Ship-induced wave motions.

Measured (black) and modeled (red) time series of overtopping during BARDEX experiment, from [MMP+14].

Short wave action¶

Short wave action balance¶

See also

The short wave action balance is implemented in func:wave_instationary_module/wave_instationary.

The wave forcing in the shallow water momentum equation is obtained from a time dependent version of the wave action balance equation. Similar to Delft University’s (stationary) HISWA model ([HBH89]) the directional distribution of the action density is taken into account, whereas the frequency spectrum is represented by a frequency, best represented by the spectral parameter ${f}_{m-1,0}$ . The wave action balance (keyword: swave) is then given by:

(1) $\frac{\partial A}{\partial t} +\frac{\partial c_{x} A}{\partial x} +\frac{\partial c_{y} A}{\partial y} +\frac{\partial c_{\theta } A}{\partial \theta } =-\frac{D_{w} +D_{f} +D_{v} }{\sigma }$

In which the wave action $A$ is calculated as:

(2) $A(x,y,t,\theta )=\frac{S_{w} (x,y,t,\theta )}{\sigma (x,y,t)}$

where $\theta$ represents the angle of incidence with respect to the x-axis, ${S}_{w}$ represents the wave energy density in each directional bin and $\sigma$ the intrinsic wave frequency. The intrinsic frequency $\sigma$ and group velocity ${c}_{g}$ is obtained from the linear dispersion relation. The intrinsic frequency is for example obtained with:

(3) $\sigma =\sqrt{gk\tanh kh}$

The wave action propagation speeds in $x$ , $y$ and directional space are given by:

(4) $\begin{array}{l} {c_{x} (x,y,t,\theta )=c_{g} \cos (\theta )} \\ {c_{y} (x,y,t,\theta )=c_{g} \sin (\theta )} \\ {c_{\theta } (x,y,t,\theta )=\frac{\sigma }{\sinh 2kh} \left(\frac{\partial h}{\partial x} \sin \theta -\frac{\partial h}{\partial y} \cos \theta \right)} \end{array}$

where $h$ represents the local water depth and $k$ the wave number. The intrinsic wave frequency $\sigma$ is determined without wave current interaction (keyword: wci = 1, see Section 2.3.1.1), which means it is equal to the absolute radial frequency $\omega$ .

Wave-current interaction (wci)¶

See also

The wave-current interaction is implemented in func:wave_instationary_module/wave_instationary.

Wave-current interaction is the interaction between waves and the mean flow. The interaction implies an exchange of energy, so after the start of the interaction both the waves and the mean flow are affected by each other. This feature is especially of importance in gullies and rip-currents ([RMTS07]).

In XBeach this is taken into account by correcting the wave number $k$ with the use of Eikonal equations, which will have impact on the group and wave propagation speed (x, y, and directional space). The cross-shore and alongshore wave numbers, ${k}_{x}$ and ${k}_{y}$ , are defined according to equation (5). In these formulations the subscripts refer to the direction of the wave vector components.

(5) $\begin{array}{l} {k_{x} =k_{x}^{n-1} +k_{x}^{:} } \\ {k_{y} =k_{y}^{n-1} +k_{y}^{:} } \\ \end{array}$

Where subscript $n-1$ refers the wave number of the previous time step, $k_{x}^{:}$ and $k_{y}^{:}$ are the wave number corrections and ${k}_{x}$ and ${k}_{y}$ are the corrected wave numbers that take into account the presence of a current. The correction terms are determined with a second set of equations, the Eikonal equations:

(6) $\begin{array}{l} {\frac{\partial k_{x} }{\partial t} +\frac{\partial \omega }{\partial x} =0} \\ {\frac{\partial k_{y} }{\partial t} +\frac{\partial \omega }{\partial y} =0} \end{array}$

The wave number is then given by:

(7) $k=\sqrt{k_{x}^{2} +k_{y}^{2} }$

The absolute radial frequency $\omega$ is calculated with:

(8) $\omega =\sigma +k_{x} u^{L} +k_{y} v^{L}$

where ${u}^{L}$ and ${v}^{L}$ are the cross-shore and alongshore depth-averaged Lagrangian velocities respectively. The wave action propagation speed (in x and y direction) is given by:

(9) $\begin{array}{l} {c_{x} (x,y,t,\theta )=c_{g} \cos (\theta )+u^{L} } \\ {c_{y} (x,y,t,\theta )=c_{g} \sin (\theta )+v^{L} } \end{array}$

The propagation speed in directional ( $\theta$ ) space, where bottom refraction (first term) and current refraction (last two terms) are taken into account, is obtained from:

(10) $\begin{array}{r} {c_{\theta } (x,y,t,\theta )=\frac{\sigma }{\sinh 2kh} \left(\frac{\partial h}{\partial x} \sin \theta -\frac{\partial h}{\partial y} \cos \theta \right)+\cos \theta \left(\sin \theta \frac{\partial u}{\partial x} -\cos \theta \frac{\partial u}{\partial y} \right)} \\ {+\, \sin \theta \left(\sin \theta \frac{\partial v}{\partial x} -\cos \theta \frac{\partial v}{\partial y} \right)} \end{array}$

Dissipation¶

In XBeach there are three short wave dissipation processes that can be accounted for: wave breaking ( ${D}_{w}$ ), bottom friction ( ${D}_{f}$ ) and vegetation ( ${D}_{v}$ ). The three processes are explained in more detail in the following subsections.

Wave breaking¶

See also

Short wave dissipation by breaking is implemented in mod:roelvink_module.

Five different wave breaking formulations are implemented in XBeach. The formulations can be selected using the keyword break (Table 1).

Different wave breaking formulations implemented¶
Wave breaking formula	Type of waves	keyword
Roelvink (1993a)	Instationary	roelvink1
Roelvink (1993a) extended	Instationary	roelvink2
Daly et al. (2010)	Instationary	roelvink_daly
Baldock et al. (1998)	Stationary	baldock
Janssen & Battjes (2007)	Stationary	janssen

For the surf beat approach the total wave energy dissipation, i.e. directionally integrated, due to wave breaking can be modeled according to [Roe93] (keyword: break = roelvink1). In the formulation of the dissipation due to wave breaking the idea is to calculate the dissipation with a fraction of breaking waves ( ${Q}_{b}$ ) multiplied by the dissipation per breaking event. In this formulation $\alpha$ is applied as wave dissipation coefficient of O (keyword: alpha), ${T}_{rep}$ is the representative wave period and ${E}_{w}$ is the energy of the wave. The fraction of wave breaking is determined with the root-mean-square wave height ( ${H}_{rms}$ ) and the maximum wave height ( ${H}_{max}$ ). The maximum wave height is calculated as ratio of the water depth ( $h$ ) plus a fraction of the wave height ( $\delta H_{rms}$ , keyword: delta) using a breaker index $\gamma$ (keyword: gamma). In the formulation for ${H}_{rms}$ the $\rho$ represents the water density and $g$ the gravitational constant. The total wave energy ${E}_{w}$ is calculated by integrating over the wave directional bins.

(11) $\begin{array}{c} {\bar{D}_{w} =2\frac{\alpha }{T_{rep} } Q_{b} E_{w} {\; }} \\ {Q_{b} {=1-exp}\left(-\left(\frac{H_{rms} }{H_{\max } } \right)^{n} \right),\quad H_{rms} =\sqrt{\frac{8E_{w} }{\rho g} } ,\quad H_{\max } =\gamma \cdot (h+\delta H_{rms} )} \\ {E_{w} (x,y,t)=\int _{0}^{2\pi }S_{w} (x,y,t,\theta )d\theta } \end{array}$

In variation of (11), one could also use another wave breaking formulation, presented in (12). This formulation is somewhat different than the formulation of [Roe93] and selected using keyword break = roelvink2. The main difference with the original formulation is that wave dissipation with break = roelvink2 is proportional to ${H}^{3} / h$ instead of ${H}^{2}$ .

(12) $\bar{D}_{w} =2\frac{\alpha }{T_{rep} } Q_{b} E_{w} \frac{H_{rms} }{h}$

Alternatively the formulation of [DRvD+10] states that waves are fully breaking if the wave height exceeds a threshold ( $\gamma$ ) and stop breaking if the wave height fall below another threshold ( $\gamma_{2}$ ). This formulation is selected by break = roelvink_daly and the second threshold, $\gamma_{2}$ , can be set using keyword gamma2.

(13) $\left\{\begin{array}{l} {Q_{b} =1\quad if\quad H_{rms} >\gamma h} \\ {Q_{b} =0\quad if\quad H_{rms} <\gamma _{2} h} \end{array}\right.$

In case of stationary waves [BHBvW98] is applied (keyword: break = baldock), which is presented in (14). In this breaking formulation the fraction breaking waves ${Q}_{b}$ and breaking wave height ${H}_{b}$ are calculated differently compared to the breaking formulations used for the non-stationary situation. In $\alpha$ is applied as wave dissipation coefficient, ${f}_{rep}$ represents a representative intrinsic frequency and $y$ is a calibration factor.

(14) $\begin{array}{l} {\bar{D}_{w} =\frac{1}{4} \alpha Q_{b} \rho gf_{rep} \left(H_{b}^{2} +H_{rms}^{2} \right)} \\ {Q_{b} =\exp \left[-\left(\frac{H_{b}^{2} }{H_{rms}^{2} } \right)\right]{\; ,\; \; }H_{b} =\frac{0.88}{k} \tanh \left[\frac{\gamma kh}{0.88} \right]} \end{array}$

Finally, it is possible to use the [JB07] formulation for wave breaking of stationary waves (keyword: break = janssen). This formulation is a revision of Baldock’s formulation.

(15) $\begin{array}{l} {\bar{D}_{w} =\frac{3\sqrt{\pi } \alpha f_{rep} \rho gH_{rms}^{3} }{16 h} Q_{b} } \\ {Q_{b} =1+\frac{4}{3\sqrt{\pi } } \left(R^{3} +\frac{3}{2} R\right)\exp \left(-R^{2} \right)-erf\left(R\right)} \\ {R=\frac{H_{b} }{H_{rms} } } \end{array}$

In both the instationary or stationary case the total wave dissipation is distributed proportionally over the wave directions with the formulation in (16).

(16) $D_{w} (x,y,t,\theta )=\frac{S_{w} (x,y,t,\theta )}{E_{w} (x,y,t)} \bar{D}_{w} (x,y,t)$

Bottom friction¶

See also

Short wave dissipation by bottom friction is implemented in func:wave_instationary_module/wave_instationary.

The short wave dissipation by bottom friction is modeled as

(17) $D_{f} =\frac{2}{3\pi } \rho f_{w} \left(\frac{\pi H_{rms} }{T_{m01} \sinh kh} \right)^{3}$

In (17) the ${f}_{w}$ is the short-wave friction coefficient. This value only affects the wave action equation and is unrelated to bed friction in the flow equation. Studies conducted on reefs (e.g. [LFK+07]) indicate that ${f}_{w}$ should be an order of magnitude (or more) larger than the friction coefficient for flow ( ${c}_{f}$ ) due to the dependency of wave frictional dissipation rates on the frequency of the motion.

The derivation of the short wave dissipation term is based time-averaged instantaneous bottom dissipation using the Johnson friction factor ${f}_{w}$ of the bed shear stress:

(18) $\tilde{D}_{f} =\left|\tau u\right|=\frac{1}{2} \rho f_{w} \left|\tilde{u}\right|^{3}$

The evaluation of the term $\left\langle\left|\tilde{u}\right|^{3}\right\rangle$ , the so-called third even velocity moment, depends on the situation. First we need expressions for the orbital velocity amplitude, which is expressed as:

(19) $u_{orb} =\frac{\pi H_{rms} }{T_{p} \sinh (kh)}$

In this formulation ${T}_{p}$ is the peak wave period, ${H}_{rms}$ is the root-mean-square wave height, $k$ is the wave number and $h$ is the local water depth.

If we consider the slowly-varying dissipation in wave groups, we need only to average over a single wave period and we can use a monochromatic (regular wave) expression. If we want to have the time-average dissipation over a full spectrum we get the best approximation from considering a linear Gaussian distribution. [GT85] give pragmatic expressions for both cases.

For the monochromatic case:

(20) $\left\langle \left|\tilde{u}\right|^{3} \right\rangle =1.20\left\langle \left|\tilde{u}\right|^{2} \right\rangle ^{3/2} =1.20\left(\frac{1}{2} u_{orb}^{2} \right)^{3/2} =0.42u_{orb}^{3}$

For the linear Gaussian approximation:

(21) $\left\langle \left|\tilde{u}\right|^{3} \right\rangle =1.60\left\langle \left|\tilde{u}\right|^{2} \right\rangle ^{3/2} =1.60\left(\frac{1}{2} u_{orb}^{2} \right)^{3/2} =0.57u_{orb}^{3}$

Combining (18) and orbital-velocity-monochromatic we get:

(22) $\left\langle \tilde{D}_{f} \right\rangle =0.21\rho f_{w} u_{orb}^{3}$

In XBeach the orbital velocity amplitude is computed as in orbital-velocity-monochromatic and the dissipation according to (22), which is correct for the case of instationary simulations on wave-group scale.

For the stationary case formulations (18) and (21) are similarly combined into:

(23) $\left\langle \tilde{D}_{f} \right\rangle =0.28\rho f_{w} u_{orb}^{3}$

Vegetation¶

See also

Short wave dissipation by vegetation is implemented in mod:vegetation_module.

The presence of aquatic vegetation within the area of wave propagation or wave breaking results in an additional dissipation mechanism for short waves. This is modeled using the approach of [ML04], which was adjusted by [SZB+12] to take into account vertically heterogeneous vegetation, see [vRVanTdVriesM+15]. The short wave dissipation due to vegetation is calculated as function of the local wave height and several vegetation parameters. The vegetation can be schematized in a number of vertical elements with each specific property. In this way the wave damping effect of vegetation such as mangrove trees, with a relatively dense root system but sparse stem area, can be modeled. The dissipation term is then computed as the sum of the dissipation per vegetation layer ([SZB+12]):

(24) $D_{v} =\sum _{i=1}^{n_{v} }D_{v,i}$

where ${D}_{v,i}$ is the dissipation by vegetation in vegetation layer $i$ and ${n}_{v}$ is the number of vegetation layers. The dissipation per layer is given by:

(25) $\begin{array}{l} {D_{v,i} =A_{v} \cdot \frac{\rho \widetilde{C}_{D,i} b_{v,i} N_{v,i} }{2\sqrt{\pi } } \left(\frac{kg}{2\sigma } \right)^{3} H_{rms} ^{3} ,{\; with}} \\ {A_{v} =\frac{\left(\sinh ^{3} k\alpha _{i} h-\sinh ^{3} k\alpha _{i-1} h\right)+3\left(\sinh k\alpha _{i} h-\sinh k\alpha _{i-1} h\right)}{3k\cosh ^{3} kh} } \end{array}$

where $\widetilde{C}_{D,i}$ is a (bulk) drag coefficient, ${b}_{v,i}$ is the vegetation stem diameter, ${N}_{v,i}$ is the vegetation density, and $\alpha_{i}$ is the relative vegetation height (= ${h}_{v} / h$ ) for layer $i$ . In case only one vegetation layer is specified, the plants are assumed to be vertically uniform, which would for example typically apply in case of modeling sea grass.

Radiation stresses¶

Given the spatial distribution of the wave action (and therefore wave energy) the radiation stresses can be evaluated by using linear wave theory as described by:

(26) $\begin{array}{l} {S_{xx,r} (x,y,t)=\int \cos ^{2} \theta S_{r} d\theta } \\ {S_{xy,r} (x,y,t)=S_{yx,r} (x,y,t)=\int \sin \theta \cos \theta S_{r} d\theta } \\ {S_{yy,r} (x,y,t)=\int \sin ^{2} \theta S_{r} d\theta } \end{array}$

Wave shape¶

See also

Wave shapes are implemented in func:morphevolution/RvR and func:morphevolution/vT.

The morphodynamic model considered is (short) wave averaged and resolves hydrodynamics associated with the wave group time scale. As a result the short wave shape is not solved for. However, as waves propagate from deep water onto beaches, their surface form and orbital water motion become increasingly non-linear because of the amplification of the higher harmonics.

There are two wave forms implemented to take this non-linearity into account:

A formulation of [RRvR12] based on a parameterization with the Ursell number. (keyword: waveform = ruessink_vanrijn)
A formulation of [vanTdVries09] based on the parameterized wave shape model of [RF81] (keyword: waveform = vanthiel)

The formulation of [RRvR12] relies on parameterizations for the non-linearity parameter $r$ and phase $\Phi$ . The parameterizations are based on a data set of 30.000+ field observations of the orbital skewness ${S}_{k}$ and asymmetry ${A}_{s}$ , collected under non-breaking and breaking wave conditions. The only variable parameter is the Ursell number, since according to [RRvR12] the Ursell that includes ${H}_{s}$ , $T$ and $h$ , describes the variability in ${S}_{k}$ and ${A}_{s}$ well. The Ursell number is calculated with the equation below.

(27) $U_{r} =\frac{3}{4} \frac{0.5H_{s} k}{(kh)^{3} }$

The value for the skewness and asymmetry is calculated with the use of a Boltzmann sigmoid. The skewness and asymmetry are a function of $\Psi$ . In the formulation of [RRvR12] the ${p}_{1:6}$ are used as parameterized factors on the data set of field observations.

(28) $\begin{array}{c} {B=p_{1} +\frac{p_{2} -p_{1} }{1+\exp \frac{p_{3} -\log Ur}{p_{4} } } } \\ {\psi =-90+90\tanh (p_{5} /Ur^{p_{6} } )} \\ {} \\ {S_{k} =B\cos \psi {\; \; \; and\; \; \; }A_{s} =B\sin \psi } \end{array}$

Alternatively, [vanTdVries09] utilized and extended the wave shape model of [RF81]. In this model the short wave shape is described by a Rienecker and Fenton lookup table with amongst others amplitudes non-linear components obtained with stream function theory. Therefore, wave skewness ( ${S}_{k}$ ) and asymmetry ( ${A}_{s})$ is computed in each grid point based on the water depth, dimensionless wave height and dimensionless wave period.

For $w$ equals one a skewed (Stokes) wave is obtained with high peaks and flat troughs whereas $w$ equals zero results in an asymmetric (saw tooth) wave with steep wave fronts. It is hypothesized that the weighting $w$ can be expressed as a function of wave skewness and asymmetry. The relation between the phase and the weighting is studied in more detail by [vanTdVries09] by varying $w$ between zero and one in small steps and computing the amplitudes with Rienecker and Fenton for a range of wave heights, wave periods and water depths. It is found that a unique relation between $w$ and $\Phi$ exists for any combination of wave height, wave period and water depth that is described by:

(29) $w=0.2719\ln \left(\left|\frac{\phi -1.8642}{0.2933-\phi } \right|\right)+0.5$

As explained in the next section, short-wave turbulence can be computed averaged over the bore interval ( ${T}_{bore}$ ). The bore interval is directly related to the wave shape and hence requires the weighting function $w$ is determined. For the formulation of [RRvR12] no exact wave shape is determined and therefore no bore interval can be calculated. Therefore this approach cannot be combined with bore averaged short-wave turbulence.

Turbulence¶

See also

Wave breaking induced turbulence is implemented in func:morphevolution/waveturb.

Wave breaking induced turbulence at the water surface has to be transported towards the bed in order to affect the up-stirring of sediment. [RS89] used an exponential decay model with the mixing length proportional to ${H}_{rms}$ to estimate the time averaged turbulence energy at the bed from turbulence at the water surface:

(30) $k_{b} =\frac{k}{\exp (h/H_{rms} )-1}$

where ${k}_{b}$ is turbulence variance at the bed and $k$ is the time averaged turbulence variance at the water surface.

There are three possibilities for the turbulence variance at the bed ( ${k}_{b}$ ) implemented into XBeach:

Wave averaged near-bed turbulence energy (keyword: turb = wave_averaged):

(31) $k_{b} =\frac{\overline{k_{s} }}{\exp (h/L_{mix} )-1}$
Bore-averaged near-bed turbulence energy [2] (keyword: turb = bore_averaged)

(32) $k_{b} =\frac{\overline{k_{s} }\cdot T_{rep} /T_{bore} }{\exp (h/L_{mix} )-1}$
Not taking into account the turbulence variance at the bed (keyword: turb = none)

Both formulations make use of the wave-averaged turbulence energy ( ${k}_{s}$ ) and a mixing length ( ${L}_{mix}$ ). The wave averaged turbulence energy at the surface is computed from the roller energy dissipation and following [Bat75] in which ${D}_{r}$ is roller dissipation:

(33) $\overline{k_{s} }=\left(D_{r} /\rho _{w} \right)^{2/3}$

The mixing length ( ${L}_{mix}$ ) is expressed as thickness of the surface roller near the water surface and depends on the roller volume ${A}_{r}$ ([Sve84]):

(34) $L_{mix} =\sqrt{A_{r} } =\sqrt{\frac{2E_{r} T_{rep} }{\rho _{w} c_{w} } }$

Roller energy balance¶

See also

The roller energy balance is implemented in func:wave_instationary_module/wave_instationary.

While the short wave action balance adequately describes the propagation and decay of organized wave energy, it has often been found that there is a delay between the point where the waves start to break (which is where you would expect the strongest radiation stress gradients to occur) and the point where the wave set-up and longshore current start to build. This transition zone effect is generally attributed to the temporary storage of shoreward momentum in the surface rollers. Several authors have analyzed the typical dimensions of such rollers and their effect on the radiation stress (e.g. [LHT74], [Sve84], [RS89], [NRS90], [Dei93], [SDeVriend94]).

The rollers can be represented as a blob of water with cross-sectional area A that slides down the front slope of a breaking wave. The roller exerts a shear stress on the water beneath it equal to:

(35) $\tau _{roller} =\frac{\rho gR}{L} \beta _{s}$

where $\beta_{s}$ is the slope of the breaking wave front, $R$ is the roller area and $L$ is the wave length. The roller has a kinetic energy equal to:

(36) $E_{r} =\frac{1}{2} \frac{\rho R(\overline{u_{roller}^{2} +w_{roller}^{2} })}{L}$

and a contribution to the radiation stress equal to:

(37) $S_{xx} =\frac{\rho R\overline{\left(u_{roller}^{2} -w_{roller}^{2} \right)}}{L}$

We can now formulate an energy balance for the roller as follows:

(38) $\frac{dE_{r} }{dt} =\frac{\partial E_{r} }{\partial t} +\frac{\partial E_{r} c\cos \theta }{\partial x} +\frac{\partial E_{r} c\sin \theta }{\partial y} =S-D$

where $S$ is the loss of organized wave motion due to breaking and $D$ is the dissipation. The latter is equal to the work done by the shear stress between the roller and the wave:

(39) $D_{r} =\tau _{roller} c_{g}$

Given the complex motion in the breaking waves, we can only give approximate estimates of the order of magnitude of the parameters in equations (35) till (39). Various authors have suggested that the velocity in the roller can be approximated as purely horizontal and equal to the wave celerity ${c}_{g}$ . In that case we get (for waves travelling in x-direction):

(40) $S_{xx,roller} =2E_{r}$

However, this must be seen as an (unrealistic) upper limit on the radiation stress contribution as this can only be valid for ${w}_{roller}=0$ . [NRS90] showed that the conceptual model of [RS89] would lead to a factor 0.22 instead of 2. However, a ratio in the order of 1 seems more realistic. [SDeVriend94] found a discrepancy between the roller shear stress derived from an energy balance and that derived from the momentum balance, in the order of a factor two. They explained this by a complicated analysis of the effect of water entering and leaving the roller, which led to a modification of the propagation term in the roller energy balance by a factor two. As this leads to the unphysical result that rollers would propagate at twice the wave celerity, we believe that the discrepancy must be sought in the ratio between roller energy and radiation stress contribution. Therefore we stick to the roller energy balance suggested by [NRS90] in equation (41) and the roller contribution to the radiation stress:

(41) $\begin{array}{l} {S_{xx,roller} \approx E_{r} \cos ^{2} \theta } \\ {S_{xy,roller} \approx E_{r} \cos \theta \sin \theta } \\ {S_{yy,roller} \approx E_{r} \sin ^{2} \theta } \end{array}$

This leads to an elegant and consistent distribution of the wave-induced forcing through the surfzone. To close the roller energy balance we need to express the dissipation of the roller as a function of ${E}_{r}$ . This can be done by introducing:

(42) $\overline{\left(u_{roller}^{2} +w_{roller}^{2} \right)}=\beta _{2} c_{g} ^{2}$

Combining this with equations (36) and (42) we then find:

(43) $D_{r} =2\beta _{s} \beta _{u} \frac{g}{c_{g} } E_{r}$

The coefficients $\beta_{s}$ and $\beta_{u}$ are usually lumped together into a single coefficient. This coefficient $\beta$ is in the O (keyword: beta), which may vary through the surf zone. The forcing of the longshore current by the radiation stress gradient can be derived from the wave and roller energy balances and :

(44) $\begin{array}{l} {F_{y} =-\frac{\partial S_{xy} }{\partial x} =-\frac{\partial }{\partial x} \left[\frac{c_{g} }{c} \left(E\cos \left(\theta \right)\sin \left(\theta \right)\right)+E_{r} \cos \left(\theta \right)\sin \left(\theta \right)\right]} \\ {\, \, \, \, \, \, \, \, \, \, \, =-\frac{\partial }{\partial x} \left[\frac{\sin \left(\theta \right)}{c} \left(Ec_{g} \cos \left(\theta \right)+E_{r} c\cos \left(\theta \right)\right)\right]} \\ {\, \, \, \, \, \, \, \, \, \, \, =-\left(Ec_{g} \cos \left(\theta \right)+E_{r} c\cos \left(\theta \right)\right)\frac{\partial }{\partial x} \left[\frac{\sin \left(\theta \right)}{c} \right]\, \, } \\ {\, \, \, \, \, \, \, \, \, \, \, \, \, \, \, -\frac{\sin \left(\theta \right)}{c} \frac{\partial }{\partial x} \left(Ec_{g} \cos \left(\theta \right)+E_{r} c\cos \left(\theta \right)\right)} \end{array}$

In a longshore uniform situation, according to Snell’s law, the first term on the right-hand side equals zero; the second term exactly equals the sum of the wave energy dissipation and the roller energy input and dissipation terms, so the forcing term reduces to:

(45) $F_{y} =\frac{D_{w} +(-D_{w} +D_{r} )}{c} \sin (\alpha )=\frac{D_{r} }{c} \sin (\alpha )$

Shallow water equations¶

See also

The shallow water equations are implemented in func:flow_timestep_module/flow.

For the low-frequency waves and mean flows we use the shallow water equations. To account for the wave induced mass-flux and the subsequent (return) flow these are cast into a depth-averaged Generalized Lagrangian Mean (GLM) formulation ([AM78], [WRG00]). In such a framework, the momentum and continuity equations are formulated in terms of the Lagrangian velocity ${u}^{L}$ which is defined as the distance a water particle travels in one wave period, divided by that period. This velocity is related to the Eulerian velocity (the short-wave-averaged velocity observed at a fixed point) by:

(46) $u^{L} =u^{E} +u^{S} \quad and\quad v^{L} =v^{E} +v^{S}$

where ${u}^{S}$ and ${v}^{S}$ represent the Stokes drift in x- and y-direction respectively ([Phi77]). The Strokes drift is calculated with in which the wave-group varying short wave energy ${E}_{w}$ and direction are obtained from the wave-action balance.

(47) $u^{S} =\frac{E_{w} \cos \theta }{\rho hc} \quad and\quad v^{S} =\frac{E_{w} \sin \theta }{\rho hc}$

The resulting GLM-momentum equations are given by:

(48) $\begin{array}{c} {\frac{\partial u^{L} }{\partial t} +u^{L} \frac{\partial u^{L} }{\partial x} +v^{L} \frac{\partial u^{L} }{\partial y} -f\, v^{L} \, -\, \nu _{h} \left(\frac{\partial ^{2} u^{L} }{\partial x^{2} } +\frac{\partial ^{2} u^{L} }{\partial y^{2} } \right)=\frac{\tau _{sx} }{\rho h} -\frac{\tau _{bx}^{E} }{\rho h} -g\frac{\partial \eta }{\partial x} +\frac{F_{x} }{\rho h} +\frac{F_{v,x} }{\rho h} } \\ {\frac{\partial v^{L} }{\partial t} +u^{L} \frac{\partial v^{L} }{\partial x} +v^{L} \frac{\partial v^{L} }{\partial y} +f\, u^{L} \, -\, \nu _{h} \left(\frac{\partial ^{2} v^{L} }{\partial x^{2} } +\frac{\partial ^{2} v^{L} }{\partial y^{2} } \right)=\frac{\tau _{sy} }{\rho h} -\frac{\tau _{by}^{E} }{\rho h} -g\frac{\partial \eta }{\partial y} +\frac{F_{y} }{\rho h} +\frac{F_{v,y} }{\rho h} } \\ {\frac{\partial \eta }{\partial t} +\frac{\partial hu^{L} }{\partial x} +\frac{\partial hv^{L} }{\partial y} =0} \end{array}$

where $\tau_{sx}$ and $\tau_{sy}$ are the wind shear stresses, $\tau_{bx}$ and $\tau_{by}$ are the bed shear stresses, $\eta$ is the water level, ${F}_{x}$ and ${F}_{y}$ are the wave-induced stresses, ${F}_{v,x}$ , and ${F}_{v,y}$ are the stresses induced by vegetation, $\nu_{h}$ is the horizontal viscosity and $f$ is the Coriolis coefficient. Note that the shear stress terms are calculated with the Eulerian velocities as experienced by the bed and not with the GLM velocities, as can be seen in .

Horizontal viscosity¶

See also

The Smagorinsky model is implemented in func:flow_timestep_module/visc_smagorinsky.

The horizontal viscosity ( ${v}_{h}$ ) is by default computed using the [Sma63] model to account for the exchange of horizontal momentum at spatial scales smaller than the computational grid size, which is given as:

(49) $v_{h} =c_{S} ^{2} 2^{\frac{1}{2} } \sqrt{\left(\frac{\delta u}{\delta x} \right)^{2} +\left(\frac{\delta v}{\delta y} \right)^{2} +\frac{1}{2} \left(\frac{\delta u}{\delta x} +\frac{\delta v}{\delta y} \right)^{2} } \Delta x\Delta y$

In ${c}_{S}$ is the Smagorinsky constant (keyword: nuh), set at 0.1 in all model simulations. It is also possible to use a user-defined value for the horizontal viscosity by turning off the Smagorinsky model (keyword: smag = 0) and specifying the value directly (also keyword: nuh).

Bed shear stress¶

See also

Bed shear stresses are implemented in mod:bedroughness_module.

The bed friction associated with mean currents and long waves is included via the formulation of the bed shear stress ( $\tau_{b}$ ). Using the approach of [RMF+01] the bed shear stress is calculated with:

(50) $\begin{array}{l} {\tau _{bx}^{E} =c_{f} \rho u_{E} \sqrt{\left(1.16u_{rms} \right)^{2} +\left(u_{E} +v_{E} \right)^{2} } } \\ {\tau _{by}^{E} =c_{f} \rho v_{E} \sqrt{\left(1.16u_{rms} \right)^{2} +\left(u_{E} +v_{E} \right)^{2} } } \end{array}$

There are 5 different formulations in order to determine the dimensionless bed friction coefficient ${c}_{f}$ (keyword: bedfriction) implemented in XBeach (Table 2).

Different bed friction formulations implemented¶
Bed friction formulation	Relevant coefficient	keyword
Dimensionless friction coefficient	${c}_{f}$	cf
Chézy	C	chezy
Manning	n	manning
White-Colebrook	${k}_{s}$	white-colebrook
White-Colebrook grain size	D90	white-colebrook-grainsize

The dimensionless friction coefficient can be calculated from the Chézy value with equation (51). A typical Chézy value is in the order of $55 {m}^{1/2}/s$ .

(51) $c_{f} =\sqrt{\frac{g}{C^{2} } }$

In the Manning formulation the Manning coefficient ( $n$ ) must be specified. The dimensionless friction coefficient is calculated from equation (52). Manning can be seen as a depth-dependent Chézy value and a typical Manning value would be in the order of $0.02 s/{m}^{1/3}$ .

(52) $c_{f} =\sqrt{\frac{gn^{2} }{h^{1/12} } }$

In the White-Colebrook formulation the geometrical roughness of Nikuradse ( ${k}_{s}$ ) must be specified. The dimensionless friction coefficient is calculated from equation (53) The White-Colebrook formulation has al log relation with the water depth and a typical ${k}_{s}$ value would be in the order of 0.01 - 0.15 m.

(53) $c_{f} =\sqrt{\frac{g}{\left(18\log \left(\frac{12h}{k_{s} } \right)\right)^{2} } }$

The option of White-Colebrook based on the grain size is somewhat different than the other four formulations. This formulation is based on the relation between the ${D}_{90}$ of the top bed layer and the geometrical roughness of Nikuradse according to equation (54). The user does not have to specify a value for the bed friction coefficient.

(54) $c_{f} =\sqrt{\frac{g}{\left(18\log \left(\frac{12h}{3D_{90} } \right)\right)^{2} } }$

Values of the drag coefficient for different seabed sediment grain sizes (flat beds) and similarly for bed form scenarios have been empirically derived from field and laboratory data in previous studies for different bed friction coefficients. The value of the friction coefficient ( $C$ , ${c}_{f}$ , $n$ or ${k}_{s}$ ) can be defined with one single value (keyword: bedfriccoef) or for a separate value per grid cell (keyword: bedfricfile)

Damping by vegetation¶

See also

Infra-gravity wave damping by vegetation is implemented in mod:vegetation_module.

The presence of aquatic vegetation within the area of wave propagation or wave breaking may not only result in short wave dissipation (Dissipation), but also in damping of infragravity waves and/or mean flow. Since both long waves and mean flow are fully resolved with the nonlinear shallow water equations, the effect of vegetation can be modeled using a drag force (e.g. [DKH84]), which can be directly added to the momentum equations ([vRVanTdVriesM+15], equation (48)):

(55) $F_{v} =F_{D} =\frac{1}{2} \rho C_{D} b_{v} Nu\left|u\right|$

Where ${C}_{D}$ is a drag coefficient, ${b}_{v}$ is the vegetation stem diameter, $N$ is the vegetation density and $u$ is the wave or current related velocity. To take into account the velocity due to mean flow and infragravity waves, we use the Lagrangian velocity ( ${u}^{L}$ ) here. The vegetation-induced time varying drag force is then calculated as the sum of the vegetation-induced drag force per vegetation layer:

(56) $\begin{array}{l} {F_{v} (t)=\sum _{i=1}^{n_{v} }F_{v,i} (t)} \\ {F_{v,i} (t)=\frac{1}{2} \rho \widetilde{C}_{D,i} b_{v,i} N_{v,i} h_{v,i} u^{L} (t)\left|u^{L} (t)\right|} \end{array}$

where $\widetilde{C}_{D,i}$ is a (bulk) drag coefficient, ${b}_{v,i}$ is the vegetation stem diameter, ${n}_{v,i}$ is the vegetation density, and ${h}_{v,i}$ is the vegetation height for layer $i$ .

Wind¶

The first term on the right hand side of the momentum equations (equation (48)) represents the forcing due to the wind stress. These forcing terms due to the wind are formulated as:

(57) $\begin{array}{rcl} \tau _{sx} &=& \rho _{a} C_{d} W\left|W_{x} \right| \\ \tau _{sy} &=& \rho _{a} C_{d} W\left|W_{y} \right| \\ \end{array}$

where $\tau_{w}$ is wind stress, $\rho_{a}$ is density of air, ${C}_{d}$ is the wind drag the coefficient, $W$ is the wind velocity. The wind stress is turned off by default, and can be turned on specifying a constant wind velocity (keyword: windv) or by specifying a time varying wind file.

Non-hydrostatic pressure correction¶

See also

The non-hydrostatic pressure correction is implemented in mod:nonh_module.

For non-hydrostatic XBeach calculations (keyword: waveform = nonh) depth-averaged flow due to waves and currents are computed using the non-linear shallow water equations, including a non-hydrostatic pressure. The non-hydrostatic model accounts for all wave motions (including short waves) within the shallow water equations, so the wave action balance should be turned off (keyword: swave = 0). The depth-averaged normalized dynamic pressure ( $q$ ) is derived in a method similar to a one-layer version of the SWASH model ([ZSS11]). The depth averaged dynamic pressure is computed from the mean of the dynamic pressure at the surface and at the bed by assuming the dynamic pressure at the surface to be zero and a linear change over depth. In order to compute the normalized dynamic pressure at the bed, the contributions of advective and diffusive terms to the vertical momentum balance are assumed to be negligible.

(58) $\frac{\delta w}{\delta t} +\frac{\delta q}{\delta z} =0$

In $w$ is the vertical velocity and $z$ is the vertical coordinate. The vertical velocity at the bed is set by the kinematic boundary condition:

(59) $w_{b} =u\frac{\delta (\eta -h)}{\delta x}$

Combining the Keller-box method ([LS76]), as applied by [SZ03] for the description of the pressure gradient in the vertical, the dynamic pressure at the bed can be described by:

(60) $q_{b} =-\frac{h}{2} \left(\left. \frac{\delta q}{\delta z} \right|_{s} +\left. \frac{\delta q}{\delta z} \right|_{b} \right)$

Substituting in allows the vertical momentum balance at the surface to be described by:

(61) $\frac{\delta w_{s} }{\delta t} =2\frac{q_{b} }{h} -\frac{\delta w_{b} }{\delta t}$

In the subscript $s$ refers to the location at the surface. The dynamic pressure at the bed is subsequently solved by combining and the local continuity equation:

(62) $\frac{\delta u}{\delta x} +\frac{w_{s} -w_{b} }{h} =0$

In order to improve the computed location and magnitude of wave breaking, the hydrostatic front approximation (HFA) of [SJHS14] is applied, in which the pressure distribution under breaking bores is assumed to be hydrostatic. Following the recommendations of [SJHS14], we consider hydrostatic bores if $\frac{\delta \eta }{\delta t} >0.6$ and reform if $\frac{\delta \eta }{\delta t} <0.3$ . The values can respectively be changed with the keywords maxbrsteep and secbrsteep.

Although this method greatly oversimplifies the complex hydrodynamics of plunging waves, [MMP+14] shows that the application of this method provides sufficient skill to describe dominant characteristics of the flow, without requiring computationally expensive high-resolution discretization of the vertical and surface tracking of overturning waves.

Groundwater flow¶

See also

Groundwater flow is implemented in mod:groundwaterflow.

The groundwater module (keyword: gwflow = 1) in XBeach utilizes the principle of Darcy flow for laminar flow conditions and a parameterization of the Forchheimer equations for turbulent groundwater flow. The module includes a vertical interaction flow between the surface water and groundwater. This flow is assumed to be a magnitude smaller than the horizontal flow and is not incorporated in the momentum balance.

Continuity¶

In order to solve mass continuity in the groundwater model, the groundwater is assumed to be incompressible. Continuity is achieved by imposing a non-divergent flow field:

(63) $\nabla U=0$

where $U$ is the total specific discharge velocity vector, with components in the horizontal ( ${u}_{gw}$ , ${v}_{gw}$ ) and vertical ( ${w}_{gw}$ ) direction:

(64) $U=\left[\begin{array}{c} {u} \\ {v} \\ {w} \end{array}\right]$

Equation of motions¶

Laminar flow of an incompressible fluid through a homogeneous medium can be described using the well-known Law of [Dar56], valid for laminar flow conditions (keyword: gwscheme = laminar)

(65) $\begin{array}{c} {u_{gw} =-K\frac{\partial H}{\partial x} } \\ {v_{gw} =-K\frac{\partial H}{\partial y} } \\ {w_{gw} =-K\frac{\partial H}{\partial z} } \end{array}$

in which $K$ is the hydraulic conductivity of the medium (keyword: $kx$ $ky$ , $kz$ , for each horizontal and vertical direction) and $H$ is the hydraulic head.

In situations in which flow is not laminar, turbulent and inertial terms may become important. In these cases the user can specify XBeach to use a method (keyword: gwscheme = turbulent) that is comparable with the USGS MODFLOW-2005 groundwater model ([Har05]), in which the turbulent hydraulic conductivity is estimated based on the laminar hydraulic conductivity ( ${K}_{lam}$ ) and the Reynolds number at the start of turbulence ( ${Re}_{crit}$ ) ([Hal00]):

(66) $\begin{array}{c} {u_{gw} =-K\left(Re\right)\frac{\partial H}{\partial x} {\; \; \; in\; which\; }Re=\frac{\left|U\right|D_{50} }{n_{p} v} } \\ {K\left(Re\right)=\left\{\begin{array}{l} {K_{lam} \sqrt{\frac{Re_{crit} }{Re} } {\; \; \; if\; \; }Re{\; >\; }Re_{crit} {\; }} \\ {K_{lam} {\; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; if\; \; }Re\le {\; }Re_{crit} {\; }} \end{array}\right. } \end{array}$

In the Reynolds number ( $Re$ ) is calculated using the median grain size ( ${D}_{50}$ ), the kinematic viscosity of water ( $\nu$ ) and the groundwater velocity in the pores ( $U/n_{p}$ ), where ${n}_{p}$ is the porosity. Similar expressions exist for the other two components of the groundwater flow.

The critical Reynolds number for the start of turbulence ( ${Re}_{crit}$ ) is specified by the user, based on in-situ or laboratory measurements, or expert judgment (keyword: gwReturb). Since the hydraulic conductivity in the turbulent regime is dependent on the local velocity, an iterative approach is taken to find the correct hydraulic conductivity and velocity.

Determination of the groundwater head¶

The XBeach groundwater model allows two methods to determine the groundwater head: a hydrostatic approach (keyword: gwnonh = 0) and a non-hydrostatic approach (keyword: gwnonh = 1).

Hydrostatic approach

In the hydrostatic approach, the groundwater head is computed as follows:

In cells where there is no surface water the groundwater head is set equal to the groundwater surface level $\eta_{gw}$ .
In cells where there is surface water, but the groundwater surface level $\eta_{gw}$ is more than ${d}_{wetlayer}$ (keyword: dwetlayer) below the surface of the bed, the groundwater head is set equal to the groundwater surface level.
In cells where there is surface water and the groundwater surface level $\eta_{gw}$ is equal to the surface of the bed, the groundwater head is set equal to the surface water level.
In cells where there is surface water and the groundwater surface level $\eta_{gw}$ is equal to or less than ${d}_{wetlayer}$ below the surface of the bed, the groundwater head is linearly weighted between that of the surface water level and the groundwater level, according to the distance from the groundwater surface to the surface of the bed.

It should be noted that the numerical parameter ${d}_{wetlayer}$ is required to ensure numerical stability of the hydrostatic groundwater model. Larger values of ${d}_{wetlayer}$ will increase numerical stability, at the expense of numerical accuracy.

Non-hydrostatic approach

Groundwater flow in the swash and surf zone has been shown to be non-hydrostatic (e.g., [LB00]; [LMHK07]). In order to capture this, it may be necessary in certain cases to reject the Dupuit–Forchheimer assumption of hydrostatic groundwater pressure.

In the non-hydrostatic approach, the groundwater head is not assumed to be constant in the vertical. Since XBeach is depth-averaged, the model cannot compute true vertical profiles of the groundwater head and velocity. In order to estimate of the groundwater head variation over the vertical, a quasi-3D modeling approach is applied, which is set by two boundary conditions and one non-hydrostatic shape assumption:

There is no exchange of groundwater between the aquifer and the impermeable layer below the aquifer.
The groundwater head at the upper surface of the groundwater is continuous with the head applied at the groundwater surface.
The shape of the non-hydrostatic head profile is parabolic (keyword: gwheadmodel = parabolic), implying that the vertical velocity increases or decreases linearly from the bottom of the aquifer to the upper surface of the groundwater, or the non-hydrostatic head profile is hyperbolic (keyword: gwheadmodel = exponential), cf., [RGE99].

The vertical groundwater head approximation can be solved for the three imposed conditions by a vertical head function, shown here for the parabolic head assumption. The depth-average value of the groundwater head is used to calculate the horizontal groundwater flux and is found by integrating the groundwater head approximation over the vertical:

(67) $\overline{H}=\frac{1}{h_{gw} } \int _{0}^{h_{gw} }H(\sigma )d\sigma =H_{bc} -\frac{2}{3} \beta h_{gw}^{1}$

In the mean vertical ground water head ( $H$ ) is calculated using the groundwater head imposed at the groundwater surface ( ${H}_{bc}$ ), the groundwater head parabolic curvature coefficient ( $\beta$ ) and the height of the groundwater level above the bottom of the aquifer ( ${h}_{gw}$ ).

The unknown curvature coefficient ( $\beta$ ) in the vertical groundwater head approximation is solved using the coupled equations for continuity and motion (equations (63) and (65)), thereby producing the depth-average horizontal groundwater head gradients and vertical head gradients at the groundwater surface.

Although the requirement for non-hydrostatic pressure has the benefit of being a more accurate representation of reality, and does not require the numerical smoothing parameter ${d}_{wetlayer}$ , resolving the non-hydrostatic pressure field can be computationally expensive, particularly in 2DH applications.

Exchange with surface water¶

In the groundwater model there are three mechanisms for the vertical exchange of groundwater and surface water: 1) submarine exchange, 2) infiltration and 3) exfiltration. The rate of exchange between the groundwater and surface water ( $S$ ) is given in terms of surface water volume, and is defined positive when water is exchanged from the surface water to the groundwater.

Infiltration and exfiltration can only occur in locations where the groundwater and surface water are not connected. Infiltration takes place when surface water covers an area in which the groundwater level is lower than the bed level. The flux of surface water into the bed is related to the pressure gradient across the wetting front.

(68) $\begin{array}{c} {S_{inf} =K\left(\frac{1}{\rho g} \frac{\left. p\right|^{z=\xi } }{\delta _{infill} } 1\right)} \\ {{in\; which\; }\delta _{infill} (t)=\int \frac{S}{n_{p} } dt } \end{array}$

In equation (68) the surface water-groundwater exchange flow of infiltration ( ${S}_{inf}$ ) is calculated using the effective hydraulic conductivity ( $K$ ), the surface water pressure at the bed ( $\left. p\right|^{z=\xi }$ ) and the thickness of the wetting front ( $\delta_{infill}$ ).

Since the groundwater model is depth-averaged and cannot track multiple layers of groundwater infiltrating into the bed, the wetting front thickness is reset to zero when there is no available surface water, the groundwater exceeds the surface of the bed, or the groundwater and the surface water become connected. In addition, all infiltrating surface water is instantaneously added to the groundwater volume, independent of the distance from the bed to the groundwater table. Since the groundwater model neglects the time lag between infiltration at the beach surface and connection with the groundwater table a phase error may occur in the groundwater response to swash dynamics

Exfiltration ( ${S}_{exf}$ ) occurs where the groundwater and surface water are not connected and the groundwater level exceeds the bed level. The rate of exfiltration is related to the rate of the groundwater level exceeding the bed level.

(69) $S_{exf} =n_{p} \frac{\delta (z_{b} -\eta _{gw} )}{\delta t}$

Submarine exchange ( ${S}_{sub}$ ) represents the high and low frequency infiltration and exfiltration through the bed due pressure gradients across the saturated bed. This process only takes place where the groundwater and surface water are connected. In the case of the non-hydrostatic groundwater model, the rate of submarine exchange is determined by the vertical specific discharge velocity at the interface between the groundwater and surface water. The value of this velocity can be found using the vertical derivative of the approximated groundwater head at the groundwater-surface water interface (shown for the parabolic head approximation).

(70) $S_{sub} =2\beta h_{gw} K$

In the case of the hydrostatic groundwater model, the difference between the surface water head and the groundwater head is used to drive submarine discharge when the groundwater level is less than ${d}_{wetlayer}$ from the bed surface.

While most beach systems can acceptably described through vertical exchange of surface water and groundwater, in cases of very steep permeable slopes (e.g., porous breakwaters), it is necessary to include the horizontal exchange of groundwater and surface water between neighboring cells (keyword: gwhorinfil = 1). In this case the horizontal head gradient between the surface water and groundwater across vertical interface between the cells is used to determine the horizontal exchange flux:

(71) $S_{hor} =-K\frac{\partial H_{s} }{\partial s} A$

where $\delta H_{s}$ is the head gradient between the surface water and groundwater in neighboring cell, $\delta s$ is the gradient distance, defined as the numerical grid size, and $A$ is the surface area through which the exchange takes place, defined as the difference in bed level between the neighboring cells.

Calculation of groundwater and surface water levels¶

Groundwater levels are updated through the continuity relation:

(72) $n_{p} \frac{\delta \eta _{gw} }{\delta t} =-\frac{\partial h_{gw} u_{gw} }{\partial x} -\frac{\partial h_{gw} v_{gw} }{\partial y} +S_{inf} +S_{exf} +S_{sub} +S_{hor}$

In these same areas the surface water level is modified to account for exchange fluxes:

(73) $\frac{\delta \eta }{\delta t} =-S_{inf} -S_{exf} -S_{sub} -S_{hor}$

Boundary conditions¶

Since the groundwater dynamics are described by a parabolic equation, the system of equations requires boundary conditions at all horizontal and vertical boundaries, as well as an initial condition:

A zero flux condition is imposed at the horizontal boundaries and bottom of the aquifer.
The initial condition for the solution is specified by the model user in terms of the initial groundwater head (keyword: gw0, or gw0file).

Sediment transport¶

See also

Sediment transport is implemented in func:morphevolution/transus.

Advection-diffusion equation¶

Sediment concentrations in the water column are modeled using a depth-averaged advection-diffusion scheme with a source-sink term based on equilibrium sediment concentrations ([GV83]):

(74) $\frac{\partial hC}{\partial t} +\frac{\partial hCu^{E} }{\partial x} +\frac{\partial hCv^{E} }{\partial y} +\frac{\partial }{\partial x} \left[D_{h} h\frac{\partial C}{\partial x} \right]+\frac{\partial }{\partial y} \left[D_{h} h\frac{\partial C}{\partial y} \right]=\frac{hC_{eq} -hC}{T_{s} }$

In $C$ represents the depth-averaged sediment concentration which varies on the wave-group time scale and ${D}_{h}$ is the sediment diffusion coefficient. The entrainment of the sediment is represented by an adaptation time ${T}_{s}$ , given by a simple approximation based on the local water depth $h$ and sediment fall velocity ${w}_{s}$ . A small value of ${T}_{s}$ corresponds to nearly instantaneous sediment response (keyword: Tsmin). The factor ${f}_{Ts}$ is a correction and calibration factor to take into account the fact that ${w}_{s}$ is determined on depth-averaged data (keyword: tsfac).

(75) $T_{s} =\max \left(f_{Ts} \frac{h}{w_{s} } ,T_{s,\min } \right)\;$

The entrainment or deposition of sediment is determined by the mismatch between the actual sediment concentration $C$ and the equilibrium concentration ${C}_{eq}$ thus representing the source term in the sediment transport equation.

General parameters¶

In the sediment transport formulations, the equilibrium sediment concentration ${C}_{eq}$ (for both the bed load and the suspended load) is related to the velocity magnitude ( ${v}_{mg}$ ), the orbital velocity ( ${u}_{rms}$ ) and the fall velocity ( ${w}_{s}$ ). This section elaborates how these are calculated. Important to note: XBeach calculates the equilibrium concentration for the bed and suspended load separately.

First of all the Eulerian , if long wave stirring is turned on (keyword: lws = 1), the velocity magnitude ${v}_{mg}$ is equal to the magnitude of the Eulerian velocity, as can be seen in .

(76) $v_{mg} =\sqrt{\left(u^{E} \right)^{2} +\left(v^{E} \right)^{2} }$

If wave stirring is turned off (keyword: lws = 0), the velocity magnitude will be determined by two terms: first of all a factor of the velocity magnitude of the previous time step ( ${v}_{mg}^{n-1}$ ) and secondly a current-averaged part. Averaging will be carried out based on a certain factor ${f}_{cats}$ (keyword: cats) of the representative wave period ${T}_{rep}$ .

(77) $v_{mg} =\left(1-\frac{dt}{f_{cats} T_{rep} } \right)v_{mg}^{n-1} +\frac{dt}{f_{cats} T_{rep} } \sqrt{\left(u^{E} \right)^{2} +\left(v^{E} \right)^{2} }$

Secondly, the , the ${u}_{rms}$ is obtained from the wave group varying wave energy using linear wave theory. In this formulation ${T}_{rep}$ is the representative wave period and the ${H}_{rms}$ is the root-mean-square wave height. In this equation the water depth is enhanced with a certain factor of the wave height (keyword: delta).

(78) $u_{rms} =\frac{\pi H_{rms} }{T_{rep} \sqrt{2} \sinh (k(h+\delta H_{rms} )}$

To account for wave breaking induced turbulence due to short waves, the orbital velocity is adjusted ([vanTdVries09]). In this formulation ${k}_{b}$ is the wave breaking induced turbulence due to short waves. The turbulence is approximated with an empirical formulation in XBeach.

(79) $u_{rms,2}^{2} =u_{rms}^{2} +1.45k_{b}$

Thirdly, the , the ${w}_{s}$ is calculated using the formulations of [Ahr00] which are derived based on a relationship suggested by [Hal81]:

(80) $w_{s} =\alpha _{1} \sqrt{\Delta gD_{50} } +\alpha _{2} \frac{\Delta gD_{50}^{2} }{\nu }$

(81) $\alpha _{1} =1.06\tanh \left(0.016A^{0.50} \exp \left(-120/A\right)\right)$

(82) $\alpha _{2} =0.055\tanh \left(12A^{-0.59} \exp \left(-0.0004A\right)\right)$

For high sediment concentrations, the fall velocity is reduced (keyword: fallvelred = 1) using the expression of [RZ54]:

(83) $w_{s,reduced} =\left(1-C\right)^{\alpha } w_{s}$

The exponent a is estimated using the equation of [Row87], which depends purely on the Reynolds particle number R:

(84) $\alpha =2.35\frac{2+0.175{R}^{3/4} }{1+0.175{R}^{3/4} }$

(85) ${R}=\frac{w_{s} D_{50} }{\nu }$

Transport formulations¶

See also

The sediment transport formulations are implemented in func:sedtransform

In the present version of XBeach, two sediment transport formulations are available. The formulae of the two formulations are presented in the following sections. For both methods the total equilibrium sediment concentration is calculated with equation (86). In this equation the minimum value of the equilibrium sediment concentration (for both bed load en suspended load) compared to the maximum allowed sediment concentration (keyword: cmax).

(86) $C_{eq} ={max\; }({min\; }(C_{eq,b} ,\frac{1}{2} C_{\max } )+{min\; }(C_{eq,s} ,\frac{1}{2} C_{\max } ),{\; }0)$

The transport formulations implemented into XBeach distinguishes bed load and suspended load transport. It is possible to in- and exclude these transports components (keywords: bed & sus, with bed = 1 will include bed load transport). There is also a possibility to compute the total bulk transport rather than bed and suspended load separately (keyword: bulk = 1). The bed load will be calculated if it is suspended transport. On top of that this switch will have impact on how the bed slope effect (see Section 2.7.6) will be calculated

Soulsby-Van Rijn¶

The first possible sediment transport formulation are the Soulsby-Van Rijn equations (keyword: form = soulsby_vanrijn) ([Sou97]; [vR85]). The equilibrium sediment concentrations are calculated according to:

(87) $\begin{array}{l} {C_{eq,b} =\frac{A_{sb} }{h} \left(\sqrt{v_{mg} ^{2} +0.018\frac{u_{rms,2} ^{2} }{C_{d} } } -U_{cr} \right)^{2.4} } \\ {C_{eq,s} =\frac{A_{ss} }{h} \left(\sqrt{v_{mg} ^{2} +0.018\frac{u_{rms,2} ^{2} }{C_{d} } } -U_{cr} \right)^{2.4} } \end{array}$

For which the bed load and suspended load coefficients are calculated with:

(88) $A_{sb} =0.005h\left(\frac{D_{50} }{h\Delta gD_{50} } \right)^{1.2} ,{\; }A_{ss} =0.012D_{50} \frac{D_{*}^{-0.6} }{(\Delta gD_{50} )^{1.2} }$

In which the dimensionless sediment diameter (D*) can be calculated with the following formulation. The $v$ is the kinematic viscosity based on the expression of Van Rijn and is a function of the water temperature. XBeach assumes a constant temperature of 20 degrees Celsius, this result in a constant kinematic viscosity of ${19}^{-6} {\rm m}^{2}/{\rm s}$ .

(89) $D_{*} =\left(\frac{\Delta g}{\nu ^{2} } \right)^{1/3} D_{50}$

The critical velocity ( ${U}_{cr}$ ) defines at which depth averaged velocity sediment motion is initiated:

(90) $U_{cr} =\left\{\begin{array}{l} {0.19D_{50}^{0.1} \log 10\left(\frac{4h}{D_{90} } \right){\; for\; }D_{50} \le 0.0005} \\ {8.5D_{50}^{0.6} \log 10\left(\frac{4h}{D_{90} } \right){\; for\; }D_{50} >0.05} \end{array}\right.$

Finally the drag coefficient ( ${C}_{d}$ ) is calculated with equation (91). A drag coefficient is used to determine the equilibrium sediment concentrations. On top of that [Sou97] gives a relation between the bed shear stress of the depth-averaged current speed.

(91) $C_{d} =\left(\frac{0.40}{\ln \left(\frac{\max (h,10z_{0} )}{z_{0} } \right)-1} \right)^{2}$

In this equation $z_0$ is used for the bed roughness length and is used as zero flow velocity level in the formulation of the sediment concentration. In XBeach this is a fixed value (keyword: z0), but [Sou97] argues there is a relation between the Nikuradse and kinematic viscosity.

Van Thiel-Van Rijn¶

The second possible sediment transport formulation are the Van Thiel-Van Rijn transport equations (keyword: form = vanthiel_vanrijn) ([vR07]; [vanTdVries09]). The major difference between the Soulsby – Van Rijn equations is twofold. First of all, there is no drag coefficient calculated anymore and secondly the critical velocity is determined by calculating separately the critical velocity for currents ( ${U}_{crc}$ ) according to [Shi36] and for waves ( ${U}_{crw}$ ) according to [KM75].

The equilibrium sediment concentrations are calculated according to

(92) $\begin{array}{l} {C_{eq,b} =\frac{A_{sb} }{h} \left(\sqrt{v_{mg} ^{2} +0.64u_{rms,2}^{2} } -U_{cr} \right)^{1.5} } \\ {C_{eq,s} =\frac{A_{ss} }{h} \left(\sqrt{v_{mg} ^{2} +0.64u_{rms,2}^{2} } -U_{cr} \right)^{2.4} } \end{array}$

For which the bed-load and suspended load coefficient are calculated with:

(93) $A_{sb} =0.015h\frac{\left(D_{50} /h\right)^{1.2} }{\left(\Delta gD_{50} \right)^{0.75} } ,{\; }A_{ss} =0.012D_{50} \frac{D_{*}^{-0.6} }{(\Delta gD_{50} )^{1.2} }$

The critical velocity is computed as weighted summation of the separate contributions by currents and waves ([vR07]):

(94) $U_{cr} =\beta U_{crc} +(1-\beta )U_{crw} {\; \; in\; which\; \; \; }\beta =\frac{v_{mg} }{v_{mg} +u_{rms} }$

The critical velocity for currents is based on [Shi36]:

(95) $U_{crc} =\left\{\begin{array}{l} {0.19D_{50}^{0.1} \log 10\left(\frac{4h}{D_{90} } \right){\; \; \; \; \; for\; }D_{50} \le 0.0005} \\ {8.5D_{50}^{0.6} \log 10\left(\frac{4h}{D_{90} } \right){\; \; \; \; \; \; \; for\; }D_{50} \le 0.002} \\ {1.3\sqrt{\Delta gD_{50} } \left(\frac{h}{D_{50} } \right)^{1/6} {\; \; \; \; \; \; \; for\; }D_{50} >0.0005} \end{array}\right.$

The critical velocity for waves is based on [KM75]:

(96) $U_{crw} =\left\{\begin{array}{l} {0.24(\Delta g)^{2/3} {\; }\left(D_{50} T_{rep} \right)^{1/3} {\; \; \; \; \; \; \; \; for\; \; }D_{50} <=0.0005} \\ {0.95(\Delta g)^{0.57} {\; }\left(D_{50} \right)^{0.43} T_{rep} ^{0.14} {\; \; for\; \; }D_{50} >0.0005} \end{array}\right.$

Van Rijn (1993)¶

The third possible sediment transport formulation are the Van Rijn (1993 equations (keyword: form = vanrijn1993) Van Rijn (1993) distinguishes between sediment transport below the reference height at which sediment is treated as bed-load transport and above the reference height which is treated as suspended-load.

The bed-load transport is computed with

(97) ${Sb} = 0.006\rho {}_s{w_s}{D_{50}}{M^{0.5}}{M_e}^{0.7}$

In which the sediment mobility number due to waves and currents ( ( ${M}$ ) ) can be calculated with the following formulation with ( ${v}_{e}$ ) being the effective velocity. The excess sediment mobility number ( ( ${M}_{e}$ ) ) is computed with the difference between the effective and critical velocity ( ( ${v}_{cr}$ ) ).

(98) $M = \frac{{{v_e}^2}}{{(s - 1)g{D_{50}}}}$

For the suspended-load, first the reference concentration is calculated in accordance with ([VanRijn84])

(99) ${c_a} = 0.015{\rho _s}\frac{{{D_{50}}{T_a}^{1.5}}}{{\alpha {D_*}^{0.3}}}$

Secondly, the concentration profile is resolved by calculating the bed-shear stresses due to waves and currents and estimating the concentration profile where the combined bed shear stress exceeds the critical bed shear stress. Depth-averaged mixing due to waves and currents.

Effects of wave non-linearity¶

Effects of wave skewness and asymmetry are accounted for in the advection-diffusion equation, repeated here:

(100) $\begin{array}{c} {\frac{\partial hC}{\partial t} +\frac{\partial hC(u^{E} -u_{a} \sin \theta _{m} )}{\partial x} +\frac{\partial hC(v^{E} -u_{a} \cos \theta _{m} )}{\partial y} } \\ {+\frac{\partial }{\partial x} \left[D_{h} h\frac{\partial C}{\partial x} \right]+\frac{\partial }{\partial y} \left[D_{h} h\frac{\partial C}{\partial y} \right]=\frac{hC_{eq} -hC}{T_{s} } } \end{array}$

XBeach considers the wave energy of short waves as averaged over their length, and hence does not simulate the wave shape. A discretization of the wave skewness and asymmetry was introduced by [vanTdVries09], to affect the sediment advection velocity. In this equation ${u}_{a}$ is calculated as function of wave skewness ( ${S}_{k}$ ), wave asymmetry parameter ( ${A}_{s}$ ), root-mean square velocity ${u}_{rms}$ and two calibration factor ${f}_{Sk}$ and ${f}_{As}$ (keyword: facSk & facAs), see equation (101). To set both values one can use the keyword: facua. The method to determine the skewness and asymmetry is described in section 2.3.4. A higher value for ${u}_{a}$ will simulate a stronger onshore sediment transport component.

(101) $u_{a} =(f_{Sk} S_{k} -f_{As} A_{s} )u_{rms}$

Hindered erosion by dilatancy¶

Under overwash and breaching conditions (high flow velocities and large bed level variations in time), dilatancy might hinder the erosion rates ([dV14]). To account for this effect, the theory of [vR10] could be applied (keyword: dilatancy = 1), reducing the critical Shields parameter at high flow velocities:

(102) $\theta _{cr}^{adjusted} =\theta _{cr} \left(1+\frac{v_{e} }{k_{l} } \frac{n_{l} -n_{0} }{1-n_{l} } \frac{A}{\Delta } \right)$

In this equation, ${v}_{e}$ refers to the erosion velocity, ${k}_{l}$ is the permeability, $n0$ is the porosity prior, ${n}_{l}$ is the porosity in the sheared zone (keyword: pormax) and the parameter $A$ (keyword: rheeA) is equal to 3/4 for single particles and approximately 1.7 for a continuum.

The larger the permeability of the bed, the smaller the dilatancy effect. [vR10] suggests using the equation proposed by [dA87]:

(103) $k_{l} =\frac{g}{160\nu } D_{15}^{2} \frac{n_{0}^{3} }{\left(1-n_{0}^{2} \right)}$

Finally, the erosion velocity ${v}_{e}$ , is the velocity at which the bottom level decreases:

(104) $v_{e} =\left\{\begin{array}{l} {-\frac{dz_{b} }{dt} {\; \; \; \; \; \; \; \; \; \; if\; \; \; \; \; \; \; \; \; \; \; }\frac{dz_{b} }{dt} <0} \\ {{\; \; \; \; }0{\; \; \; \; \; \; \; \; \; \; \; else}\; \; \; \; \; \; \; \; \; \; \; } \end{array}\right.$

Bed slope effect¶

The bed slope affects the sediment transport in various ways ([WvRVanOrmondt+07]):

The bed slope influences the local near-bed flow velocity;
The bed slope may change the transport rate once the sediment is in motion;
The bed slope may change the transport direction once the sediment is in motion;
The bed slope will change the threshold conditions for initiation of motion.

The influence of the bed slope on the local hydrodynamics is not considered in XBeach.

Two possible expressions are implemented to change the magnitude of the sediment transport. The first method is the default one in XBeach:

(105) $\begin{array}{l} {q_{x,slope} =q_{x} -\alpha hC\sqrt{\left(u^{L} \right)^{2} +\left(v^{L} \right)^{2} } \frac{\partial z_{b} }{\partial x} } \\ {q_{y,slope} =q_{y} -\alpha hC\sqrt{\left(u^{L} \right)^{2} +\left(v^{L} \right)^{2} } \frac{\partial z_{b} }{\partial y} \; \; \; \; \; \; \; } \end{array}$

This method could be applied on either the total sediment transport (keyword: bdslpeffmag = roelvink_total) or only on the bed load transport (keyword: bdslpeffmag = roelvink_bed). The second method is based on the engineering formula of [Sou97]:

(106) $q_{slope} =q\left(1-\alpha \frac{\partial z_{b} }{\partial s} \right)\;$

Also this method could be applied on the total transport (keyword: bdslpeffmag = soulsby_total) or on the bed load transport only (keyword: bdslpeffmag = soulsby_total). To change the direction of the bed load transport, the expressions of [vB47] and [TvMS95] could be used (keyword: bdslpeffdir = talmon):

(107) $\tan \left(\alpha _{\psi ,new} \right)=\frac{\sin \left(\alpha _{\psi } \right)-f\left(\theta \right)\frac{dz_{b} }{dy} }{\cos \left(\alpha _{\psi } \right)-f\left(\theta \right)\frac{dz_{b} }{dx} }$

(108) $f\left(\theta \right)=\frac{1}{9\left(D_{50} /h\right)^{0.3} \theta ^{0.5} }$

(109) $\begin{array}{l} {q_{b,x} =\left|q_{b} \right|\cos \left(\alpha _{\psi ,new} \right)} \\ {q_{b,y} =\left|q_{b} \right|\sin \left(\alpha _{\psi ,new} \right)} \end{array}$

Finally, it is possible to adjust the initiation of motion criteria for the total transport (keyword: bdslpeffini = total) or the bed load transport only (keyword: bdslpeffini = bed) through ([Sou97]):

(110) $\theta _{cr}^{adjusted} =\theta _{cr} \frac{\cos \left(\psi \right)\sin \left(\beta \right)+\sqrt{\cos ^{2} \left(\beta \right)\tan ^{2} \left(\phi _{i} \right)-\sin ^{2} \left(\psi \right)\sin ^{2} \left(\beta \right)} }{\tan \left(\phi _{i} \right)}$

In this equation is $\psi$ the difference in angle between the flow direction and the on-slope directed vector, $\beta$ the bed slope and ${\phi}_{i}$ the angle of repose.

[dV14] provides a detailed overview on how the bed slope and flow direction are calculated and how the bed slope effect is combined with the dilatancy concept if the adjustment to the initiation of motion is considered.

It is also possible to prescribe a given bed slope. The result is that the swash zone profile is teased towards a given bermslope. This functionality Works in surfbeat mode (where H/h>1) and in stationary mode (where h<1m) and have been tested for profiles Praia de Faro (keyword: bermslope = desired slope).

Bottom updating¶

See also

Bed updating is implemented in func:morphevolution/bed_update.

Due to sediment fluxes¶

Based on the gradients in the sediment transport the bed level changes according to:

(111) $\frac{\partial z_{b} }{\partial t} +\frac{f_{mor} }{\left(1-p\right)} \left(\frac{\partial q_{x} }{\partial x} +\frac{\partial q_{y} }{\partial y} \right)=0$

In $\rho$ is the porosity, ${f}_{mor}$ (keyword: morfac) is a morphological acceleration factor of O(1-10) ([RRT04]) and ${q}_{x}$ and ${q}_{y}$ represent the sediment transport rates in x- and y-direction respectively. Sediment transport can be activated with the keyword: sedtrans.

The morphological acceleration factor speeds up the morphological time scale relative to the hydrodynamic timescale. It means that if you have a simulation of 10 minutes with a morfac of 6 you effectively simulate the morphological evolution over one hour. There are now two ways in which you can input the time-varying parameters in combination with morfac:

All times are prescribed on input in morphological time. If you apply a morfac all input time series and other time parameters are divided internally by morfac. This is determined with keyword morfacopt = 1. If you now specify a morfac of 6, the model just runs for 10 (hydrodynamic) minutes each hour, during which the bottom changes per step are multiplied by a factor 6. This of course saves a factor of 6 in computation time.

This method is appropriate for short-term simulations with extreme events. This approach is only valid as long as the water level changes that are now accelerated by morfac do not modify the hydrodynamics too much. This is the case if the tide is perpendicular to the coast and the vertical variations do not lead to significant currents. If you have an alongshore tidal current, as is the case in shallow seas, you cannot apply this method because you would affect the inertia terms and thus modify the tidal currents.

Alternatively you run the model over, say, over a tidal cycle, and apply the morfac without modifying the time parameters. This means you leave all the hydrodynamic parameters unchanged and just exaggerate what happens within a tidal cycle. As long as the evolution over a single tidal cycle is limited, the mean evolution over a tidal cycle using a morfac is very similar to running morfac tidal cycles without morfac. See [Roe06] for a more detailed description of this approach. This option is enabled with keyword: morfacopt = 0.

This method is more appropriate for longer-term simulations with not too extreme events.

Avalanching¶

To account for the slumping of sandy material from the dune face to the foreshore during storm-induced dune erosion avalanching (keyword: avalanching) is introduced to update the bed evolution. Avalanching is introduced via the use of a critical bed slope for both the dry and wet area (keyword: wetslp and dryslp). It is considered that inundated areas are much more prone to slumping and therefore two separate critical slopes for dry and wet points are used. The default values are 1 and 0.3 respectively. When this critical slope is exceeded, material is exchanged between the adjacent cells to the amount needed to bring the slope back to the critical slope.

(112) $\left|\frac{\partial z_{b} }{\partial x} \right|>m_{cr}$

To prevent the generation of large shockwaves due to sudden changes of the bottom level, bottom updating due to avalanching has been limited to a maximum speed of ${v}_{av,max}$ (keyword: dzmax). Equation (113) shows the resulting bed level change within one time step.

(113) $\begin{array}{l} {\Delta z_{b} =\min \left(\, \, \, \, \left(\left|\frac{\partial z_{b} }{\partial x} \right|-m_{cr} \right)\Delta x,\, \, \, \, v_{av,\max } \Delta t\right)\quad ,\frac{\partial z_{b} }{\partial x} >0} \\ {\Delta z_{b} =\max \left(-\left(\left|\frac{\partial z_{b} }{\partial x} \right|-m_{cr} \right)\Delta x,-v_{av,\max } \Delta t\right)\quad ,\frac{\partial z_{b} }{\partial x} <0} \end{array}$

Bed composition¶

If the effect of different sediment fractions, sorting and armoring are of importance, a bed composition constituting multiple sediment fractions can be defined. Each sediment fraction is characterized by a median grain size ( ${D}_{50}$ ) and possible a ${D}_{15}$ and ${D}_{90}$ as well. When using multiple sediment fractions, multiple bed layers are needed as well to describe the vertical distribution of the sediment fractions in the bed.

By specifying multiple bed layers, XBeach can keep track of the different sediment fractions both in the horizontal and in the vertical. Coarse sediments may be deposited on top of fine sediment after which erosion of the coarse sediment is needed to expose the fine sediment again, effectively armoring the bed. Three types of bed layers are distinguished: 1) the top layers 2) the variable or “breathing” layer and 3) the bottom layers. The top layer is the only layer that interacts with the water column and can be eroded, but preserves its thickness. The bottom layers are layers of constant thickness that move with the top layer. A single variable or “breathing” layer is defined that adapts its thickness to the erosion and sedimentation of the bed. For example: if a grid cell is eroded, particular fractions of sediment are removed from the top layer, but the top layer preserves its thickness and thus it takes the same volume of sediment, likely of different composition than the eroded sediment, from the layer below. If this layer is a top layer as well, the thickness is preserved and again the same volume of sediment is taken form a lower bed layer. This continues until the variable or “breathing” layer is reached. This layer adapts its thickness to the amount of erosion. If the thickness of the layer becomes too small, the variable layer is merged with an adjacent bottom layer and a new bottom layer is defined underneath the existing ones to ensure a constant number of bed layers. Reversely, if a grid cell is accreting, the thickness of the variable layer will be increased and with sufficient increase the variable layer will be split in two effectively creating a new bottom layer. The lowest existing bottom layer is then discarded to ensure a constant number of bed layers. The “breathing” layer can be the upper or bottom layer in which case the top layer or bottom layer class does not exist. The thickness of the different layer classes can be set separately (keyword: dzg1, dzg2 and dzg3) or at once (keyword: dzg).

Each grid cell in XBeach holds its own sediment distribution and the sediment transport formulations are used differentiate between fractions. Therefore the distribution of sediment may change over time and processes like armoring and sorting can be simulated. Due to the shifting of sediment between bed layers numerical mixing of sediment occurs. Choosing bed layer thicknesses that are in balance with the expected erosion and deposition during the simulation should keep the numerical mixing to a minimum. A bed layer thickness that is too large will result in relatively uniform behavior, while a bed layer thickness that is too small will result in a lot of shifting and thus numerical mixing (Fig. 8).

Visualization of the diffusion that occurs when XBeach calculates sediment compositions. After sedimentation of fine sediment on top of coarser material it is uniformly mixed over the whole layer. Subsequent erosion erodes both the fines as the coarser material. To avoid this phenomenon, layers should not be too thick ([vdZ14]).

Ship-induced wave motions¶

See also

Ship-induced wave motions are implemented in mod:ship_module.

A relatively new application field for XBeach is the generation and propagation of waves induced by sailing vessels. This functionality has been implemented recently ([ZRVL13]), and has currently been used in several studies (e.g. [ZRZvW14], [dJRB13]), showing very good results.

For computing ship-induced waves the non-hydrostatic version of XBeach is used. A moving ship is represented as a pressure head that moves along a pre-defined track through the model domain. The ship is defined on a separate grid, where the ship draft is specified per grid point. Each computational time step the ship draft is interpolated from the ship grid to the global grid, where the ship volume is kept constant. Then the water pressure head in each global grid cell is updated based on the interpolated ship draft. By moving the pressure fields, the waves are generated and will propagate further through the global domain.

In Fig. 9 an example XBeach setup for ship waves is shown. The ship track is user defined and can, for instance, be obtained from the Automatic Identification System (AIS) for marine traffic. In this example, the model results were compared with measurements taken at Bath, The Netherlands. A filtered time series of the measured and computed water level is shown in Fig. 10. The time series was filtered to focus on the computation of the primary ship wave.

Example XBeach setup (left) and result (right) for a ship wave simulation in the Scheldt Estuary (The Netherlands). The ship track (red dashed line) is user-defined, and the measurement location is indicated (magenta dot).

Example XBeach result for ship-induced waves. Measurements are taken at Bath, in the Scheldt Estuary, The Netherlands ([SHvdWT11]).

In addition to the propagation of ship-induced waves, XBeach computes the forces and moments acting on the ship body. With this functionality, passing ship effects can be analyzed (e.g. [ZRVL13]).

Gravel (XBeach-G)¶

XBeach-G was a branch of the main XBeach development that has been developed to simulate storm impacts on gravel beaches. The development of XBeach-G have been taking place as a joint collaboration between Plymouth University and Deltares, as part of the EPSRC-funded NUPSIG-project. The relevant XBeach-G formulations have been merged back into to the XBeach trunk for the XBeachX release (fall 2017). XBeach-G formulations can be activated with the keyword useXBeachGSettings = 1).

XBeach-G uses the one-layer, depth-averaged, non-hydrostatic extension to the XBeach model (nonh=1), which is similar to the SWASH model ([ZSS11]) to solve wave-by-wave flow and surface elevation variations due to short waves in intermediate and shallow water depths. This is particularly important for application on gravel beaches, where due to steep slopes swash motion is mainly at incident wave frequencies, and infragravity wave motion, which dominates the inner surf and swash zone on sandy beaches during storms, is of secondary importance. To correctly account for upper swash infiltration losses and exfiltration effects on lower swash hydrodynamics on gravel beaches, XBeach-G computes groundwater dynamics and the exchange between groundwater and surface water using the XBeach groundwater model (gwflow = 1). Again, interaction between swash flows and the beach groundwater table are considered particularly important on gravel beaches due to the relatively large hydraulic conductivity of the sediment, while on sandy beaches this process is of significantly less importance. Finally, gravel sediment transport processes (McCall & Van Rijn) have been included in XBeach-G to simulate the morphodynamics of gravel beaches during storms. These transport processes are currently under further development and validation.

For more information on XBeach-G, download the PhD thesis of McCall (2015) on URL: http://hdl.handle.net/10026.1/3929.

Boundary conditions¶

Waves¶

See also

Wave boundary conditions are implemented in mod:waveparams. The latest functionalities, like spatially varying spectral conditions are implemented in mod:spectral_wave_bc_module.

XBeach allows users to include two different options for wave boundary conditions in the model. These wave boundary conditions can be applied only at the seaward boundary (keyword: wbctype). First of all, in Spectral conditions the method to specify wave spectra is discussed. Secondly, in Non-spectral conditions the method to apply non-spectra, such as stationary wave conditions or time-series is elaborated. In Lateral boundary conditions the lateral boundary conditions for waves are discussed. There is currently not a possibility to force waves on the landward boundary of a model.

Spectral conditions¶

The most-used wave boundary condition in XBeach is a spectral type. The input description of spectral wave boundary conditions can be found in Spectral wave boundary conditions. XBeach allows the user to define these with three possibilities:

: With this option you define the boundary condition as parametric spectral input. The parameters (i.e. the spectral shape, the wave period and the directional spreading) can be specified. The option is especially handy when there is no nested model or measured spectrum. Here are two options:
1. Specify a single parametric spectrum (keyword wbctype = jons).
2. Specify a series of parametric spectra (keyword wbctype = jons_table).
: In this case the two-dimensional (frequency-direction) output by the spectral wave model SWAN (.sp2 files) can be specified. (keyword wbctype = swan). This option is especially convenient when nesting XBeach into a SWAN model.
: In this case a more general type spectrum can be specified. (keyword wbctype = vardens). This option is often used when a measured spectrum is available.

Non-spectral conditions¶

XBeach also allows the user to define non-spectral wave boundary conditions. This is a variation of both wave conditions without wave groups and time series. The input description of non-spectral wave boundary conditions can be found in Non-spectral wave boundary conditions. XBeach allows the user to define these with two possibilities:

This means that a uniform and constant wave energy is specified, based on the given values of , , direction and power of the directional distribution function. The station boundary condition will contain wave groups. Here there are two options:
1. Specify a single sea state (keyword wbctype = stat)
2. Specify a series of sea states (keyword wbctype = stat_table)
. The user can also specify the variation in time of the wave energy. There are three options:
1. First-order time series of waves (keyword wbctype = ts_1). XBeach will calculate the bound long wave based on the theory of [LHS64]).
2. Second-order time series of waves (keyword wbctype = ts_2). The bound long wave is specified by the user via a long wave elevation.
3. It is also possible to specify a variation in time of the horizontal velocity, vertical velocity and the free surface elevation (keyword: wbctype = ts_nonh). Last two terms are optional in this boundary conditions type.

Special conditions¶

Besides clear spectral or non-spectral wave boundary conditions, there are also three special boundary condition types implemented in XBeach.

(keyword wbctype = bichrom). In this case, XBeach will be forced with regular wave groups as the two short-wave components force one difference (infragravity) wave period. The user needs to specify not only variables of the stationary situation but also a wave period for the long wave. This wave period will be used to calculate the long wave based on the theory of [LHS64]. The bichromatic boundary condition is the most simplified form of a wave spectrum.
(keyword wbctype = off). This is a simple no wave action boundary condition. It still allows for a tidal record to be specified, however this trough the zs0file parameter.
(keyword: wbctype = reuse). If the user does not wish to recalculate boundary condition files or specifically wants to reuse the boundary condition files of another XBeach simulation should be used. No further wave boundary condition data need be given. Obviously, the calculation grid should remain the same between runs, as the angles and number of grid points are embedded in the boundary condition files.

Lateral boundary conditions¶

There are two options to set the lateral boundaries for the wave model:

Neumann boundaries (keyword: lateralwave = neumann): here the longshore gradient is set to zero.
Wave crest boundaries (keyword: lateralwave = wavecrest). here the gradient in the wave energy along the wave crest is set to zero.

For the stationary wave mode (keyword: wavemodel = stationary) this is the only option. It allows a correct representation of the wave propagation near the lateral boundaries, without the usual shadow zones in e.g. SWAN. By neglecting the longshore gradients, the model automatically computes a consistent 1D solution.

For the surfbeat mode (keyword: wavemodel = surfbeat), Neumann leads to shadow zones, not so much in the wave height, but in the groupiness; the ’blobs’ propagating in the mean wave direction turn into elongated, longshore uniform patches. To reduce this effect, the gradient along the wave crests of the wave energy can be set to zero, instead of the longshore gradient (keyword: lateralwave = wavecrest). This way the crests of the wave groups have approximately the right orientation, though the along-crest groupiness also disappears. In the wavecrest case, the wave refraction may be overestimated leading to somewhat too large longshore currents. The effects of both boundary conditions are shown in Fig. 11.

Effect of the lateral wave boundary conditions on root-mean square wave height patterns (top) and longshore velocity (bottom) for the Delilah test case. In this figure the left panels are used for simulations with Neumann boundaries and the right panel with the wavecrest boundary.

Shallow water equations¶

Offshore boundary¶

Typically, an offshore or lateral boundary is an artificial boundary which has no physical meaning. On the offshore boundary wave and flow conditions are imposed. In the domain waves and currents will be generated which need to pass through the offshore boundary to the deep sea with minimal reflection. One way to do this is to impose a weakly reflective-type boundary condition (absorbing-generating), but there are also other possibilities implemented in XBeach (keyword: front). This method can be applied in 1D or 2D, is recommended and therefore the default value for XBeach.

In XBeach, there are two options with regard to the offshore absorbing-generating boundary condition. With the parameter setting front = abs1d a simple one-dimensional absorbing-generating boundary condition is activated. This option allows for a time-varying water level (surge and/or infragravity waves) to be specified at the boundary while allowing any waves propagating perpendicularly towards the boundary to be absorbed (i.e., passed through the boundary with a minimum of reflection. It is therefore only useful for 1D (flume like) simulations.

With option front = abs2d (default value) the formulation by [vDS97] is activated which in turn is based on [VSO81] and is based on the ‘Method of Characteristics’. This boundary condition allows for obliquely-incident and obliquely-reflected waves to pass through the boundary. It is possible to account for situations with boundary-perpendicular and boundary-parallel currents. In order to differentiate between the particle velocities, the keyword epsi must be set. This parameter control a simple Kalman-update filter which controls which part of the particle velocity is assumed to be part of the current and which part is wave-related. By default XBeach computes the value for epsi automatically using offshore boundary conditions (keyword: epsi = -1).

There are three other possibilities implemented besides the absorbing-generating boundary conditions:

No flux wall (keyword: front = wall). This boundary condition type is a simple no flux boundary condition.
Water level specification (keyword: front = wlevel). This boundary sets the water level at a prescribed value. This can be constant or time-varying. With this option the outgoing long waves are not absorbed.
Boundary condition for the non-hydrostatic option (keyword: : front = nonh_1d). This boundary condition is required for non-hydrostatic simulations.
Radiation boundary condition (keyword: front = waveflume). This boundary uses a continuity relation at the front boundary. This means that no net water can come into the model domain. The wave flume boundary condition is especially useful in lab experiments with a large set-up (e.g. coral reefs).

Lateral boundaries¶

Lateral boundaries are the boundaries perpendicular to the coastline. Usually these are artificial, because the model domain is limited but the physical coast will continue. At these boundaries (keywords: left & right) we need to prescribe information about the area beyond the numerical model domain in such a way that the boundary condition does not influence the results in an adverse way. One way to do this is to prescribe a so-called “no-gradient” or Neumann boundaries (XBeach default), which state that there is locally no change in surface elevation and velocity, but there are also other possibilities implemented into XBeach. This method is recommended and is therefore the default value for XBeach. Each lateral boundary is a separate condition, so it is possible to mix different type of lateral boundary per side.

Neumann boundary conditions are activated where the longshore water level gradient is prescribed. The alongshore gradient is prescribed by the difference in specified water levels at the offshore corner points, divided by the alongshore length of the domain. This type of Neumann boundary condition has been shown to work quite well with (quasi-) stationary situations, where the coast can be assumed to be uniform alongshore outside the model domain. So far we have found that also in case of obliquely incident wave groups this kind of boundary conditions appears to give reasonable results when a shadow zone is taken into account. This means that regions where the boundary conditions are not fully enforced the results are not taken into account. Neumann boundaries can be individually defined (keyword: left = neumann).

There are three other possibilities implemented besides the absorbing-generating boundary conditions:

Simple no-flux boundary conditions can also be applied (keyword: left = wall). Wall boundary conditions will result in a zero velocity at the lateral boundary.
Velocity at the boundary will be calculated from NLSWE, but only include the advective terms (keywords: left = no_advec). The effect is that only terms that decrease the velocity will be taken into account. The result is an intermediate form between a full Neumann boundary and a wall boundary.
Velocity at the boundary will simply be copied from the adjacent cell in the model domain (keyword: left = neumann_v).

Tide and surge¶

XBeach can take in up to four time-vary tidal signals to be applied to the four boundaries (offshore-right, offshore-left, backshore-left, backshore-right). A time-varying water level signal is read into XBeach by reading the specified file in zs0file. The input signal will be interpolated to the local time step of the simulation; therefore the signals only need to be long enough and temporally-fine enough to resolve the water level phenomenon of interest (i.e. tide variations, surge event).

There are now four options for handling the tidal and/or surge contribution to the boundaries:

Uniform water level (keyword: tideloc = 0)
One time-varying water level signal (keyword: tideloc = 1)
Two time-varying water level signals, which requires point of application indication. (keyword: tideloc = 2)
Four time-varying water level signals (keyword: tideloc = 4)

For the option with a uniform water level the value specified in the params.txt is applied in the complete model domain (keyword: zs0). For the option with one time-varying water level signal the specified water level is applied (keyword: zs0file = <name_of_your_time_series_file>) to the offshore boundary and a fixed value is applied at the backshore boundary (keyword: zs0). For the option with two time-varying water level signals two water level signals are read from the zs0file. Note: one tidal record is applied to both sea corners and one tidal record to both land corners. This means there is no alongshore variation. An alongshore variation can be applied when applying four time-varying water level signals.

River and point discharge¶

The effect of a river outflow or other discharges can be simulated with XBeach. Multiple discharge locations can be designated. At a discharge location the discharge orifice is defined as well as the discharge time series in ${\rm m}^{3}/{\rm s}$ . The discharge orifice always constitutes an uninterrupted series of full grid abreast cell borders. It is not possible to define a discharge over half a grid cell nor is it possible to define a single discharge through grid cell borders that are either not adjacent or are not abreast.

At each time step the model sets the discharge and velocities at the grid cell borders that constitute the discharge orifice, which can be computed given the size of the discharge orifice and discharge time series. The discharge is positive in positive x or y direction. An exception is made when discharges are defined at the domain border. In that case the discharge is positive towards the domain (influx).

When a discharge is defined with a zero size orifice the discharge is assumed to be in vertical direction where a positive discharge is into the domain (influx). In these cases the discharge is linked to the closest grid cell center and at each time step mass according to the discharge time series is added. No momentum is added in case of a vertical discharge.

Sediment transport¶

The boundary conditions for sediment transport are Neumann boundaries everywhere, implying that the cross-boundary gradients in the advection-diffusion equation are set to zero, as well as the gradients of the bed load transports in that direction. Cross-shore profile changes due to cross-shore transport gradients are possible, allowing the boundary to smoothly follow the rest of the model. Still, it is good modeling practice to have the boundaries away from the area of interest.

Input description¶

General¶

Upon running the XBeach executable xbeach.exe, the file params.txt in the current working directory will be read. The params.txt file contains grid and bathymetry info, wave input, flow input, morphological input, etc. in the form of keyword/value pairs. Each keyword/value pair may contain an actual model parameter or refer to another file with additional information on the model setup. If a params.txt file cannot be found then XBeach will not run.

In the params.txt file there can be a single keyword/value pair per line. The keywords can be specified in any order. A keyword/value pair is separated by an equal sign (=). Each line containing an equal sign is interpreted as a keyword/value pair. Reversely, any lines without an equal sign are ignored and may be used for comments. Only a few keywords are required for the model to run, others have default values that are used in case the keyword is not mentioned in the params.txt file. The essential parameters for a simulation with a JONSWAP spectrum are listed below:

A . This can both in XBeach format (separate x and y files; keyword: xfile and yfile) or Delft3D (one single xy file; keyword: xyfile). On top of that the user needs to specify the width of each domain (keyword: nx and ny)
A file (keyword: depfile) that matches with the grid you specified at 1)
A (keyword: tstop) in seconds
A for short waves and rollers. The grid is determined by a minimum and maximum angle and width per bin (keywords: thetamin, thetamax and dtheta).
A (keyword: wbctype = jons). With a separate file containing the variables of the parametric (keyword: bcfile).

It is strongly recommended to specify as few parameters explicitly as possible and rely on the defaults for the other parameters. When running XBeach, a file called xbeach.log is created, which lists all the parameters set through the params.txt file but also all parameters not set, for which the defaults are used. When the user starts the model, it generates a file named XBlog.txt. In this file all the different keyword available are determined. When no keyword is defined the default value will be applied.

This chapter describes the possibilities of the params.txt file and any auxiliary information files that are called from the params.txt file. The tables in this chapter contain a description of the keywords, the default values, its units and recommended value ranges, while the formats for additional input files are described in the relevant sections. Keyword marked with an astrix (*) are essential for XBeach to run. Keywords marked with a plus (+) are considered advanced expert options and should not be used for regular applications of XBeach.

In this chapter, any references to keywords refer to keywords that can be used in the params.txt file. Also any references to time indications are in seconds unless stated otherwise. A typical params.txt file for a 1D XBeach model is:

params.txt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% XBeach parameter settings input file                                %%%
%%%                                                                     %%%
%%% date: 01-Jan-2015 12:00                                             %%%
%%% function: xb_write_params                                           %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% Grid parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

depfile = bed.dep
posdwn = 0
nx = 265
ny = 0
alfa = 0
vardx = 1
xfile = x.grd
yfile = y.grd
thetamin = -90
thetamax = 90
dtheta = 15
thetanaut = 0

%%% Model time %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

tstop = 3600

%%% Physical constants %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

rho = 1025

%%% Tide boundary conditions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

tideloc = 2
zs0file = tide.txt

%%% Wave boundary condition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

wbctype = jons
bcfile = filelist.txt

%%% Output variables %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

outputformat = netcdf
tint = 3600
tstart = 0
nglobalvar = 3
zb
zs
H

Physical processes¶

XBeach supports a variety of physical processes from generic, like waves and flow, to very specific, like ship motions and point discharge. Each process can be switched on or off. The commonly used processes are turned on by default. The table below lists the keywords used to switch on or off physical processes in XBeach.

Overview of available keywords related to physical processes¶
parameter	description	default	range
advection	Include advection in flow solver	1	0 - 1
avalanching	Turn on avalanching	1	0 - 1
bchwiz	Turn on beachwizard	0	0 - 1
cyclic	Turn on cyclic boundary conditions	0	0 - 1
flow	Turn on flow calculation	1	0 - 1
gwflow+	Turn on groundwater flow	0	0 - 1
lwave	Turn on short wave forcing on nlsw equations and boundary conditions	1	0 - 1
morphology	Turn on morphology	1	0 - 1
nonh+	Turn on non-hydrostatic pressure: 0 = nswe, 1 = nsw + non-hydrostatic pressure compensation stelling & zijlema, 2003	0	0 - 1
q3d	Turn on quasi-3d sediment transport	0	0 - 1
sedtrans	Turn on sediment transport	1	0 - 1
setbathy	Turn on timeseries of prescribed bathy input	0	0 - 1
ships+	Turn on ship waves	0	0 - 1
single_dir+	Turn on stationary model for refraction, surfbeat based on mean direction	0	0 - 1
snells+	Turn on snell’s law for wave refraction	0	0 - 1
swave	Turn on short waves	1	0 - 1
swrunup	Turn on short wave runup	0	0 - 1
vegetation+	Turn on interaction of waves and flow with vegetation	0	0 - 1
viscosity	Include viscosity in flow solver	1	0 - 1
wavemodel	Stationary (0), surfbeat (1) or non-hydrostatic (2)	surfbeat	stationary, surfbeat, nonh
wind	Include wind in flow solver	1	0 - 1

Grid and bathymetry¶

XBeach’ spatial grid size is defined by the keywords nx and ny. Here nx are the number of grid points in the cross-shore direction and ny the number in the alongshore direction. The size of the computational grid will be nx +1 by ny +1 cells large. The initial bathymetry is provided using a separate file that is referred to by the depfile keyword, which has to have a size of [nx+1, ny+1]. This file contains an initial bed level for each grid cell where each line corresponds to a transect in x-direction (cross-shore). The values are positive down by default (so e.g. a value of ‘10’ is 10 meters depth), but this can be changed using the posdwn keyword.

Three main types of XBeach grids are supported: fast 1D, 1D and 2DH. Fast 1D grids have a single alongshore grid cell and thus a value ny = 0 and thus a single row (ny+1=1) in the depfile. The 1D grids have 3 alongshore grid cells and thus a value ny = 2 and three rows in the depfile. The 2DH grids have more than 3 alongshore grid cells, a value ny >2 and as many rows in the depfile. In general, the bathymetry file has the following space-separated format:

bed.dep

<z 1,1> <z 2,1> <z 3,1> ... <z nx,1> <z nx+1,1>
<z 1,2> <z 2,2> <z 3,2> ... <z nx,2> <z nx+1,2>
<z 1,3> <z 2,3> <z 3,3> ... <z nx,3> <z nx+1,3>

...

<z 1,ny> <z 2,ny> <z 3,ny> ... <z nx,ny> <z nx+1,ny>
<z 1,ny+1> <z 2,ny+1> <z 3,ny+1> ... <z nx,ny+1> <z nx+1,ny+1>

XBeach spatial grids can be equidistant or non-equidistant. In the former case the grid size is defined by the keywords dx and dy. In the latter case the keyword vardx should be set to 1 and x- and y-coordinates of the grid cells should be provided through the files referenced by the xfile and yfile keywords. These files take exactly the same format as the depfile file where all coordinates along the x-direction are in one row and each row represents a cell in y-direction. XBeach grids are defined in a coordinate system of choice and can be either rectangular or curvilinear grids as discussed in Domain and definitions.

Delft3D grids created with tools like RFGRID are also supported. To use Delft3D grids, choose gridform = delft3d and provide a grid file via the keyword xyfile. The format of Delft3D grids is not described here, but can be found in the Delft3D manual ([Del11]). Also forced updating of bathymetries is supported as described in Bed update.

Apart for the spatial grid, XBeach also uses a directional grid for short waves and rollers. The grid is determined by a minimum and maximum angle and a directional bin size using the keywords thetamin, thetamax and dtheta respectively. The thetamin and thetamax angles are either defined according to the Cartesian convention (angle w.r.t. the computational x-axis) or according to the nautical convention (angle w.r.t. deg. N, so from W is 270 deg. N). The convention is chosen using the keyword thetanaut (thetanaut = 0 for Cartesian and thetanaut = 1 for Nautical)

Examples of typical input for a non-equidistant, fast 1D XBeach model, together with the params.txt example at the start of this chapter, are:

depfile = bed.dep

-20.00 -20.00 -19.90 -19.80 -19.70 ... 14 14 15 15 15

xfile = x.grd

0.00 10.00 20.00 30.00 40.00 ... 1992.00 1994.00 1996.00 1998.00 2000.00

yfile = y.grd

0.00 0.00 0.00 0.00 0.00 0.00 0.00 ... 0.00 0.00 0.00 0.00 0.00 0.00 0.00

All keywords related to grid and bathymetry input are listed in the following table:

Overview of available keywords related to grid parameters¶
parameter	description	default	range	units
alfa	Angle of x-axis from east	0.0	0.0 - 360.0	deg
depfile*	Name of the input bathymetry file			<file>
dtheta*	Directional resolution	10.0	0.1 - 180.0	deg
dtheta_s*	Directional resolution in case of stationary refraction	10.0	0.1 - 20.0	deg
dx*	Regular grid spacing in x-direction	-1.0	0.0 - 1000000000.0	m
dy*	Regular grid spacing in y-direction	-1.0	0.0 - 1000000000.0	m
gridform	Grid definition format	xbeach	xbeach, delft3d
nx*	Number of computational cell corners in x-direction	50	2 - 10000
ny*	Number of computational cell corners in y-direction	2	0 - 10000
nz	Number of computational cells in z-direction	1	1 - 100
posdwn	Bathymetry is specified positive down (1) or positive up (-1)	1.0	-1.0 - 1.0
thetamax*	Higher directional limit (angle w.r.t computational x-axis)	90.0	-360.0 - 360.0	deg
thetamin*	Lower directional limit (angle w.r.t computational x-axis)	-90.0	-360.0 - 360.0	deg
thetanaut	Switch to specify thetamin and thetamax in nautical convention rather than cartesian	0	0 - 1
vardx	Switch for variable grid spacing	0	0 - 1
xfile	Name of the file containing x-coordinates of the calculation grid			<file>
xori	X-coordinate of origin of axis	0.0	-1000000000.0 - 1000000000.0	m
xyfile*	Name of the file containing delft3d xy-coordinates of the calculation grid			<file>
yfile	Name of the file containing y-coordinates of the calculation grid			<file>
yori	Y-coordinate of origin of axis	0.0	-1000000000.0 - 1000000000.0	m

Waves input¶

An XBeach model is generally forced by waves on its offshore boundary. These waves are described by the wave boundary conditions discussed in this section. The details of the wave motions within the model are described by the wave numerics in terms of the wave action balance (see Short wave action balance), wave dissipation model (see 0) and wave roller model (see Roller energy balance)

XBeach supports a variety of wave boundary condition types that are divided in two main groups: stationary and spectral boundary conditions. The wbctype keyword can be used to select one particular type of wave boundary conditions. Waves gives an overview of all types of wave boundary conditions available for XBeach. Fig. 12 can be used to help determine what type of wave boundary conditions is appropriate for your case. Each wave boundary condition type is explained in the following subsections. Note that most spectral wave boundary conditions can vary both in space and time using a FILELIST and/or LOCLIST construction as described in Temporally and/or spatially varying wave boundary conditions.

Overview of available keywords related to wave boundary condition parameters¶
parameter	description	default	range	units
Hrms	Hrms wave height for instat = stat, bichrom, ts_1 or ts_2	1.0	0.0 - 10.0	m
Tlong	Wave group period for case instat = bichrom	80.0	20.0 - 300.0	s
Trep	Representative wave period for instat = stat, bichrom, ts_1 or ts_2	10.0	1.0 - 20.0	s
bclwonly	Switch to run boundary conditions with long waves only	0	0 - 1
dir0	Mean wave direction for instat = stat, bichrom, ts_1 or ts_2 (nautical convention)	270.0	-360.0 - 360.0	deg
instat	Old wave boundary condition type	bichrom	stat, bichrom, ts_1, ts_2, jons, swan, vardens, reuse, ts_nonh, off, stat_table, jons_table
lateralwave	Switch for lateral boundary at left	neumann	neumann, wavecrest, cyclic
m	Power in cos^m directional distribution for instat = stat, bichrom, ts_1 or ts_2	10	2 - 128
nmax+	Maximum ratio of cg/c for computing long wave boundary conditions	0.8	0.5 - 1.0
taper	Spin-up time of wave boundary conditions, in morphological time	100.0	0.0 - 1000.0	s
wbctype	New wave boundary condition type	params	params, parametric, swan, vardens, off, jonstable, reuse, ts_1, ts_2, ts_nonh

Decision tree for selecting the appropriate type of wave boundary conditions

Spectral wave boundary conditions¶

Spectral wave boundary conditions are enabled using wbctype values jons, swan, vardens or jons_table. The conditions are defined in separate files referenced from the params.txt file using the bcfile keyword. A spectral wave boundary condition describes a spectrum shape that XBeach uses to generate a (random) wave time series. The length and resolution of the generated time series is determined by the keywords rt and dtbc respectively. XBeach will reuse the generated time series until the simulation is completed. The resolution of the time series should be enough to accurately represent the bound long wave, but need not be as small as the time step used in XBeach.

An overview of all keywords relevant for spectral wave boundary conditions is given in the table below. The necessary file formats for each type of spectral wave boundary condition is explained in the following subsections.

Overview of available keywords related to wave-spectrum boundary condition parameters¶
parameter	description	default	range	units
Tm01switch+	Switch to enable tm01 rather than tm-10	0	0 - 1
bcfile	Name of spectrum file			<file>
correctHm0	Switch to enable hm0 correction	1	0 - 1
dtbc+	Timestep used to describe time series of wave energy and long wave flux at offshore boundary (not affected by morfac)	1.0	0.1 - 2.0	s
dthetaS_XB+	The (counter-clockwise) angle in the degrees needed to rotate from the x-axis in swan to the x-axis pointing east	0.0	-360.0 - 360.0	deg
fcutoff+	Low-freq cutoff frequency for instat = jons, swan or vardens boundary conditions	0.0	0.0 - 40.0	Hz
nonhspectrum+	Spectrum format for wave action balance of nonhydrostatic waves	0	0 - 1
nspectrumloc+	Number of input spectrum locations	1	1 - par%ny+1
nspr	Switch to enable long wave direction forced into centres of short wave bins	0	0 - 1
random+	Switch to enable random seed for instat = jons, swan or vardens boundary conditions	1	0 - 1
rt	Duration of wave spectrum at offshore boundary, in morphological time	min(3600.d0,par%tstop)	1200.0 - 7200.0	s
sprdthr+	Threshold ratio to maximum value of s above which spectrum densities are read in	0.08	0.0 - 1.0
trepfac+	Compute mean wave period over energy band: par%trepfac*maxval(sf) for instat jons, swan or vardens; converges to tm01 for trepfac = 0.0 and	0.01	0.0 - 1.0
wbcversion	Version of wave boundary conditions	3	1 - 3

JONSWAP wave spectra¶

JONSWAP spectrum input is enabled using wbctype = jons. A JONSWAP wave spectrum is parametrically defined in a file that is referenced using the bcfile keyword. This file contains a single parameter per line in arbitrary order. The parameters that can be defined are listed in Table 7. All variables are optional. If no value is given, the default value as specified in the table is used. It is advised not to specify the keyword dfj and allow XBeach to calculate the default value.

A typical JONSWAP definition file looks as follows:

jonswap.txt

Hm0 = 0.8
Tp = 8
mainang = 285.
gammajsp = 3.3
s = 10.
fnyq = 0.3

For the definitions see the table below.

It is possible to use an alternative file format for time-varying JONSWAP spectra. To enable this option use the wbctype value jons_table. In this case, each line in the spectrum definition file contains a parametric definition of a spectrum, like in a regular JONSWAP definition file, plus the duration for which that spectrum is used during the simulation. XBeach does not reuse time-varying spectrum files. Therefore the total duration of all spectra should at least match the duration of the simulation. The name of the file can be chosen freely, but the file format is fixed as follows and all parameters should be present in all lines:

jonswap.txt

<Hm0> <Tp> <mainang> <gammajsp> <s> <duration> <dtbc>

Note that we refer to the keywords used in a regular JONSWAP definition file in this example, with three differences: 1) the peak period rather than the peak frequency is defined 2) the duration is added (similar to rt in params.txt) 3) the time resolution is added (similar to dtbc in params.txt). The duration and boundary condition time step in this file overrules rt and dtbc in params.txt. This format is also used for time-varying stationary wave boundary conditions as described in Temporally and/or spatially varying wave boundary conditions. As an example, the JONSWAP spectrum definition file presented above would look as follows if the significant wave height should be increased with 0.2 m every hour:

jonswap.txt

8 8. 285. 3.3 10. 0.3 3600. 1
0 8. 285. 3.3 10. 0.3 3600. 1
2 8. 285. 3.3 10. 0.3 3600. 1

A more generic way of providing time-varying spectral wave boundary conditions is using a FILELIST construction as described in Temporally and/or spatially varying wave boundary conditions. This approach is compatible with all spectral wave boundary condition types as well as spatially varying boundary conditions as described in the same section.

The parameter s in the JONSWAP spectrum definition is related to the directional spreading (in deg.) through the following relation $\sigma =\sqrt{\frac{2}{s+1} } \, s=\frac{2}{\sigma ^{2} } -1$ . Here $\sigma$ is the directional spreading in radians and s the JONSWAP spreading parameter.

Effect a variation in s for the direction spreading of wave energy

Overview of available keywords in JONSWAP definition file¶
parameter	description	default	range
Hm0	Hm0 of the wave spectrum, significant wave height [m]	0.0	0.0 - 5.0
fp	Peak frequency of the wave spectrum [s-1]	0.08	0.06258 - 0.4
gammajsp	Peak enhancement factor in the JONSWAP expression [-]	3.3	1.0 - 5.0
s	Directional spreading coefficient, law [-]	10.0	1.0 - 1000.0
mainang	Main wave angle (nautical convention) []	270.0	180.0 - 360.0
fnyq	Highest frequency used to create JONSWAP spectrum [s-1]	0.3	0.2 - 1.0
dfj	Step size frequency used to create JONSWAP spectrum [s-1]	fnyq/200	fnyq/1000 - fnyq/20

SWAN wave spectra¶

XBeach can read standard SWAN 2D variance density or energy density output files (+.sp2 files) as specified in the SWAN v40.51 manual. This option is enabled using wbctype = swan in params.txt and a reference to the spectrum file via the keyword bcfile. XBeach assumes the directional information in the SWAN file is according to the nautical convention. If the file uses the Cartesian convention for directions, the user must specify the angle in degrees to rotate the x-axis in SWAN to the x-axis in XBeach (by the Cartesian convention). This value is specified in params.txt using the keyword dthetaS_XB.

Note that time-varying and spatially varying SWAN spectra can be provided using the FILELIST and LOCLIST constructions as described in Temporally and/or spatially varying wave boundary conditions.

An example of a 2D SWAN spectrum is given below:

swan.txt

SWAN 1 Swan standard spectral file
$ Data produced by SWAN version 40.51
$ Project:’projname’ ; run number:’runnum’
LOCATIONS locations in x-y-space
number of locations
22 0.00
RFREQ relative frequencies in Hz
number of frequencies
0545
0622
0710
0810
0924
1055
1204
1375
1569
1791
2045
2334
2664
3040
3470
3961
4522
5161
5891
6724
7675
8761
0000
CDIR spectral Cartesian directions in degr 12 number of directions
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
QUANT 1 number of quantities in table VaDens variance densities in m2/Hz/degr m2/Hz/degr unit
-0.9900E+02 exception value
FACTOR
675611E-06
242 574 956 1288 1482 1481 1286 957 579 244 51
610 1443 2402 3238 3725 3724 3234 2406 1454 613 128
1287 3054 5084 6846 7872 7869 6837 5091 3076 1295 271
3152 7463 12402 16712 19229 19221 16690 12419 7518 3172 662
6159 14608 24275 32688 37618 37603 32644 24309 14716 6198 1296
10989 26020 43341 58358 67109 67080 58281 43401 26213 11058 2317
15922 37712 62733 84492 97150 97110 84380 62820 37991 16021 3349
16230 38440 63939 86109 99010 98969 85995 64027 38724 16331 3410
9612 22730 37790 50909 58529 58505 50841 37843 22898 9672 2018
3178 7538 12535 16892 19440 19432 16870 12552 7594 3198 669
479 1135 1890 2542 2924 2923 2539 1892 1144 482 101
11 26 43 57 66 66 57 43 26 11 2
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0

Variance density spectra¶

2D spectral information that is not in SWAN format can be provided using a formatted variance density spectrum file and wbctype = vardens. The spectrum file itself is again referenced using the keyword bcfile. The contents of the file must adhere to a specific format:

vardens.txt

<number of frequencies (n)>
<frequency 1>
<frequency 2>
<frequency 3>

...

<frequency n-1>
<frequency n>
<number of directions (m)>
<directions 1>
<directions 2>
<directions 3>

...

<directions m-1>
<directions m>
<variance density 1,1> <variance density 2,1> ... <variance density m,1>
<variance density 1,2> <variance density 2,2> ... <variance density m,2>

...

<variance density 1,n> <variance density 2,n> ... <variance density m,n>

Note that the directions must be defined according to the Cartesian convention and in the coordinate system used by XBeach. In this coordinate system ${0}^\circ$ corresponds to waves travelling in the direction of the x-axis, while ${90}^\circ$ corresponds to the direction of the y-axis. Also, the directions must be defined in increasing order. Time-varying and spatially varying variance density spectra can be provided using the FILELIST and LOCLIST constructions as described in Temporally and/or spatially varying wave boundary conditions.

An example of a formatted variance density file is given below:

vardens.txt

15
0418
0477
0545
0622
0710
0810
0924
1055
1204
1375
1569
1791
2045
2334
2664
13
-180.0000
-150.0000
-120.0000
-90.0000
-60.0000
-30.0000
0000
0000
0000
0000
0000
0000
0000
0 0 0 0 0 0 0 0 0 0 0
242 574 956 1288 1482 1481 1286 957 579 244 51
610 1443 2402 3238 3725 3724 3234 2406 1454 613 128
1287 3054 5084 6846 7872 7869 6837 5091 3076 1295 271
3152 7463 12402 16712 19229 19221 16690 12419 7518 3172 662
6159 14608 24275 32688 37618 37603 32644 24309 14716 6198 1296
10989 26020 43341 58358 67109 67080 58281 43401 26213 11058 2317
15922 37712 62733 84492 97150 97110 84380 62820 37991 16021 3349
16230 38440 63939 86109 99010 98969 85995 64027 38724 16331 3410
9612 22730 37790 50909 58529 58505 50841 37843 22898 9672 2018
3178 7538 12535 16892 19440 19432 16870 12552 7594 3198 669
479 1135 1890 2542 2924 2923 2539 1892 1144 482 101
11 26 43 57 66 66 57 43 26 11 2
0 0 1 1 1 1 1 1 0 0 0
0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0

Non-spectral wave boundary conditions¶

Stationary wave boundary conditions are enabled using wbctype values stat, ts_1, ts_2, ts_nonh or stat_table. The conditions are generally defined within the params.txt file directly using the keywords described in the table below. In addition, in case of wbctype values ts_1 or ts_2 the file bc/gen.ezs should be present that describes the infragravity wave forcing generated outside of XBeach. For the wbctype ts_nonh also a separate file is needed. More information about these files in Non-spectral wave boundary conditions.

Stationary wave boundary conditions¶

Only in case of wbctype = stat_table the time-varying stationary wave boundary conditions are fully described in an external file referenced by the bcfile keyword. The bcfile keyword is part of the spectral wave boundary condition input and also the referenced file is designed for time-varying spectral input in the form of JONSWAP spectra (see Spectral wave boundary conditions). In stationary mode only the relevant data from this file is used and irrelevant data like gamma and dfj are discarded.

Overview of available keywords related to wave boundary condition parameters¶
parameter	description	default	range	units
Hrms	Hrms wave height for instat = stat, bichrom, ts_1 or ts_2	1.0	0.0 - 10.0	m
Tlong	Wave group period for case instat = bichrom	80.0	20.0 - 300.0	s
Trep	Representative wave period for instat = stat, bichrom, ts_1 or ts_2	10.0	1.0 - 20.0	s
bclwonly	Switch to run boundary conditions with long waves only	0	0 - 1
dir0	Mean wave direction for instat = stat, bichrom, ts_1 or ts_2 (nautical convention)	270.0	-360.0 - 360.0	deg
instat	Old wave boundary condition type	bichrom	stat, bichrom, ts_1, ts_2, jons, swan, vardens, reuse, ts_nonh, off, stat_table, jons_table
lateralwave	Switch for lateral boundary at left	neumann	neumann, wavecrest, cyclic
m	Power in cos^m directional distribution for instat = stat, bichrom, ts_1 or ts_2	10	2 - 128
nmax+	Maximum ratio of cg/c for computing long wave boundary conditions	0.8	0.5 - 1.0
taper	Spin-up time of wave boundary conditions, in morphological time	100.0	0.0 - 1000.0	s
wbctype	New wave boundary condition type	params	params, parametric, swan, vardens, off, jonstable, reuse, ts_1, ts_2, ts_nonh

Time series¶

The wave boundary condition types of ts_1 and ts_2 need a separate file containing short wave energy and free surface elevation (including long wave motions). The format of this file is as follows:

bc/gen.ezs

<time 1> <zs 1> <E 1>
<time 1> <zs 2> <E 2>
<time 2> <zs 3> <E 3>

...

The wave boundary condition type of ts_nonh also needs a separate file in order to run the simulation. This file, however, needs to contain free surface elevations and velocities (both in u and v).

Boun_u.bcf

<scalar/vector>
<number of variables>
<variables: t,U,Zs,W>

(114) $\left. \begin{array}{cccccccccc} {t^{0} } & {U_{1}^{0} } & {\cdots } & {U_{J}^{0} } & {\eta _{1}^{0} } & {\cdots } & {\eta _{J}^{0} } & {W_{1}^{0} } & {\cdots } & {W_{J}^{0} } \\ {\vdots } & {\vdots } & {} & {\vdots } & {\vdots } & {} & {\vdots } & {\vdots } & {} & {\vdots } \\ {t^{n} } & {U_{1}^{N} } & {\cdots } & {U_{J}^{N} } & {\eta _{1}^{N} } & {\cdots } & {\eta _{J}^{N} } & {W_{1}^{N} } & {\cdots } & {W_{J}^{N} } \end{array}\right\}{[Data]}$

Special types of wave boundary conditions¶

Two special types of wave boundary conditions are available that makes XBeach skip the generation of new wave time series. The first is wbctype = off which simply does not provide any wave forcing on the model and hence no wave action in the model.

The second is wbctype = reuse which makes XBeach reuse wave time series that were generated during a previous simulation. This can be a simulation using the same or a different model as long as the computational grids are identical. In order to reuse boundary conditions, all relevant files should be copied to the current working directory of the model (where the params.txt file is located). Relevant files are the ebcflist.bcf and qbcflist.bcf files and all files referenced therein. Generally, the referenced files have E_ and q_ prefixes. No further wave boundary condition data need be given in params.txt.

On top of that bichromatic waves are also supported. Currently the same input parameters as non-spectral waves (see Non-spectral wave boundary conditions) are required; however there are planes to elaborate the input parameters of the bichromatic wave in order to specify individual frequency.

Temporally and/or spatially varying wave boundary conditions¶

Time-varying spectral wave boundary conditions can be defined by feeding in multiple spectrum definition files rather than a single definition file. In addition, the duration for which these spectra should occur needs to be defined.

To make use of this option, the user must specify a regular wbctype value for spectral wave boundary conditions (jons, swan or vardens), but instead of referencing a single spectrum definition file using the bcfile keyword, an extra file listing all spectrum definition files is now referenced.

The first word in this extra file must be the keyword FILELIST. In the following lines, each line contains the duration of this wave spectrum condition in seconds (similar to rt in params.txt), the required time step in this boundary condition file in seconds (similar to dtbc in params.txt) and the name of the spectral definition file used to generate these boundary conditions. The duration and boundary condition time step in this file overrules rt and dtbc in params.txt. XBeach does not reuse time-varying spectrum files. Therefore the total duration of all spectra should at least match the duration of the simulation.

A typical input file contains the following:

filelist.txt

FILELIST
0.2 jonswap1.inp
0.2 jonswap1.inp
0.2 jonswap2.inp
0.2 jonswap3.inp
0.2 jonswap2.inp
0.2 jonswap4.inp

Similar to time-varying spectral wave boundary conditions, also spatially varying wave boundary conditions can be defined using a similar construction. In order to apply spatially varying spectra on the offshore boundary, the user must specify set the keywords wbcversion = 3 and nspectrumloc = <ns> in params.txt where <ns> is the number of locations in which a spectrum is defined. By default the number of defined spectra is one.

Similar to time-varying spectral wave boundary conditions, its spatially varying sibling uses an extra file listing all relevant spectrum definition files. The first word in this extra file must be the keyword LOCLIST. This line should be followed by one line per spectrum definition location containing the world x-coordinate and world y-coordinate of the location that the input spectrum should apply, and the name of the file containing spectral wave information.

A typical input file for a run with three JONSWAP spectra contains the following:

loclist.txt

LOCLIST
0. jonswap1.inp
100. jonswap2.inp
200. jonswap3.inp

Note that it is not possible to use a mix of JONSWAP, SWAN and variance density files in either a FILELIST or a LOCLIST construction. It is also not possible to vary dthetaS_XB between files in case of non-nautical SWAN spectra. However, it is possible to combine FILELIST and LOCLIST files by referencing FILELIST files from the LOCLIST file. In this case all FILELIST files should adhere to the same time discretization, so the duration and time step values should be constant over al FILELIST files as well as the number of wave spectra definitions.

The user is reminded that along the offshore boundary of the model, the wave energy, rather than the wave height, is interpolated linearly between input spectra without consideration of the physical aspects of the intermediate bathymetry. In cases with large gradients in wave energy, direction or period, the user should specify sufficient wave spectra for the model to accurately represent changes in offshore wave conditions.

Flow, tide and surge input¶

An XBeach model needs flow boundary conditions on all boundaries of the model domain. Moreover, on each boundary tidal elevations and/ or surges may be imposed. The flow boundary conditions and time-varying tide or surge input are discussed in this section. The details on how the flow is computed within the model are described in the sections on bed friction and viscosity parameters (see Shallow water equations).

Flow boundary conditions¶

Flow boundary conditions need to be specified on all sides of the domain. We will differentiate between the offshore, lateral and landward boundaries that are set using the keywords front, back and left / right, respectively. Table 9, Table 10 and Table 11 give an overview of the available flow boundary condition types for each of these boundaries.

The keyword freewave can be used to switch from bound to free long waves, which can be useful when time series of the free long wave incident on the offshore boundary need to be specified. The file bc/gen.ezs can be used to describe the free long waves at the offshore boundary as discussed in Waves.

Overview of available offshore flow boundary condition types¶
front	description
abs1d	absorbing-generating (weakly-reflective) boundary in 1D
abs2d	absorbing-generating (weakly-reflective) boundary in 2D
wall	no flux wall
wlevel	water level specification (from file)
nonh_1d	boundary condition for non-hydrostatic option
waveflume	boundary condition for flume experiments based on a continuity relation

Overview of available landward flow boundary condition types¶
back	description
wall	no flux wall
abs1d	absorbing-generating (weakly-reflective) boundary in 1D
abs2d	absorbing-generating (weakly-reflective) boundary in 2D
wlevel	water level specification (from file)

Overview of available lateral flow boundary condition types¶
left right	description
wall	no flux wall
neumann	Neumann boundary condition (constant water level gradient)
neumann_v	velocity is determined by the adjacent cell
no_advec	Neumann boundary condition, but only the advective terms are taken into account. Intermediate form between wall and neumann

Overview of available keywords related to flow boundary condition parameters¶
parameter	description	default	range
ARC+	Switch for active reflection compensation at seaward boundary	1	0 - 1
back	Switch for boundary at bay side	abs_2d	wall, abs_1d, abs_2d
epsi+	Ratio of mean current to time varying current through offshore boundary	-1.0	-1.0 - 0.2
freewave+	Switch for free wave propagation 0 = use cg (default); 1 = use sqrt(gh) in instat = ts_2	0	0 - 1
front	Switch for seaward flow boundary	abs_2d	abs_1d, abs_2d, wall, nonh_1d, waveflume
left	Switch for lateral boundary at ny+1	neumann	neumann, wall, no_advec, neumann_v, abs_1d
nc	Smoothing distance for estimating umean (defined as nr of cells)	par%ny+1	1 - par%ny+1
order+	Switch for order of wave steering,first order wave steering (short wave energy only), second oder wave steering (bound long wave corresponding to short wave forcing is added)	2.0	1.0 - 2.0
right	Switch for lateral boundary at 0	neumann	neumann, wall, no_advec, neumann_v, abs_1d
tidetype+	Switch for offfshore boundary, velocity boundary or instant water level boundary	velocity	instant, velocity

Time-varying tide/surge¶

Time-varying tidal (or surge) signals can be applied all four boundaries in a number of ways.

The number of tidal signals is determined by the keyword tideloc that can take the values 0, 1, 2 or 4. Specifying three tidal signals is not an option. Setting tideloc = 0 disables the time-varying tide/surge option. In this case a constant and uniform water level is used specified by the keyword zs0. With tideloc = 1 the specified tidal record is specified on all four corners of the domain and interpolated along the boundaries.

Using tideloc = 2, two tidal signals are specified and there are two options available: 1) the first signal is imposed on the offshore boundary and the second on the landward boundary or 2) the first signal is imposed on the left lateral boundary and the second on the right lateral boundary. The choice between the two options is made using the keyword paulrevere where a value 0 indicates the first option and a value 1 indicates the second option. Also in the case of two tidal signals the signals are spatially interpolated along the boundaries.

Using tideloc = 4, four tide/surge signals are to be specified on each corner of the model domain and spatially interpolated along the boundaries. The first signal is imposed to the left offshore boundary seen from sea (x=1,y=1) and the others according to a clockwise rotation. Therefore the columns in the zs0file must follow the order of: (x=1,y=1), (x=1,y=N), (x=N,y=N), (x=N,y=1).

The length of the tidal signals is determined by the keyword tidelen. This is the number of water levels specified in the file referenced with the zs0file keyword. The tidal signal will be interpolated to the local time step of the XBeach simulation; therefore the resolution of the signals only needs to be enough to resolve the water level phenomenon of interest (i.e. tide variations, surge event). The tidal signals are not re-used, therefore the signal should be at least as long as the simulation time.

The zs0file file must adhere to the following format where the last three columns are optional depending on the value of tideloc and tlen represents the value of tidelen:

tide.txt

<time 1> <zs 1,1> [<zs 2,1> [<zs 3,1> <zs 4,1>]]
<time 2> <zs 1,2> [<zs 2,2> [<zs 3,2> <zs 4,2>]]
<time 3> <zs 1,3> [<zs 2,3> [<zs 3,3> <zs 4,3>]]

...

<time tlen> <zs 1,tlen> [<zs 2,tlen> [<zs 3,tlen> <zs 4,tlen>]]

In case of a single tidal signal, the signal is imposed on both offshore corners of the domain, while a constant water level defined by the keyword zs0 is imposed on the landward corners.

Overview of available keywords related to tide boundary conditions¶
parameter	description	default	range	units
paulrevere	Specifies tide on sea and land or two sea points if tideloc = 2	land	land, sea
tideloc	Number of corner points on which a tide time series is specified	0	0 - 4
zs0file	Name of tide boundary condition series			<file>

Water level (dam break)¶

Water levels can be imposed on the model boundaries as explained in Time-varying tide/surge after which the shallow water equations force the water body in the model domain. Specific applications may require the initialization of the entire water body in the model domain at the start of the simulation. For example, an initial significant gradient in the water level that “collapses” at the start of the simulation may simulate a dam break. The initialization of the water level in the model domain is governed by the keywords listed in the table below.

The keyword zsinitfile references an external file describing the initial water levels in the entire model domain. The file should have the same format as the bathymetry input files described in Grid and bathymetry.

Overview of available keywords related to initial conditions¶
parameter	description	default	range	units
hotstartflow+	Switch for hotstart flow conditions with pressure gradient balanced by wind and bed stress	0	0 - 1
zs0	Inital water level	0.0	-5.0 - 5.0	m
zsinitfile	Name of inital water level file			<file>

Wind input¶

Spatially-uniform winds can parametrically defined using the keywords windv and windth that represent the wind velocity and direction (nautical convention) respectively. Time-varying winds can be defined in an external file referenced by the windfile keyword. The file should adhere to the format indicated below. The total length of the time series is automatically determined and should be at least as long as the simulation time.

wind.txt

<time 1> <windv 1> <windth 1>
<time 2> <windv 2> <windth 2>
<time 3> <windv 3> <windth 3>

...

The table below gives an overview of all keywords related to the wind:

Overview of available keywords related to wind parameters¶
parameter	description	default	range	units
Cd+	Wind drag coefficient	0.002	0.0001 - 0.01
rhoa+	Air density	1.25	1.0 - 2.0	kgm^-3
windfile	Name of file with non-stationary wind data			<file>
windth	Nautical wind direction, in case of stationary wind	270.0	-360.0 - 360.0	deg
windv	Wind velocity, in case of stationary wind	0.0	0.0 - 200.0	ms^-1

Sediment input¶

The sediment input determines the (initial) composition of the bed and the detail in which processes related to sediment sorting are resolved. This is different from how the sediment transport processes are handled in the model itself and that are described in Sediment transport and Bottom updating

The simplest situation is an XBeach simulation with uniform sediment. In this case it is sufficient to specify the uniform grain size using the keyword D50 indicating the median grain size. The effects of a specific sediment distribution can be parametrically defined by additionally specifying values for D15 and D90 and optionally the bed composition can be fine-tuned by specifying the porosity and sediment density using the keywords por and rhos respectively. In this case no sorting of sediment will be simulated.

If the effect of different sediment fractions, sorting and armoring are of importance, multiple sediment fractions can be defined. The number of sediment fraction is determined by the keyword ngd. For each sediment fraction a value for D50, and optionally D15 and D90, should be defined separated by a space. Moreover, when using multiple sediment fractions, multiple bed layers are needed as well. The number of bed layers can be defined using the keyword nd.

Three types of bed layers are distinguished: 1) the top layer 2) the variable or “breathing” layer and 3) the bottom layers. At least one of each type of bed layer is needed, which makes that at least three bed layers are required (see Bed composition). Each bed layer has a thickness. Choosing bed layer thicknesses that are in balance with the expected erosion and deposition during the simulation should keep the numerical mixing to a minimum. A bed layer thickness that is too large will result in relatively uniform behavior, while a bed layer thickness that is too small will result in a lot of shifting and thus numerical mixing. The bed layer thicknesses are determined by the three keywords dzg1, dzg2 and dzg3 for the top, variable and bottom layers respectively.

Apart from the discretization of the grain size distribution and the vertical structure of the bed, the initial bed composition needs to be defined. The bed composition is defined using external files that are not explicitly referenced from params.txt, but are assumed to be located in the working directory of the model (next to params.txt). There is one file for each sediment fraction specified by ngd. The file corresponding to the first sediment fraction is named gdist1.inp, the second gdist2.inp, et cetera.

The bed composition files hold information on how much sediment of a specific fraction is in each grid cell and bed layer at the start of the simulation. The values are a volumetric fraction that implies that they should add up to unity over all fractions. For example, if a specific grid cell is filled with the first sediment fraction only, the value corresponding to this grid cell will be one in the gdist1.inp file and zero in all others. Alternatively, if we defined five sediment fractions and a specific grid cell is filled equally with all fractions, the value corresponding to this grid cell will be 1/5 = 0.2 in all files. The gidst< N >.inp files are formatted comparable to the bathymetry files (see Grid and bathymetry), but now holds values over the three dimensions x (nx+1), y (ny+1) and the bed layers (nd). The file format is as follows:

gdist1.inp

<p 1,1,1> <p 1,2,1> <p 1,3,1> ... <p 1,nx,1> <p 1,nx+1,1>
<p 1,1,2> <p 1,2,2> <p 1,3,2> ... <p 1,nx,2> <p 1,nx+1,2>
<p 1,1,3> <p 1,2,3> <p 1,3,3> ... <p 1,nx,3> <p 1,nx+1,3>

...

<p 1,1,ny> <p 1,2,ny> <p 1,3,ny> ... <p 1,nx,ny> <p 1,nx+1,ny>
<p 1,1,ny+1> <p 1,2,ny+1> <p 1,3,ny+1> ... <p 1,nx,ny+1> <p 1,nx+1,ny+1>

...

<p 2,1,1> <p 2,2,1> <p 2,3,1> ... <p 2,nx,1> <p 2,nx+1,1>
<p 2,1,2> <p 2,2,2> <p 2,3,2> ... <p 2,nx,2> <p 2,nx+1,2>
<p 2,1,3> <p 2,2,3> <p 2,3,3> ... <p 2,nx,3> <p 2,nx+1,3>

...

<p 2,1,ny> <p 2,2,ny> <p 2,3,ny> ... <p 2,nx,ny> <p 2,nx+1,ny>
<p 2,1,ny+1> <p 2,2,ny+1> <p 2,3,ny+1> ... <p 2,nx,ny+1> <p 2,nx+1,ny+1>

...

<p nd,1,1> <p nd,2,1> <p nd,3,1> ... <p nd,nx,1> <p nd,nx+1,1>
<p nd,1,2> <p nd,2,2> <p nd,3,2> ... <p nd,nx,2> <p nd,nx+1,2>
<p nd,1,3> <p nd,2,3> <p nd,3,3> ... <p nd,nx,3> <p nd,nx+1,3>

...

<p nd,1,ny> <p nd,2,ny> <p nd,3,ny> ... <p nd,nx,ny> <p nd,nx+1,ny>
<p nd,1,ny+1> <p nd,2,ny+1> ... <p nd,nx,ny+1> <p nd,nx+1,ny+1>

The table below gives an overview of all keywords related to working with multiple sediment fractions and bed layers:

Overview of available keywords related to bed composition parameters¶
parameter	description	default	range	units
dzg1+	Thickness of top sediment class layers	par%dzg1	0.01 - 1.0	m
dzg2+	Nominal thickness of variable sediment class layer	par%dzg1	0.01 - 1.0	m
dzg3+	Thickness of bottom sediment class layers	par%dzg1	0.01 - 1.0	m
nd+	Number of computational layers in the bed	3	3 - 1000
ngd	Number of sediment classes	1	1 - 20
por	Porosity	0.4	0.3 - 0.5
rhos	Solid sediment density (no pores)	2650.0	2400.0 - 2800.0	kgm^-3
ws	Average fall velocity (is computed in morphevolution)	0.02d0		m/s

Vegetation input¶

Short wave dissipation, long wave dissipation and flow interaction due to vegetation is supported. The user can define multiple vegetation species. The number of vegetation species is set by the keyword nveg. Furthermore, two files should be created and specified in the params.txt-file: a vegetation characteristics file (keyword: veggiefile) and a vegetation location file (keyword: veggiemapfile).

The veggiefile is a text file listing the names of the vegetation characteristics files that should be created for every individual vegetation species that should be accounted for. These property files contain the vegetation parameters nsec, ah, Cd, bv and N that represent the number of vertical sections, height of vegetation section relative to the bed , the drag coefficient, stem diameter and vegetation density per vegetation section, respectively. An example of a set of files describing two different vegetation species is given below.

veggiefile.txt

seagrass.txt
mangrove.txt

seagrass.txt

ah = 0.2
Cd = 1.0
bv = 0.02
N = 1200

mangrove.txt

nsec = 3
ah = 0.5 0.8 1.3
Cd = 2.0 1.0 2.0
bv = 0.05 0.15 0.1
N = 1000 50 500

The nsec keyword in the species property file allows the user to define multiple height segments of the species with different properties. The height per vegetation section is defined relative to the bed level. For all properties, the values are given from bottom to top. A definition sketch is given in Fig. 14.

Definition sketch of vegetation specification in XBeach (example for mangrove type vegetation schematized in three vertical sections).

Finally, the veggiemapfile indicates in what grid cell which vegetation species can be found. The format of this file is similar to the bathymetry files described in Grid and bathymetry, but the values are integers referring to a species where 1 refers to the first listed species, 2 to the second, et cetera. A zero indicates no vegetation at that particular location. The use of non-integer values in this file will result in an error.

In summary, the following files should be created when the effect of vegetation is modeled:

1 x Veggiemapfile: file similar to bathymetry file containing 0, 1 etc. (up to nveg)
1 x Veggiefile: list of file names of vegetation property files per species
nveg x vegetation property file(s): describing vegetation properties per species

Below the relevant keywords in the params.txt are given. In addition, the keyword vegetation should be set to 1.

Overview of available keywords related to vegetation parameters¶
parameter	description	default	range
nveg	Number of vegetation species	-123
vegcanflo	Include incanopy flow [1] or not [0]	0	0 - 1
veggiefile	Name of veggie species list file
veggiemapfile	Name of veggie species map file
vegnonlin	Include non-linear wave effect [1] or not [0]	0	0 - 1
veguntow	Include undertow in phase-averaged vegetati	1	0 - 1

Discharge input¶

Discharge of water at the model boundaries or directly in the model domain is defined along specific grid sections. The keywords ndischarge and ntdischarge define the number of discharge sections and the length of the discharge time series respectively. The disch_loc_file keyword references a file that defines the discharge sections. Each line in this file corresponds to a grid section and each line contains four numbers being the start and end coordinates of the section. The file is formatted as follows, where ndisch refers to the keyword ndischarge:

disch_loc.txt

<x_start 1> <y_start 1> <x_end 1> <y_end 1>
<x_start 2> <y_start 2> <x_end 2> <y_end 2>
<x_start 3> <y_start 3> <x_end 3> <y_end 3>

...

<x_start ndisch> <y_start ndisch> <x_end ndisch> <y_end ndisch >

The world coordinates specified in this file must be chosen such that they are close to the desired grid cell borders, since the grid cell borders are eventually used as discharge section. Discharge sections can be located along grid cell borders that are either oriented cross-shore or alongshore, but not a combination of the two. In a regular grid this implies that either the start or end x-coordinates are equal, or the start and end y-coordinates are equal. Alternatively, both are equal. In this case a vertical discharge from above is assumed, rather than a horizontal discharge. Vertical discharges only add mass and no momentum to the water body.

The keyword disch_timeseries_file references a file defining the time series imposed on the discharge locations. The file lists the timings in the first column and a discharge value in ${\rm m}^{3}/{\rm s}$ for each discharge section as follows, where ntdisch refers to the keyword ntdischarge:

disch_timeseries.txt

<t 1> <Q 1,1> <Q 2,1> ... <Q ndisch,1>
<t 2> <Q 1,2> <Q 2,2> ... <Q ndisch,2>
<t 3> <Q 1,3> <Q 2,3> ... <Q ndisch,3>

...

<t ntdisch> <Q 1,ntdisch> <Q 2,ntdisch> ... <Q ndisch,ntdisch >

Discharges defined at the domain borders are positive in direction towards the domain (influx). Discharges defined in the domain itself are positive in direction of the positive x or y direction. Vertical discharges are positive into the domain (influx).

Possible discharge orifices. A discharge orifice is defined as line in between two points (red). The resulting discharge orifice constitutes out of full abreast grid cells (green). The discharge direction is in positive grid direction (s or n), except at the domain border where the discharge is an influx in the domain (green arrows).

The table below gives an overview of all keywords related to discharges:

Overview of available keywords related to flow discharge boundary conditions¶
parameter	description	default	range	units
disch_loc_file+	Name of discharge locations file			<file>
disch_timeseries_file+	Name of discharge timeseries file			<file>
ndischarge+	Number of discharge locations	par%ndischarge	0 - 100
ntdischarge+	Length of discharge time series	par%ntdischarge	0 - 100

Drifters input¶

Drifters can be deployed during the model simulation by specifying the number of drifters using the keyword ndrifter and the location, start and end time of the drifter deployment in a separate file referenced by the drifterfile keyword. The file format is as follows:

drifter.txt

<x 1> <y 1> <t_start 1> <t_end 1>
<x 2> <y 2> <t_start 2> <t_end 2>
<x 3> <y 3> <t_start 3> <t_end 3>

...

<x ndrifter> <y ndrifter> <t_start ndrifter> <t_end ndrifter>

The table below gives an overview of all keywords related to drifters:

Overview of available keywords related to drifters parameters¶
parameter	description	default	range	units
drifterfile	Name of drifter data file			<file>
ndrifter	Number of drifers	par%ndrifter	0 - 50

Ship-induced wave motions¶

Ship waves can be simulated by defining the ships’ geometries and trajectories in a collection of files. The user can define multiple ships. The number of ships is set by the keyword nship. In the file referenced by the keyword shipfile each ship is given a name. The properties of each ship are summarized in another textfile with the name of the ship (shipname.txt). This properties file defines the parameters for the discretization of the ships geometry. The ship grid is determined by the keywords dx, dy, nx, and ny, and the ship geometry itself is given in a separate file, referenced bythe keyword shipgeom. This file contains the ship draft per ship grid point, and should have a size of nx + 1 by ny + 1. The center of gravity of the ship is also defined in the ship properties file using the keywords xCG, yCG and zCG. The ships trajectory is defined in a file referenced from the ship properties file by the keyword shiptrack. Each row in this file contains a time, x- and y-coordinate indicating the ships position as function of time.

To avoid numerical problems, the full ship track should be within the model domain (i.e. a vessel cannot sail through the model boundary). Furthermore, it is advised to start the ship track with a very low velocity and gradually increase the sailing speed. When not taking into account such spin up period, the impact of the ship on the water level can be too abrupt, resulting in unrealistic wave patterns. In addition, it is advised to maintain a relatively deep edge of a few grid cells at both model boundaries (i.e. front and back side).

Another way to avoid numerical issues at the initialization of a ship simulation is to use the ’flying’ option, which can be specified in the ship file (flying = 1). In case the option flying is enabled, also a z-coordinate is defined in the shiptrack-file indicating the vertical position of the ship. In this way, the vessel can ‘land’ on the water with its correct sailing speed, thereby avoiding unwanted disturbance to the water level. Also, the ship can ‘fly out’ of the model domain before reaching the back boundary. By using this method the spin-up time can be reduced considerably and both inflow and outflow boundaries are unaffected by the ship

The two keywords compute_force and compute_motion enable the computation of forces on the ship and the ships motions due to wave forcing respectively; the latter has not been implemented yet. Forces on a ship in motion may be unreliable due to near-field effects; forces on a ship at rest are much more reliable. An example of ship definition files is:

shipfile.txt

containership.txt
oiltanker.txt

containership.txt

dx = 10
dy = 10
nx = 30
ny = 10
shipgeom = container_geom.dep
xCG = 120
yCG = 50
zCG = 30
shiptrack = container_track.txt
flying = 1
compute_force = 1
compute_motion = 1

pannamax_geom.txt

<z 0,0> <z 1,0> <z 2,0> <z 3,0> ... <z nx,0> <z nx+1,0>
<z 0,1> <z 1,1> <z 2,1> <z 3,1> ... <z nx,1> <z nx+1,1>

...

<z 0,ny> <z 1,ny> <z 2,ny> <z 3,ny> ... <z nx,ny> <z nx+1,ny>
<z 0,ny+1> <z 1,ny+1> <z 2,ny+1> <z 3,ny+1> ... <z nx,ny+1> <z nx+1,ny+1>

pannamax_track.txt

<t 1> <x 1> <y 1> <z 1>
<t 2> <x 2> <y 2> <z 2>
<t 3> <x 3> <y 3> <z 3>

...

oiltanker.txt

dx = 2
dy = 2
nx = 20
ny = 4
shipgeom = tanker_geom.dep
xCG = 20
yCG = 40
zCG = 1.5
shiptrack = tanker_track.txt
flying = 0

tanker_track.txt

<t 1> <x 1> <y 1>
<t 2> <x 2> <y 2>
<t 3> <x 3> <y 3>

...

Overview of available keywords related to ship parameters¶
parameter	description	default	range	units
nship+	Number of ships	-123
shipfile	Name of ship data file			<file>

Output selection¶

Output selection determines what data computed by XBeach is written to a file in terms of location and time and in what format. The output types, output times and output formats supported by XBeach are explained in more detail in the following subsections. The table below gives an overview of all keywords related to model output:

Overview of available keywords related to output variables¶
parameter	description	default	range	units
ncfilename+	Xbeach netcdf output file name			<file>
nglobalvar	Number of global output variables (as specified by user)	-1	-1 - 20
nmeanvar	Number of mean, min, max, var output variables	0	0 - 15
npoints	Number of output point locations	0	0 - 50
npointvar	Number of point output variables	0	0 - 50
nrugauge	Number of output runup gauge locations	0	0 - 50
nrugdepth+	Number of depths to compute runup in runup gauge	1	1 - 10
outputformat+	Output file format	fortran	fortran, netcdf, debug
outputprecision	Switch between single and double precision output in netcdf	double	single, double
timings+	Switch enable progress output to screen	1	0 - 1
tintc+	Interval time of cross section output	-123		s
tintg	Interval time of global output	1.0	0.01 - par%tstop-par%tstart	s
tintm	Interval time of mean, var, max, min output	par%tstop-par%tstart	1.0 - par%tstop-par%tstart	s
tintp	Interval time of point and runup gauge output	1.0	0.01 - par%tstop-par%tstart	s
tsglobal+	Name of file containing timings of global output
tsmean+	Name of file containing timings of mean, max, min and var output
tspoints+	Name of file containing timings of point output
tstart	Start time of output, in morphological time	0.0	0.0 - par%tstop	s

Output types¶

XBeach supports four different types of output: 1) instantaneous spatial output 2) time-averaged spatial output 3) fixed point output or 4) run-up gauge output. In principle any variable in XBeach can be outputted as long as it is part of the spaceparams structure defined in variables.f90 in the XBeach source code. An overview of all currently supported parameters in this file is presented in Table 22.

The amount of output variables used for each type is determined by the keywords nglobalvar, nmeanvar, npoints and nrugauge. Each of these keywords takes a number indicating the number of parameters or locations that should be written to file. If any of the keywords is set to zero, the output type is effectively disabled. If nglovalvar is set to -1 then a standard set of output variables is used, being H, zs, zs0, zb, hh, u, v, ue, ve, urms, Fc, Fy, ccg, ceqsg, ceqbg, Susg, Svsg, E, R, D and DR. If nglobalvar is not set it defaults to -1. The lines in the params.txt file immediately following these keywords determine what parameters or locations are used, as will be explained in more detail in the following subsections.

Overview of available keywords related to *¶
parameter	description	units
As	Asymmetry of short waves
BR	Maximum wave surface slope used in roller dissipation formulation
Cdrag	Vegetation drag coefficient
D	Dissipation	W/m2
D15	D15 grain diameters for all sediment classses	m
D50	D50 grain diameters for all sediment classses	m
D50top	Friction coefficient flow
D90	D90 grain diameters for all sediment classses	m
D90top	Friction coefficient flow
DR	Roller energy dissipation	W/m2
Dc	Diffusion coefficient	m2/s
Df	Dissipation rate due to bed friction	W/m2
Dp	Dissipation rate in the swash due to transformation of kinetic wave energy to potential wave energy	W/m2
Dveg	Dissipation due to short wave attenuation by vegetation	W/m2
E	Wave energy	Nm/m2
Fvegu	X-forcing due to long wave attenuation by vegetation	N/m2
Fvegv	Y-forcing due to long wave attenuation by vegetation	N/m2
Fx	Wave force, x-component	N/m2
Fy	Wave force, y-component	N/m2
H	Hrms wave height based on instantaneous wave energy	m
Hrunup	Short wave height used in runup formulation	m
L1	Wave length (used in dispersion relation)	m
Qb	Fraction breaking waves
R	Roller energy	Nm/m2
Sk	Skewness of short waves
Subg	Bed sediment transport for each sediment class (excluding pores), x-component	m2/s
Susg	Suspended sediment transport for each sediment class (excluding pores), x-component	m2/s
Sutot	Sediment transport integrated over bed load and suspended and for all sediment grains, x-component	m2/s
Svbg	Bed sediment transport for each sediment class (excluding pores), y-component	m2/s
Svsg	Suspended sediment transport for each sediment class (excluding pores), y-component	m2/s
Svtot	Sediment transport integrated over bed load and suspended and for all sediment grains, y-component	m2/s
Sxx	Radiation stress, x-component	N/m
Sxy	Radiation stress, y-component	N/m
Syy	Radiation stress, y-component	N/m
Tbore	Wave period interval associated with breaking induced turbulence	s
Tsg	Sediment response time for each sediment class	s
alfau	Grid orientation at u-point	rad
alfav	Grid orientation at v-point	rad
alfaz	Grid orientation at z-point	rad
bedfriccoef	Dimensional/dimensionless input bed friction coefficient; depends on value of parameter bedfriction
bi	Incoming bound long wave	m
breaking	Indicator whether cell has breaking nonh waves
bwalpha	Beachwizard weighting factor
c	Wave celerity	m/s
ca	Reference concentration	m3/m3
ccg	Depth-averaged suspended concentration for each sediment fraction	m3/m3
cctot	Sediment concentration integrated over bed load and suspended and for all sediment grains	m3/m3
ccz	Concentration profile	m3/m3
ceqbg	Depth-averaged bed equilibrium concentration for each sediment class	m3/m3
ceqsg	Depth-averaged suspended equilibrium concentration for each sediment class	m3/m3
cf	Friction coefficient flow
cfu	Friction coefficient flow in u-points
cfv	Friction coefficient flow in v-points
cg	Group velocity	m/s
cgx	Group velocity, x-component	m/s
cgx_s	Group velocity, x-component	m/s
cgy	Group velocity, y-component	m/s
cgy_s	Group velocity, y-component	m/s
cobs	Beachwizard observed wave celerity	m/s
costh	Cos of wave angles relative to grid direction
costh_s	Cos of wave angles relative to grid direction
ctheta	Wave celerity theta-direction (refraction)	rad/s
ctheta_s	Wave celerity theta-direction (refraction)	rad/s
cx	Wave celerity, x-component	m/s
cy	Wave celerity, y-component	m/s
dU	U-velocity difference between two vertical layers (reduced 2-layer non-hydrostatic model)	m2/s2
dUi	Velocity difference at boundary due to (short) waves	m/s
dV	V-velocity difference between two vertical layers (reduced 2-layer non-hydrostatic model)	m2/s2
dassim	Beachwizard depth change	m
dcbdx	Bed concentration gradient x-dir.	kg/m3/m
dcbdy	Bed concentration gradient y-dir.	kg/m3/m
dcmdo	Beachwizard computed minus observed dissipation	W/m2
dcsdx	Suspended concentration gradient x-dir.	kg/m3/m
dcsdy	Suspended concentration gradient y-dir.	kg/m3/m
depo_ex	Explicit bed deposition rate per fraction	m/s
depo_im	Implicit bed deposition rate per fraction	m/s
dinfil	Infiltration layer depth used in quasi-vertical flow model for groundwater	m
dnc	Grid distance in n-direction, centered around c-point	m
dnu	Grid distance in n-direction, centered around u-point	m
dnv	Grid distance in n-direction, centered around v-point	m
dnz	Grid distance in n-direction, centered around z-point (=eta-point)	m
dobs	Beachwizard observed dissipation	W/m2
dsc	Grid distance in s-direction, centered around c-point	m
dsdnui	Inverse of grid cell surface, centered around u-point	1/m2
dsdnvi	Inverse of grid cell surface, centered around v-point	1/m2
dsdnzi	Inverse of grid cell surface, centered around z-point	1/m2
dsu	Grid distance in s-direction, centered around u-point	m
dsv	Grid distance in s-direction, centered around v-point	m
dsz	Grid distance in s-direction, centered around z-point (=eta-point)	m
dzav	Total bed level change due to avalanching	m
dzbdt	Rate of change bed level	m/s
dzbdx	Bed level gradient in x-direction
dzbdy	Bed level gradient in y-direction
dzbed	No description
dzbnow	Bed level change in current time step	m
dzs0dn	Alongshore water level gradient due to tide alone
dzsdt	Rate of change water level	m/s
dzsdx	Water surface gradient in x-direction	m/s
dzsdy	Water surface gradient in y-direction	m/s
ee	Directionally distributed wave energy	J/m2/rad
ee_s	Directionally distributed wave energy	J/m2/rad
ero	Bed erosion rate per fraction	m/s
fw	Wave friction coefficient
gw0back	Boundary condition back boundary for groundwater head	m
gwbottom	Level of the bottom of the aquifer	m
gwcurv	Curvature coefficient of groundwater head function
gwhead	Groundwater head (differs from gwlevel)	m
gwheadb	Groundwater head at bottom (differs from gwlevel)	m
gwheight	Vertical size of aquifer through which groundwater can flow	m
gwlevel	Groundwater table (min(zb,gwhead))	m
gwqx	Groundwater discharge in x-direction	m/s
gwqy	Groundwater discharge in y-direction	m/s
gwu	Groundwater flow in x-direction	m/s
gwv	Groundwater flow in y-direction	m/s
gww	Groundwater flow in z-direction (interaction between surface and ground water)	m/s
hh	Water depth	m
hhw	Water depth used in all wave computations, includes h*par%delta	m
hhwcins	Water depth used in wave instationary computation in case of wci	m
hhws	Water depth used in wave stationary computation (and single_dir wave directions)	m
hold	Water depth previous time step	m
hu	Water depth in u-points	m
hum	Water depth in u-points	m
hv	Water depth in v-points	m
hvm	Water depth in v-points	m
idrift	Drifter x-coordinate in grid space
infil	Rate of exchange of water between surface and groundwater (positive from sea to groundwater)	m/s
istruct	Location of revetments toe
iwl	Location of water line (including long wave runup)
jdrift	Drifter y-coordinate in grid space
k	Wave number	rad/m
kb	Near bed turbulence intensity due to depth induces breaking	m2/s2
kturb	Depth averaged turbulence intensity due to long wave breaking	m2/s2
maxzs	Maximum elevation in simulation	m
minzs	Minimum elevation in simulation	m
n	Ratio group velocity/wave celerity
nd	Number of bed layers (can be different for each computational cell)
ndist	Cum. distance from right boundary along n-direction	m
nuh	Horizontal viscosity coefficient	m2/s
nutz	Turbulence viscosity
pbbed	No description
pdisch	Discharge locations
ph	Pressure head due to ship	m
pntdisch	Point discharge locations (no momentum)
pres	Normalized dynamic pressure	m2/s2
qdisch	Discharges	m2/s
qx	Discharge in u-points, x-component	m2/s
qy	Discharge in u-points, y-component	m2/s
refA	Reference level	m
rolthick	Long wave roller thickness	m
rr	Directionally distributed roller energy	J/m2/rad
runup	Short wave runup height	m
sdist	Cum. distance from offshore boundary along s-direction	m
sedcal	Equilibrium sediment concentartion factor for each sediment class
sedero	Cum. sedimentation/erosion	m
setbathy	Prescribed bed levels	m
shipFx	Force on ship in x-direction	N
shipFy	Force on ship in y-direction	N
shipFz	Force on ship in z-direction	N
shipMx	Moment on ship around x-axis	Nm
shipMy	Moment on ship around y-axis	Nm
shipMz	Moment on ship around z-axis	Nm
shipchi	Turning angle arround y-axis	deg
shipphi	Turning angle arround x-axis	deg
shippsi	Turning angle arround z-axis	deg
shipxCG	X-coordinate of ship center of gravity	m
shipyCG	Y-coordinate of ship center of gravity	m
shipzCG	Z-coordinate of ship center of gravity	m
shobs	Beachwizard observed shoreline	m
sig2prior	Beachwizard prior std squared	m2
sigm	Mean frequency	rad/s
sigt	Relative frequency	rad/s
sigz	Vertical distribution of sigma layers q3d
sinth	Sin of wave angles relative to grid direction
sinth_s	Sin of wave angles relative to grid direction
strucslope	Slope of structure
structdepth	Depth of structure in relation to instantaneous bed level	m
taubx	Bed shear stress, x-component	N/m2
taubx_add	Additional bed shear stress due to boundary layer effects, x-component	N/m2
tauby	Bed shear stress, y-component	N/m2
tauby_add	Additional bed shear stress due to boundary layer effects, y-component	N/m2
tdisch	Discharge time series
tdriftb	Drifter release time	s
tdrifte	Drifter retrieval time	s
thet	Wave angles	rad
thet_s	Wave angles	rad
theta	Wave angles directional distribution w.r.t. comp. x-axis	rad
theta_s	Wave angles directional distribution w.r.t. comp. x-axis	rad
thetamean	Mean wave angle	rad
tideinpt	Input time of input tidal signal	s
tideinpz	Input tidal signal	m
tsetbathy	Points in time of prescibed bed levels	s
u	Glm velocity in cell centre, x-component	m/s
ua	Time averaged flow velocity due to wave assymetry	m/s
ucrcal	Calibration factor for u critical for each sediment class
ududx	Advection	m2/s2
udvdx	Advection	m2/s2
ue	Eulerian velocity in cell centre, x-component	m/s
ue_sed	Advection velocity sediment in cell centre, x-component	m/s
ueu	Eulerian velocity in u-points, x-component	m/s
ui	Incident bound wave velocity in, x-component	m/s
umean	Longterm mean velocity at bnds in u-points, x-component	m/s
umwci	Velocity (time-averaged) for wci, x-component	m/s
ur	Reflected velocity at bnds in u-points	m/s
urepb	Representative flow velocity for sediment advection and diffusion, x-component	m/s
ureps	Representative flow velocity for sediment advection and diffusion, x-component	m/s
urms	Orbital velocity	m/s
usd	Return flow due to roller after breaker delay	m/s
ust	Stokes drift	m/s
ustr	Return flow due to roller	m/s
ustz	Stokes velocity (q3d)
uu	Glm velocity in u-points, x-component	m/s
uv	Glm velocity in v-points, x-component	m/s
uwcins	U-velocity used in wave stationary computation in case of wci	m/s
uwf	Stokes drift, x-component	m/s
uws	U-velocity used in wave stationary computation (and single_dir wave directions)	m/s
uz	Velocity (q3d) ksi-comp
v	Glm velocity in cell centre, y-component	m/s
vdudy	Advection	m2/s2
vdvdy	Advection	m2/s2
ve	Eulerian velocity in cell centre, y-component	m/s
ve_sed	Advection velocity sediment in cell centre, y-component	m/s
vegtype	Vegetation type index
vev	Eulerian velocity in u-points, y-component	m/s
vi	Incident bound wave velocity in, y-component	m/s
viscu	Viscosity	m2/s2
viscv	Viscosity	m2/s2
vmag	Velocity magnitude in cell centre	m/s
vmageu	Eulerian velocity magnitude u-points	m/s
vmagev	Eulerian velocity magnitude v-points	m/s
vmagu	Glm velocity magnitude u-points	m/s
vmagv	Glm velocity magnitude v-points	m/s
vmean	Longterm mean velocity at bnds in u-points, y-component	m/s
vmwci	Velocity (time-averaged) for wci, y-component	m/s
vrepb	Representative flow velocity for sediment advection and diffusion, y-component	m/s
vreps	Representative flow velocity for sediment advection and diffusion, y-component	m/s
vu	Glm velocity in u-points, y-component	m/s
vv	Glm velocity in v-points, y-component	m/s
vwcins	V-velocity used in wave stationary computation in case of wci	m/s
vwf	Stokes drift, y-component	m/s
vws	V-velocity used in wave stationary computation (and single_dir wave directions)	m/s
vz	Velocity (q3d) eta-comp
wb	Vertical velocity at the bottom	m/s
wete	Mask wet/dry wave-points
wetu	Mask wet/dry u-points
wetv	Mask wet/dry v-points
wetz	Mask wet/dry eta-points
wi	Vertical velocity at boundary due to (short) waves	m/s
winddirts	Input wind direction	deg_nautical
windinpt	Input time of input wind signal	s
windnv	Wind velocity in n direction in v point at current time step	m/s
windsu	Wind velocity in s direction in u point at current time step	m/s
windvelts	Input wind velocity	m/s
windxts	Time series of input wind velocity (not s direction), x-component	m/s
windyts	Time series of input wind velocity (not n direction), y-component	m/s
wm	Mean abs frequency	rad/s
ws	Vertical velocity at the free surface	m/s
wscrit	Critial vertical velocity at the free surface for breaking	m/s
x	X-coord. original cmp. grid	m
xHrunup	Location at which short wave height for runup is taken	m
xu	X-coord. comp. grid u-points	m
xv	X-coord. comp. grid v-points	m
xyzs01	Global xy coordinates of corner (x=1,y=1)
xyzs02	Global xy coordinates of corner (x=1,y=n)
xyzs03	Global xy coordinates of corner (x=n,y=n)
xyzs04	Global xy coordinates of corner (x=n,y=1)
xz	X-coord. comp. grid (positive shoreward, perp. to coastline)	m
y	Y-coord. original comp. grid	m
yu	Y-coord. comp. grid u-points	m
yv	Y-coord. comp. grid v-points	m
yz	Y-coord. comp. grid	m
z0bed	No description
zb	Bed level	m
zb0	Initial bed level	m
zbobs	Beachwizard observed depth	m
zi	Surface elevation at boundary due to (short) waves	m
zs	Water level	m
zs0	Water level due to tide alone	m
zs0fac	Relative weight of offshore boundary and bay boundary for each grid point is stored in zs0fac
zs1	Water level minus tide	m
zswci	Waterlevel (time-averaged) for wci	m

Instantaneous spatial output¶

Instantaneous spatial output describes the instantaneous state of variables across the entire model domain at various points in time. To make use of this option the user must specify the number of output variables required using the nglobalvar keyword in params.txt, immediately followed by the names of the requested variables on a separate line each. The output of three instantaneous grids can look as follows:

params.txt

nglobalvar = 3
zs
zb
H

Time-averaged spatial output¶

Time-averaged spatial output describes the time-averaged state of variables across the entire model domain at various points in time. The user can define the averaging period in params.txt. To make use of this option the user must specify the number of output variables required using the nmeanvar keyword in params.txt, immediately followed by the names of the requested variables on a separate line each. The output of two time-averaged grids may look as follows:

params.txt

nmeanvar = 2
u
v

Fixed point output¶

Fixed point output allows the user to select one or more locations for which a time series of data is stored. This output describes a time-series of one or more variables at one point in the model domain. To make use of this option, the user must specify the number of output locations using the npoints keyword in params.txt, immediately followed by one line per output location describing the location coordinates given as the x-coordinate and y-coordinate and in world coordinates. XBeach will link the output location to the nearest computational point.

The user can specify the number and selection of output variables for all points (and run-up gauges, discussed in the following section) using the npointvar keyword in params.txt to specify the number of output variables, immediately followed by the names of the requested variables on a separate line each.

Fixed point output significantly reduces the amount of data written to file in each time step and is therefore particularly suitable for high temporal resolution output.

An example with two output locations is given below. The first point is located on the offshore boundary (x = 0.0) and somewhere in the middle of the model domain in y-direction (y = 800.0). The second point is located on the lateral boundary (y = 1600.0) and somewhere in the middle of the domain in x-direction (x = 2000.0). Both locations have four output variables: H, zs, zb and D.

params.txt

npoints = 2
0. 800.
2000. 1600.
npointvar = 4
H
zs
zb
D

Run-up gauge output¶

Run-up gauge output describes a time-series of a number of variables at the (moving) waterline. In this case XBeach scans in an x-directional transect defined by the user for the location of the waterline. Output information is recorded for this moving point. This is particularly useful to keep track of run-up levels in cross-shore transects.

The definition of run-up gauges is similar to the definition of fixed point output. The user needs to specify the number of run-up gauges using the nrugauge keyword in params.txt, immediately followed by one line per run-up gauge location describing the coordinates of the initial location of the run-up gauge. XBeach will subsequently link the initial run-up gauge location to the nearest computational cross-shore transect rather than just the nearest computational point.

Run-up gauges share their selection of output variables with regular point output. However, in the case of run-up gauges, XBeach will automatically also include the variables xw, yw and zs to the point output variables, if these variables were not specified using the npointvar keyword in params.txt. Note that the user should refer to the pointvars.idx output file to check order of output variables for points and run-up gauges.

An example of a run-up gauge input is given below. The run-up gauge is initially located on the offshore boundary (x = 0.0) and somewhere in the middle of the model domain in y-direction (y = 800.0). The run-up gauge will display standard output variables (xw, yw and zs, as well as any output variables specified by the npointvar keyword).

params.txt

nrugauge = 1
0. 800.

Output times¶

The user may determine the output times for regular spatial output variables, time averaged spatial variables and point location variables individually. Run-up gauge output and fixed point output are given at the same moments in time. For all three types of output the user may choose to either state a fixed interval time at which output is given or supply an external file containing times at which output should be given or a combination of both.

Output at fixed intervals¶

The user should define a point in time after the start of the simulation at which the first output is generated for fixed interval output. The user can do this by using the tstart keyword in params.txt. All output that is being generated at fixed intervals uses tstart as their base. The interval for instantaneous spatial output is given by the tintg keyword. The keywords for the interval of time-averaged spatial output and point output are tintm and tintp respectively, where tintp is used both for fixed point and run-up gauge output. Note that tintg, tintm and tintp supersede the older tint parameter that is valid for all types of output. The default value of tintg is one second. If tintp or tintm is not stated, but output is declared (npoints, nrugauge or nmeanvar is stated larger than zero), XBeach assumes the same output interval as tintg. An example of the definition of fixed intervals is given below.

params.txt

tstart = 100.
tintg = 100.
tintp = 2.
tintm = 3600.

In the case of instantaneous spatial output and point output, the first output is given at tstart. In the case of time-averaged spatial variables, the first output is given at tstart+tintm. This output represents the average condition over the interval between tstart and tstart+tintm.

Output times defined by external file¶

The user is given the option to have output at a set of points in time that are not separated by regular intervals. In this case the user must supply an additional file for each output type. The user specifies the name of the output time series file for instantaneous spatial output using the tsglobal keyword. The keywords for time series files for time-averaged spatial output and point output are tsmean and tspoint respectively, where tspoint is again used for both fixed point and run-up gauge output. All time series files must contain on the first line the number of output times followed by every output time on a new line. An example of such irregular output time definition is given below.

params.txt

tsglobal= time_series1.txt
tspoints = time_series2.txt
tsmean= time_series3.txt

time_series1.txt

In the case of instantaneous spatial output and point output, the first output is given at the first stated point in time. In the case of time-averaged spatial variables, the first output is given at the second stated point in time. This output represents the average condition over the interval between first and second stated point in time. Subsequent averaging is done over every interval.

Combinations of fixed internal and external files¶

The user is allowed to define certain types of output using fixed intervals and others using external files. The use of an external file supersedes the use of fixed intervals. Note that tstart will only apply to output of fixed interval type. An example of mixing fixed and varying output time intervals is given below.

param.txt

tstart = 100.
tintg = 100.
tspoints = time_series2.txt
tintm = 3600.

Output format¶

XBeach supports two types of output: 1) Fortran binary and 2) netCDF. The output format used is determined by the keyword outputformat. The use of netCDF output is more convenient since all output (and input) is stored in a single, easy accessible file. Also the netCDF file format is compatible with many programming languages (e.g. Matlab, Python) as well as many visualization tools (e.g. QuickPlot, Morphan). It should be noted that the support for output types in netCDF could be limited for recent functionalities of the XBeach model.

Fortran binary¶

Output files in Fortran binary format are bare matrix dumps of XBeach’ computational matrices. At each output time, one such matrix block is added to the output file. These files can generally be read by binary read functions, like fread in Matlab and the struct package in Python.

Output files written in Fortran binary format are given the name < variable >.dat, for example zs.dat, for instantaneous spatial output. The only exception is that files containing information about the wave height of the short waves are called hrms.dat instead of H.dat to maintain backward compatibility. Time-averaged spatial output is stored similarly, but the file names have a suffix indicating the type of averaging < variable >_mean.dat. For time-averaged spatial output also the variance, minimum and maximum values are stored using the suffixes _var, _min and _max respectively.

All data corresponding to fixed point locations will be stored in files called point< NNN >.dat. < NNN > represents a number between 001 and 999 corresponding to the order in which the points are declared in params.txt. The data files are plain text and contain one row for each output time step. The first position on each row is the time at which the output is given. The subsequent positions in the row are the instantaneous values of the variables at the given point. The order of the variables is equal to the order in which they are defined for that point in params.txt. Data corresponding to run-up gauge locations are stored in the same format as fixed point output, but the files are named rugau< NNN >.dat.

An extra file called dims.dat is always written at the start of the simulation in Fortran binary output mode. This file contains the dimensions of the XBeach model. It simply states the following dimensions in order: nt (number of output time steps), nx (number of grid cells in x-direction), ny (number of grid cells in y-direction), ngd (number of sediment fractions), nd (number of bed layers), ntp (number of point output time steps), ntm (number of time-averaged output time steps). Subsequently, the irregular time series are stored, if applicable: tsglobal (irregular output times), tspoints (irregular point output times) and tsmean (irregular time-averaged output times). Similarly, a file xy.dat is written containing the x- and y- coordinates of the full computational grid.

netCDF¶

All data in netCDF output is stored in a single output file. By default this file is named xboutput.nc, but this name can be chosen freely using the keyword ncfilename. The netCDF file holds all output data, dimensions and input data in a single file. It should be noted that netCDF files can hold a multiple time axes. The temporal unit can be specified in the params.txt file using the keyword tunits. This unit does not affect calculations and is only used for output. An example of the layout of the netcdf file is given below:

xboutput.nc (structure only, no real contents)

netcdf xboutput {
   dimensions:
      x = 565 ;
      y = 101 ;
      wave_angle = 9 ;
      bed_layers = 3 ;
      sediment_classes = 1 ;
      inout = 2 ;
      globaltime = 2 ;
      tidetime = 435 ;
      tidecorners = 2 ;
      windtime = 2 ;
   variables:
      double x(x) ;
         x:units = “m” ;
         x:long_name = “local x coordinate” ;
      double y(y) ;
         y:units = “m” ;
         y:long_name = “local y coordinate” ;
      double globaltime(globaltime) ;
         globaltime:units = “s” ;
      double H(globaltime, y, x) ;
         H:units = “m” ;
         H:long_name = “wave height” ;
      double zs(globaltime, y, x) ;
         zs:units = “m” ;
         zs:long_name = “water level” ;
      double zb(globaltime, y, x) ;
         zb:units = “m” ;
         zb:long_name = “bed level” ;
      double ue(globaltime, y, x) ;
         ue:units = “m/s” ;
}

Time parameters¶

In all XBeach simulations the hydrodynamic simulation starts at time 0. Model output can be postponed until the time specified by the keyword tstart. The simulation stops at the time specified by tstop. The time step used in the hydrodynamic simulation is determined based on a given maximum Courant number using the keyword CFL. The table below gives an overview of all keywords related to time management:

Overview of available keywords related to model time¶
parameter	description	default	range	units
CFL	Maximum courant-friedrichs-lewy number	0.7	0.1 - 0.9
defuse	Turn on timestep explosion prevention mechanism	1	0 - 1
dtset	Fixed timestep, overrides use of cfl	0.0	0.001 - 100.0
maxdtfac	Maximum increase/decrease in time stp in explosion prevention mechanism	500.0	100.0 - 1000.0
tstop*	Stop time of simulation, in morphological time	2000.0	1.0 - 1000000.0	s
tunits+	Time units in udunits format (seconds since 1970-01-01 00:00:00.00 +1:00)	s

Appendices¶

Hands on exercises (based on basic XBeach of the Delft Software Days 2014)¶

The hands-on exercises can be downloaded via subversion. Subversion is a well-known version management system that allows you to always have the most recent source code at hand. It also allows developers to commit changes to the source code, without interfering with other developers. In order to use Subversion, you will need a Subversion client. A well-known client for Windows is Tortoise. If you have registered, you can download the source code via the following URL: https://svn.oss.deltares.nl/repos/xbeach/Courses/DSD_2014/Examples – Basic. For the tools like Quickplot and Quickin the Delft3D environment is needed.

Dune erosion at Delfland, Netherlands (1D)¶

The first case we will run is a relative simple 1D case. It concerns a profile along the Dutch coast and the hydraulic boundary conditions are based on the 1953 storm surge that caused substantial flooding in the Netherlands.

You can work on the following assignments:

Go to the folder “Examples\DelflandStorm” and double click the file “run_model.bat”. The simulation will start. The model will run for a few minutes, but in the meantime you can already work on question 2 to 5.
Open params.txt in which you specify the model input files and settings. Check the number of grid-points in x-direction (keyword: nx) and y-direction (keyword: ny). Check the filenames in which you specify the wave conditions (keyword: bcfile) and the storm surge level (SSL) (keyword: zs0file).
Do the wave conditions change during the simulation? What is/are the wave height(s) and wave period(s) applied in the simulation?
Does the storm surge level change during the simulation? What is the maximum surge height in the simulation. Surge height is defined with respect to the mean sea level (MSL)?
What is the simulation time (keyword: tstop)? Do we apply a morphological acceleration factor (keyword: morfac)? What variables are stored as output and with what time interval? How much hydrodynamic time is simulated?
Probably the simulation has finished. When you start the model, it generates a file named XBlog.txt. Open this file and check what is stored in the file. What was the total simulation time?
To check out the simulation results we make use of the Quickplot tool (A brief tutorial is attached to this document). You can start Quickplot via the Delft3D environment we installed (Start Programs Deltares Delft3D Delft3D). In the Delft 3D menu choose Utilities Quickplot. Choose Files of type “NetCDF files and GRIB files” and open “xboutput.nc” in the simulation folder.
Use the Quickplot tutorial and try to make an animation in which you plot short wave height (H), water level (including long wave variations, zs) and bed level (zb) as function of time.
Plot the offshore water level as function of time. Also open the file “tide.tek” (Tekal data files format), which contains the imposed surge level. Did the model correctly simulate the imposed surge level?
Copy all model files to a new folder named “superfast”. Edit params.txt and set ny=0 (instead of ny=2), and run the model. What is the simulation time compare to the original simulation?
Compare simulation results for the “superfast” and “default” simulation. Are these the same? What option will you use in the future?

Nourishment scenarios near Kijkduin, Holland (1D)¶

This case concerns the exploration of a nourishment strategy near Kijkduin along the Holland coast in the Netherlands. At this location a mega nourishment of 21 ${\rm Mm}^{3}$ named the Sand Engine was constructed. In this case we will explore to what extent nourishments can reduce the (dune and beach) erosion during a storm event.

You can work on the following assignments:

Go to the folder “Examples\Nourishment case” and double click on the file “runall.bat”. This batch file will run three simulations sequentially in which the profile configuration varies and corresponds with the undisturbed profile (folder reference), a shoreface nourishment (folder shoreface) and a beach nourishment (folder beach) respectively. Each model will run for a few minutes. While running you can already answer question 2 to 6.
For the reference case open the params.txt in which you specify model input files and settings. Check the number of grid-points in x-direction (keyword: nx) and y-direction (keyword: ny). How many directional wave bins are defined and what is their width (keywords: thetamin, thetamax, dtheta).
Do the wave conditions change during the simulation? What is/are the wave height(s) and wave period(s) applied in the simulation?
Does the storm surge level change during the simulation? What is the maximum surge height in the simulation. Surge height is defined with respect to the mean sea level (MSL)?
What is the simulation time (keyword: tstop)? Do we apply a morphological acceleration factor (keyword: morfac)? What variables are stored as output and with what time interval? How much hydrodynamic time is simulated?
Probably the simulation has finished. When you start the model, it generates a file named XBlog.txt. Open this file and check what is stored in the file. What was the total simulation time?
Inspect the initial bathymetries of each simulation with QUICKPLOT. Choose Files of type “NetCDF files and GRIB files” and open “xboutput.nc” in the simulation folder).
1. At what cross-shore position were the shoreface nourishment and beach nourishment placed?
2. What is the (average) thickness of the nourishments?
3. Is the volume of the nourishments comparable?
4. Plot the reference profile with markers; does the grid resolution vary in cross-shore direction?
Use the Quickplot tutorial and try to make an animation in which you plot short wave height (H), water level (including long wave variations, zs) and bed level (zb) as function of time.
Plot the offshore water level as function of time. Also open the file “tide.tek” (Tekal data files format), which contains the imposed surge level. Did the model correctly simulate the imposed surge level?
Inspect the final bathymetries of each simulation.
1. What is the dune face retreat in the three simulations you have carried out?
2. Where does the eroded sediment form the dunes deposit?
3. What nourishment type is most effective in reducing the impact of a storm and do you have an explanation for this?
In the folder “banquette” you find a final simulation in which a special beach nourishment type is evaluated named a banquette. This beach nourishment has a highly elevated flat area that connects to the dune foot on which beach restaurants can be build.
1. Run the model and compare in Quickplot the banquette design with the beach nourishment design we have evaluated before. Do you expect more or less erosion?
2. Check your hypothesis by comparing the final profile of the banquette simulation to the other simulations.
3. What would be your approach to further reduce beach and dune erosion?

Overwash at Santa Rosa Island , USA (2DH)¶

This case concerns overwash at Santa Rosa island in the Gulf of Mexico during hurricane Ivan in 2004.

You can work on the following assignments.

For the reference case open the params.txt in which you specify model input files and settings. Check the number of grid-points in x-direction (keyword: nx) and y-direction (keyword: ny). How many directional wave bins are defined and what is their width (keywords: thetamin, thetamax, dtheta).
In this simulation the grid is specified in Delft3D format. Open Quickin in the Delft 3D menu (Grid Quickin) and use the brief tutorial to read in the grid and bathymetry. Does the grid resolution vary in cross-shore direction? And in longshore direction? What are the minimum dx and dy? Why can the grid be coarse offshore?
How many wave conditions do we apply in this simulation? What is the offshore mean wave direction? Does the surge level change in the simulation?
What is the simulation time (hydrodynamic and morphologic)?
Inspect the model results and make an animation of the short wave height (H) and the water levels (including long wave, zs). Describe what is happening.
For the water levels set the color limits manual between -0.5 and 3.5.
Make an animation of cumulative sedimentation/erosion. Describe what is happening.
For the sedimentation/erosion set the color limits manual between -3 and 3
Look at the mean flow field. Plot the flow field in colored vectors. Where are the flow velocities highest and what is the direction of the flow (cross-shore or longshore)? Is there (also) a longshore current present and what is its intensity?

If you have time left feel free to:

Narrow or broaden the imposed spectrum by changing the parameter directional spreading (s) in ‘jonswap.inp’ (you could for example set s = 100 and s = 2 respectively). Make animations of the instantaneous short wave height to see what is happening to the size of the wave groups.
Design a nourishment in Quickin to reduce the impact of the storm on Santa Rosa Island. Change the depth file in params.txt to make a simulation with the updated bathymetry.

Yanchep perched beach and natural breakwater (2DH)¶

This case is an example of a beach 60km north of Perth most commonly known as Yanchep lagoon. Many beaches in WA like Yanchep are fronted by shallow reef and here we are investigating the effects of the reef on the morphodynamics.

You can work on the following assignments:

Go to the folder “Examples\YanchepBeach” and double click the file “run_model.bat”. The simulation will start (and will run about 15 minutes).
Meanwhile, inspect the bathymetry file and the structure file (using Quickin). What is the depth in the lagoon? Is the reef enclosing the lagoon below or above the model initial water level? What is the wave height at the boundary condition?
Use Quickplot and try to make an animation in which you plot short wave height (H), water level (including long wave variations) (zs) and Eulerian velocities (ue and ve) as function of time. What happens in the lagoon?
Use Quickplot and try to make an animation of cumulative sedimentation/erosion. What happens in the lagoon?
How is the lagoon affected by the mean water level? Increase or decrease the mean water level condition (‘tide.tx’), run the model again (maybe for a shorter time by reducing keyword: tstop). How are the circulation and sediment transport affected?
What would happen if the lagoon was open at the southern end? Open the structure file (keyword: ne_layer = reef.dep) with the Quickin tool and modify it to allow the southern end of the lagoon to be eroded. Modify the param.txt file to use this new structure file and run the model. Alternatively, remove the reef from the bathymetry and rerun the model without the structure file, by setting the keyword struct = 0.

If you still have time;

Reefs are very rough what happens in the model when the friction is increased? Reduce the Chezy roughness and increase the value of ${f}_{w}$ . Rerun the model what do you observe?
Is wave/current interaction (keyword: wci = 1) switched on? Rerun the model with the wave/current switch on/off. Compare the output with model you ran previously. How much effect do you see on the morphology?

Advanced model coefficients¶

In General the main input parameters and files required by XBeach to start a simulation are explained. It explained how the user can switch on and off specific processes and how the user can define the model initial and boundary conditions. XBeach offers, however, many more parameters to fine-tune the simulation of different processes. These parameters are listed in the following subsections grouped by process. Most parameters are not relevant for the average XBeach user. Parameters marked with a plus (+) are considered advanced options that are recommended to stay untouched unless you know what you are doing.

Wave numerics¶

The parameters listed in the table below involve the numerical aspects of the wave action balance that solves the wave propagation in the model. The keyword scheme can be used to set the numerical scheme. To overcome the undesired effects of steepening of wave groups we implemented a correction to the second-order upwind scheme according to ([BW76]), which implies a small additional diffusion term which is a function of time step and group velocity. By default Warming and Beam (1976) is used.

Overview of available keywords related to wave numerics parameters¶
parameter	description	default	range	units
maxerror+	Maximum wave height error in wave stationary iteration	0.0005	1e-05 - 0.001	m
maxiter+	Maximum number of iterations in wave stationary	500	2 - 1000
scheme+	Numerical scheme for wave propagation	warmbeam	upwind_1, lax_wendroff, upwind_2, warmbeam
swkhmin	Minimum kh value to include in wave action balance, lower included in nlswe (default -1.d0)	-0.01	-0.01 - 0.35
wavint	Interval between wave module calls (only in stationary wave mode)	60.0	1.0 - 3600.0	s

Wave dissipation¶

The parameters listed in the table below involve the wave dissipation process. For instationary model runs use either break = roelvink1, roelvink2 or roelvink_daly. Note that the standard value gamma = 0.55 and n = 10 was calibrated for option break = roelvink1. For break = roelvink2 the wave dissipation is proportional to ${H}^{3}/h$ instead of ${H}^{2}$ ; this affects the calibration. For stationary runs the break = baldock option is suitable. The break = roelvink_daly option is a model in which waves start and stop breaking. Reducing gammax will reduce wave heights in very shallow water, probably 2 is a reasonable value.

Overview of available keywords related to wave breaking parameters¶
parameter	description	default	range	units
alpha+	Wave dissipation coefficient in roelvink formulation	1.0	0.5 - 2.0
break	Type of breaker formulation	roelvink2	roelvink1, baldock, roelvink2, roelvink_daly, janssen
breakerdelay+	Switch to enable breaker delay model	1.0	0.0 - 3.0
delta+	Fraction of wave height to add to water depth	0.0	0.0 - 1.0
facrun	Calibration coefficient for short wave runup	1.0	0.0 - 2.0
facsd	Fraction of the local wave length to use for shoaling delay depth	1.0	0.0 - 2.0
fwcutoff	Depth greater than which the bed friction factor is not applied	1000.0	0.0 - 1000.0
gamma	Breaker parameter in baldock or roelvink formulation	0.55	0.4 - 0.9
gamma2	End of breaking parameter in roelvink daly formulation	0.3	0.0 - 0.5
gammax+	Maximum ratio wave height to water depth	2.0	0.4 - 5.0
n+	Power in roelvink dissipation model	10.0	5.0 - 20.0
shoaldelay	Switch to enable shoaling delay	0	0 - 1
wavfriccoef	Wave friction coefficient	-123
wavfricfile	Wave friction file			<file>

Rollers¶

The parameters listed in the table below involve the wave roller model. Using the roller model will give a shoreward shift in wave-induced setup, return flow and alongshore current. This shift becomes greater for lower beta values.

Overview of available keywords related to roller parameters¶
parameter	description	default	range
beta+	Breaker slope coefficient in roller model	0.1	0.05 - 0.3
rfb+	Switch to feed back maximum wave surface slope in roller energy balance, otherwise rfb = par%beta	0	0 - 1
roller+	Switch to enable roller model	1	0 - 1

Wave-current interaction¶

The parameters listed in the table below involve the process of wave-current interaction. With the switch wci one can turn off or on the wave-current interaction, the wave current interaction will result in a feedback of currents on the wave propagation. On top of that, hwci limits the computation of wave-current interaction in very shallow water where the procedure may not converge.

Overview of available keywords related to wave-current interaction parameters¶
parameter	description	default	range	units
cats+	Current averaging time scale for wci, in terms of mean wave periods	4.0	1.0 - 50.0	Trep
hwci+	Minimum depth until which wave-current interaction is used	0.1	0.001 - 1.0	m
hwcimax+	Maximum depth until which wave-current interaction is used	100.0	0.01 - 100.0	m
wci	Turns on wave-current interaction	0	0 - 1

Bed friction and viscosity¶

The parameters listed in the table below involve the settings for bed friction and viscosity influencing the flow in XBeach. The bed friction is influenced by the dimensionless friction coefficient cf or other formulation like the dimensional Chézy or Manning. The bed friction formulation applied needs to be determined with the keyword bedfriction. It is possible both to define one value (keyword: bedfriccoef) or to apply, spatially varying values for the bed friction. A spatial varying friction can be provided through an external file referenced via the keyword bedfricfile. The file has the same format as the bathymetry file explained in Grid and bathymetry.

The horizontal viscosity is composed of an overall background viscosity nuh and a viscosity depending on the roller dissipation tuned by nuhfac. In the alongshore direction the viscosity may be multiplied by a factor nuhv to account for additional advective mixing. It is also possible to use a user-defined value for the horizontal viscosity (keyword smag = 0)

Overview of available keywords related to flow parameters¶
parameter	description	default	range	units
bedfriccoef	Bed friction coefficient	0.01	3.5e-05 - 0.9
bedfricfile	Bed friction file (only valid with values of c)			<file>
bedfriction	Bed friction formulation	chezy	chezy, cf, white-colebrook, manning, white-colebrook-grainsize
friction_acceleration	Turn on or off the effect of acceleration on bed roughness (morrison)	none	none, mccall, nielsen
friction_infiltration	Turn on or off the effect of infiltration on bed roughness (conley and inman)	0	0 - 1
friction_turbulence	Turn on or off the effect of turbulence on bed roughness (reniers van thiel)	0	0 - 1
gamma_turb	Calibration factor for turbulence contribution to bed roughness	1.0	0.0 - 2.0
nuh	Horizontal background viscosity	0.1	0.0 - 1.0	m^2s^-1
nuhfac+	Viscosity switch for roller induced turbulent horizontal viscosity	1.0	0.0 - 1.0
nuhv	Longshore viscosity enhancement factor, following svendsen (?)	1.0	1.0 - 20.0
smag+	Switch for smagorinsky subgrid model for viscocity	1	0 - 1

Flow numerics¶

The parameters listed in the table below involve the numerical aspects of the shallow water equations that solve the water motions in the model. Especially in very shallow water some processes need to be limited to avoid unrealistic behavior. For example hmin prevents very strong return flows or high concentrations and the eps determines whether points are dry or wet and can be taken quite small.

Overview of available keywords related to flow numerics parameters¶
parameter	description	default	range	units
eps	Threshold water depth above which cells are considered wet	0.005	0.001 - 0.1	m
eps_sd	Threshold velocity difference to determine conservation of energy head versus momentum	0.5	0.0 - 1.0	m/s
hmin	Threshold water depth above which stokes drift is included	0.2	0.001 - 1.0	m
oldhu	Switch to enable old hu calculation	0	0 - 1
secorder+	Use second order corrections to advection/non-linear terms based on maccormack scheme	0	0 - 1
umin	Threshold velocity for upwind velocity detection and for vmag2 in equilibrium sediment concentration	0.0	0.0 - 0.2	m/s

Sediment transport¶

The parameters listed in the table below involve the process of sediment transport. The keywords facAs and facSk determine the effect of the wave form on the sediment transport, this is especially important in the nearshore. The facua is an alias setting in which both parameters can be varied at once. The wave form model itself is selected using the keyword waveform. Processes like short- and long-wave stirring and turbulence can be switched on or off using the keywords sws, lws and lwt. Several options for calibrating the sediment transport formulations are available as well as keywords to incorporate the bed slope effect.

Overview of available keywords related to sediment transport parameters¶
parameter	description	default	range	units
BRfac+	Calibration factor surface slope	1.0	0.0 - 1.0
Tbfac+	Calibration factor for bore interval tbore: tbore = tbfac*tbore	1.0	0.0 - 1.0
Tsmin+	Minimum adaptation time scale in advection diffusion equation sediment	0.5	0.01 - 10.0	s
bdslpeffdir	Modify the direction of the sediment transport based on the bed slope	none	none, talmon
bdslpeffdirfac	Calibration factor in the modification of the direction	1.0	0.0 - 2.0
bdslpeffini	Modify the critical shields parameter based on the bed slope	none	none, total, bed
bdslpeffmag	Modify the magnitude of the sediment transport based on the bed slope, uses facsl	roelvink_total	none, roelvink_total, roelvink_bed, soulsby_total, soulsby_bed
bed+	Calibration factor for bed transports	1	0 - 1
bermslope	Swash zone slope for (semi-) reflective beaches	0.0	0.0 - 1.0
betad+	Dissipation parameter long wave breaking turbulence	1.0	0.0 - 10.0
bulk+	Switch to compute bulk transport rather than bed and suspended load separately	0	0 - 1
ci+	Mass coefficient in shields inertia term	1.0	0.5 - 1.5
cm	Mass coefficient in shields inertia term	1.5	0.0 - 3.0
dilatancy	Switch to reduce critical shields number due dilatancy	0	0 - 1
facAs+	Calibration factor time averaged flows due to wave asymmetry	0.1	0.0 - 1.0
facDc+	Option to control sediment diffusion coefficient	1.0	0.0 - 1.0
facSk+	Calibration factor time averaged flows due to wave skewness	0.1	0.0 - 1.0
facsl+	Factor bedslope effect	1.6	0.0 - 1.6
facua+	Calibration factor time averaged flows due to wave skewness and asymmetry	0.1	0.0 - 1.0
fallvelred	Switch to reduce fall velocity for high concentrations	0	0 - 1
form	Equilibrium sediment concentration formulation	vanthiel_vanrijn	soulsby_vanrijn, vanthiel_vanrijn, vanrijn1993
jetfac	Option to mimic turbulence production near revetments	0.0	0.0 - 1.0
lws+	Switch to enable long wave stirring	1	0 - 1
lwt+	Switch to enable long wave turbulence	0	0 - 1
phit+	Phase lag angle in nielsen transport equation	25.0	0.0 - 90.0
pormax	Max porosity used in the experession of van rhee	0.5	0.3 - 0.6
reposeangle	Angle of internal friction	30.0	0.0 - 45.0	deg
rheeA	A parameter in the van rhee expression	0.75	0.75 - 2.0
smax+	Maximum shields parameter for equilibrium sediment concentration acc. diane foster	-1.0	-1.0 - 3.0
sus+	Calibration factor for suspensions transports	1	0 - 1
sws+	Switch to enable short wave and roller stirring and undertow	1	0 - 1
tsfac+	Coefficient determining ts = tsfac * h/ws in sediment source term	0.1	0.01 - 1.0
turb+	Switch to include short wave turbulence	wave_averaged	none, wave_averaged, bore_averaged
turbadv+	Switch to activate turbulence advection model for short and or long wave turbulence	none	none, lagrangian, eulerian
waveform	Wave shape model	vanthiel	ruessink_vanrijn, vanthiel
z0+	Zero flow velocity level in soulsby and van rijn (1997) sediment concentration	0.006	0.0001 - 0.05	m

Sediment transport numerics¶

The parameters listed in the table below involve the numerical aspects of sediment transport that are all considered advanced options. For example the maximum allowed sediment concentration can be varied with the keyword cmax. It is however not recommended varying these settings.

Overview of available keywords related to sediment transport numerics parameters¶
parameter	description	default	range
cmax+	Maximum allowed sediment concentration	0.1	0.0 - 1.0
sourcesink+	Switch to enable source-sink terms to calculate bed level change rather than suspended transport gradients	0	0 - 1
thetanum+	Coefficient determining whether upwind (1) or central scheme (0.5) is used.	1.0	0.5 - 1.0

Quasi-3D sediment transport¶

The parameters listed in the table below involve the tuning of quasi-3D sediment transport, if enabled. The most important setting is the kmax in which the user specifies the number of layers used in the quasi 3D sediment model.

Overview of available keywords related to q3d sediment transport parameters¶
parameter	description	default	range
deltar	Estimated ripple height	0.025	0.001 - 1.0
kmax	Number of sigma layers in quasi-3d model; kmax = 1 is without vertical structure of flow and suspensions	100	1 - 1000
rwave	User-defined wave roughness adjustment factor	2.0	0.1 - 10.0
sigfac	Dsig scales with log(sigfac)	1.3	0.0 - 10.0
vicmol	Molecular viscosity	1e-06	0.0 - 0.001
vonkar	Von karman constant	0.4	0.01 - 1.0

Morphology¶

The parameters listed in the table below involve the morphological processes. The dryslp and wetslp keyword define the critical avalanching slope above and below water respectively. If the bed exceeds the relevant critical slope it collapses and slides downward (avalanching). To reduce the impact of these landslides the maximum bed level change due to avalanching is limited by the dzmax value. Which of the two slopes is applied to a grid cell is determined by the hswitch keyword.

The keyword morfac enables the user to decouple the hydrodynamical and the morphological time. This is suitable for situations where the morphological process is much slower than the hydrodynamic process. The factor defined by the morfac keyword is applied to all morphological change. A morfac = 10 therefore results in 10 times more erosion and deposition in a given time step than usual. The simulation time is however then shortened with the same factor to obtain an approximate result more quickly. The user can prevent the simulation time to be adapted to the morfac value by setting morfacopt to zero. The keywords morstart and morstop let the user enable the morphological processes in XBeach only for a particular period during the (hydrodynamic) simulation. These options can be useful if a spin-up time is needed for the hydrodynamics.

The struct and ne_layer keywords enable the user to specify non-erodible structures in the model. To switch on non-erodible structures use struct = 1. The location of the structures is specified in an external file referenced by the ne_layer keyword. The file has the same format as the bathymetry file explained in Grid and bathymetry. The values of the file define the thickness of the erodible layer on top of the non-erodible layer. A ne_layer file with only zeros therefore defines a fully non-erodible bathymetry and a file with only tens means a erodible layer of 10 meters. Only at the grid cells where the value in the ne_layer file is larger than zero erosion can occur. Non-erodible layers are infinitely deep and thus no erosion underneath these layers can occur.

Overview of available keywords related to morphology parameters¶
parameter	description	default	range	units
dryslp	Critical avalanching slope above water (dz/dx and dz/dy)	1.0	0.1 - 2.0
dzmax+	Maximum bed level change due to avalanching	0.05	0.0 - 1.0	m/s/m
hswitch+	Water depth at which is switched from wetslp to dryslp	0.1	0.01 - 1.0	m
lsgrad	Factor to include longshore transport gradient in 1d simulationsdsy/dy=lsgrad*sy; dimension 1/length scale of longshore gradients	0.0	-0.1 - 0.1	1/m
morfac	Morphological acceleration factor	1.0	0.0 - 1000.0
morfacopt+	Switch to adjusting output times for morfac	1	0 - 1
morstart	Start time morphology, in morphological time	0.0	0.0 - par%tstop	s
morstop	Stop time morphology, in morphological time	2000.0	0.0 - 10000000.0	s
ne_layer	Name of file containing thickness of the erodible layer			<file>
struct	Switch for enabling hard structures	0	0 - 1
wetslp	Critical avalanching slope under water (dz/dx and dz/dy)	0.3	0.1 - 1.0

Bed update¶

The parameters listed in the table below involve the settings for the bed update process especially in the case multiple sediment fractions and bed layers are involved. The frac_dz, split and merge keywords determine the fraction of the variable bed layer thickness at which the layer is split or merged respectively with the surrounding bottom layers. The variable layer is chosen using the nd_var keyword.

Pre-defined bed evolution can be used with the keywords setbathy that is used to turn user-imposed bed level change on, nsetbathy that determines the number of imposed bed level conditions and setbathyfile that references a file that specifies the time series of imposed bed levels. If the setbathy option is used, XBeach will automatically interpolate the bed level at each computational time step from the imposed bed level time series.

The setbathyfile file must contain a time series (of length nsetbathy) of the bed level at every grid point in the XBeach model. The format of the setbathyfile file is such that each imposed bed level starts with the time at which the bed level should be applied (in seconds relative to the start of the simulation), followed on a new line by the bed level in each grid cell in an identical manner to the normal initial bathymetry file (e.g., one line per transect in the x-direction). The following imposed bed level condition starts on a new line with the time at which the condition is imposed and the bed levels at that time, etc. An example of a setbathyfile is given below.

setbathyfile.dep (generalized)

<t 0>
<z 1,1> <z 2,1> <z 3,1> ... <z nx,1> <z nx+1,1>
<z 1,2> <z 2,2> <z 3,2> ... <z nx,2> <z nx+1,2>
<z 1,3> <z 2,3> <z 3,3> ... <z nx,3> <z nx+1,3>

...

<z 1,ny> <z 2,ny> <z 3,ny> ... <z nx,ny> <z nx+1,ny>
<z 1,ny+1> <z 2,ny+1> <z 3,ny+1> ... <z nx,ny+1> <z nx+1,ny+1>
<t 1>
<z 1,1> <z 2,1> <z 3,1> ... <z nx,1> <z nx+1,1>
<z 1,2> <z 2,2> <z 3,2> ... <z nx,2> <z nx+1,2>
<z 1,3> <z 2,3> <z 3,3> ... <z nx,3> <z nx+1,3>

...

<z 1,ny> <z 2,ny> <z 3,ny> ... <z nx,ny> <z nx+1,ny>
<z 1,ny+1> <z 2,ny+1> <z 3,ny+1> ... <z nx,ny+1> <z nx+1,ny+1>

...

...

<t nsetbathy>
<z 1,1> <z 2,1> <z 3,1> ... <z nx,1> <z nx+1,1>
<z 1,2> <z 2,2> <z 3,2> ... <z nx,2> <z nx+1,2>
<z 1,3> <z 2,3> <z 3,3> ... <z nx,3> <z nx+1,3>

...

<z 1,ny> <z 2,ny> <z 3,ny> ... <z nx,ny> <z nx+1,ny>
<z 1,ny+1> <z 2,ny+1> <z 3,ny+1> ... <z nx,ny+1> <z nx+1,ny+1>

setbathyfile.dep (short 1D example, nx = 20, ny = 0, nsetbathy = 4)

  -20 -18 -16 -14 -12 -10 -8 -6 -5 -4 -3   -2   -1    -0.5  0    0.5 1   2   3   4   5
-20 -18 -16 -14 -12 -10 -8 -6 -5 -4 -3   -1.8 -0.75 -0.25 0    0.2 0.7 2   3   4   5
-20 -18 -16 -14 -12 -10 -8 -6 -5 -4 -2.5 -1.6 -0.5  -0.3  0    0.1 0.6 1.5 3   4   5
-20 -18 -16 -14 -12 -10 -8 -6 -5 -4 -2   -1.4 -0.3   0    0.05 0.1 0.6 1   2.2 3.5 5

Note that if the setbathy option is used, the initial bed level is derived from an interpolation of the setbathyfile file time series, not from the depfile file. It is strongly advised to turn of the computation of morphological updating (keyword: morphology = 0) if the setbathy option is used, as the computed morphological change will be overridden by the imposed morphological change.

Overview of available keywords related to bed update numerics parameters¶
parameter	description	default	range	units
frac_dz+	Relative thickness to split time step for bed updating	0.7	0.5 - 0.98
merge+	Merge threshold for variable sediment layer (ratio to nominal thickness)	0.01	0.005 - 0.1
nd_var+	Index of layer with variable thickness	2	1 - par%nd
nsetbathy+	Number of prescribed bed updates	1	1 - 1000
setbathyfile*+	Name of prescribed bed update file			<file>
split+	Split threshold for variable sediment layer (ratio to nominal thickness)	1.01	1.005 - 1.1

Groundwater flow¶

The parameters listed in the table below involve the process of groundwater flow. The vertical permeability coefficient in the vertical can be set differently than that of the horizontal using the keywords kz and kz respectively. The initial bed level of the aquifer is read from an external file referenced by the aquiferbotfile keyword and the initial groundwater head can be set to either a uniform value using the gw0 keyword or to spatially varying values using an external file referenced by the gw0file keyword. Both files have the same format as the bathymetry file explained in Grid and bathymetry.

Overview of available keywords related to groundwater parameters¶
parameter	description	default	range	units
aquiferbot+	Level of uniform aquifer bottom	-10.0	-100.0 - 100.0	m
aquiferbotfile+	Name of the aquifer bottom file			<file>
dwetlayer+	Thickness of the top soil layer interacting more freely with the surface water	0.1	0.01 - 1.0	m
gw0+	Level initial groundwater level	0.0	-5.0 - 5.0	m
gw0file+	Name of initial groundwater level file			<file>
gwReturb+	Reynolds number for start of turbulent flow in case of gwscheme = turbulent	100.0	1.0 - 600.0
gwfastsolve	Reduce full 2d non-hydrostatic solution to quasi-explicit in longshore direction	0	0 - 1
gwheadmodel+	Model to use for vertical groundwater head	parabolic	parabolic, exponential
gwhorinfil+	Switch to include horizontal infiltration from surface water to groundwater	0	0 - 1
gwnonh+	Switch to turn on or off non-hydrostatic pressure for groundwater	0	0 - 1
gwscheme+	Scheme for momentum equation	laminar	laminar, turbulent
kx+	Darcy-flow permeability coefficient in x-direction	0.0001	1e-05 - 0.1	ms^-1
ky+	Darcy-flow permeability coefficient in y-direction	0.0001	1e-05 - 0.1	ms^-1
kz+	Darcy-flow permeability coefficient in z-direction	0.0001	1e-05 - 0.1	ms^-1

Non-hydrostatic correction¶

The parameters listed in the table below involve the settings for the non-hydrostatic option (keyword: wavemodel = nonh). These are all considered advanced options and it is thus recommended not to change these

Overview of available keywords related to non-hydrostatic correction parameters¶
parameter	description	default	range	units
Topt+	Absolute period to optimize coefficient	10.0	1.0 - 20.0	s
breakviscfac+	Factor to increase viscosity during breaking	1.5	1.0 - 3.0
breakvisclen+	Ratio between local depth and length scale in extra breaking viscosity	1.0	0.75 - 3.0
dispc+	Coefficient in front of the vertical pressure gradient	-1.0	0.1 - 2.0	?
kdmin+	Minimum value of kd (pi/dx > min(kd))	0.0	0.0 - 0.05
maxbrsteep+	Maximum wave steepness criterium	0.4	0.3 - 0.8
nhbreaker+	Non-hydrostatic breaker model	2	0 - 2
nhlay+	Layer distribution in the nonhydrostatic model, default = 0.33	0.33	0.0 - 1.0
nonhq3d	Turn on or off the the reduced two-layer nonhydrostatic model, default = 0	0	0 - 1
reformsteep+	Wave steepness criterium to reform after breaking	0.25d0*par%maxbrsteep	0.0 - 0.95d0*par%maxbrsteep
secbrsteep+	Secondary maximum wave steepness criterium	0.5d0*par%maxbrsteep	0.0 - 0.95d0*par%maxbrsteep
solver+	Solver used to solve the linear system	tridiag	sip, tridiag
solver_acc+	Accuracy with respect to the right-hand side usedin the following termination criterion: \|\|b-ax \|\| < acc*\|\|b\|\|	0.005	1e-05 - 0.1
solver_maxit+	Maximum number of iterations in the linear sip solver	30	1 - 1000
solver_urelax+	Underrelaxation parameter	0.92	0.5 - 0.99

Physical constants¶

The parameters listed in the table below involve physical constants used by XBeach. The gravitational acceleration and density of water are universally used coefficient. The depthscale is a factor in order to set different cut-off values like eps and hswitch. A value of the depthscale lower than one means the cut-off values will increase.

Overview of available keywords related to physical constants¶
parameter	description	default	range	units
depthscale+	Depthscale of (lab)test simulated, affects eps, hmin, hswitch and dzmax	1.0	1.0 - 200.0
g	Gravitational acceleration	9.81	9.7 - 9.9	ms^-2
rho	Density of water	1025.0	1000.0 - 1040.0	kgm^-3

Coriolis force¶

The parameters listed in the table below involve the settings for incorporating the effect of Coriolis on the shallow water equations. The keywords are universally used coefficients.

Overview of available keywords related to coriolis force parameters¶
parameter	description	default	range	units
lat+	Latitude at model location for computing coriolis	0.0	-90.0 - 90.0	deg
wearth+	Angular velocity of earth calculated as: 1/rotation_time (in hours)	1.d0/24.d0	0.0 - 1.0	hour^-1

MPI¶

The parameters listed in the table below involve the settings for parallelization of XBeach. When running XBeach in parallel mode, the model domain is subdivided in sub models and each sub model is then computed on a separate core. This will increase the computational speed of the model. The sub models only exchange information over their boundaries when necessary. The MPI parameters determine how the model domain is subdivided. The keyword mpiboundary can be set to auto, x, y or man. In auto mode the model domain is subdivided such that the internal boundary is smallest. In x or y mode the model domain is subdivided in sub models extending to either the full alongshore or the full cross-shore extent of the model domain. In man mode the model domain is manually subdivided using the values specified with the mmpi and nmpi keywords. The number of sub models is not determined by XBeach itself, but by the MPI wrapper (e.g. MPICH2 or OpenMPI). It is important to note that information about slopes isn’t exchanged over the boundaries. Therefore the avalanching algorithm will not function over MPI boundaries.

Overview of available keywords related to mpi parameters¶
parameter	description	default	range
mmpi+	Number of domains in cross-shore direction when manually specifying mpi domains	2	1 - 100
mpiboundary+	Fix mpi boundaries along y-lines, x-lines, use manual defined domains or find shortest boundary automatically	auto	auto, x, y, man
nmpi+	Number of domains in alongshore direction when manually specifying mpi domains	4	1 - 100

Output projection¶

The parameters listed in the table below involve the projection of the model output. These settings do not influence the model results in anyway. The rotate keyword can be used to rotate the model output with an angle specified by the keyword alfa. The projection string can hold a string specifying the coordinate reference system used and is stored in the netCDF output file as metadata.

Overview of available keywords related to output projection¶
parameter	description	default	range
projection+	Projection string
remdryoutput	Remove dry output points from output data of zs etc.	1	0 - 1
rotate	Rotate output as postprocessing with given angle	1	0 - 1

Numerical implementation¶

Grid set-up¶

The new implementation utilizes a curvilinear, staggered grid where depths, water levels, wave action and sediment concentrations are given in the cell centers (denoted by subscript z) and velocities and sediment fluxes at the cell interfaces (denoted by subscript u or v). In Fig. 16 the z, u, v and c (corner) points with the same numbering are shown. The grid directions are named s and n; grid distances are denoted by $\Delta s$ and $\Delta n$ , with subscripts referring to the point where they are defined. A finite-volume approach is utilized where mass, momentum and wave action are strictly conserved. In the middle panel of Fig. 16, the control volume for the mass balance is shown with the corresponding grid distances around the u- and v-points. The right panel explains the numbering of the fluxes Q and the volume V.

Location of staggered grid points (left panel); definition of grid distances (middle) and terms in volume balance (right)

Wave action balance¶

Surfbeat solver¶

The time-varying wave action balance solved in XBeach is as follows:

(115) $\frac{\partial E}{\partial t} +\frac{\partial EC_{g,u} }{\partial s} +\frac{\partial EC_{g,v} }{\partial n} +\frac{\partial EC_{\vartheta } }{\partial \vartheta } =-Sink$

Where $E$ is the wave energy or wave action, $C_g$ is the group velocity, $C_{\vartheta}$ the refraction speed in theta-space and $Sink$ refers to effects of wave breaking and bottom friction.

Again, the advection terms are the only ones affected by the curvilinear scheme so we will discuss their treatment in detail. The control volume is the same as for the mass balance. In equation (116) the procedure to compute the wave energy fluxes across the cell boundaries is outlined. All variables should also have an index $itheta$ referring to the directional grid, but for brevity these are omitted here.

The component of the group velocity normal to the cell boundary, at the cell boundary, is interpolated from the two adjacent cell center points. Depending on the direction of this component, the wave energy at the cell boundary is computed using linear extrapolation based on the two upwind points, taking into account their grid distances. This second order upwind discretization preserves the propagation of wave groups with little numerical diffusion.

(116) $\begin{array}{l} {Cg_{u,u}^{i,j} =\frac{1}{2} (Cg_{u}^{i,j} +Cg_{u}^{i+1,j} )} \\ {E_{u}^{i,j} =E^{i,j} +\frac{1}{2} \Delta s_{u}^{i,j} \frac{E^{i,j} -E^{i-1,j} }{\Delta s_{u}^{i-1,j} } =} \\ {=\left(\left(\Delta s_{u}^{i-1,j} +\frac{1}{2} \Delta s_{u}^{i,j} \right)E^{i,j} -\frac{1}{2} \Delta s_{u}^{i,j} E^{i-1,j} \right)/\Delta s_{u}^{i-1,j} \, \, \, \, \, ,Cg_{u,u}^{i,j} >0} \\ {E_{u}^{i,j} =E^{i+1,j} -\frac{1}{2} \Delta s_{u}^{i,j} \frac{E^{i+2,j} -E^{i+1,j} }{\Delta s_{u}^{i+1,j} } =} \\ {=\left(\left(\Delta s_{u}^{i+1,j} +\frac{1}{2} \Delta s_{u}^{i,j} \right)E^{i+1,j} -\frac{1}{2} \Delta s_{u}^{i,j} E^{i+2,j} \right)/\Delta s_{u}^{i+1,j} \, \, \, \, \, ,Cg_{u,u}^{i,j} <0} \\ {} \\ {Flux_{u}^{i,j} =Cg_{u,u}^{i,j} E_{u}^{i,j} \Delta n_{u}^{i,j} } \end{array}$

The other three fluxes are computed in a similar way; for brevity we will not present all formulations.

The time integration is explicit and the same as in the original implementation. The advection in u- and v-direction is computed simply by adding the four fluxes and dividing by the cell area. This procedure guarantees conservation of wave energy.

The procedure for the roller energy balance is identical to that for the wave energy balance and will not be repeated here.

Stationary solver¶

In the stationary solver the wave energy and roller energy balances are solved line by line, from the seaward boundary landward. For each line the automatic timestep is computed and the quasi-time-dependent balance is solved until convergence or the maximum number of iterations is reached, after which the solver moves to the next line.

The iteration is controlled by the parameters maxiter and maxerror.

Shallow water equations¶

Mass balance equation¶

The mass balance reads as follows:

(117) $\frac{\partial V}{\partial t} =Q_{u}^{i,j} -Q_{u}^{i-1,j} +Q_{v}^{i,j} -Q_{v}^{i,j-1}$

This is discretized according to:

(118) $\begin{array}{l} {A_{z}^{i,j} \frac{z_{s}^{i,j,n+1} -z_{s}^{i,j,n} }{\Delta t} =u_{u}^{i,j,n+1/2} h_{u}^{i,j,n} \Delta n_{u}^{i,j} -u_{u}^{i-1,j,n+1/2} h_{u}^{i-1,j,n} \Delta n_{u}^{i-1,j} } \\ {\, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, +v_{v}^{i,j,n+1/2} h_{v}^{i,j,n} \Delta s_{v}^{i,j} -v_{v}^{i,j-1,n+1/2} h_{v}^{i,j-1,n} \Delta s_{v}^{i,j-1} } \end{array}$

Here, ${A}_{z}$ is the area of the cell around the cell centre, ${z}_{s}$ is the surface elevation, ${u}_{u}$ is the u-velocity in the u-point, ${h}_{u}$ the water depth in the u-point and ${v}_{v}$ the v-velocity in the v-point. The indices $i,j$ refer to the grid number in u resp. v direction; the index $n$ refers to the time step.

Momentum balance equation¶

Second, we will outline the derivation of the u-momentum balance. The control volume is given in Fig. 17. It is centeredaround the u-point. We now consider the rate of change of the momentum in the local u-direction as follows:

(119) $\frac{d\left(Vu\right)}{dt} -\sum Q_{in} u_{in} +\sum Q_{out} u +Vg\frac{\partial z_{s} }{\partial s} +A\frac{\tau _{b,u} }{\rho } =A\frac{\tau _{s,u} }{\rho } +A\frac{F_{u} }{\rho }$

where V is the cell volume, u the velocity in local grid direction, Q the fluxes, $\rho$ the density, g acceleration of gravity, $\tau_{b,u}, \tau_{b,u}, F_{u}$ the bed shear stress, wind shear stress and wave force in u-direction. We consider that the outgoing fluxes carry the velocity inside the cell, $u$ , and that ${u}_{in}$ is determined at each inflow boundary by interpolation, reconstructing the component in the same direction as $u$ .

The volume balance for the same volume reads:

(120) $\frac{dV}{dt} -\sum Q_{in} + \sum Q_{out} =0$

By multiplying the volume balance by $u$ , subtracting it from the momentum balance and dividing the result by $V$ we arrive at the following equation:

(121) $\frac{du}{dt} +\frac{\sum Q_{in} \left(u-u_{in} \right) }{Ah_{um} } +g\frac{\partial z_{s} }{\partial s} +\frac{\tau _{b,s} }{\rho h_{um} } =\frac{\tau _{s,u} }{\rho h_{um} } +\frac{F_{u} }{\rho h_{um} }$

where $A$ is the cell area and ${h}_{um}$ is the average depth of the cell around the u-point. The procedure for the second term (the others are straightforward) now boils down to integrating (only) the incoming fluxes over the interfaces and multiplying them with the difference between $u$ in the cell and the component of velocity in the same direction at the upwind cell.

Control volume u-momentum balance and definition of fluxes

In the following three quations the procedure for computing the u-momentum balance is outlined. The discharges in the u-points are computed by multiplying the velocity in the u- or v-point by the water depth at that point. These discharges are then interpolated to the borders of the control volume around the u-point. The difference $\Delta \alpha$ in grid orientation between the incoming cell and the u-point is computed and used to compute the component of the incoming velocity in the local u-direction, from the left and right side of the control volume.

(122) $\begin{array}{rclcrcl} q_u^{i,j} &=& u_u^{i,j,n-1/2} h_u^{i,j,n} &~& ~ &~& ~ \\ q_{in}^{left} &=& \frac{1}{2} \left( q_u^{i,j} + q_u^{i-1,j} \right ) &,& q_{in}^{right} &=& -\frac{1}{2} \left( q_u^{i+1,j} + q_u^{i,j} \right ) \\ \Delta \alpha^{left} &=& \alpha_u^{i,j} - \alpha_u^{i-1,j} &,& \Delta \alpha^{right} &=& \alpha_u^{i+1,j} - \alpha_u^{i,j} \\ u_{in}^{left} &=& u_u^{i-1,j} \cos \left( \Delta \alpha \right ) - v_u^{i-1,j} \sin \left( \Delta \alpha \right ) &,& u_{in}^{right} &=& u_u^{i+1,j} \cos \left( \Delta \alpha \right ) - v_u^{i+1,j} \sin \left( \Delta \alpha \right ) \\ \end{array}$

The same is done for the top and bottom of the control volume, based on the discharges in v-direction:

(123) $\begin{array}{rclcrcl} q_v^{i,j} &=& v_v^{i,j,n-1/2} h_v^{i,j,n} &~& ~ &~& \\ q_{in}^{bottom} &=& \frac{1}{2} \left( q_v^{i,j-1} + q_v^{i+1,j-1} \right ) &,& q_{in}^{top} &=& -\frac{1}{2} \left( q_v^{i,j} + q_v^{i+1,j} \right ) \\ \Delta \alpha ^{bottom} &=& \alpha_u^{i,j} - \alpha_u^{i,j-1} &,& \Delta \alpha ^{top} &=& \alpha_u^{i,j+1} - \alpha_u^{i,j} \\ u_{in}^{bottom} &=& u_u^{i,j-1} \cos \left( \Delta \alpha \right ) - v_u^{i,j-1} \sin \left( \Delta \alpha \right ) &,& u_{in}^{top} &=& u_u^{i,j+1} \cos \left( \Delta \alpha \right ) - v_u^{i,j+1} \sin \left( \Delta \alpha \right ) \\ \end{array}$

Finally, the advective term in the momentum balance is given as:

(124) $\begin{array}{l} {\left(\frac{\sum Q_{in} \left(u-u_{in} \right) }{Ah_{um} } \right)^{i,j} =\, {max(q}_{in}^{left} ,0){(}u_{u}^{i,j} {-}u_{in}^{left} {)}\frac{\Delta n_{z}^{i,j} }{h_{um}^{i,j} A_{u}^{i,j} } \, \, \, } \\ {\, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, +\, \, {max(q}_{in}^{right} ,0){(}u_{u}^{i,j} {-}u_{in}^{right} {)}\frac{\Delta n_{z}^{i+1,j} }{h_{um}^{i,j} A_{u}^{i,j} } \, } \\ {\, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, +\, {max(q}_{in}^{bottom} ,0){(}u_{u}^{i,j} {-}u_{in}^{bottom} {)}\frac{\Delta s_{c}^{i,j-1} }{h_{um}^{i,j} A_{u}^{i,j} } } \\ {\, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, \, +\, \, {max(q}_{in}^{top} ,0){(}u_{u}^{i,j} {-}u_{in}^{top} {)}\frac{\Delta s_{c}^{i,j} }{h_{um}^{i,j} A_{u}^{i,j} } \, } \end{array}$

Time integration scheme¶

The time integration of the mass and momentum balance equations is combined in an explicit leap-frog scheme, as depicted in Fig. 18. The velocities (in the ’-’ points) are updated using the momentum balance, the water levels are updated using the mass balance. The water level gradients influence the momentum balance and the velocities and derived discharges affect the mass balance. Because of the leap-frog scheme these influences are always computed at the half time step level, which makes the scheme second order accurate.

Leap-frog time integration scheme

Using this straightforward finite volume approach, complicated transformations of the equations are avoided and the solution scheme remains transparent. It is also completely compatible with the original rectilinear implementation and is even slightly more efficient.

Groundwater flow¶

In order to solve the equations in xx, the spatial and temporal domain of the groundwater system is split into the same spatial grid and time steps as the XBeach surface water model it is coupled to. At each time step in the numerical model, the depth average groundwater head is calculated in the center of the groundwater cells, and the fluxes (specific discharge, submarine exchange, infiltration and exfiltration) are calculated on the cell interfaces

At the start of the time step, every cell is evaluated whether the groundwater and surface water are connected:

(125) $\kappa _{i,j} =\eta _{gw,i,j} \ge z_{b,i,j} -\varepsilon \wedge \eta _{i,j} \ge z_{b,i,j} +\varepsilon$

In equation (125) $\varepsilon$ is a numerical smoothing constant used to deal with numerical round off errors near the bed (equal to the parameter dwetlayer in the case of hydrostatic groundwater flow, and to the parameter eps in the case of non-hydrostatic groundwater flow), and $i$ and $j$ represent cross-shore and longshore coordinates in the numerical solution grid, respectively. Infiltration is calculated in cells where the groundwater and surface water are not connected and there exists surface water. As shown in equation (68) the infiltration rate is a function of the thickness of the wetting front, which is zero at the start of infiltration, and increases as a function of the infiltration rate. The equations for the infiltration rate and the thickness of the wetting front are approximated by first-order schemes, in which the wetting front is updated using a backward-Euler scheme, which ensures numerical stability:

(126) $\begin{array}{c} {S_{inf,i,j}^{n} =K_{i,j} \left(\frac{1}{\rho g} \frac{\left. p_{lpf,i,j} \right|^{z=z_{b} } }{\delta _{infill,i,j}^{n} } 1\right)} \\ {{\; }\delta _{infill,i,j}^{n} =\delta _{infill,i,j}^{n-1} +S_{inf,i,j}^{n} \frac{\Delta t}{n_{p} } } \end{array}$

In the pressure term ${p}_{lpf}$ is the surface water pressure at the bed, which in the case of non-hydrostatic surface water flow is high-pass filtered at $4/{T}_{rep}$ , the superscript $n$ corresponds to the time step number and $\Delta t$ is the size of the time step. The infiltration rate in the coupled relationship can be solved through substitution:

(127) $S_{inf,i,j}^{n} =\frac{-\delta _{infill,i,j}^{n-1} +\frac{\Delta t}{n_{p} K_{i,j} } +\sqrt{\left(\delta _{infill,i,j}^{n-1} \right)^{2} +\frac{2}{n_{p} } \frac{\Delta t}{\delta _{infill,i,j}^{n-1} K_{i,j} } +\frac{4\rho g}{n_{p} } \frac{\Delta t}{p_{i,j} \left|^{z=\xi } \right. K_{i,j} } +\frac{\Delta t^{2} }{K_{_{i,j} }^{2} } } }{\frac{2\Delta t}{n_{p} } }$

At the end of infiltration, i.e. when the groundwater and surface water become connected or there is no surface water left, the wetting front thickness is reset to zero. If the infiltration rate exceeds the Reynolds number for the start of turbulence, the local hydraulic conductivity is updated using the local Reynolds number:

(128) $K_{i,j} =K_{lam} \sqrt{\frac{Re_{crit} }{\max (Re_{i,j} ,Re_{crit} )} }$

XBeach iterates until a minimum threshold difference between iterations is found for and . Infiltration in one time step is limited to the amount of surface water available in the cell and to the amount of water required to raise the groundwater level to the level of the bed:

(129) $S_{inf,i,j}^{n} =\min \left(S_{inf,i,j}^{n} ,\frac{\eta _{i,j-} z_{b,i,j} }{\Delta t} ,\frac{z_{b,i,j} -\eta _{gw,i,j-} }{n_{p} \Delta t} \right)$

If during infiltration the groundwater level reaches the bed level, the fraction of the time step required to do so is estimated (x) and the remaining fraction is used in the submarine exchange.

(130) $\begin{array}{c} {\Lambda _{t,i,j} =\frac{n_{p} \left(z_{b,i,j} -\eta _{gw,i,j} \right)}{K_{i,j} \left(\frac{1}{\rho g} \frac{\left. p_{i,j} \right|^{z=\xi } }{z_{b,i,j} -\eta _{gw,i,j} } +1\right)} \frac{1}{\Delta t} } \\ {} \\ {0\le \Lambda _{t,i,j} \le 1} \end{array}$

Exfiltration is calculated in cells where the groundwater and surface water are not connected and the groundwater level exceeds the bed level:

(131) $S_{exf,i,j} =n_{p} \frac{z_{b,i,j} -\eta _{gw,i,j} }{\Delta t}$

Horizontal infiltration and exfiltration (keyword: gwhorinfil = 1) is computed across the numerical vertical interface between the groundwater domain and the surface water domain in adjoining cells. The direction of exchange is determined by the head gradient, and the bed level slope direction:

(132) $\begin{array}{l} {S_{i,j,hor}^{u} =\left\{\begin{array}{cc} {K_{_{i,j} }^{u} \left(\frac{\eta _{i,j} +\frac{q_{i,j} }{g} -H_{gw,i+1,j} }{\Delta x} \right)\left(z_{b,i+1,j} -z_{b,i,j} \right)} & {z_{b,i+1,j} >z_{b,i,j} \wedge \eta _{i,j} >eps} \\ {K_{_{i,j} }^{u} \left(\frac{\eta _{i+1,j} +\frac{q_{i+1,j} }{g} -H_{gw,i,j} }{\Delta x} \right)\left(z_{b,i,j} -z_{b,i+1,j} \right)} & {z_{b,i+1,j} <z_{b,i,j} \wedge \eta _{i+1,j} >eps} \end{array}\right. } \\ {S_{i,j,hor}^{v} =\left\{\begin{array}{cc} {K_{_{i,j} }^{v} \left(\frac{\eta _{i,j} +\frac{q_{i,j} }{g} -H_{gw,i,j+1} }{\Delta y} \right)\left(z_{b,i,j+1} -z_{b,i,j} \right)} & {z_{b,i,j+1} >z_{b,i,j} \wedge \eta _{i,j} >eps} \\ {K_{_{i,j} }^{v} \left(\frac{\eta _{i,j+1} +\frac{q_{i,j+1} }{g} -H_{gw,i,j} }{\Delta y} \right)\left(z_{b,i,j} -z_{b,i,j+1} \right)} & {z_{b,i,j+1} <z_{b,i,j} \wedge \eta _{i,j+1} >eps} \end{array}\right. } \end{array}$

After infiltration and exfiltration have been calculated, the groundwater level and surface water level are updated:

(133) $\begin{array}{l} {\eta _{gw,i,j}^{n+\frac{1}{2} } =\eta _{gw,i,j}^{n} +\frac{\Delta t}{n_{p} } \left(S_{\inf } +S_{exf} +S_{hor} \right)} \\ {\eta _{i,j}^{n+\frac{1}{2} } =\eta _{i,j}^{n} +\Delta t\left(-S_{\inf } -S_{exf} -S_{hor} \right)} \end{array}$

All updated cells are subsequently re-evaluated on whether the surface water and groundwater are connected or unconnected

The cell height at the center of the groundwater cells ( $\Delta z_{H,i,j}$ ) is calculated from the groundwater level and the bottom of the aquifer in the center of the cell, whereas the cell heights at the horizontal cell interfaces are calculated using an upwind procedure:

(134) $\begin{array}{c} {\Delta z_{H,i,j} =\eta _{gw,i,j} -z_{aquifier,i,j} =h_{gw,i,j} } \\ {} \\ {\Delta z_{u,i,j} =\left\{\begin{array}{l} {\Delta z_{H,i+1,j} {\; \; if\; }q_{qw,i,j}^{x} <0} \\ {\Delta z_{H,i,j} {\; \; \; \; if\; }q_{qw,i,j}^{x} \ge 0} \end{array}\right. } \\ {\Delta z_{v,i,j} =\left\{\begin{array}{l} {\Delta z_{H,i+1,j} {\; \; if\; }q_{qw,i,j}^{y} <0} \\ {\Delta z_{H,i,j} {\; \; \; \; if\; }q_{qw,i,j}^{y} \ge 0} \end{array}\right. } \end{array}$

In ${z}_{aquifer}$ is the level of the bottom of the aquifer. As described in Sediment transport, the head applied on the top boundary of the groundwater domain ( ${H}_{bc}$ ) depends on whether the groundwater and surface water are connected or unconnected:

(135) $\begin{array}{l} {H_{bc,i,j} =\left(1-\kappa _{r,i,j} \right)\eta _{gw,i,j} +\kappa _{r,i,j} \left(z_{b,i,j} {+}\frac{\left. p_{i,j} \right|^{z=z_{b} } }{\rho g} \right)} \\ {\begin{array}{ccc} {\kappa _{r,i,j} =1-\frac{z_{b,i,j} -\eta _{gw,i,j} }{\varepsilon } } & {} & {0\le \kappa _{r,i,j} \le 1} \end{array}} \end{array}$

In the parameter $\kappa_{r}$ is the relative numerical ‘connectedness’ of the groundwater and surface water head, determined by linear interpolation across the numerical smoothing constant $\varepsilon$ .

In the case of hydrostatic groundwater flow, the groundwater head in each cell is set equal to the head applied on the top boundary of the groundwater domain ( ${H}_{bc}$ ) and the horizontal groundwater flux is computed from the groundwater head gradient:

(136) $\begin{array}{l} {q_{gw,i,j}^{x} =-K_{u,i,j} \Delta z_{u,i} \frac{H_{i+1,j} -H_{i,j} }{\Delta x_{u,i,j} } =-K_{u,i,j} \Delta z_{u,i} \frac{H_{bc,i+1,j} -H_{bc,i,j} }{\Delta x_{u,i,j} } } \\ {q_{gw,i,j}^{y} =-K_{v,i,j} \Delta z_{v,i} \frac{H_{i+1,j} -H_{i,j} }{\Delta y_{v,i,j} } =-K_{v,i,j} \Delta z_{v,i} \frac{H_{bc,i+1,j} -H_{bc,i,j} }{\Delta y_{v,i,j} } } \end{array}$

In the superscripts $x$ and $y$ refer to the components of the variable in the cross-shore and longshore direction, respectively, and the subscripts $u$ and $v$ refer to variables approximated at the horizontal cell interfaces in the cross-shore and longshore direction, respectively.

In the case of non-hydrostatic groundwater flow, the horizontal specific discharge on each cell interface can be found through an approximation of the non-hydrostatic groundwater head gradient:

(137) $\begin{array}{l} {q_{gw,i,j}^{x} =-K_{u,i,j} \Delta z_{u,i} \frac{H_{i+1,j} -H_{i,j} }{\Delta x_{u,i,j} } =-K_{u,i,j} \Delta z_{u,i} \frac{H_{bc,i+1,j} -\frac{2}{3} \beta _{i+1,j} \Delta z_{H,i+1,j}^{2} -H_{bc,i,j} +\frac{2}{3} \beta _{i,j} \Delta z_{H,i,j}^{2} }{\Delta x_{u,i,j} } } \\ {q_{gw,i,j}^{y} =-K_{v,i,j} \Delta z_{v,i} \frac{H_{i+1,j} -H_{i,j} }{\Delta y_{v,i,j} } =-K_{v,i,j} \Delta z_{v,i} \frac{H_{bc,i+1,j} -\frac{2}{3} \beta _{i+1,j} \Delta z_{H,i+1,j}^{2} -H_{bc,i,j} +\frac{2}{3} \beta _{i,j} \Delta z_{H,i,j}^{2} }{\Delta y_{v,i,j} } } \end{array}$

In the subscript $H$ refers to variables approximated at the cell centers. The hydraulic conductivity may be different at each cell interface and is therefore computed at every interface where every K is calculated separately.

Continuity in the groundwater cell is found following:

(138) $q_{gw,i-1,j}^{x} -q_{gw,i,j}^{x} +q_{gw,i,j-1}^{y} -q_{gw,i,j}^{y} -q_{gw,i,j}^{z} =0$

In the variable ${q}^{z}$ refers to the vertical groundwater discharge (e.g., submarine exchange if connected to the surface water, or groundwater level fluctuations if the groundwater is not connected to the surface water).

In the case of hydrostatic groundwater flow, the variable ${q}^{z}$ can be solved through the known variables ${q}^{x}$ and ${q}^{y}$ . However, in the case of non-hydrostatic groundwater flow, all variables in contain an unknown value for the groundwater pressure head, described in terms of a known head at the surface of the groundwater ( ${H}_{bc}$ ) and the unknown curvature of the vertical groundwater head function ( $\beta$ ). Since water is incompressible, the groundwater pressure must be solved for all cells simultaneously using matrix algebra:

(139) $Ax+b=0$

In A is a matrix containing coefficients for the horizontal and vertical specific discharge, x is a vector containing the unknown groundwater head curvature, and b contains the known forcing terms. For a one dimensional cross-shore case, A is reduced to a tridiagonal matrix. The vector of known forcing consists of the numerical gradients in the contribution of the head applied on the top boundary of the groundwater domain to the horizontal specific discharge.

In the one dimensional case, the solution to the tridiagonal matrix A can be computed using the efficient Thomas algorithm ([Tho49]). In the two dimensional case, matrix A contains two additional diagonals that are not placed along the main diagonal, and vector b contains additional forcing terms from the alongshore contribution. The solution to the two dimensional case requires a more complex and less computationally efficient matrix solver. In this case the Strongly Implicit Procedure ([Sto68]) is used in a manner similar to [ZSS11]. The horizontal and vertical groundwater fluxes are calculated using the solution of x plus and .

Since in both hydrostatic and non-hydrostatic groundwater flow some local velocities may exceed the critical Reynolds number for the start of turbulence ( ${Re}_{crit}$ ), the turbulent hydraulic conductivity ( $K$ ) is updated using the local Reynolds number. The solution to and the update of the turbulent hydraulic conductivity are iterated until a minimum threshold difference between iterations is found. Note that this approach is only used is the turbulent groundwater model is selected (keyword: gwscheme = turbulent).

The (iterated) solution for the specific vertical discharge is used to update the groundwater level and surface water level:

(140) $\begin{array}{rcl} {\eta _{_{gw,i,j} }^{n+1} } & {=} & {\left\{\begin{array}{l} {\eta _{_{gw,i,j} }^{n+\frac{1}{2} } {\; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; }C_{i,j} } \\ {\eta _{_{gw,i,j} }^{n+\frac{1}{2} } +\frac{\Delta t}{n_{p} } \frac{q_{i,j}^{z} }{\Delta x_{H,i,j} } {\; \; \; }\neg C_{i,j} {\; \; \; }} \end{array}\right. } \\ {\eta _{_{i,j} }^{n+1} } & {=} & {\left\{\begin{array}{l} {\eta _{_{i,j} }^{n+\frac{1}{2} } +\Delta t\frac{q_{i,j}^{z} }{\Delta x_{H,i,j} } {\; \; \; \; \; }C_{i,j} } \\ {\eta _{_{i,j} }^{n+\frac{1}{2} } {\; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; }\neg C_{i,j} } \end{array}\right. } \end{array}$

If the groundwater and surface water are connected, and the submarine exchange from the surface water to the groundwater estimated in is greater than the amount of surface water available in the cell, continuity is enforced by lowering the groundwater level to compensate for the lack of permeating water:

(141) $\eta _{_{gw,i,j} }^{n+1} =\eta _{_{gw,i,j} }^{n+1} +\frac{1}{n_{p} } \left(\eta _{_{i,j} }^{n+\frac{1}{2} } -z_{b,i,j} -\Delta t\frac{q_{i,j}^{z} }{\Delta x_{H,i,j} } \right){\; if\; \; }\kappa _{i,j} \wedge \eta _{i,j}^{n+\frac{1}{2} } -z_{b,i,j} <\Delta t\frac{q_{i,j}^{z} }{\Delta x_{H,i,j} }$

Sediment transport¶

The advection-diffusion equation for suspended sediment is the basis for the sediment transport computations in XBeach. The partial differential equation to solve is:

(142) $\frac{\partial hc}{\partial t} +\nabla \vec{S}_{s} =\frac{hc_{eq} -hc}{T_{s} } =-\frac{hc}{T_{s} } +Ero$

Here $c$ is the depth-averaged concentration, ${c}_{eq}$ the equilibrium concentration, $Ts$ a typical timescale proportional to water depth divided by fall velocity. As is often done to increase robustness, we treat the erosion term explicitly but take an implicit scheme for the sedimentation term:

(143) $\frac{{c}_{{z}}^{{i,j,n+1}} h_{h}^{i,j,n+1} -h_{h}^{i,j,n} {c}_{z}^{{i,j,n}} }{\Delta {t}} {\; =\; }-\frac{h_{h}^{i,j,n+1} {c}_{z}^{{i,j,n+1}} }{{T}_{{s}}^{{i,j}} } -\left(\nabla \vec{S}_{s} \right)^{i,j,n} {+\; \; }Ero^{i,j,n}$

This can be rewritten as:

(144) ${c}_{{c}}^{{i,j,n+1}} {\; =\; }\frac{{T}_{{s}}^{{i,j}} \Delta {t}}{h_{h}^{i,j,n+1} \left({T}_{{s}}^{{i,j}} +\Delta {t}\right)} \left(\frac{h_{h}^{i,j,n} {c}_{{c}}^{{i,j,n}} }{\Delta t} -\left(\nabla \vec{S}_{s} \right)^{i,j,n} {+}Ero^{i,j,n} \right)$

The sediment transport gradient is discretized in a similar way as the mass balance:

(145) $\left(\nabla \vec{S}_{s} \right)^{i,j} =\frac{\left(S_{u,s}^{i,j} \Delta n_{u}^{i,j} -S_{u,s}^{i-1,j} \Delta n_{u}^{i-1,j} +S_{v,s}^{i,j} \Delta s_{v}^{i,j} -S_{v,s}^{i,j-1} \Delta s_{v}^{i,j-1} \right)}{A_{z}^{i,j} }$

The sediment transports in the u- points contain an advective term, a diffusive term and a bed slope term:

(146) ${S}_{{u,s}} {=c}_{u} {u}_{{rep,s}} {h}_{{u}} {-D}_{{c}} {h}_{{u}} \frac{\partial c}{\partial s} {-f}_{slope} {c}_{{u}} \left|v\right|_{u} {h}_{{u}} \frac{\partial z_{b} }{\partial s} {)}$

Here ${u}_{rep,s}$ is a representative velocity for suspended transport, which contains contributions due to return flow, wave skewness and wave asymmetry; ${D}_{c}$ is a horizontal diffusion coefficient and ${f}_{slope}$ a coefficient. In discretized form the expression for the suspended transport in the u-point is:

(147) $S_{u,s}^{i,j} = c_u^{i,j} u_{rep,s}^{i,j} h_u^{i,j} -D_c^{i,j} h_u^{i,j} \frac{c_c^{i+1,j} -c_c^{i,j} }{\Delta s_u^{i,j} } -f_{slope} c_u^{i,j} \left|v\right|_u^{i,j} h_u^{i,j} \frac{z_b^{i+1,j} -z_b^{i,j} }{\Delta s_u^{i,j} } )$

The concentrations in the u-points are computed with a $\theta$ -method, where $\theta=1$ means a fully upwind approximation, and $\theta=0.5$ a central scheme. In practice, we mostly use the upwind approximation for its robustness.

(148) $\begin{array}{l} {c_{u}^{i,j} =\theta c_{z}^{i,j} +\left(1-\theta \right)c_{z}^{i+1,j} \, \, \, \, \, \, \, ,u_{rep,s}^{i,j} >0} \\ {c_{u}^{i,j} =\left(1-\theta \right)c_{z}^{i,j} +\theta c_{z}^{i+1,j} \, \, \, \, \, \, \, ,u_{rep,s}^{i,j} <0} \end{array}$

The erosion and deposition terms, which may also be used in the bed updating, are finally computed from:

(149) $\begin{array}{l} {Ero^{i,j,n} {=\; h}_{{h}}^{i,j,n} {c}_{{eq}}^{{i,j,n}} {/T}_{{s}}^{{i,j}} } \\ {Depo^{i,j} ={h}_{{h}}^{i,j,n+1} {c}_{z}^{{i,j,n+1}} {/T}_{{s}}^{{i,j}} } \end{array}$

The evaluation of the bedload transport takes place in the same way as in the previous versions of XBeach, except for the fact that the directions are taken in local grid direction, and will not be repeated here.

Bottom updating schemes¶

Two alternative formulations are available for the bed updating: one where the bottom changes are computed based on the gradients of suspended and bed load transport, equation (150) , and one where the changes due to suspended transport are accounted for through the erosion and deposition terms, equation (151).

(150) $\left(1-n_{p} \right)\frac{\partial z_{b} }{\partial t} +MF\left(\nabla \overrightarrow{S}_{s} +\nabla \overrightarrow{S}_{b} \right)=0$

(151) $\left(1-n_{p} \right)\frac{\partial z_{b} }{\partial t} +MF\left(Ero-Depo+\nabla \overrightarrow{S}_{b} \right)=0$

In both cases $MF$ is the morphological factor used to accelerate morphological changes. In the first case, the sediment in the bottom is conserved in all cases, but changes in the amount of sediment in the water are not considered; one can also say that the sediment in suspension is added to the bottom sediment. In the second case, the storage of sediment in the water is accounted for, but will be distorted in cases of high $MF$ . Since under most circumstances the real effect of the storage in the water phase is small we prefer the first formulation which guarantees mass conservation in the bottom. Both formulations are calculated using an explicit scheme:

(152) $\Delta z_{b} ^{i,j,n+1} =\Delta t\frac{MF}{\left(1-n_{p} \right)} \left(\left(\nabla \overrightarrow{S}_{s} \right)^{i,j,n} +\left(\nabla \overrightarrow{S}_{b} \right)^{i,j,n} \right)$

(153) $\Delta z_{b} ^{i,j,n+1} =\Delta t\frac{MF}{(1-n_{p} )} \left(Ero^{i,j,n} -Depo^{i,j,n} +\left(\nabla \overrightarrow{S}_{b} \right)^{i,j,n} \right)$

Avalanching¶

XBeach implements avalanching as described in section Avalanching. It first calculates bed level change due to avalanching in the cross-shore dimension. It then calculates the slopes in alongshore direction and bottom change due to avalanching in this direction. To avoid disrupted sediment balance XBeach does not calculate bottom change due to avalanching at the boundary grid cells. Consequently XBeach cannot calculate avalanching at the boundary between two MPI domains.

Bed composition¶

The bed is discretized into layers with mass $M(i,j)$ in which $i$ refers to the layer number and $j$ to the sediment class. The mass fraction per sediment class $p$ , layer thickness $\Delta$ and bed level ${z}_{b}$ are defined by:

(154) $\begin{array}{l} {p(i,j)=\frac{M(i,j)}{\sum _{j=1}^{J}M(i,j) } } \\ {\Delta (i)=\frac{1}{\left(1-n_{p} \right)\rho _{s} } \sum _{j=1}^{J}M(i,j) } \\ {z_{b} =z_{0} +\sum _{i=1}^{I}\Delta (i) } \end{array}$

with porosity ${n}_{p}$ and sediment density $\rho$ . The level ${z}_{0}$ is the lowest point of the array of bed layers.

Due to bed load transport, sediment is exchanged between the top layer and the four horizontally neighboring top layers. Exchange with the water column and the top layer is due to erosion rate $E$ and deposition rate $D$ . A mixed Eulerian/Lagrangian framework is proposed. Within the set of layers, one layer is defined as the variable layer. This is the only layer that has a variable total mass. All other layers have a constant total mass, which implies for a constant porosity a constant thickness. Above the variable layer, the layers move with the bed level (Lagrangian): upwards in case of aggradation and downwards in case of degradation. This vertical movement gives an advective flux with advection velocity equal to the bed level change $A=dz/dt$ . The variable layer is the transition to the lower layers, which are passive. The number of layers below the variable layer has thus no influence on the computation time. Note that diffusive processes within the bed are not considered yet. These could lead to fluxes between the layers below the variable layer.

The mass balance for the top layer can now be defined by:

(155) $\begin{array}{l} {\frac{\partial M(1,j)}{\partial t} =dy\left\{p(1,j)S_{b} (j)\right\}_{W} -dy\left\{p(1,j)S_{b} (j)\right\}_{E} } \\ {\quad \quad \quad \quad dx\left\{p(1,j)S_{b} (j)\right\}_{S} -dx\left\{p(1,j)S_{b} (j)\right\}_{N} } \\ {\quad \quad \quad \quad -dxdyp(1,j)E(j)+dxdyD(j)+dxdy\delta Ap_{bot} (1,j)} \\ {} \\ {A=\sum _{j=1}^{J}\left\{\begin{array}{l} {dy\left\{p(1,j)S_{b} (j)\right\}_{W} -dy\left\{p(1,j)S_{b} (j)\right\}_{E} } \\ {\quad \quad dx\left\{p(1,j)S_{b} (j)\right\}_{S} -dx\left\{p(1,j)S_{b} (j)\right\}_{N} } \\ {\quad \quad -dxdyp(1,j)E(j)+dxdyD(j)} \end{array}\right\} } \end{array}$

in which ${S}_{b}$ is the bed-load transport (e.g. Meyer-Peter-Muller), based on the sediment properties of the specific class. The dimensions of the grid cell are defined by $dx$ and $dy$ . The subscripts W, E, S and N refer to West, East, South and North indicating the four vertical faces of the bed cell. The horizontal faces are indicated with bot for the bottom of the cell and ceil for the ceiling of the cell. As the fraction p is not defined at the faces but in the cell centers, the upstream fraction is required. For the bed load fluxes, the velocity direction used. For the vertical advection term, the upstream value is based on the bed level variation: in case of aggradation the value in the top layer is used and in case of degradation the value of the second layer is used. If the top layer is the variable layer, there is no advective flux: $\delta=0$ otherwise $\delta=1$ .

The mass balance for the layers in between the top layer and the variable layer is:

(156) $\frac{\partial M(i,j)}{\partial t} =dxdyA\left(p_{bot} (i,j)-p_{ceil} (i,j)\right)$

and for the variable layer, it reads:

(157) $\frac{\partial M(i,j)}{\partial t} =Ap_{ceil} (i,j)$

In order to avoid too thin a or too thick a variable layer, the variable layer is merged or split. If the thickness is smaller than the critical value $\Delta_{merge}$ , the variable layer is merged with the lower layer. To keep the same number of cells, a cell is added at the bottom of the array, implying that ${z}_{0} = z_{0} - \Delta$ . Similarly, the variable is split into two layers if the critical value $\Delta_{split}$ is exceeded. Then, the array is shifted upwards: ${z}_{0} = z_{0} + \Delta$ .

As the bed level update is explicit, the timestep is limited. A conservative estimate can be made by assuming that no more mass can be eroded than available in the top layer:

(158) $\begin{array}{l} {dy\left\{p(1,j)S_{b} (j)\right\}_{W/E} +dx\left\{p(1,j)S_{b} (j)\right\}_{S/N} +dxdyp(1,j)E(j)<\frac{M(1,j)}{dt} } \\ {dt<\frac{dxdy\left(1-n_{p} \right)\rho _{s} \Delta (1)}{dyS_{b,W/E} (1)+dyS_{b,N/S} (1)+dxdyE(1)} } \end{array}$

The transport rate depends on the direction of the transport. The transport rates and erosion rates should be based on the formulation for the smallest fraction: $j=1$ . Note that the fraction p falls out. This time step restriction is less severe than the one for shallow water flow. Only in case of very top layers and/or the use of a morphological factor, this time step restriction might be relevant.

Boundary conditions¶

At the start of the XBeach simulation, XBeach checks whether non-stationary varying wave boundary conditions are to be used. If this is the case, it next checks whether the wave spectrum of the wave boundary conditions is to change over time, or remain constant. If the wave spectrum is to remain constant, XBeach will only read from one input file to generate wave boundary conditions. If the wave spectrum is to vary in time, XBeach reads from multiple files.

Whether or not the wave spectrum of the boundary conditions changes over time, the XBeach module requires a record length during which the current wave spectral parameters are applied. For the duration of the record length, boundary conditions are calculated at every boundary condition file time step. These time steps are not required to be the same as the time steps in the XBeach main program; XBeach will interpolate where necessary. The boundary condition time steps should therefore only be small enough to accurately describe the incoming bound long waves. The statistical data for the generation of the wave boundary conditions is read from user-specified files. The XBeach module tapers the beginning and end of the boundary condition file. This is done to ensure smooth transitions from one boundary condition file to the next.

The combination of a large record length and a small time step lead to large demands on the system memory. If the memory requirement is too large XBeach will shut down. The user must choose to either enlarge the boundary condition time step, or to reduce the record length. In case of the latter, several boundary condition files can be generated and read sequentially. It is unwise however to reduce the record length too much, as then the transitions between the boundary condition files may affect the model results.

Every time the XBeach wave boundary condition module is run, it outputs data to the local directory. Metadata about the wave boundary conditions are stored in list files: ebcflist.bcf and qbcflist.bcf. The main XBeach program uses the list files to know how and when to read and generate boundary condition files. The actual incoming short-wave energy and long-wave mass flux data is stored in other files. These files have E_ and q_ prefixes. The main XBeach program uses these files for the actual forcing along the offshore edge.

Non-hydrostatic¶

Global continuity equation¶

As was outlined in the previous chapter the global continuity equation, which describes the relation between the free surface and the depth averaged discharge, is given by

(159) $\frac{\partial \eta }{\partial t} +\frac{\partial }{\partial x} \left(UH\right)+\frac{\partial }{\partial x} \left(VH\right)=0$

A simple semi-discretisation of using central differences for the space derivative and using the Hansen scheme for the coupling between velocity and free surface results in

(160) $\frac{\eta_{i,j}^{\*} - \eta_{i,j}^{n}}{\Delta t} + \frac{{}^{x} q_{i+{\tfrac{1}{2}},j}^{\*} - {}^{x} q_{i-{\tfrac{1}{2}},j}^{\*}}{\Delta x} + \frac{{}^{y} q_{i,j+{\tfrac{1}{2}}}^{\*} - {}^{y} q_{i,j-{\tfrac{1}{2}}}^{\*}}{\Delta y} = 0$

With ${}^{x} q_{i+{\tfrac{1}{2}} ,j}^{\*} = H_{i+{\tfrac{1}{2}} ,j}^{n} U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ , ${}^{y} q_{i,j+{\tfrac{1}{2}} }^{\*} =H_{i,j+{\tfrac{1}{2}} }^{n} V_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} }$ and the water depth is defined by a first order accurate upwind interpolation

(161) $H_{i+{\tfrac{1}{2}} ,j}^{n} =\left\{\begin{array}{c} {\zeta _{i,j}^{n} +d_{i,j} {\; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; }if{\; }U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } >0} \\ {\zeta _{i+1,j}^{n} +d_{i+1,j} {\; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; \; }if{\; }U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } <0} \\ {\max \left(\zeta _{i,j}^{n} ,\zeta _{i+1,j}^{n} \right)+\min \left(d_{i} ,d_{i+1,j} \right){\; }if{\; }U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } =0} \end{array}\right. {\; }$

The resulting scheme is only first order accurate by virtue of the upwind interpolations and mass conservative. When first order computations are considered accurate enough $\eta_{i,j}^{n+1}$ is set to $\eta_{i,j}^{n\*}$ . For higher order accuracy the first order prediction is corrected using a limited version of the McCormack scheme. The corrector step reads

(162) $\frac{\eta _{i,j}^{n+1} -\eta _{i,j}^{*} }{\Delta t} +\frac{{}^{x} \Delta q_{i+{\tfrac{1}{2}} ,j}^{*} -{}^{x} \Delta q_{i-{\tfrac{1}{2}} ,j}^{*} }{\Delta x} +\frac{{}^{y} \Delta q_{i,j+{\tfrac{1}{2}} }^{*} -{}^{y} \Delta q_{i,j-{\tfrac{1}{2}} }^{*} }{\Delta y} =0$

With ${}^{x} \Delta q_{i+{\tfrac{1}{2}} ,j}^{n\*} = U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \Delta H_{i+{\tfrac{1}{2}} ,j}$ and $\Delta H_{i+{\tfrac{1}{2}} ,j}$ is given for positive flow as

(163) $\Delta H_{i+{\tfrac{1}{2}} ,j}^{n\*} ={\tfrac{1}{2}} \psi \left(^{\zeta } r_{i+{\tfrac{1}{2}} } \right)\left(\zeta _{i+1,j}^{n\*} -\zeta _{i,j}^{n} \right){\; \; \; \; \; \; \; \; \; \; }^{\zeta } {r}_{{i+}{\tfrac{{1}}{{2}}} } =\frac{\zeta _{i,j}^{n\*} -\zeta _{i-1,j}^{n} }{\zeta _{i+1,j}^{n\*} -\zeta _{i,j}^{n} } {\; \; \; \; \; \; \; \; \; \; }\psi \left(r\right)=\max \left(0,\min \left(r,1\right)\right)$

Here $\psi \left(r\right)$ denotes the minmod limiter. Similar expression can be constructed for negative flow. The expression for ${}^{y} \Delta q_{i,j+{\tfrac{1}{2}} }^{n\*}$ and $\Delta H_{i,j+{\tfrac{1}{2}} }$ are obtained in a similar manner. Note that the total flux ${}^{x} q_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ at the cell boundaries thus reads

(164) ${}^{x} q_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } ={}^{x} q_{i+{\tfrac{1}{2}} ,j}^{\*} +{}^{x} \Delta q_{i+{\tfrac{1}{2}} ,j}^{\*} {,\; \; \; \; }{}^{y} q_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } ={}^{y} q_{i,j+{\tfrac{1}{2}} }^{\*} +{}^{y} \Delta q_{i,j+{\tfrac{1}{2}} }^{\*} {\; }$

The predictor-corrector set is second order accurate in regions where the solution is smooth, and reduces locally to first order accuracy near discontinuities. Furthermore, the method remains mass conservative. Note that other flux limiters can be used instead of the minmod limiter. However, as the minmod limiter performed adequately, this has not been investigated. (for an overview of flux limiters see [Hir07])

Local continuity equation¶

The depth averaged local continuity equation is given by

(165) $\frac{\partial HU}{\partial x} +\frac{\partial HV}{\partial y} +\left. w\right|_{z=\eta } -\left. u\frac{\partial z}{\partial x} \right|_{z=-\zeta } -\left. v\frac{\partial z}{\partial y} \right|_{z=-\zeta } =0$

This equation is discretized using central differences

(166) $\frac{H_{i+{\tfrac{1}{2}} ,j}^{n+1} U_{i+{\tfrac{1}{2}} ,j}^{n+1{\tfrac{1}{2}} } -H_{i-{\tfrac{1}{2}} ,j}^{n+1} U_{i-{\tfrac{1}{2}} ,j}^{n+1{\tfrac{1}{2}} } }{\Delta x} +\frac{H_{i+{\tfrac{1}{2}} ,j}^{n+1} V_{i,j+{\tfrac{1}{2}} }^{n+1{\tfrac{1}{2}} } -H_{i,j-{\tfrac{1}{2}} }^{n+1} V_{i,j-{\tfrac{1}{2}} }^{n+1{\tfrac{1}{2}} } }{\Delta y} +w_{i,j,s}^{n+1{\tfrac{1}{2}} } -\bar{U}_{i,j}^{n+1{\tfrac{1}{2}} } \frac{\eta _{i+{\tfrac{1}{2}} ,j}^{n+1} -\eta _{i-{\tfrac{1}{2}} ,j}^{n+1} }{\Delta x} -\bar{V}_{i,j}^{n+1{\tfrac{1}{2}} } \frac{\eta _{i,j+{\tfrac{1}{2}} }^{n+1} -\eta _{i,j-{\tfrac{1}{2}} }^{n+1} }{\Delta x} =0$

Missing grid variables $\eta _{i+{\tfrac{1}{2}} ,j}^{n+1} ,\eta _{i,j+{\tfrac{1}{2}} }^{n+1}$ are approximated with upwind interpolation. Because there is no separate time evolution equation for the pressure the local continuity equation will be used to setup a discrete set of poison type equations in which the pressures are the only unknown quantities.

Horizontal Momentum¶

To obtain a conservative discretisation of the momentum equation the approach from [SZ03] is followed. However, to improve the accuracy of the method the combined space-time discretisation of the advection is done using a variant of the [Mac69] is used. This scheme consists of a first order predictor step and a flux limited corrector step. The hydrostatic pressure is integrated using the midpoint rule and central differences, while the source terms and the turbulent stresses are integrated using an explicit Euler time integration. Formally the time integration is therefore first order accurate, but in regions where the turbulent stresses are negligible the scheme is of almost second order accuracy.

The depth averaged horizontal momentum equation for $HU$ is given by

(167) $\frac{\partial }{\partial t} \left(HU\right)+\frac{\partial }{\partial x} \left(HU^{2} +{\tfrac{1}{2}} gH^{2} +H\bar{p}-\tau _{xx} \right)+\frac{\partial }{\partial y} \left(HUV-\tau _{yx} \right)=gH\frac{\partial d}{\partial x} -p\frac{\partial d}{\partial x} +S_{x}$

A first order accurate predictor step in time and space is then given as

(168) $\begin{array}{l} {\frac{\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{*} -\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\Delta t} +\frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } U_{i+1,j}^{n+{\tfrac{1}{2}} } -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } U_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x} +\frac{{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } U_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } -{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } U_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\Delta y} } \\ {+g\frac{\left(H^{2} \right)_{i+1,j}^{n+1} -\left(H^{2} \right)_{i,j}^{n+1} }{2\Delta x} =g\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n} \frac{d_{i+{\tfrac{1}{2}} ,j} -d_{i-{\tfrac{1}{2}} ,j} }{\Delta x} +{}^{x} {Pr}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } +{}^{x} {S}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } +{}^{x} {T}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } } \end{array}$

Here Pr represents a discretisation of the dynamic pressure; T the effect of (turbulent) viscosity and S includes all other source terms. The discretisation of the (turbulent) viscous terms is given by central differences:

(169) $\begin{array}{rcl} {{}^{x} T_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } } & {=} & {\frac{2}{\Delta x_{i+{\tfrac{1}{2}} } } \left[\nu _{i+1,j}^{n} H_{i+1,j}^{n+1} \frac{U_{i+1{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } -U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\Delta x_{i+1} } -\nu _{i,j}^{n} H_{i,j}^{n+1} \frac{U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } -U_{i-{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\Delta x_{i} } \right]} \\ {} & {} & {+\frac{1}{\Delta y_{i} } \left[\bar{\bar{\nu }}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \bar{\bar{H}}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \frac{U_{i+{\tfrac{1}{2}} ,j+1}^{n+1} -U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\Delta y_{i+{\tfrac{1}{2}} } } -\bar{\bar{\nu }}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \bar{\bar{H}}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+1} \frac{U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } -U_{i+{\tfrac{1}{2}} ,j-1}^{n+{\tfrac{1}{2}} } }{\Delta y_{i-{\tfrac{1}{2}} } } \right]} \\ {} & {} & {+\frac{1}{\Delta y_{i} } \left[\bar{\bar{\nu }}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \bar{\bar{H}}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \frac{V_{i+1,j+{\tfrac{1}{2}} }^{n+1} -V_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\Delta x_{i+{\tfrac{1}{2}} } } -\bar{\bar{\nu }}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \bar{\bar{H}}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+1} \frac{V_{i+1,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } -V_{i,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\Delta x_{i+{\tfrac{1}{2}} } } \right]} \end{array}$

Here $\bar{\bar{\nu }}_{i+{\tfrac{1}{2}} ,j+1}^{n+{\tfrac{1}{2}} }$ and $\bar{\bar{H}}_{i+{\tfrac{1}{2}} ,j+1{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} }$ are obtained from the surrounding points by simple linear interpolation.

Due to the incompressible flow assumption the dynamic pressure does not have a separate time evolution equation, but instead it satisfies an elliptical equation in space. As such its effect cannot be calculated explicitly using values at the previous time level. However to improve the accuracy of the predictor step the effect of the dynamic pressure is included explicitly. To do this first the unknown pressure is decomposed as:

(170) $p_{i,j}^{n+1{\tfrac{1}{2}} } =p_{i,j}^{n+{\tfrac{1}{2}} } +\Delta p_{i,j}^{n+1{\tfrac{1}{2}} }$

where the difference in pressure $\Delta p_{i,j}^{n+1{\tfrac{1}{2}} }$ is generally small. In the predictor step the effect of the pressure is included explicitly using $p_{i,j}^{n+{\tfrac{1}{2}} }$ . In the corrector step the full Poisson equation is then solved for $\Delta p_{i,j}^{n+1{\tfrac{1}{2}} }$ . The pressure term in the predictor step is thus given as

(171) ${}^{{x}} {Pr}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } {=}\frac{H_{i+1,j}^{n+1} \bar{p}_{i+1,j}^{n+{\tfrac{1}{2}} } -H_{i,j}^{n+1} \bar{p}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x} -p_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \frac{d_{i+{\tfrac{1}{2}} ,j} -d_{i-{\tfrac{1}{2}} ,j} }{\Delta x} =\frac{\left(\eta _{i+1,j}^{n+1} +d_{i,j}^{n+1} \right)p_{i+1,j}^{n+{\tfrac{1}{2}} } -\left(\eta _{i,j}^{n+1} -d_{i+1,j}^{n+1} \right)p_{i,j}^{n+{\tfrac{1}{2}} } }{2\Delta x}$

Here $\bar{p}_{i+1,j}^{n+{\tfrac{1}{2}} }$ represents the average pressure over the vertical which is approximated with $\bar{p}_{i+1,j}^{n+{\tfrac{1}{2}} } ={\tfrac{1}{2}} p_{i+1,j}^{n+{\tfrac{1}{2}} }$ , in which $p_{i+1,j}^{n+{\tfrac{1}{2}} }$ is the pressure at the bottom. Furthermore $p_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ is given as $p_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } ={\tfrac{1}{2}} \left(p_{i+1,j}^{n+{\tfrac{1}{2}} } +p_{i,j}^{n+{\tfrac{1}{2}} } \right)$ .

Currently is formulated with the depth integrated momentum as the primitive variable, and not the depth averaged velocity. To reformulate in terms of $U$ we use the method by [SZ03]. First note that $\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ and $\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{\*}$ are approximated as $\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n} U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ and $\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} U_{i+{\tfrac{1}{2}} ,j}^{\*}$ . Now using $\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ is equivalent to:

(172) $\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } =\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } -U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \Delta t\frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x} -U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \Delta t\frac{{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } -{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\Delta y}$

(173) $\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} ={\tfrac{1}{2}} \left(H_{i+1,j}^{n+1} +H_{i,j}^{n+1} \right){,\; \; }{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } ={\tfrac{1}{2}} \left({}^{x} q_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } +{}^{x} q_{i-{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \right){,\; \; \; }{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } ={\tfrac{1}{2}} \left({}^{y} q_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } +{}^{y} q_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \right)$

Substituting into the full expressions (including those for $V_{i,j+{\tfrac{1}{2}} }^{\*}$ ) become:

(174) $\begin{array}{r} {\frac{U_{i+{\tfrac{1}{2}} ,j}^{*} -U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\Delta t} +\frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } U_{i+1,j}^{n+{\tfrac{1}{2}} } -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } U_{i,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} \Delta x} +\frac{{}^{y} \bar{q}_{i,j+1}^{n+{\tfrac{1}{2}} } U_{i,j+1}^{n+{\tfrac{1}{2}} } -{}^{y} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } U_{i,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} \Delta y} -\frac{U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} } \frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x} } \\ {-\frac{U_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} } \frac{{}^{y} \bar{q}_{i,j+1}^{n+{\tfrac{1}{2}} } -{}^{y} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta y} +g\frac{\eta _{i+1,j}^{n+1} -\eta _{i,j}^{n+1} }{\Delta x} =\frac{^{{x}} {Pr}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } +{}^{x} {S}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } +{}^{x} {T}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} } } \\ {\frac{V_{i,j+{\tfrac{1}{2}} }^{*} -V_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\Delta t} +\frac{{}^{y} \bar{q}_{i,j+1}^{n+{\tfrac{1}{2}} } V_{i,j+1}^{n+{\tfrac{1}{2}} } -{}^{y} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } V_{i,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} \Delta y} +\frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } V_{i+1,j}^{n+{\tfrac{1}{2}} } -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } V_{i,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} \Delta x} -\frac{V_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} } \frac{{}^{y} \bar{q}_{i,j+1}^{n+{\tfrac{1}{2}} } -{}^{y} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta y} } \\ {\frac{V_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} } \frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x} +g\frac{\eta _{i,j+1}^{n+1} -\eta _{i,j}^{n+1} }{\Delta x} =\frac{{}^{y} {Pr}_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } +{}^{y} {S}_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } +{}^{y} {T}_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} } } \end{array}$

Where we again use a first order upwind interpolation for $U_{i+1,j}^{n+{\tfrac{1}{2}} }$ and $U_{i,j+1}^{n+{\tfrac{1}{2}} }$ . This is exactly the approximation used by [SZ03] and is fully momentum conservative.

The predictor step is first order accurate in both space and time due to the use of upwind approximations for and Euler explicit time integration for the advective terms, and first order time integration for the source/viscous terms. This level of accuracy is acceptable near shore, where strong non-linearity (wave breaking, flooding and drying) will force the use of small steps in space and time anyway. However, in the region where waves only slowly change (e.g. shoaling/refraction on mild slopes), the first order approximations suffer from significant numerical damping. To improve the accuracy of the numerical model in these regions a corrector step is implemented after the predictor step.

The corrector step is given by:

(175) $\begin{array}{l} {\frac{\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{n+1{\tfrac{1}{2}} } -\left(HU\right)_{i+{\tfrac{1}{2}} ,j}^{n*} }{\Delta t} +\frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } \Delta U_{i+1,j}^{} -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } \Delta U_{i,j}^{} }{\Delta x} +\frac{{}^{y} \bar{q}_{i,j+1}^{n+{\tfrac{1}{2}} } \Delta U_{i,j+1}^{} -{}^{y} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } \Delta U_{i,j}^{} }{\Delta y} +} \\ {\frac{\left(\eta _{i+1,j}^{n+1} +d_{i,j}^{n+1} \right)\Delta p_{i+1,j}^{n+1{\tfrac{1}{2}} } -\left(\eta _{i,j}^{n+1} -d_{i+1,j}^{n+1} \right)\Delta p_{i,j}^{n+1{\tfrac{1}{2}} } }{2\Delta x} =0} \end{array}$

Or, when formulated in terms of the depth averaged velocity

(176) $\begin{array}{r} {\frac{U_{i+{\tfrac{1}{2}} ,j}^{n+1{\tfrac{1}{2}} } -U_{i+{\tfrac{1}{2}} ,j}^{n*} }{\Delta t} +\frac{{}^{x} \bar{q}_{i+1,j}^{n+{\tfrac{1}{2}} } \Delta U_{i+1,j}^{} -{}^{x} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } \Delta U_{i,j}^{n*} }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} \Delta x} +\frac{{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \Delta U_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{} -{}^{y} \bar{q}_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \Delta U_{i+{\tfrac{1}{2}} ,j-{\tfrac{1}{2}} }^{} }{\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} \Delta y} +...} \\ {...+\frac{\left(\eta _{i+1,j}^{n+1} +d_{i,j}^{n+1} \right)\Delta p_{i+1,j}^{n+1{\tfrac{1}{2}} } -\left(\eta _{i,j}^{n+1} -d_{i+1,j}^{n+1} \right)\Delta p_{i,j}^{n+1{\tfrac{1}{2}} } }{2\bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} \Delta x} =0} \\ {\frac{V_{i,j+{\tfrac{1}{2}} }^{n+1{\tfrac{1}{2}} } -V_{i,j+{\tfrac{1}{2}} }^{n*} }{\Delta t} +\frac{{}^{y} \bar{q}_{i,j+1}^{n+{\tfrac{1}{2}} } \Delta V_{i,j+1}^{} -{}^{y} \bar{q}_{i,j}^{n+{\tfrac{1}{2}} } \Delta V_{i,j}^{} }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} \Delta y} +\frac{{}^{x} \bar{q}_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \Delta V_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{} -{}^{y} \bar{q}_{i-{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \Delta V_{i-{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }^{} }{\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} \Delta y} +...} \\ {...+\frac{\left(\eta _{i,j+1}^{n+1} +d_{i,j}^{n+1} \right)\Delta p_{i,j+1}^{n+1{\tfrac{1}{2}} } -\left(\eta _{i,j}^{n+1} -d_{i,j+1}^{n+1} \right)\Delta p_{i,j}^{n+1{\tfrac{1}{2}} } }{2\bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} \Delta x} =0} \end{array}$

The values of $\Delta U_{i+1,j}^{n\*}$ are obtained from slope limited expressions. For positive flow these read:

(177) $\Delta U_{i,j}^{n*} ={\tfrac{1}{2}} \psi \left(^{{u}} {r}_{{i+}{\tfrac{{1}}{{2}}} }^{} \right)\left(U_{i+{\tfrac{1}{2}} ,j}^{*} -U_{i-{\tfrac{1}{2}} ,j}^{n} \right){\; \; \; \; \; }^{{u}} {r}_{{i+}{\tfrac{{1}}{{2}}} }^{} =\frac{U_{i-{\tfrac{1}{2}} ,j}^{*} -U_{i-1{\tfrac{1}{2}} ,j}^{n} }{U_{i+{\tfrac{1}{2}} ,j}^{*} -U_{i-{\tfrac{1}{2}} ,j}^{n} } {\; \; \; \; \; \; \; \; if\; q}_{{i},j}^{{n+}{\tfrac{{1}}{{2}}} } >0$

Where $\psi$ again denotes the minmod limiter. Similar expressions can be constructed for $\Delta U_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }$ , $\Delta V_{i,j}$ and $\Delta V_{i+{\tfrac{1}{2}} ,j+{\tfrac{1}{2}} }$ .

The predictor-corrector set is second order accurate in regions where the solution is smooth, and reduces to first order accuracy near sharp gradients in the solutions to avoid unwanted oscillations. Furthermore, the method remains momentum conservative.

Vertical momentum equations¶

The vertical momentum equation is discretized in a similar manner to the horizontal momentum equations using the McCormack scheme. In terms of the depth averaged vertical velocity the predictor step is:

(178) $\begin{array}{r} {\frac{\bar{W}_{i,j}^{*} -\bar{W}_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta t} +\frac{{}^{x} q_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \bar{W}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } -{}^{x} q_{i-{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \bar{W}_{i-{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{H_{i,j}^{n+1} \Delta x} -\frac{\bar{W}_{i,j}^{n+{\tfrac{1}{2}} } }{H_{i,j}^{n+1} } \frac{{}^{x} q_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } -{}^{x} q_{i-{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } }{\Delta x} +\frac{{}^{y} q_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \bar{W}_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } -{}^{y} q_{i,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \bar{W}_{i,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{H_{i,j}^{n+1} \Delta y} } \\ {-\frac{\bar{W}_{i,j}^{n+{\tfrac{1}{2}} } }{H_{i,j}^{n+1} } \frac{{}^{y} q_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } -{}^{y} q_{i,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } }{\Delta y} +\frac{p_{i,j,1}^{n+{\tfrac{1}{2}} } -p_{i,j,0}^{n+{\tfrac{1}{2}} } }{H_{i,j}^{n+1} } =\frac{{}^{w} {S}_{i,j}^{n+{\tfrac{1}{2}} } +{}^{w} {T}_{i,j}^{n+{\tfrac{1}{2}} } }{H_{i,j}^{n+1} } } \end{array}$

The pressures are defined on the cell faces and therefore do not have to be interpolated. Furthermore, we can exactly set the dynamic pressure at the free surface $p_{i,j,1}^{n+{\tfrac{1}{2}} }$ to zero. The vertical velocities are defined on the cell faces and therefore the depth averaged velocity $\bar{W}_{i,j}^{n+{\tfrac{1}{2}} }$ needs to be expressed in terms of the bottom and surface velocities. Using a simple central approximation gives

(179) $\bar{W}_{i,j}^{n+{\tfrac{1}{2}} } ={\tfrac{1}{2}} \left(w_{i,j,1}^{n+{\tfrac{1}{2}} } +w_{i,j,0}^{n+{\tfrac{1}{2}} } \right),{\; \; \; \; \; \; }\bar{W}_{i,j}^{*} ={\tfrac{1}{2}} \left(w_{i,j,1}^{*} +w_{i,j,0}^{*} \right)$

At the bottom the kinematic boundary condition is used for the vertical velocity:

(180) $w_{i,j,0}^{*} ={\tfrac{1}{2}} \left(U_{i+{\tfrac{1}{2}} ,j}^{*} +U_{i-{\tfrac{1}{2}} ,j}^{*} \right)\frac{d_{i+{\tfrac{1}{2}} ,j} -d_{i-{\tfrac{1}{2}} ,j} }{\Delta x_{i} } +{\tfrac{1}{2}} \left(V_{i,j+{\tfrac{1}{2}} }^{*} +V_{i,j-{\tfrac{1}{2}} }^{*} \right)\frac{d_{i,j+{\tfrac{1}{2}} } -d_{i,j-{\tfrac{1}{2}} } }{\Delta x_{j} }$

Horizontal interpolation of $\bar{W}_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} }$ and $\bar{W}_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} }$ is done using first order upwind similar to . The turbulent stresses are again approximated using a central scheme as

(181) $\begin{array}{rcl} {{}^{w} T_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } } & {=} & {\frac{1}{\Delta x_{i} } \left[{}^{x} \bar{\nu }_{i+{\tfrac{1}{2}} ,j}^{n} {}^{x} \bar{H}_{i+{\tfrac{1}{2}} ,j}^{n+1} \frac{W_{i+1,j}^{n+{\tfrac{1}{2}} } -W_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x_{i+{\tfrac{1}{2}} } } -{}^{x} \bar{\nu }_{i-{\tfrac{1}{2}} ,j}^{n} {}^{x} \bar{H}_{i-{\tfrac{1}{2}} ,j}^{n+1} \frac{W_{i,j}^{n+{\tfrac{1}{2}} } -W_{i-1,j}^{n+{\tfrac{1}{2}} } }{\Delta x_{i+{\tfrac{1}{2}} } } \right]} \\ {} & {} & {+\frac{1}{\Delta y_{i} } \left[{}^{y} \bar{\nu }_{i,j+{\tfrac{1}{2}} }^{n} {}^{y} \bar{H}_{i,j+{\tfrac{1}{2}} }^{n+1} \frac{W_{i,j+1}^{n+{\tfrac{1}{2}} } -W_{i,j}^{n+{\tfrac{1}{2}} } }{\Delta x_{j+{\tfrac{1}{2}} } } -{}^{y} \bar{\nu }_{i,j-{\tfrac{1}{2}} }^{n} {}^{y} \bar{H}_{i,j-{\tfrac{1}{2}} }^{n+1} \frac{W_{i,j}^{n+{\tfrac{1}{2}} } -W_{i,j-1}^{n+{\tfrac{1}{2}} } }{\Delta y_{j+{\tfrac{1}{2}} } } \right]} \end{array}$

Thus combining, and explicit expressions for $w_{i,j,1}^{\*}$ and $w_{i,j,0}^{\*}$ are obtained.

The predicted values are again corrected using a variant of the McCormack scheme and including the pressure difference implicitly gives the corrector step:

(182) $\frac{\bar{W}_{i,j}^{n+1{\tfrac{1}{2}} } -\bar{W}_{i,j,1}^{*} }{\Delta t} +\frac{{}^{x} q_{i+{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \Delta \bar{W}_{i+{\tfrac{1}{2}} ,j}^{} -{}^{x} q_{i-{\tfrac{1}{2}} ,j}^{n+{\tfrac{1}{2}} } \Delta \bar{W}_{i-{\tfrac{1}{2}} ,j}^{} }{H_{i,j}^{n+1} \Delta x} +\frac{{}^{y} q_{i,j+{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \Delta \bar{W}_{i,j+{\tfrac{1}{2}} }^{} -{}^{y} q_{i,j-{\tfrac{1}{2}} }^{n+{\tfrac{1}{2}} } \Delta \bar{W}_{i,j-{\tfrac{1}{2}} }^{} }{H_{i,j}^{n+1} \Delta y} -\frac{\Delta p_{i,j}^{n+1{\tfrac{1}{2}} } }{H_{i,j}^{n+1} } =0$

Where $\Delta \bar{W}_{i+{\tfrac{1}{2}} ,j}$ and $\Delta \bar{W}_{i,j+{\tfrac{1}{2}} }$ are obtained using relations similar to . Note that similar to $\bar{W}_{i,j}^{n+1{\tfrac{1}{2}} } ={\tfrac{1}{2}} \left(w_{i,j.1}^{n+1{\tfrac{1}{2}} } +w_{i,j,0}^{n+1{\tfrac{1}{2}} } \right)$ and again the kinematic boundary conditions is substituted for $w_{i,j,0}^{n+1{\tfrac{1}{2}} }$ .

The discrete vertical momentum balance of and looks very different from the relations found in [ZS05], [ZS08] and [Smi08]. This is mainly due to the application of the McCormack scheme for the advection. The discretisation of the pressure term is numerically fully equivalent to either the Keller box scheme as used in [ZS05], [ZS08] or the Hermetian relation used in [Smi08].

Bibliography

[Ahr00]

J. Ahrens. A fall velocity equation. Journal of Waterway, Port, Coastal and Ocean engineering, 126(2):99:102, 2000.

[AM78]

D. G. Andrews and M. E. Mcintyre. An exact theory of nonlinear waves on a Lagrangian-mean flow. Journal of Fluid Mechanics, 89:609, 1978. doi:10.1017/S0022112078002773.

[BHBvW98]

(1, 2) T.E. Baldock, P. Holmes, S. Bunker, and P. van Weert. Cross-shore hydrodynamics within an unsaturated surfzone. Coastal Engineering, 34:173–196, 1998.

[Bat75]

J. A. Battjes. Modelling of turbulence in the surfzone. Symposium on Modelling Techniques, San Francisco,, pages 1050–1061, 1975.

[BW76]

Richard M. Beam and R. F. Warming. An implicit finite-difference algorithm for hyperbolic systems in conservation-law form. Journal of Computational Physics, 22(1):87–110, 1976. doi:10.1016/0021-9991(76)90110-8.

[DKH84]

R.A Dalrymple, J.T. Kirby, and P.A Hwang. Wave diffraction due to areas of energy dissipation. Journal of Waterway, Port, Coastal and Ocean Engineering, pages 67–79, 1984.

[DRvD+10]

Christopher Daly, J. A. Roelvink, A. R. van Dongeren, J. S. M. Van Thiel de Vries, and R. T. McCall. Short wave breaking effects on low frequency waves. Proceedings 32th International Conference on Coastal Engineering, pages 1–13, 2010.

[DRvD+12]

Christopher Daly, J. A. Roelvink, A. R. van Dongeren, J. S. M. van Thiel de Vries, and R. T. McCall. Validation of an advective-deterministic approach to short wave breaking in a surf-beat model. Coastal Engineering, 60:69–83, February 2012. URL: http://linkinghub.elsevier.com/retrieve/pii/S0378383911001517, doi:10.1016/j.coastaleng.2011.08.001.

[Dar56]

H. Darcy. Les fontaines publiques de la ville de dijon. Tech. Rep., Dalmont, Paris, 1856.

[dJRB13]

M. P. C. de Jong, J. A. Roelvink, and C. Breederveld. Numerical modelling of passing-ship effects in complex geometries and on shallow water. Pianc Smart Rivers 2013, 2013.

[dV14]

(1, 2) P. L. M. de Vet. Modelling sediment transport and morphology during overwash and breaching events. Technical Report, Delft University of Technology, Delft, 2014.

[Dei93]

R. Deigaard. A note on the three-dimensional shear stress distribution in a surf zone. Coastal Engineering, 20:157–171, 1993. doi:10.1016/0378-3839(93)90059-H.

[Del11]

Deltares. Delft3D-FLOW: user manual. Technical Report, Version 3.15. Revision: 14499, 2011.

[dA87]

H den Adel. Heranalyse doorlatendheidsmetingen door middel van de forchheimer relatie. Technical Report M 1795/H 195, CO 272550/56, Grondmechanica Delft, Waterloopkundig Laboratorium. Dutch., 1987.

[GV83]

R. Galappatti and C. B. Vreugdenhill. A depth integrated model for suspended transport. Journal for Hydraulic Research, 23(4):359–377, 1983.

[GT85]

R. T. Guza and E. B. Thornton. Velocity moments in the nearshore. Coastal Engineering, 111(2):235–256, 1985.

[Hal00]

K. Halford. Simulation and interpretation of borehole flowmeter results under laminar and turbulent flow conditions. Proceedings of the Seventh International Symposium on Logging for Minerals and Geotechnical Applications, Golden, Colorado, The Minerals and Geotechnical Logging Society, pages 157–168, 2000.

[Hal81]

R.J. Hallermeier. Terminal settling velocity of commonly occurring sand grains. Sedimentology, 28:859–865, 1981.

[Har05]

A. W. Harbaugh. MODFLOW-2005 , The USGS Modular Ground-Water Model. U.S. Geological Survey Techniques and Methods, pages 253, 2005.

[Hir07]

C. Hirsch. Numerical computation of internal & external flows. New York, John Wiley & Sons., 2007.

[HBH89]

(1, 2, 3) L.H. Holthuijsen, N. Booij, and T.H.C. Herbers. A prediction model for stationary, short-crested waves in shallow water with ambient currents. Coastal Engineering, 13(1):23–54, May 1989. URL: http://linkinghub.elsevier.com/retrieve/pii/0378383989900318, doi:10.1016/0378-3839(89)90031-8.

[JB07]

T. T. Janssen and J. A. Battjes. A note on wave energy dissipation over steep beaches. Coastal Engineering, 54:711–716, 2007. doi:10.1016/j.coastaleng.2007.05.006.

[KM75]

(1, 2) P. D. Komar and M. C. Miller. On the comparison between the threshold of sediment motion under waves under unidirectional currents with a discussion of the practical evaluation of the threshold. Journal of Sedimentary Research, pages 362–367, 1975.

[LS76]

D. C. L. Lam and R. B. Simpson. Centered differencing and the box scheme for diffusion convection problems. Journal of Computational Physics, 22:486–500, 1976.

[LMHK07]

K. H. Lee, Norimi Mizutani, Dong S. Hur, and Atsushi Kamiya. The effect of groundwater on topographic changes in a gravel beach. Ocean Engineering, 34:605–615, 2007. doi:10.1016/j.oceaneng.2005.10.026.

[LB00]

L. Li and D. A. Barry. Wave-induced beach groundwater flow. Advances in Water Resources, 23:325–337, 2000. doi:10.1016/S0309-1708(99)00032-9.

[LHS62]

M. S. Longuet-Higgins and R. W. Stewart. Radiation stress and mass transport in gravity waves, with application to ‘surf beats’. Journal of Fluid Mechanics, 13:481–504, 1962.

[LHS64]

(1, 2, 3) M. S. Longuet-Higgins and R. W. Stewart. Radiation stress in water waves: a physical discussion with applications. Deep-Sea Research, pages 529–562, 1964.

[LHT74]

M. S. Longuet-Higgins and J. S. Turner. An ‘entraining plume’ model of a spilling breaker. Journal of Fluid Mechanics, 63(01):1–20, 1974.

[LFK+07]

R. J. Lowe, James L. Falter, Jeffrey R. Koseff, Stephen G. Monismith, and Marlin J. Atkinson. Spectral wave flow attenuation within submerged canopies: Implications for wave energy dissipation. Journal of Geophysical Research, 112:1–14, 2007. doi:10.1029/2006JC003605.

[Mac69]

R.W. MacCormack. The effect of viscosity in hypervelocity impact cratering. AIAA Hyper velocity Impact Conference. Paper 69-354., 1969.

[MMP+14]

(1, 2, 3) R. T. McCall, Gerhard Masselink, T. G. Poate, J. a. Roelvink, L. P. Almeida, M. Davidson, and P. E. Russell. Modelling storm hydrodynamics on gravel beaches with XBeach-G. Coastal Engineering, 91:231–250, 2014. URL: http://dx.doi.org/10.1016/j.coastaleng.2014.06.007, doi:10.1016/j.coastaleng.2014.06.007.

[ML04]

F. J. Mendez and I. J. Losada. An empirical model to estimate the propagation of random breaking and nonbreaking waves over vegetation fields. Coastal Engineering, 51:103–118, 2004. doi:10.1016/j.coastaleng.2003.11.003.

[NRS90]

(1, 2, 3, 4) R.B. Nairn, J. A. Roelvink, and H.N. Southgate. Transition zone width and implications for modeling surfzone hydrodynamics. Proceedings 22th International Conference on Coastal Engineering, pages 68–81, 1990. doi:10.9753/icce.v22.

[NLB+15]

(1, 2) C. M. Nederhoff, Q. J. Lodder, Marien Boers, J. P. Den Bieman, and J. K. Miller. Modeling the effects of hard structures on dune erosion and overwash - a case study of the impact of Hurricane Sandy on the New Jersey coast. Proceedings Coastal Sediments, San Diego, CA, 2015.

[Phi77]

(1, 2) O.M. Phillips. The dynamics of the upper ocean. Cambridge University Press, pages 366, 1977.

[RGE99]

B. Raubenheimer, R. T. Guza, and Steve Elgar. Tidal water table fluctuations in a sandy ocean beach. Water Resources Research, 35(8):2313, 1999. doi:10.1029/1999WR900105.

[RMTS07]

A. J. H. M. Reniers, J. H. MacMahan, E. B. Thornton, and T. P. Stanton. Modeling of very low frequency motions during RIPEX. Journal of Geophysical Research, 112(February):1–14, 2007. doi:10.1029/2005JC003122.

[RRT04]

A. J. H. M. Reniers, J. A. Roelvink, and E. B. Thornton. Morphodynamic modeling of an embayed beach under wave group forcing. Journal of Geophysical Research, 109:1–22, 2004. doi:10.1029/2002JC001586.

[RZ54]

J. Richardson and W. Zaki. Sedimentation and fluidisation - Part i. Trans. Inst. Chem. Eng., 32(1):35–53, 1954.

[RF81]

(1, 2) M. M. Rienecker and J. D. Fenton. A Fourier approximation method for steady water waves. Journal of Fluid Mechanics, 104:119, 1981. doi:10.1017/S0022112081002851.

[Roe93]

(1, 2, 3) J. A. Roelvink. Dissipation in random wave group incident on a beach. Coastal Engineering, 19:127–150, 1993.

[Roe06]

J. A. Roelvink. Coastal morphodynamic evolution techniques. Coastal Engineering, 53:277–287, 2006. doi:10.1016/j.coastaleng.2005.10.015.

[RRvD+09]

J. A. Roelvink, A. J. H. M Reniers, A. R. van Dongeren, J. S. M. van Thiel de Vries, R. T. McCall, and Jamie Lescinski. Modelling storm impacts on beaches, dunes and barrier islands. Coastal Engineering, 56(11-12):1133–1152, November 2009. URL: http://linkinghub.elsevier.com/retrieve/pii/S0378383909001252, doi:10.1016/j.coastaleng.2009.08.006.

[RS89]

(1, 2, 3) J. A. Roelvink and M. J. F. Stive. Bar-generating cross-shore flow mechanisms on a beach. Journal of Geophysical Research, 94:4785–4800, 1989.

[Row87]

P.N. Rowe. A convenient empirical equation for estimation of the richardson-zaki exponent. Chemical Engineering Science, 42(11):2795 – 2796, 1987.

[RMF+01]

B. G. Ruessink, J.R. Miles, F. Feddersen, R. T. Guza, and Steve Elgar. Modeling the alongshore current on barred beaches. Journal of Geophysical Research, 106(22):451–463, 2001.

[RRvR12]

(1, 2, 3, 4, 5) B. G. Ruessink, G. Ramaekers, and L. C. van Rijn. On the parameterization of the free-stream non-linear wave orbital motion in nearshore morphodynamic models. Coastal Engineering, 65:56–63, July 2012. URL: http://linkinghub.elsevier.com/retrieve/pii/S0378383912000488, doi:10.1016/j.coastaleng.2012.03.006.

[SHvdWT11]

M. Schroevers, B.J. Huisman, A. van der Wal, and J. Terwindt. Measuring ship induced waves and currents on a tidal flat in the Western Scheldt Estuary. Current, Waves and Turbulence Measurements (CWTM), 2011 IEEE/OES 10th, pages 123–129, 2011.

[Shi36]

(1, 2) A. Shields. Anwendung der Aehnlichkeitsmechanik under der Turbulenzforschung auf die Geschiebebewegung. Preussischen Versuchsanstalt fur Wasserbau and Schiffbau, 26:524–526, 1936.

[Sma63]

J. Smagorinsky. General circulation experiments wiht the primitive equations I. The basic experiment. Monthly Weather Review, 91:99–164, 1963. doi:10.1126/science.27.693.594.

[Smi08]

(1, 2) P. B. Smit. Non-hydrostatic modelling of large scale tsunamis. Technical Report, MSc thesis, Delft University of Technology, Delft, 2008.

[SJHS14]

(1, 2) P. B. Smit, T. T. Janssen, L.H. Holthuijsen, and Jane Smith. Non-hydrostatic modeling of surf zone wave dynamics. Coastal Engineering, 83:36–48, 2014. URL: http://dx.doi.org/10.1016/j.coastaleng.2013.09.005, doi:10.1016/j.coastaleng.2013.09.005.

[Sou97]

(1, 2, 3, 4, 5) R.L. Soulsby. Dynamics of Marine Sands. Thomas Telford Publications, London, 1997. ISBN 07272584X.

[SZ03]

(1, 2, 3, 4) G. S. Stelling and Marcel Zijlema. An accurate and efficient finite-difference algorithm for non-hydrostatic free-surface flow with application to wave propagation. International Journal for Numerical Methods in Fluids, 43(1):1–23, 2003.

[SDeVriend94]

(1, 2, 3) M. J. F. Stive and H. J. De Vriend. Shear stresses and mean flow in shoaling and breaking waves. Proceedings 24th International Conference on Coastal Engineering, pages 594–608, 1994. doi:10.9753/icce.v24.

[Sto68]

H.L. Stone. Iterative Solution of Implicit Approximations of Multidimensional Partial Differential Equations. Journal on Numerical Analysis, 5(3):530–658, 1968.

[SZB+12]

(1, 2) Tomohiro Suzuki, Marcel Zijlema, Bastiaan Burger, Martijn C. Meijer, and Siddharth Narayan. Wave dissipation by vegetation with layer schematization in SWAN. Coastal Engineering, 59(1):64–71, 2012. URL: http://dx.doi.org/10.1016/j.coastaleng.2011.07.006, doi:10.1016/j.coastaleng.2011.07.006.

[Sve84]

(1, 2, 3) I. A. Svendsen. Wave heights and set-up in a surf zone. Coastal Engineering, 8:303–329, 1984. doi:10.1016/0378-3839(84)90028-0.

[TvMS95]

A. M. Talmon, M. C. van Mierlo, and N. Struiksma. Laboratory measurements of the direction of sediment transport on transverse alluvial-bed slope. Journal of Hydraulic Research, 33(4):495–517, 1995.

[Tho49]

L. H. Thomas. Elliptic problems in linear difference equations over a network. Technical Report, Watson Sci. Comput. Lab., Columbia University, 1949.

[vB47]

L. van Bendegom. Enige beschouwingen over riviermorphologie en rivierverbetering. Technical Report, Ministerie van Verkeer en Waterstaat. Dutch., 1947.

[vdZ14]

J. van der Zwaag. Modelling sediment sorting near the large scale nourishment ’ The Sand Motor ’. Technical Report, Delft University of Technology, Delft, 2014.

[vDS97]

A. R. van Dongeren and I. A. Svendsen. An Absorbing-Generating Boundary condition for Shallow Water Models. J. of Waterways, Ports, Coastal and Ocean Engineering, vol. 123, no. 6, pp. 303-313. Journal of Waterways, Ports, Coastal and Ocean Engineering, 123(6):303–313, 1997.

[vR10]

(1, 2) C van Rhee. Sediment entrainment at high flow velocity. Journal of Hydraulic Engineering, 136:572–582, 2010.

[vR85]

L. C. van Rijn. Sediment transport, part III: bed forms and alluvial roughness. Journal of Hydraulic Engineering, 110(12):1733–1754, 1985.

[vR07]

(1, 2) L. C. van Rijn. Unified View of Sediment Transport by Currents and Waves: part I and II. Journal of Hydraulic Engineering, pages 649–667, 2007.

[vRVanTdVriesM+15]

(1, 2) A.A. van Rooijen, J. S. M. Van Thiel de Vries, R. T. McCall, A. R. van Dongeren, J. A. Roelvink, and A. J. H. M. Reniers. Modeling of wave attenuation by vegetation with XBeach. E-proceedings of the 36th IAHR World Congress 28 June – 3 July, 2015, The Hague, The Netherlands., 2015.

[VSO81]

G.K. Verboom, G. S. Stelling, and M.J. Officer. Boundary conditions for the shallow water equations. Engineering applications of computational hydraulics, pages 230–262., 1981.

[WRG00]

D. J. R. Walstra, J. A. Roelvink, and J. Groeneweg. Calculation of wave-driven currents in a 3D mean flow model. In Proceedings 27th International Conference on Coastal Engineering, 1050–1063. 2000.

[WvRVanOrmondt+07]

D. J. R. Walstra, L. C. van Rijn, Maarten Van Ormondt, C. Briere, and A. M. Talmon. The Effects of Bed Slope and Wave Skewness on Sediment Transport and Morphology. In Coastal Sediments ’07, 137–150. 2007.

[ZRVL13]

(1, 2) M. Zhou, J. A. Roelvink, H. J. Verheij, and H. Ligteringen. Study of Passing Ship Effects along a Bank by Delft3D-FLOW and XBeach. International Workshop on Nautical Traffic Models 2013, Delft, The Netherlands, July 5-7, 2013. Delft University of Technology, 2013.

[ZRZvW14]

M. Zhou, J. A. Roelvink, Z. Zou, and H. J. van Wijhe. Effects of Passing Ship With a Drift Angle on a Moored Ship. ASME 2014 33rd International Conference on Ocean, Offshore and Arctic Engineering, 2014.

[ZS05]

(1, 2) M. Zijlema and G. S. Stelling. Further experiences with computing non-hydrostatic free-surface flows involving water waves. INTERNATIONAL JOURNAL FOR NUMERICAL METHODS IN FLUIDS, pages 169–197, 2005.

[ZS08]

(1, 2) M. Zijlema and G. S. Stelling. Efficient computation of surf zone waves using the nonlinear shallow water equations with non-hydrostatic pressure. Coastal Engineering, 55(10):780–790, 2008.

[ZSS11]

(1, 2, 3, 4) Marcel Zijlema, G. S. Stelling, and P. B. Smit. SWASH: An operational public domain code for simulating wave fields and rapidly varied flows in coastal waters. Coastal Engineering, 58(10):992–1012, 2011. URL: http://dx.doi.org/10.1016/j.coastaleng.2011.05.015, doi:10.1016/j.coastaleng.2011.05.015.

[VanRijn84]

L. C. Van Rijn. Sediment transport, part II: suspended load transport. Journal of Hydraulic Engineering, 110:1613–1641, 1984.

[vanTdVries09]

(1, 2, 3, 4, 5, 6, 7) J. S. M. van Thiel de Vries. Dune erosion during storm surges. PhD thesis, PhD thesis, Delft Unversity of Technology, Delft, 2009.

Footnotes

[2]	Currently, this formulation is only possible when the wave shape formulation of [vanTdVries09] is applied, see Wave shape.

Input parameters¶

Overview of available keywords related to *¶
parameter	description	default	range	units
ARC+	Switch for active reflection compensation at seaward boundary	1	0 - 1
BRfac+	Calibration factor surface slope	1.0	0.0 - 1.0
CFL	Maximum courant-friedrichs-lewy number	0.7	0.1 - 0.9
Cd+	Wind drag coefficient	0.002	0.0001 - 0.01
Hrms	Hrms wave height for instat = stat, bichrom, ts_1 or ts_2	1.0	0.0 - 10.0	m
Tbfac+	Calibration factor for bore interval tbore: tbore = tbfac*tbore	1.0	0.0 - 1.0
Tlong	Wave group period for case instat = bichrom	80.0	20.0 - 300.0	s
Tm01switch+	Switch to enable tm01 rather than tm-10	0	0 - 1
Topt+	Absolute period to optimize coefficient	10.0	1.0 - 20.0	s
Trep	Representative wave period for instat = stat, bichrom, ts_1 or ts_2	10.0	1.0 - 20.0	s
Tsmin+	Minimum adaptation time scale in advection diffusion equation sediment	0.5	0.01 - 10.0	s
advection	Include advection in flow solver	1	0 - 1
alfa	Angle of x-axis from east	0.0	0.0 - 360.0	deg
alpha+	Wave dissipation coefficient in roelvink formulation	1.0	0.5 - 2.0
aquiferbot+	Level of uniform aquifer bottom	-10.0	-100.0 - 100.0	m
aquiferbotfile+	Name of the aquifer bottom file			<file>
avalanching	Turn on avalanching	1	0 - 1
back	Switch for boundary at bay side	abs_2d	wall, abs_1d, abs_2d, wlevel
bcfile	Name of spectrum file			<file>
bchwiz	Turn on beachwizard	0	0 - 1
bclwonly	Switch to run boundary conditions with long waves only	0	0 - 1
bdslpeffdir	Modify the direction of the sediment transport based on the bed slope	none	none, talmon
bdslpeffdirfac	Calibration factor in the modification of the direction	1.0	0.0 - 2.0
bdslpeffini	Modify the critical shields parameter based on the bed slope	none	none, total, bed
bdslpeffmag	Modify the magnitude of the sediment transport based on the bed slope, uses facsl	roelvink_total	none, roelvink_total, roelvink_bed, soulsby_total, soulsby_bed
bed+	Calibration factor for bed transports	1	0 - 1
bedfriccoef	Bed friction coefficient	0.01	3.5e-05 - 0.9
bedfricfile	Bed friction file (only valid with values of c)			<file>
bedfriction	Bed friction formulation	chezy	chezy, cf, white-colebrook, manning, white-colebrook-grainsize
bermslope	Swash zone slope for (semi-) reflective beaches	0.0	0.0 - 1.0
beta+	Breaker slope coefficient in roller model	0.1	0.05 - 0.3
betad+	Dissipation parameter long wave breaking turbulence	1.0	0.0 - 10.0
break	Type of breaker formulation	roelvink2	roelvink1, baldock, roelvink2, roelvink_daly, janssen
breakerdelay+	Switch to enable breaker delay model	1.0	0.0 - 3.0
breakviscfac+	Factor to increase viscosity during breaking	1.5	1.0 - 3.0
breakvisclen+	Ratio between local depth and length scale in extra breaking viscosity	1.0	0.75 - 3.0
bulk+	Switch to compute bulk transport rather than bed and suspended load separately	0	0 - 1
cats+	Current averaging time scale for wci, in terms of mean wave periods	4.0	1.0 - 50.0	Trep
ci+	Mass coefficient in shields inertia term	1.0	0.5 - 1.5
cm	Mass coefficient in shields inertia term	1.5	0.0 - 3.0
cmax+	Maximum allowed sediment concentration	0.1	0.0 - 1.0
compi	Imaginary unit	-123
correctHm0	Switch to enable hm0 correction	1	0 - 1
cyclic	Turn on cyclic boundary conditions	0	0 - 1
defuse	Turn on timestep explosion prevention mechanism	1	0 - 1
delta+	Fraction of wave height to add to water depth	0.0	0.0 - 1.0
deltar	Estimated ripple height	0.025	0.001 - 1.0
depfile*	Name of the input bathymetry file			<file>
depthscale+	Depthscale of (lab)test simulat, affects eps, hmin, hswitch and dzma	1.0	1.0 - 200.0
dilatancy	Switch to reduce critical shields number due dilatancy	0	0 - 1
dir0	Mean wave direction for instat = stat, bichrom, ts_1 or ts_2 (nautical convention)	270.0	-360.0 - 360.0	deg
disch_loc_file+	Name of discharge locations file			<file>
disch_timeseries_file+	Name of discharge timeseries file			<file>
dispc+	Coefficient in front of the vertical pressure gradient	-1.0	0.1 - 2.0	?
drifterfile	Name of drifter data file			<file>
dryslp	Critical avalanching slope above water (dz/dx and dz/dy)	1.0	0.1 - 2.0
dt	Computational time step, in hydrodynamic time	-123		s
dtbc+	Timestep used to describe time series of wave energy and long wave flux at offshore boundary (not affected by morfac)	1.0	0.1 - 2.0	s
dtheta*	Directional resolution	10.0	0.1 - 180.0	deg
dthetaS_XB+	The (counter-clockwise) angle in the degrees needed to rotate from the x-axis in swan to the x-axis pointing east	0.0	-360.0 - 360.0	deg
dtheta_s*	Directional resolution in case of stationary refraction	10.0	0.1 - 20.0	deg
dtset	Fixed timestep, overrides use of cfl	0.0	0.001 - 100.0
dwetlayer+	Thickness of the top soil layer interacting more freely with the surface water	0.1	0.01 - 1.0	m
dx*	Regular grid spacing in x-direction	-1.0	0.0 - 1000000000.0	m
dy*	Regular grid spacing in y-direction	-1.0	0.0 - 1000000000.0	m
dzg1+	Thickness of top sediment class layers	par%dzg1	0.01 - 1.0	m
dzg2+	Nominal thickness of variable sediment class layer	par%dzg1	0.01 - 1.0	m
dzg3+	Thickness of bottom sediment class layers	par%dzg1	0.01 - 1.0	m
dzmax+	Maximum bed level change due to avalanching	0.05	0.0 - 1.0	m/s/m
eps	Threshold water depth above which cells are considered wet	0.005	0.001 - 0.1	m
eps_sd	Threshold velocity difference to determine conservation of energy head versus momentum	0.5	0.0 - 1.0	m/s
epsi+	Ratio of mean current to time varying current through offshore boundary	-1.0	-1.0 - 0.2
facAs+	Calibration factor time averaged flows due to wave asymmetry	0.1	0.0 - 1.0
facDc+	Option to control sediment diffusion coefficient	1.0	0.0 - 1.0
facSk+	Calibration factor time averaged flows due to wave skewness	0.1	0.0 - 1.0
facrun	Calibration coefficient for short wave runup	1.0	0.0 - 2.0
facsd	Fraction of the local wave length to use for shoaling delay depth	1.0	0.0 - 2.0
facsl+	Factor bedslope effect	1.6	0.0 - 1.6
facua+	Calibration factor time averaged flows due to wave skewness and asymmetry	0.1	0.0 - 1.0
fallvelred	Switch to reduce fall velocity for high concentrations	0	0 - 1
fcutoff+	Low-freq cutoff frequency for instat = jons, swan or vardens boundary conditions	0.0	0.0 - 40.0	Hz
flow	Turn on flow calculation	1	0 - 1
form	Equilibrium sediment concentration formulation	vanthiel_vanrijn	soulsby_vanrijn, vanthiel_vanrijn, vanrijn1993
frac_dz+	Relative thickness to split time step for bed updating	0.7	0.5 - 0.98
freewave+	Switch for free wave propagation 0 = use cg (default); 1 = use sqrt(gh) in instat = ts_2	0	0 - 1
friction_acceleration	Turn on or off the effect of acceleration on bed roughness (morrison)	none	none, mccall, nielsen
friction_infiltration	Turn on or off the effect of infiltration on bed roughness (conley and inman)	0	0 - 1
friction_turbulence	Turn on or off the effect of turbulence on bed roughness (reniers van thiel)	0	0 - 1
front	Switch for seaward flow boundary	abs_2d	abs_1d, abs_2d, wall, wlevel, nonh_1d, waveflume
fwcutoff	Depth greater than which the bed friction factor is not applied	1000.0	0.0 - 1000.0
g	Gravitational acceleration	9.81	9.7 - 9.9	ms^-2
gamma	Breaker parameter in baldock or roelvink formulation	0.55	0.4 - 0.9
gamma2	End of breaking parameter in roelvink daly formulation	0.3	0.0 - 0.5
gamma_turb	Calibration factor for turbulence contribution to bed roughness	1.0	0.0 - 2.0
gammax+	Maximum ratio wave height to water depth	2.0	0.4 - 5.0
gridform	Grid definition format	xbeach	xbeach, delft3d
gw0+	Level initial groundwater level	0.0	-5.0 - 5.0	m
gw0file+	Name of initial groundwater level file			<file>
gwReturb+	Reynolds number for start of turbulent flow in case of gwscheme = turbulent	100.0	1.0 - 600.0
gwfastsolve	Reduce full 2d non-hydrostatic solution to quasi-explicit in longshore direction	0	0 - 1
gwflow+	Turn on groundwater flow	0	0 - 1
gwheadmodel+	Model to use for vertical groundwater head	parabolic	parabolic, exponential
gwhorinfil+	Switch to include horizontal infiltration from surface water to groundwater	0	0 - 1
gwnonh+	Switch to turn on or off non-hydrostatic pressure for groundwater	0	0 - 1
gwscheme+	Scheme for momentum equation	laminar	laminar, turbulent
hmin	Threshold water depth above which stokes drift is included	0.2	0.001 - 1.0	m
hotstartflow+	Switch for hotstart flow conditions with pressure gradient balanced by wind and bed stress	0	0 - 1
hswitch+	Water depth at which is switched from wetslp to dryslp	0.1	0.01 - 1.0	m
hwci+	Minimum depth until which wave-current interaction is used	0.1	0.001 - 1.0	m
hwcimax+	Maximum depth until which wave-current interaction is used	100.0	0.01 - 100.0	m
instat	Old wave boundary condition type	bichrom	stat, bichrom, ts_1, ts_2, jons, swan, vardens, reuse, ts_nonh, off, stat_table, jons_table
irhog8	^-1	-123		N^-1m^3
jetfac	Option to mimic turbulence production near revetments	0.0	0.0 - 1.0
kdmin+	Minimum value of kd (pi/dx > min(kd))	0.0	0.0 - 0.05
kmax	Number of sigma layers in quasi-3d model; kmax = 1 is without vertical structure of flow and suspensions	100	1 - 1000
kx+	Darcy-flow permeability coefficient in x-direction	0.0001	1e-05 - 0.1	ms^-1
ky+	Darcy-flow permeability coefficient in y-direction	0.0001	1e-05 - 0.1	ms^-1
kz+	Darcy-flow permeability coefficient in z-direction	0.0001	1e-05 - 0.1	ms^-1
lat+	Latitude at model location for computing coriolis	0.0	-90.0 - 90.0	deg
lateralwave	Switch for lateral boundary at left	neumann	neumann, wavecrest, cyclic
left	Switch for lateral boundary at ny+1	neumann	neumann, wall, no_advec, neumann_v, abs_1d
lsgrad	Factor to include longshore transport gradient in 1d simulationsdsy/dy=lsgrad*sy; dimension 1/length scale of longshore gradients	0.0	-0.1 - 0.1	1/m
lwave	Turn on short wave forcing on nlsw equations and boundary conditions	1	0 - 1
lws+	Switch to enable long wave stirring	1	0 - 1
lwt+	Switch to enable long wave turbulence	0	0 - 1
m	Power in cos^m directional distribution for instat = stat, bichrom, ts_1 or ts_2	10	2 - 128
maxbrsteep+	Maximum wave steepness criterium	0.4	0.3 - 0.8
maxdtfac	Maximum increase/decrease in time stp in explosion prevention mechanism	500.0	100.0 - 1000.0
maxerror+	Maximum wave height error in wave stationary iteration	0.0005	1e-05 - 0.001	m
maxiter+	Maximum number of iterations in wave stationary	500	2 - 1000
merge+	Merge threshold for variable sediment layer (ratio to nominal thickness)	0.01	0.005 - 0.1
mmpi+	Number of domains in cross-shore direction when manually specifying mpi domains	2	1 - 100
morfac	Morphological acceleration factor	1.0	0.0 - 1000.0
morfacopt+	Switch to adjusting output times for morfac	1	0 - 1
morphology	Turn on morphology	1	0 - 1
morstart	Start time morphology, in morphological time	0.0	0.0 - par%tstop	s
morstop	Stop time morphology, in morphological time	2000.0	0.0 - 10000000.0	s
mpiboundary+	Fix mpi boundaries along y-lines, x-lines, use manual defined domains or find shortest boundary automatically	auto	auto, x, y, man
n+	Power in roelvink dissipation model	10.0	5.0 - 20.0
nc	Smoothing distance for estimating umean (defined as nr of cells)	par%ny+1	1 - par%ny+1
ncfilename+	Xbeach netcdf output file name			<file>
nd+	Number of computational layers in the bed	3	3 - 1000
nd_var+	Index of layer with variable thickness	2	1 - par%nd
ndischarge+	Number of discharge locations	par%ndischarge	0 - 100
ndrifter	Number of drifers	par%ndrifter	0 - 50
ne_layer	Name of file containing thickness of the erodible layer			<file>
ngd	Number of sediment classes	1	1 - 20
nglobalvar	Number of global output variables (as specified by user)	-1	-1 - 20
nhbreaker+	Non-hydrostatic breaker model	2	0 - 2
nhlay+	Layer distribution in the nonhydrostatic model, default = 0.33	0.33	0.0 - 1.0
nmax+	Maximum ratio of cg/c for computing long wave boundary conditions	0.8	0.5 - 1.0
nmeanvar	Number of mean, min, max, var output variables	0	0 - 15
nmpi+	Number of domains in alongshore direction when manually specifying mpi domains	4	1 - 100
nonh+	Turn on non-hydrostatic pressure: 0 = nswe, 1 = nsw + non-hydrostatic pressure compensation stelling & zijlema, 2003	0	0 - 1
nonhq3d	Turn on or off the the reduced two-layer nonhydrostatic model, default = 0	0	0 - 1
nonhspectrum+	Spectrum format for wave action balance of nonhydrostatic waves	0	0 - 1
npoints	Number of output point locations	0	0 - 50
npointvar	Number of point output variables	0	0 - 50
nrugauge	Number of output runup gauge locations	0	0 - 50
nrugdepth+	Number of depths to compute runup in runup gauge	1	1 - 10
nsetbathy+	Number of prescribed bed updates	1	1 - 1000
nship+	Number of ships	-123
nspectrumloc+	Number of input spectrum locations	1	1 - par%ny+1
nspr	Switch to enable long wave direction forced into centres of short wave bins	0	0 - 1
ntdischarge+	Length of discharge time series	par%ntdischarge	0 - 100
nuh	Horizontal background viscosity	0.1	0.0 - 1.0	m^2s^-1
nuhfac+	Viscosity switch for roller induced turbulent horizontal viscosity	1.0	0.0 - 1.0
nuhv	Longshore viscosity enhancement factor, following svendsen (?)	1.0	1.0 - 20.0
nveg	Number of vegetation species	-123
nx*	Number of computational cell corners in x-direction	50	2 - 10000
ny*	Number of computational cell corners in y-direction	2	0 - 10000
nz	Number of computational cells in z-direction	1	1 - 100
oldhu	Switch to enable old hu calculation	0	0 - 1
order+	Switch for order of wave steering,first order wave steering (short wave energy only), second oder wave steering (bound long wave corresponding to short wave forcing is added)	2.0	1.0 - 2.0
outputformat+	Output file format	fortran	fortran, netcdf, debug
outputprecision	Switch between single and double precision output in netcdf	double	single, double
paulrevere	Specifies tide on sea and land or two sea points if tideloc = 2	land	land, sea
phit+	Phase lag angle in nielsen transport equation	25.0	0.0 - 90.0
por	Porosity	0.4	0.3 - 0.5
pormax	Max porosity used in the experession of van rhee	0.5	0.3 - 0.6
posdwn	Bathymetry is specified positive down (1) or positive up (-1)	1.0	-1.0 - 1.0
projection+	Projection string
px	Pi	4.d0*atan(1.d0)
q3d	Turn on quasi-3d sediment transport	0	0 - 1
random+	Switch to enable random seed for instat = jons, swan or vardens boundary conditions	1	0 - 1
reformsteep+	Wave steepness criterium to reform after breaking	0.25d0*par%maxbrsteep	0.0 - 0.95d0*par%maxbrsteep
remdryoutput	Remove dry output points from output data of zs etc.	1	0 - 1
reposeangle	Angle of internal friction	30.0	0.0 - 45.0	deg
rfb+	Switch to feed back maximum wave surface slope in roller energy balance, otherwise rfb = par%beta	0	0 - 1
rheeA	A parameter in the van rhee expression	0.75	0.75 - 2.0
rho	Density of water	1025.0	1000.0 - 1040.0	kgm^-3
rhoa+	Air density	1.25	1.0 - 2.0	kgm^-3
rhog8	1/8rhog	-123		Nm^-3
rhos	Solid sediment density (no pores)	2650.0	2400.0 - 2800.0	kgm^-3
right	Switch for lateral boundary at 0	neumann	neumann, wall, no_advec, neumann_v, abs_1d
roller+	Switch to enable roller model	1	0 - 1
rotate	Rotate output as postprocessing with given angle	1	0 - 1
rt	Duration of wave spectrum at offshore boundary, in morphological time	min(3600.d0,par%tstop)	1200.0 - 7200.0	s
rwave	User-defined wave roughness adjustment factor	2.0	0.1 - 10.0
scheme+	Numerical scheme for wave propagation	warmbeam	upwind_1, lax_wendroff, upwind_2, warmbeam
secbrsteep+	Secondary maximum wave steepness criterium	0.5d0*par%maxbrsteep	0.0 - 0.95d0*par%maxbrsteep
secorder+	Use second order corrections to advection/non-linear terms based on maccormack scheme	0	0 - 1
sedtrans	Turn on sediment transport	1	0 - 1
setbathy	Turn on timeseries of prescribed bathy input	0	0 - 1
setbathyfile*+	Name of prescribed bed update file			<file>
shipfile	Name of ship data file			<file>
ships+	Turn on ship waves	0	0 - 1
shoaldelay	Switch to enable shoaling delay	0	0 - 1
sigfac	Dsig scales with log(sigfac)	1.3	0.0 - 10.0
single_dir+	Turn on stationary model for refraction, surfbeat based on mean direction	0	0 - 1
smag+	Switch for smagorinsky subgrid model for viscocity	1	0 - 1
smax+	Maximum shields parameter for equilibrium sediment concentration acc. diane foster	-1.0	-1.0 - 3.0
snells+	Turn on snell’s law for wave refraction	0	0 - 1
solver+	Solver used to solve the linear system	tridiag	sip, tridiag
solver_acc+	Accuracy with respect to the right-hand side usedin the following termination criterion: \|\|b-ax \|\| < acc*\|\|b\|\|	0.005	1e-05 - 0.1
solver_maxit+	Maximum number of iterations in the linear sip solver	30	1 - 1000
solver_urelax+	Underrelaxation parameter	0.92	0.5 - 0.99
sourcesink+	Switch to enable source-sink terms to calculate bed level change rather than suspended transport gradients	0	0 - 1
split+	Split threshold for variable sediment layer (ratio to nominal thickness)	1.01	1.005 - 1.1
sprdthr+	Threshold ratio to maximum value of s above which spectrum densities are read in	0.08	0.0 - 1.0
struct	Switch for enabling hard structures	0	0 - 1
sus+	Calibration factor for suspensions transports	1	0 - 1
swave	Turn on short waves	1	0 - 1
swkhmin	Minimum kh value to include in wave action balance, lower included in nlswe (default -1.d0)	-0.01	-0.01 - 0.35
swrunup	Turn on short wave runup	0	0 - 1
sws+	Switch to enable short wave and roller stirring and undertow	1	0 - 1
t	Computational time, in hydrodynamic time	-123		s
taper	Spin-up time of wave boundary conditions, in morphological time	100.0	0.0 - 1000.0	s
thetamax*	Higher directional limit (angle w.r.t computational x-axis)	90.0	-360.0 - 360.0	deg
thetamin*	Lower directional limit (angle w.r.t computational x-axis)	-90.0	-360.0 - 360.0	deg
thetanaut	Switch to specify thetamin and thetamax in nautical convention rather than cartesian	0	0 - 1
thetanum+	Coefficient determining whether upwind (1) or central scheme (0.5) is used.	1.0	0.5 - 1.0
tideloc	Number of corner points on which a tide time series is specified	0	0 - 4
tidetype+	Switch for offfshore boundary, velocity boundary or instant water level boundary	velocity	instant, velocity
timings+	Switch enable progress output to screen	1	0 - 1
tintc+	Interval time of cross section output	-123		s
tintg	Interval time of global output	1.0	0.01 - par%tstop-par%tstart	s
tintm	Interval time of mean, var, max, min output	par%tstop-par%tstart	1.0 - par%tstop-par%tstart	s
tintp	Interval time of point and runup gauge output	1.0	0.01 - par%tstop-par%tstart	s
tnext	Next time point for output or wave stationary calculation, in hydrodynamic time	-123		s
trepfac+	Compute mean wave period over energy band: par%trepfac*maxval(sf) for instat jons, swan or vardens; converges to tm01 for trepfac = 0.0 and	0.01	0.0 - 1.0
tsfac+	Coefficient determining ts = tsfac * h/ws in sediment source term	0.1	0.01 - 1.0
tsglobal+	Name of file containing timings of global output
tsmean+	Name of file containing timings of mean, max, min and var output
tspoints+	Name of file containing timings of point output
tstart	Start time of output, in morphological time	0.0	0.0 - par%tstop	s
tstop*	Stop time of simulation, in morphological time	2000.0	1.0 - 1000000.0	s
tunits+	Time units in udunits format (seconds since 1970-01-01 00:00:00.00 +1:00)	s
turb+	Switch to include short wave turbulence	wave_averaged	none, wave_averaged, bore_averaged
turbadv+	Switch to activate turbulence advection model for short and or long wave turbulence	none	none, lagrangian, eulerian
umin	Threshold velocity for upwind velocity detection and for vmag2 in equilibrium sediment concentration	0.0	0.0 - 0.2	m/s
vardx	Switch for variable grid spacing	0	0 - 1
vegcanflo	Include incanopy flow [1] or not [0]	0	0 - 1
vegetation+	Turn on interaction of waves and flow with vegetation	0	0 - 1
veggiefile	Name of veggie species list file
veggiemapfile	Name of veggie species map file
vegnonlin	Include non-linear wave effect [1] or not [0]	0	0 - 1
veguntow	Include undertow in phase-averaged vegetati	1	0 - 1
vicmol	Molecular viscosity	1e-06	0.0 - 0.001
viscosity	Include viscosity in flow solver	1	0 - 1
vonkar	Von karman constant	0.4	0.01 - 1.0
waveform	Wave shape model	vanthiel	ruessink_vanrijn, vanthiel
wavemodel	Stationary (0), surfbeat (1) or non-hydrostatic (2)	surfbeat	stationary, surfbeat, nonh
wavfriccoef	Wave friction coefficient	-123
wavfricfile	Wave friction file			<file>
wavint	Interval between wave module calls (only in stationary wave mode)	60.0	1.0 - 3600.0	s
wbctype	New wave boundary condition type	params	params, parametric, swan, vardens, off, jonstable, reuse, ts_1, ts_2, ts_nonh
wbcversion	Version of wave boundary conditions	3	1 - 3
wci	Turns on wave-current interaction	0	0 - 1
wearth+	Angular velocity of earth calculated as: 1/rotation_time (in hours)	1.d0/24.d0	0.0 - 1.0	hour^-1
wetslp	Critical avalanching slope under water (dz/dx and dz/dy)	0.3	0.1 - 1.0
wind	Include wind in flow solver	1	0 - 1
windfile	Name of file with non-stationary wind data			<file>
windth	Nautical wind direction, in case of stationary wind	270.0	-360.0 - 360.0	deg
windv	Wind velocity, in case of stationary wind	0.0	0.0 - 200.0	ms^-1
ws	Average fall velocity (is computed in morphevolution)	0.02d0		m/s
xfile	Name of the file containing x-coordinates of the calculation grid			<file>
xori	X-coordinate of origin of axis	0.0	-1000000000.0 - 1000000000.0	m
xyfile*	Name of the file containing delft3d xy-coordinates of the calculation grid			<file>
yfile	Name of the file containing y-coordinates of the calculation grid			<file>
yori	Y-coordinate of origin of axis	0.0	-1000000000.0 - 1000000000.0	m
z0+	Zero flow velocity level in soulsby and van rijn (1997) sediment concentration	0.006	0.0001 - 0.05	m
zs0	Inital water level	0.0	-5.0 - 5.0	m
zs0file	Name of tide boundary condition series			<file>
zsinitfile	Name of inital water level file			<file>

Output variables¶

Overview of available keywords related to *¶
parameter	description	units
As	Asymmetry of short waves
BR	Maximum wave surface slope used in roller dissipation formulation
Cdrag	Vegetation drag coefficient
D	Dissipation	W/m2
D15	D15 grain diameters for all sediment classses	m
D50	D50 grain diameters for all sediment classses	m
D50top	Friction coefficient flow
D90	D90 grain diameters for all sediment classses	m
D90top	Friction coefficient flow
DR	Roller energy dissipation	W/m2
Dc	Diffusion coefficient	m2/s
Df	Dissipation rate due to bed friction	W/m2
Dp	Dissipation rate in the swash due to transformation of kinetic wave energy to potential wave energy	W/m2
Dveg	Dissipation due to short wave attenuation by vegetation	W/m2
E	Wave energy	Nm/m2
Fvegu	X-forcing due to long wave attenuation by vegetation	N/m2
Fvegv	Y-forcing due to long wave attenuation by vegetation	N/m2
Fx	Wave force, x-component	N/m2
Fy	Wave force, y-component	N/m2
H	Hrms wave height based on instantaneous wave energy	m
Hrunup	Short wave height used in runup formulation	m
L1	Wave length (used in dispersion relation)	m
Qb	Fraction breaking waves
R	Roller energy	Nm/m2
Sk	Skewness of short waves
Subg	Bed sediment transport for each sediment class (excluding pores), x-component	m2/s
Susg	Suspended sediment transport for each sediment class (excluding pores), x-component	m2/s
Sutot	Sediment transport integrated over bed load and suspended and for all sediment grains, x-component	m2/s
Svbg	Bed sediment transport for each sediment class (excluding pores), y-component	m2/s
Svsg	Suspended sediment transport for each sediment class (excluding pores), y-component	m2/s
Svtot	Sediment transport integrated over bed load and suspended and for all sediment grains, y-component	m2/s
Sxx	Radiation stress, x-component	N/m
Sxy	Radiation stress, y-component	N/m
Syy	Radiation stress, y-component	N/m
Tbore	Wave period interval associated with breaking induced turbulence	s
Tsg	Sediment response time for each sediment class	s
alfau	Grid orientation at u-point	rad
alfav	Grid orientation at v-point	rad
alfaz	Grid orientation at z-point	rad
bedfriccoef	Dimensional/dimensionless input bed friction coefficient; depends on value of parameter bedfriction
bi	Incoming bound long wave	m
breaking	Indicator whether cell has breaking nonh waves
bwalpha	Beachwizard weighting factor
c	Wave celerity	m/s
ca	Reference concentration	m3/m3
ccg	Depth-averaged suspended concentration for each sediment fraction	m3/m3
cctot	Sediment concentration integrated over bed load and suspended and for all sediment grains	m3/m3
ccz	Concentration profile	m3/m3
ceqbg	Depth-averaged bed equilibrium concentration for each sediment class	m3/m3
ceqsg	Depth-averaged suspended equilibrium concentration for each sediment class	m3/m3
cf	Friction coefficient flow
cfu	Friction coefficient flow in u-points
cfv	Friction coefficient flow in v-points
cg	Group velocity	m/s
cgx	Group velocity, x-component	m/s
cgx_s	Group velocity, x-component	m/s
cgy	Group velocity, y-component	m/s
cgy_s	Group velocity, y-component	m/s
cobs	Beachwizard observed wave celerity	m/s
costh	Cos of wave angles relative to grid direction
costh_s	Cos of wave angles relative to grid direction
ctheta	Wave celerity theta-direction (refraction)	rad/s
ctheta_s	Wave celerity theta-direction (refraction)	rad/s
cx	Wave celerity, x-component	m/s
cy	Wave celerity, y-component	m/s
dU	U-velocity difference between two vertical layers (reduced 2-layer non-hydrostatic model)	m2/s2
dUi	Velocity difference at boundary due to (short) waves	m/s
dV	V-velocity difference between two vertical layers (reduced 2-layer non-hydrostatic model)	m2/s2
dassim	Beachwizard depth change	m
dcbdx	Bed concentration gradient x-dir.	kg/m3/m
dcbdy	Bed concentration gradient y-dir.	kg/m3/m
dcmdo	Beachwizard computed minus observed dissipation	W/m2
dcsdx	Suspended concentration gradient x-dir.	kg/m3/m
dcsdy	Suspended concentration gradient y-dir.	kg/m3/m
depo_ex	Explicit bed deposition rate per fraction	m/s
depo_im	Implicit bed deposition rate per fraction	m/s
dinfil	Infiltration layer depth used in quasi-vertical flow model for groundwater	m
dnc	Grid distance in n-direction, centered around c-point	m
dnu	Grid distance in n-direction, centered around u-point	m
dnv	Grid distance in n-direction, centered around v-point	m
dnz	Grid distance in n-direction, centered around z-point (=eta-point)	m
dobs	Beachwizard observed dissipation	W/m2
dsc	Grid distance in s-direction, centered around c-point	m
dsdnui	Inverse of grid cell surface, centered around u-point	1/m2
dsdnvi	Inverse of grid cell surface, centered around v-point	1/m2
dsdnzi	Inverse of grid cell surface, centered around z-point	1/m2
dsu	Grid distance in s-direction, centered around u-point	m
dsv	Grid distance in s-direction, centered around v-point	m
dsz	Grid distance in s-direction, centered around z-point (=eta-point)	m
dzav	Total bed level change due to avalanching	m
dzbdt	Rate of change bed level	m/s
dzbdx	Bed level gradient in x-direction
dzbdy	Bed level gradient in y-direction
dzbed	No description
dzbnow	Bed level change in current time step	m
dzs0dn	Alongshore water level gradient due to tide alone
dzsdt	Rate of change water level	m/s
dzsdx	Water surface gradient in x-direction	m/s
dzsdy	Water surface gradient in y-direction	m/s
ee	Directionally distributed wave energy	J/m2/rad
ee_s	Directionally distributed wave energy	J/m2/rad
ero	Bed erosion rate per fraction	m/s
fw	Wave friction coefficient
gw0back	Boundary condition back boundary for groundwater head	m
gwbottom	Level of the bottom of the aquifer	m
gwcurv	Curvature coefficient of groundwater head function
gwhead	Groundwater head (differs from gwlevel)	m
gwheadb	Groundwater head at bottom (differs from gwlevel)	m
gwheight	Vertical size of aquifer through which groundwater can flow	m
gwlevel	Groundwater table (min(zb,gwhead))	m
gwqx	Groundwater discharge in x-direction	m/s
gwqy	Groundwater discharge in y-direction	m/s
gwu	Groundwater flow in x-direction	m/s
gwv	Groundwater flow in y-direction	m/s
gww	Groundwater flow in z-direction (interaction between surface and ground water)	m/s
hh	Water depth	m
hhw	Water depth used in all wave computations, includes h*par%delta	m
hhwcins	Water depth used in wave instationary computation in case of wci	m
hhws	Water depth used in wave stationary computation (and single_dir wave directions)	m
hold	Water depth previous time step	m
hu	Water depth in u-points	m
hum	Water depth in u-points	m
hv	Water depth in v-points	m
hvm	Water depth in v-points	m
idrift	Drifter x-coordinate in grid space
infil	Rate of exchange of water between surface and groundwater (positive from sea to groundwater)	m/s
istruct	Location of revetments toe
iwl	Location of water line (including long wave runup)
jdrift	Drifter y-coordinate in grid space
k	Wave number	rad/m
kb	Near bed turbulence intensity due to depth induces breaking	m2/s2
kturb	Depth averaged turbulence intensity due to long wave breaking	m2/s2
maxzs	Maximum elevation in simulation	m
minzs	Minimum elevation in simulation	m
n	Ratio group velocity/wave celerity
nd	Number of bed layers (can be different for each computational cell)
ndist	Cum. distance from right boundary along n-direction	m
nuh	Horizontal viscosity coefficient	m2/s
nutz	Turbulence viscosity
pbbed	No description
pdisch	Discharge locations
ph	Pressure head due to ship	m
pntdisch	Point discharge locations (no momentum)
pres	Normalized dynamic pressure	m2/s2
qdisch	Discharges	m2/s
qx	Discharge in u-points, x-component	m2/s
qy	Discharge in u-points, y-component	m2/s
refA	Reference level	m
rolthick	Long wave roller thickness	m
rr	Directionally distributed roller energy	J/m2/rad
runup	Short wave runup height	m
sdist	Cum. distance from offshore boundary along s-direction	m
sedcal	Equilibrium sediment concentartion factor for each sediment class
sedero	Cum. sedimentation/erosion	m
setbathy	Prescribed bed levels	m
shipFx	Force on ship in x-direction	N
shipFy	Force on ship in y-direction	N
shipFz	Force on ship in z-direction	N
shipMx	Moment on ship around x-axis	Nm
shipMy	Moment on ship around y-axis	Nm
shipMz	Moment on ship around z-axis	Nm
shipchi	Turning angle arround y-axis	deg
shipphi	Turning angle arround x-axis	deg
shippsi	Turning angle arround z-axis	deg
shipxCG	X-coordinate of ship center of gravity	m
shipyCG	Y-coordinate of ship center of gravity	m
shipzCG	Z-coordinate of ship center of gravity	m
shobs	Beachwizard observed shoreline	m
sig2prior	Beachwizard prior std squared	m2
sigm	Mean frequency	rad/s
sigt	Relative frequency	rad/s
sigz	Vertical distribution of sigma layers q3d
sinth	Sin of wave angles relative to grid direction
sinth_s	Sin of wave angles relative to grid direction
strucslope	Slope of structure
structdepth	Depth of structure in relation to instantaneous bed level	m
taubx	Bed shear stress, x-component	N/m2
taubx_add	Additional bed shear stress due to boundary layer effects, x-component	N/m2
tauby	Bed shear stress, y-component	N/m2
tauby_add	Additional bed shear stress due to boundary layer effects, y-component	N/m2
tdisch	Discharge time series
tdriftb	Drifter release time	s
tdrifte	Drifter retrieval time	s
thet	Wave angles	rad
thet_s	Wave angles	rad
theta	Wave angles directional distribution w.r.t. comp. x-axis	rad
theta_s	Wave angles directional distribution w.r.t. comp. x-axis	rad
thetamean	Mean wave angle	rad
tideinpt	Input time of input tidal signal	s
tideinpz	Input tidal signal	m
tsetbathy	Points in time of prescibed bed levels	s
u	Glm velocity in cell centre, x-component	m/s
ua	Time averaged flow velocity due to wave assymetry	m/s
ucrcal	Calibration factor for u critical for each sediment class
ududx	Advection	m2/s2
udvdx	Advection	m2/s2
ue	Eulerian velocity in cell centre, x-component	m/s
ue_sed	Advection velocity sediment in cell centre, x-component	m/s
ueu	Eulerian velocity in u-points, x-component	m/s
ui	Incident bound wave velocity in, x-component	m/s
umean	Longterm mean velocity at bnds in u-points, x-component	m/s
umwci	Velocity (time-averaged) for wci, x-component	m/s
ur	Reflected velocity at bnds in u-points	m/s
urepb	Representative flow velocity for sediment advection and diffusion, x-component	m/s
ureps	Representative flow velocity for sediment advection and diffusion, x-component	m/s
urms	Orbital velocity	m/s
usd	Return flow due to roller after breaker delay	m/s
ust	Stokes drift	m/s
ustr	Return flow due to roller	m/s
ustz	Stokes velocity (q3d)
uu	Glm velocity in u-points, x-component	m/s
uv	Glm velocity in v-points, x-component	m/s
uwcins	U-velocity used in wave stationary computation in case of wci	m/s
uwf	Stokes drift, x-component	m/s
uws	U-velocity used in wave stationary computation (and single_dir wave directions)	m/s
uz	Velocity (q3d) ksi-comp
v	Glm velocity in cell centre, y-component	m/s
vdudy	Advection	m2/s2
vdvdy	Advection	m2/s2
ve	Eulerian velocity in cell centre, y-component	m/s
ve_sed	Advection velocity sediment in cell centre, y-component	m/s
vegtype	Vegetation type index
vev	Eulerian velocity in u-points, y-component	m/s
vi	Incident bound wave velocity in, y-component	m/s
viscu	Viscosity	m2/s2
viscv	Viscosity	m2/s2
vmag	Velocity magnitude in cell centre	m/s
vmageu	Eulerian velocity magnitude u-points	m/s
vmagev	Eulerian velocity magnitude v-points	m/s
vmagu	Glm velocity magnitude u-points	m/s
vmagv	Glm velocity magnitude v-points	m/s
vmean	Longterm mean velocity at bnds in u-points, y-component	m/s
vmwci	Velocity (time-averaged) for wci, y-component	m/s
vrepb	Representative flow velocity for sediment advection and diffusion, y-component	m/s
vreps	Representative flow velocity for sediment advection and diffusion, y-component	m/s
vu	Glm velocity in u-points, y-component	m/s
vv	Glm velocity in v-points, y-component	m/s
vwcins	V-velocity used in wave stationary computation in case of wci	m/s
vwf	Stokes drift, y-component	m/s
vws	V-velocity used in wave stationary computation (and single_dir wave directions)	m/s
vz	Velocity (q3d) eta-comp
wb	Vertical velocity at the bottom	m/s
wete	Mask wet/dry wave-points
wetu	Mask wet/dry u-points
wetv	Mask wet/dry v-points
wetz	Mask wet/dry eta-points
wi	Vertical velocity at boundary due to (short) waves	m/s
winddirts	Input wind direction	deg_nautical
windinpt	Input time of input wind signal	s
windnv	Wind velocity in n direction in v point at current time step	m/s
windsu	Wind velocity in s direction in u point at current time step	m/s
windvelts	Input wind velocity	m/s
windxts	Time series of input wind velocity (not s direction), x-component	m/s
windyts	Time series of input wind velocity (not n direction), y-component	m/s
wm	Mean abs frequency	rad/s
ws	Vertical velocity at the free surface	m/s
wscrit	Critial vertical velocity at the free surface for breaking	m/s
x	X-coord. original cmp. grid	m
xHrunup	Location at which short wave height for runup is taken	m
xu	X-coord. comp. grid u-points	m
xv	X-coord. comp. grid v-points	m
xyzs01	Global xy coordinates of corner (x=1,y=1)
xyzs02	Global xy coordinates of corner (x=1,y=n)
xyzs03	Global xy coordinates of corner (x=n,y=n)
xyzs04	Global xy coordinates of corner (x=n,y=1)
xz	X-coord. comp. grid (positive shoreward, perp. to coastline)	m
y	Y-coord. original comp. grid	m
yu	Y-coord. comp. grid u-points	m
yv	Y-coord. comp. grid v-points	m
yz	Y-coord. comp. grid	m
z0bed	No description
zb	Bed level	m
zb0	Initial bed level	m
zbobs	Beachwizard observed depth	m
zi	Surface elevation at boundary due to (short) waves	m
zs	Water level	m
zs0	Water level due to tide alone	m
zs0fac	Relative weight of offshore boundary and bay boundary for each grid point is stored in zs0fac
zs1	Water level minus tide	m
zswci	Waterlevel (time-averaged) for wci	m

Examples, tutorials and excercises¶

Examples¶

Holland default¶

1D, surfbeat, random normal incident waves.Aim: Dune erosion

This test simulates dune erosion on the standard Holland profile (DUROS) under normative conditions. Simple exampe with minimal input.

model data: https://svn.oss.deltares.nl/repos/xbeach/skillbed/input/holland_default/

Field experiment: DELILAH¶

2D, surfbeat, directional spreading. Aim: comparison field data hydrodynamics

In order to verify the 2DH hydrodynamics of XBeach when forced by directionally-spread short waves, a simulation is set up to compare model results to field measurements. In this case the DELILAH field experiment at Duck, North Carolina is selected as a suitable test location. The period that is modeled is October 13th 1990, which was a stormy day, between 16:00 and 17:00 hours. For more info, check: http://oss.deltares.nl/web/xbeach/skillbed

model data: https://svn.oss.deltares.nl/repos/xbeach/skillbed/input/Delilah_199010131000/

Longcrested Refraction¶

2D, surfbeat, random long crested incident waves, hydrodynamics only. Aim: simulation of refraction

Longcrested waves are supported in XBeach by using a value s larger than 1,000. This test shows the numerical directional diffusion in the comparison of a few runs where the angle of wave incidence and the number of directional bins vary. The bathymetry is a linear sloping beach and no morphological change is computed in these runs.

model data: https://svn.oss.deltares.nl/repos/xbeach/skillbed/input/longcrested_refraction/

Hurricane Sandy¶

2D, surfbeat, nested in SWAN simulation. Aim: beach and dune erosion

This model setup is used as a tool to model the impact of Hurricane Sandy on the New Jersey coast. Hurricane Sandy caused wide-spread erosion of the coastal system as well as barrier island breaching at several spots. The model focusses on the area of Camp Osborne, Brick, NJ where a condominium resulted in 32% additional erosion in adjacent locations.

model data: https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files/Model tutorial: http://xbeach.readthedocs.io/en/latest/tutorials/sandy/index.html

Port application¶

2D, surfbeat, random incident waves, hydrodynamics only. Aim: simulation of port hydrodynamics.

The laboratory experiments were conducted at Deltares in the Vinjè directional basin in 2004. The tests were carried out under controlled conditions for the purpose of validating new numerical models of wave forces on moored ships (van der Molen, 2006). In this study, the dataset is only used to examine the computational skills of XBeach in a harbour basin by comparing the measured and calculated results of the hydrodynamics. Wave forces are not considered in this study

thesis: http://repository.tudelft.nl/islandora/object/uuid:533ad406-9d7f-44bb-ba3b-7fe60e112432?collection=education model data: https://svn.oss.deltares.nl/repos/xbeach/testcases/Wong2016/

Excercises¶

The hands-on exercises can be downloaded via subversion. Subversion is a well-known version management system that allows you to always have the most recent source code at hand. It also allows developers to commit changes to the source code, without interfering with other developers. In order to use Subversion, you will need a Subversion client. A well-known client for Windows is Tortoise. If you have registered, you can download the source code via the following URL: https://svn.oss.deltares.nl/repos/xbeach/Courses/DSD_2014/Examples – Basic. For the tools like Quickplot and Quickin the Delft3D environment is needed.

Dune erosion at Delfland, Netherlands (1D)¶

The first case we will run is a relative simple 1D case. It concerns a profile along the Dutch coast and the hydraulic boundary conditions are based on the 1953 storm surge that caused substantial flooding in the Netherlands.

You can work on the following assignments:

Go to the folder “Examples\DelflandStorm” and double click the file “run_model.bat”. The simulation will start. The model will run for a few minutes, but in the meantime you can already work on question 2 to 5.
Open params.txt in which you specify the model input files and settings. Check the number of grid-points in x-direction (keyword: nx) and y-direction (keyword: ny). Check the filenames in which you specify the wave conditions (keyword: bcfile) and the storm surge level (SSL) (keyword: zs0file).
Do the wave conditions change during the simulation? What is/are the wave height(s) and wave period(s) applied in the simulation?
Does the storm surge level change during the simulation? What is the maximum surge height in the simulation. Surge height is defined with respect to the mean sea level (MSL)?
What is the simulation time (keyword: tstop)? Do we apply a morphological acceleration factor (keyword: morfac)? What variables are stored as output and with what time interval? How much hydrodynamic time is simulated?
Probably the simulation has finished. When you start the model, it generates a file named XBlog.txt. Open this file and check what is stored in the file. What was the total simulation time?
To check out the simulation results we make use of the Quickplot tool (A brief tutorial is attached to this document). You can start Quickplot via the Delft3D environment we installed (Start Programs Deltares Delft3D Delft3D). In the Delft 3D menu choose Utilities Quickplot. Choose Files of type “NetCDF files and GRIB files” and open “xboutput.nc” in the simulation folder.
Use the Quickplot tutorial and try to make an animation in which you plot short wave height (H), water level (including long wave variations, zs) and bed level (zb) as function of time.
Plot the offshore water level as function of time. Also open the file “tide.tek” (Tekal data files format), which contains the imposed surge level. Did the model correctly simulate the imposed surge level?
Copy all model files to a new folder named “superfast”. Edit params.txt and set ny=0 (instead of ny=2), and run the model. What is the simulation time compare to the original simulation?
Compare simulation results for the “superfast” and “default” simulation. Are these the same? What option will you use in the future?

Nourishment scenarios near Kijkduin, Holland (1D)¶

This case concerns the exploration of a nourishment strategy near Kijkduin along the Holland coast in the Netherlands. At this location a mega nourishment of 21 Mm ${}^{3}$ named the Sand Engine was constructed. In this case we will explore to what extent nourishments can reduce the (dune and beach) erosion during a storm event.

You can work on the following assignments:

Go to the folder “Examples\Nourishment case” and double click on the file “runall.bat”. This batch file will run three simulations sequentially in which the profile configuration varies and corresponds with the undisturbed profile (folder reference), a shoreface nourishment (folder shoreface) and a beach nourishment (folder beach) respectively. Each model will run for a few minutes. While running you can already answer question 2 to 6.
For the reference case open the params.txt in which you specify model input files and settings. Check the number of grid-points in x-direction (keyword: nx) and y-direction (keyword: ny). How many directional wave bins are defined and what is their width (keywords: thetamin, thetamax, dtheta).
Do the wave conditions change during the simulation? What is/are the wave height(s) and wave period(s) applied in the simulation?
Does the storm surge level change during the simulation? What is the maximum surge height in the simulation. Surge height is defined with respect to the mean sea level (MSL)?
What is the simulation time (keyword: tstop)? Do we apply a morphological acceleration factor (keyword: morfac)? What variables are stored as output and with what time interval? How much hydrodynamic time is simulated?
Probably the simulation has finished. When you start the model, it generates a file named XBlog.txt. Open this file and check what is stored in the file. What was the total simulation time?
Inspect the initial bathymetries of each simulation with QUICKPLOT. Choose Files of type “NetCDF files and GRIB files” and open “xboutput.nc” in the simulation folder).
1. At what cross-shore position were the shoreface nourishment and beach nourishment placed?
2. What is the (average) thickness of the nourishments?
3. Is the volume of the nourishments comparable?
4. Plot the reference profile with markers; does the grid resolution vary in cross-shore direction?
Use the Quickplot tutorial and try to make an animation in which you plot short wave height (H), water level (including long wave variations, zs) and bed level (zb) as function of time.
Plot the offshore water level as function of time. Also open the file “tide.tek” (Tekal data files format), which contains the imposed surge level. Did the model correctly simulate the imposed surge level?
Inspect the final bathymetries of each simulation.
1. What is the dune face retreat in the three simulations you have carried out?
2. Where does the eroded sediment form the dunes deposit?
3. What nourishment type is most effective in reducing the impact of a storm and do you have an explanation for this?
In the folder “banquette” you find a final simulation in which a special beach nourishment type is evaluated named a banquette. This beach nourishment has a highly elevated flat area that connects to the dune foot on which beach restaurants can be build.
1. Run the model and compare in Quickplot the banquette design with the beach nourishment design we have evaluated before. Do you expect more or less erosion?
2. Check your hypothesis by comparing the final profile of the banquette simulation to the other simulations.
3. What would be your approach to further reduce beach and dune erosion?

Overwash at Santa Rosa Island , USA (2DH)¶

This case concerns overwash at Santa Rosa island in the Gulf of Mexico during hurricane Ivan in 2004.

You can work on the following assignments.

For the reference case open the params.txt in which you specify model input files and settings. Check the number of grid-points in x-direction (keyword: nx) and y-direction (keyword: ny). How many directional wave bins are defined and what is their width (keywords: thetamin, thetamax, dtheta).
In this simulation the grid is specified in Delft3D format. Open Quickin in the Delft 3D menu (Grid Quickin) and use the brief tutorial to read in the grid and bathymetry. Does the grid resolution vary in cross-shore direction? And in longshore direction? What are the minimum dx and dy? Why can the grid be coarse offshore?
How many wave conditions do we apply in this simulation? What is the offshore mean wave direction? Does the surge level change in the simulation?
What is the simulation time (hydrodynamic and morphologic)?
Inspect the model results and make an animation of the short wave height (H) and the water levels (including long wave, zs). Describe what is happening.
For the water levels set the color limits manual between -0.5 and 3.5.
Make an animation of cumulative sedimentation/erosion. Describe what is happening.
For the sedimentation/erosion set the color limits manual between -3 and 3
Look at the mean flow field. Plot the flow field in colored vectors. Where are the flow velocities highest and what is the direction of the flow (cross-shore or longshore)? Is there (also) a longshore current present and what is its intensity?

If you have time left feel free to:

Narrow or broaden the imposed spectrum by changing the parameter directional spreading (s) in ‘jonswap.inp’ (you could for example set s = 100 and s = 2 respectively). Make animations of the instantaneous short wave height to see what is happening to the size of the wave groups.
Design a nourishment in Quickin to reduce the impact of the storm on Santa Rosa Island. Change the depth file in params.txt to make a simulation with the updated bathymetry.

Yanchep perched beach and natural breakwater (2DH)¶

This case is an example of a beach 60km north of Perth most commonly known as Yanchep lagoon. Many beaches in WA like Yanchep are fronted by shallow reef and here we are investigating the effects of the reef on the morphodynamics.

You can work on the following assignments:

Go to the folder “Examples\YanchepBeach” and double click the file “run_model.bat”. The simulation will start (and will run about 15 minutes).
Meanwhile, inspect the bathymetry file and the structure file (using Quickin). What is the depth in the lagoon? Is the reef enclosing the lagoon below or above the model initial water level? What is the wave height at the boundary condition?
Use Quickplot and try to make an animation in which you plot short wave height (H), water level (including long wave variations) (zs) and Eulerian velocities (ue and ve) as function of time. What happens in the lagoon?
Use Quickplot and try to make an animation of cumulative sedimentation/erosion. What happens in the lagoon?
How is the lagoon affected by the mean water level? Increase or decrease the mean water level condition (‘tide.tx’), run the model again (maybe for a shorter time by reducing keyword: tstop). How are the circulation and sediment transport affected?
What would happen if the lagoon was open at the southern end? Open the structure file (keyword: ne_layer=’reef.dep’) with the Quickin tool and modify it to allow the southern end of the lagoon to be eroded. Modify the param.txt file to use this new structure file and run the model. Alternatively, remove the reef from the bathymetry and rerun the model without the structure file, by setting the keyword struct=0.

If you still have time;

Reefs are very rough what happens in the model when the friction is increased? Reduce the Chezy roughness and increase the value of f:math:`{}_{w}`. Rerun the model what do you observe?
Is wave/current interaction (keyword: wci=1) switched on? Rerun the model with the wave/current switch on/off. Compare the output with model you ran previously. How much effect do you see on the morphology?

Tutorials¶

Hindcast hurricane impact Sandy¶

Autor: Kees Nederhoff Email: kees.nederhoff@deltares.nl Date: 26-June-2017

Introduction in the case¶

In this tutorial the sandy coast of Bay Head (New Jersey, United States) during Hurricane Sandy (2012) is modeled. Hurricane Sandy originated from the Western North Atlantic Ocean in October 2012. The storm caused flooding, wind and wave damage. During Hurricane Sandy the state of New York and New Jersey were most severely hit (National Hurricane Center, 2012), see Fig. 19. Sandy made landfall on October 29, 2012 at 12:00 PM UTC during spring tide near Atlantic City, NJ. Hurricane Sandy caused wide-spread erosion of the coastal system as well as barrier island breaching at several spots. Sandy was the second costliest hurricane in the United States history with a total of 68 billion dollar in property damage (National Hurricane Center, 2012). XBeach (Roelvink et al., 2009) is a process-based model designed to describe the different storm regimes described by Sallenger (2000) and is used in as a tool to model the impact of Hurricane Sandy on the New Jersey coast.

Upper pictures show characteristic examples of damage which occurred during Sandy (Lopez-Feliciano, 2014). Bottom pictures shows examples of depositional features such as described by Donneley (2007) (source: Google Earth). Pictures are in the area of Bay Head, NJ and taken on November 3th 2012. ?

Tools and ingredients needed¶

We need the following tools:

Matlab with the OpenEarth toolbox
- Can be retrieved via: https://svn.oss.deltares.nl/repos/openearthtools/trunk
An XBeach executable
- Can be retrieved via: http://www.xbeach.org
This tutorial data folder with scripts, data and model set-up
- Can be retrieved via: https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files
Add the files in the folder Functions to your Matlab folder. Antoher option is to ad the entire path of Functions. This can be done with the Matlab command addpath.

The ingredients of every XBeach model set-up contains 5 steps:

Bathymetric information: pre and post storm of several sources (LiDAR and Coastal Relief Model). LiDAR is gathered by the USGS, both pre and post Sandy. The Coastal Relief Model (CRM) doesn’t have specific date.
Boundary conditions: water levels and wave spectra. This can either be measured by a buoy or simulated by another model (nesting). In this tutorial we are going to nest XBeach in an existing Delft3D model of the Atlantic coast.
Generate your XBeach model: once we have the bathymetry (step 1) and boundary conditions (step 2) we can generate the XBeach model. It’s recommended to start with default values in XBeach.
Calibrate and validate your XBeach model: a process-based model is a schematic reproduction of the reality. It’s however always important to have some idea of the skill of your model (eg. bias, RMSE, BSS, see Van Rijn, 2003). One can either only validate the default model set-up or also calibrate different model parameters. A straight-forward method of calibrating an XBeach model is by applying the two-step calibration approach of Nederhoff et al. (2015).
Post-processing: make graphs and animations of the final run to present your supervisor or client. ?

Step 1: make a bathymetry¶

In this first step we are going to use two different data sources in order to define all the bathymetric information we need to model this area with XBeach. There are two important steps. First of all, we need to interpolate the different data sources to our area of interest. Secondly, we need to combine the different data sources together. In this tutorial we will use Coastal Relief Model (CRM; NGDC, 2014) as a basis of our model. Everywhere there is LiDAR data from the USGS the CRM values will be overwritten. An optional third step is applying a small smoothing function in order to get rid of large disturbances or add more data sources.

Download the data sources. In this example we use two sources: LiDAR and CRM
- For LiDAR information one goes to the website: http://www.csc.noaa.gov/dataviewer. LiDAR is a remote sensing technology that measures distance by illuminating a target with a laser and analyzing the reflected light. This technique is often used to measure barrier erosion during extreme events like Hurricane Sandy.
  - Draw a box around the barrier that you want to model.
  - Select the ‘2012 USGS Pre Sandy LiDAR’ and click on ‘add to chart’. See Fig. 20.
  - Repeat this step if you would like to have more data (eg. Post Sandy data).
  - Click on ‘Checkout’ and define output settings. XBeach uses a Cartesian grid laid out (eg. UTM) in meters. It’s recommended to use grid output instead of points cloud and to select ‘ground-based’ on the ‘last return’. This makes it possible to model the ‘bare earth’ without small trees and bushes. See Fig. 21 for the recommended settings.
  - You will receive an email from NOAA in a few minutes where you can download the files.
- For CRM data one goes to the website: http://maps.ngdc.noaa.gov/viewers/wcs-client/. Coastal Relief Model provides a comprehensive view of the U.S. coastal zone, integrating offshore bathymetry with land topography.
  - Draw a box around the barrier that you want to model
  - Select ASCII grid and click on download. See Fig. 22
  - The function to read .asc files (arcgridread_v2.m) wants to read a no data header. The CRM doesn’t provides such a values, so we have to enter it manually. See the .asc files of the LiDAR for the format.
NB: For this tutorial one can use the ``crm.asc``, ``2012_USGS_preSandy_NJ.asc`` and ``2012_USGS_postSandy_NJ.asc``, see https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files/Data/Step1_makebathy/
Interpolate the data to the area of interest on a defined grid resolution
- A minimum resolution of 2x2m is recommended in order to keep enough information of the exact shape of the dune face.
- CRM needs to be converted to the UTM coordinate system because XBeach cannot handle geographic coordinate systems (eg. lat/lon)
Optional steps:
- Add more data sources of for example beach profiles
- Smooth the data in cross-shore and longshore direction

After this first step one will have bathymetric information both pre and post storm of the area of interest. This data sources can be used in a data analysis (eg. determine erosion volumes) and will be used as an input in order to set-up and compare the model with (step 3 and 4). The different steps as described are coded in the Matlab m-file JIP_1_combinebathy.m. One can found the data in https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files/Data/Step1_makebathy/ . The final bathy is saved in the mat-file bathy_final.mat and will be used when we will make the actual XBeach model.

Select the LiDAR data for the area of interest

Define the output variables. Make sure you use UTM coordinates!

Also download the CRM model in order to have values for all the grid cells.

Step 2: determine boundary conditions¶

In this second step we are going to determine the boundary conditions (waves and water levels) for XBeach by nesting (offline coupling) the model in a Delft3D model of the Atlantic Ocean during Hurricane Sandy (van Ormondt, personal communication, 2014). The results of the Delft3D model needs be validated with available measurement data in order to have an idea of the quality of the nesting procedure (skill scores: eg. R2, RMSE, bias).

Determine the water levels and wave information on sea by making an observation points in Delft3D-FLOW and WAVE. The water levels can be extracted from the trih-file, see Fig. 23. The wave information can be saved as a sp2-file which can directly be read by XBeach, Fig. 25.
- Validate the wave information. Wave heights and periods are determined at buoy 44065 and 44025 offshore of Sandy Hook. Data can be retrieved from the National Data Buoy Center from NOAA at http://www.ndbc.noaa.gov/, see Fig. 26.
  - Go to buoy, click on it a select ‘view history’.
  - Go to Standard meteorological data and the year of the event (Sandy it is 2012). WVHT is the significant wave height, DPD is the dominant wave period and the MWD is the wave direction (in nautical degrees).
  - Validate the wave height and period. What is the RMSE per station per parameter?
- Validate the water levels. Information of NOAA with the use of tide gauge 8534720 near Atlantic City, 8531680 near Sandy Hook, 8518750 near Battery. Data can be retrieved at https://tidesandcurrents.noaa.gov/map/. Make sure you select the same horizontal and vertical reference as the bathymetry (for example NAVD88 and MSL).
  
  The full URL for water level data during Hurricane Sandy of the station of Atlantic City, for other stations change the gauge number (8534720) in the required gauge number (eg. 8531680, 8518750) https://tidesandcurrents.noaa.gov/waterlevels.html?id=8534720&units=metric&bdate=20121025&edate=20121031&timezone=GMT&datum=MSL&interval=6&action=
  - Select the measurement station and click on it
  - Click on gauge height. This will automatically refer you to the webpage of the USGS waterbase were all the USGS measurements can be found.
  - Validate the water level. What is the RMSE per station?

In this tutorial we will not go through all the validation steps, however Nederhoff (2014; Section F5, page 145) gives an elaborate validation of the Delft3D model. In https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files/Data/Step2_makebc/Measurements some measurements of the water levels and waves can be found. In https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files/Data/Step2_makebc/Model the model output of Delft3D can be found.

Determine the water levels in the bay. The Delft3D-model doesn’t contain water levels in the Barnegat Bay. For the bay surge information the USGS website ‘Waterbase’ can be visited. Data can be retrieved at http://nwis.waterdata.usgs.gov/. There are in total four different stations in Barnegat Bay, however not all data is quality approved. The data at Barnegat Light NJ is approved (01409125). One should search for the name of gauge number. Make sure you select the same reference system as the bathymetry, see Fig. 28.

For the full URL of the Waterbase website for data of the Barnegat Bay during Sandy: http://nwis.waterdata.usgs.gov/usa/nwis/uv/?cb_00065=on&format=gif_default&site_no=01409125&period=&begin_date=2012-10-25&end_date=2012-10-31

After this first step one will have the boundary conditions needed to force XBeach. These data sources can be used in a data analysis (eg. determine maximum wave height) and will be used as an input in order to set-up and compare the model with (step 3 and 4). The different steps as described are not coded in Matlab. The data can be found in https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/sandy/files/Data/Step2_makebc/ . The result of the waves, water levels (sea and bay) can be found in Fig. 23.

The wave and surge level data at sea are obtained by a nesting procedure between XBeach and Delft3D. The bay water level are measured. Reference level: NAVD88.

Observation points in Delft3D-FLOW

Observation points in Delft3D-WAVE

The National Data Buoy Center. All information related to wave buoys can be found here.

NOAA: tides and currents. A useful website for tide information along the US coast

USGS: Waterbase. Information related to rivers and bays (eg. discharges, temperature, gauge height, salinity) can be found here.

Step 3: generate a XBeach model¶

We now have the two most basic input requirements for the XBeach model: bathymetry and boundary conditions. Step 3 will be the load everything into Matlab and generate the actual XBeach grid and settings file (so called params.txt). One can found a Matlab script to generate the model with the name JIP_3_makeXBeach.m

We will go no trough the basic set-up steps one should consider the following when applying the Matlab function xb_generate_model. A full list of options in the params.txt can be found in the XBeach manual. On top of that the params.txt of this tutorial is added.

Bathymetry
- Location: think about the area of interest, shadow zone of waves (depends on the incident wave angle) and offshore boundary depth (no wave breaking, cg / c < 0.8).
- Resolution. Grid resolution should be sufficient to describe long wave (10-20 points) and multiple grid points per feature (5-10). For dune erosion and overwash cases a minimum resolution in cross-shore (dx) of 1 till 2 meter is advised in order to have enough accuracy to solve the morphological processes. A resolution of 5 till 10 meters is advised; however it is possible to increase this to higher values. The toolbox will make a robust model set-up based on a set of default settings (like points per wave length and Courant number).
- Other settings which are important are for example settings the grid in world coordinates, and seaward flatten and extending of the model. The last step is needed to have no bathymetry gradient at the boundary. Offshore boundary at sufficiently deep water for realistic long wave boundary conditions (n < 0.8). Uniform coast (three cells) near lateral boundaries and offshore boundary This is needed to have realistic long waves and proper boundaries.
Boundary conditions
- Waves. Different types (keyword ‘instat’, see Fig. 29) | Stationary: no wave groups, short wave action | Wave group forcing: resolving long wave (‘surf-beat’) | Parameterized JONSWAP/PM spectrum (instat = jons) | 2D Variance density input (instat = vardens) | SWAN sp2 output (instat = swan) | Reusing exact previous realization (instat = reuse) | Non-hydrostatic: also resolving short waves
- Waterlevels.
  
  To initialize with a given (possibly spatially varying) waterlevel zsinitfile specifying a water level per grid cell zs0 imposes one initial water level across the domain
- Lateral boundary | Neumann: no-gradient boundary | Wall: no flux boundary
- Offshore boundary | abs1d / abs2d absorbing generation; long waves can enter / leave | wall no flux boundary | waterlevel a waterlevel is prescribed on the boundary
Other settings
- Bed friction
  
  There are multiple bed friction formulations (keyword: bedfriction) in XBeach. This gives the user the possiblity to calculate with for example Chezy, Manning, cf
- Sediment transport
  
  A common used method to calibrate the sediment transport time is the facua option. This will change the offshore sediment transport. A value between 0.1 and 0.3 is advised.
- Morphology
  
  A common used method to decrease the computational time is the morfac option. A value between 1 and 10 is advised.

Different wave boundary options: surf beat versus non-hydrostatic.

Example params.txt¶

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% XBeach parameter settings input file                                     %%%
%%%                                                                          %%%
%%% date:     30-Nov-2015 23:46:15                                           %%%
%%% function: xb_write_params                                                %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% Bed composition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

D50          = 0.000300
D90          = 0.000400

%%% Flow boundary condition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

front        = abs_2d
back         = abs_2d
epsi         = -1

%%% Flow parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

bedfriction  = manning
bedfricfile  = bedfricfile.txt

%%% General %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

tidelen      = 144

%%% Grid parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

depfile      = bed.dep
posdwn       = 0
nx           = 836
ny           = 100
alfa         = 0
vardx        = 1
xfile        = x.grd
yfile        = y.grd
xori         = 0
yori         = 0
thetamin     = 0
thetamax     = 180
dtheta       = 10
thetanaut    = 1

%%% MPI parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

mpiboundary  = x

%%% Model time %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

tstop        = 259200
CFL          = 0.700000

%%% Morphology parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

morfac       = 10
morstart     = 0

%%% Sediment transport parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

facua        = 0.100000

%%% Tide boundary conditions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

zs0file      = tide.txt
tideloc      = 2

%%% Wave boundary condition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

instat       = 5

%%% Wave-spectrum boundary condition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

bcfile       = loclist.txt
rt           = 1800
dtbc         = 1

%%% Output variables %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

outputformat = netcdf
tintm        = 43200
tintg        = 3600
tstart       = 0

nglobalvar   = 6
zb
zs
H
ue
ve
sedero

nmeanvar     = 5
zb
zs
H
ue
ve

Step 4: running XBeach¶

There are four ways to run a XBeach simulation:

Windows: with one core. This can be done by making a bat file. One can make a bat-file with a simple texteditor like Notepad or Textpad and type: call “folderofXBeachsourceXBeach.exe” The bat file needs to be save as ‘run_XBeach.bat’
Windows: with multiple cores via MPI. MPI is a standardized and portable system designed by a to function on a wide variety of parallel computers. Fortran (the programming languages of XBeach) can use MPI. For Windows computers one can use MPICH. For more information about MPICH one is referred to http://www.mpich.org/downloads/. For a tutorial to install MPICH on Windows (http://oss.deltares.nl/web/xbeach/forum/-/message_boards/view_message/718128).

Running xbeach in mpi mode with mpich is quite easy once the previous steps have been successfully completed. Firstly, mpi jobs should be started with the mpiexec.exe process (not with a call to xbeach.exe directly). To do so open a command prompt window and enter the following command:

mpiexec.exe –n [N] –wdir [xbeach_params.txt_dir] –mapall [dirtoxbeachxbeach.exe]
UNIX: It is also possible to calculate on a UNIX system. For more information about compiling XBeach on your UNIX system see https://oss.deltares.nl/web/xbeach/compile-code.
Cloud computing: we support a virtual machine on Amazon. The newest release can be found as a AMI (Amazon Machine Image). Search for XBeach_Kingsday.

XBeach has an unit speed of about $3 - 4 \cdot 10^{-6}$ per second. This means that 1 million grid cells (nx: 1000 and ny: 1000) for one hour (3600 seconds) will take 3.66 hours to calculate. When running on 8 cores this will decrease to 0,5 till 1,0 hours. So when calculating large grids or for long times, the simulation time of XBeach can get out of hand. Below a couple of tips in order to reduce the computational expenses:

Disable processes that you don’t need (eg. morphology = 0)
Calculating on multiple cores with MPI.
Reduce the simulation time. Model for example only the ‘real’ peak of the storm.
Increase the morfac. Morfac of 10 is the maximum for strom conditions
When running in multi_dir:
- Decrease the wave grid by reducing the thetamin, thetamax and dtheta.
- Run with single_dir = 1. This will turn on stationary model for refraction and use surfbeat based on the mean direction. Settings needed are dtheta = thetamax – thetamin and dtheta_s = 10.
Optimize the model grid by making use of the OpenEarth toolbox. The function xb_generate_bathy optimize the grid by varying the grid size in x and y.

Step 5: calibrate / validate the model¶

An important fourth step in modeling with any morphological process-based model is the calibrating and validation part. In this tutorial we propose to calibrate by applying a two-step morphological calibration approach as suggested and demonstrated by Nederhoff (2014). This is a simple straight-forward calibration method for morphological development during extreme conditions in XBeach when multiple regimes of Sallanger (2000) are of importance (combination of dune erosion and overwash).

The first substep is to increase the parameterized wave asymmetry sediment transport component (facua). A higher value will result in less net offshore sediment transport and is suitable for calibrating dune erosion. XBeach considers the wave energy of short waves as averaged over their length, and hence does not simulate the wave shape. A discretization of the wave skewness and asymmetry was introduced by Van Thiel de Vries (2009), to affect the sediment advection velocity. One hypothesis is that on steep beaches wave asymmetry becomes more important and since the facua parameter is determined for Dutch beaches, calibration is needed (Nederhoff, 2014). Nederhoff et al. (2015) shown that a facua of 0.25 leads to good agreement in morphological development during Sandy for New Jersey. This is much higher that the default value of XBeach (0.1).

The second substep is to increase the roughness of the barrier (parameter: bedfricvalue). A higher roughness will result in less sediment transport on top of the barrier and is applied to calibrate the overwash regime. Friction is used for the bed stability and the sediment transport via the formulation of the bed shear stress (?b). For a situation with hydraulic rough flow on top of a barrier island the roughness needs to be higher than the default value, since a higher Manning value represents friction due to the presence of structures and/or vegetation. In fact the friction can be used as a sum for all kind of different contributions that can have an impact on the flow. The reason is that small constructions have limited impact on the morphological development of the barrier. However to take into account some of the effect friction (with a higher Manning value) can be used as a sum for all kind of different contribution. De Vet et al. (2015) shown that a Manning value of 0.04 leads to good agreement in morphological development during Sandy for New York. Nederhoff et al. (2015) did a similar calibration however with a Chezy coefficient and for the state of New Jersey, however this lead to a similar dimensionless friction value.

Step 6: Post-processing: make graphs and animations¶

When one is happy with its result (in terms of skill score) post processing needs to be carried out. Post processing is the term used for all work related to making figures, animations and graphs. An example of an XBeach animation can be foud here (https://www.youtube.com/watch?v=qw7kvt-aBdU) or in

Pre (top panel) and post Sandy (lower panel) in a three dimensional plot with both bed and water levels. (Nederhoff et al., 2015) ?

References¶

De Vet, P. L. M., McCall, R. T., Den Bieman, J. P., Stive, M. J. F., Van Ormondt, M. (2015). Modelling dune erosion, overwash and breaching at Fire Island (NY) during Hurricane Sandy. Proceedings Coastal Sediments, San Diego, CA.

Donnelly, C. (2007). Morphologic Change by Overwash : Establishing and Evaluating Predictors. Journal of Coastal Research, (50), 520–526.

National Hurricane Center. (2012). Hurricane Sandy Advisory Archive.

Lopez-Feliciano, O. L. (2014). Implementation of CMS high resolution model to study morphology change in a groin field during Hurricane Sandy. Hoboken, New Jersey.

Nederhoff, C. M. (2014). Modeling the effects of hard structures on dune erosion and overwash Hindcasting the impact of Hurricane Sandy on New Jersey.

Nederhoff, C. M., Lodder, Q. J., Boers, M., Den Bieman, J. P., & Miller, J. K. (2015). Modeling the effects of hard structures on dune erosion and overwash - a case study of the impact of Hurricane Sandy on the New Jersey coast. Proceedings Coastal Sediments, San Diego, CA.

Roelvink, J. A., Reniers, A. J. H. M., van Dongeren, A. R., van Thiel de Vries, J. S. M., McCall, R. T., & Lescinski, J. (2009). Modelling storm impacts on beaches, dunes and barrier islands. Coastal Engineering, 56(11-12), 1133–1152. doi:10.1016/j.coastaleng.2009.08.006

Sallenger, A. (2000). Storm impact scale for barrier islands. Journal of Coastal Research, 16(3), 890–895.

Van Ormondt, M. (2014). Delft3D model of waves and surge among the East coast of the USA. Personal communication. Deltares, Delft.

Van Rijn, L. C. (2003). The predictability of cross-shore bed evolution of sandy beaches at the time scale of storms and seasons using process-based models. Coastal Engineering, 47(3), 295–327. doi:10.1016/S0378-3839(02)00120-5

Van Thiel de Vries, J. S. M. (2009). Dune erosion during storm surges. PhD thesis, Delft Unversity of Technology, Delft.

Cloud computing with XBeach¶

by Marco Westra MetOcean Consult

In this tutorial discusses the possibilities of cloud computing for XBeach (Roelvink et al., 2009) on two different cloud computing systems is presented. Cloud computing is a web service that provides resizable compute capacity in the cloud. A simple web service interface allows the user to obtain and configure capacity with minimal friction. Cloud computing reduces the time required to obtain and boot new machine to minutes, allowing the user to quickly scale capacity, both up and down, as your computing requirements change.

The cloud computing systems analysed in this memo are Amazon EC2 (Chapter 2) and Microsoft Azure (Chapter 3). The focus of this analysis is to identify the possibilities per system and to determine the best option in terms of price per XBeach simulation. This analysis is carried out for WP5 (Application at case studies sites) within the RISC-KIT program in order to provide partners that do not have high speed computational facilities with an alternative. The conclusions are presented in Chapter 4.

Amazon EC2¶

Amazon offers via AWS (Amazon Web Services) several possibilities of cloud computing (EC2: Elastic Compute Cloud). The possibilities of the on-demand instances are tested. There are however also possibilities with so-called reserved instances. This can potentially save up to 75% in prices, but doesn’t have the flexibility of the on-demand services. An Instance is the name for a computer / virtual machine. In this memo the possibilities of the UNIX-environment (Linux) are tested.

More information about the cloud computing possibilities of Amazon can be found on their website: http://aws.amazon.com/ec2/.

Creating an account¶

Creating an account at Amazon is quite easy. On top of that there is a free tier that is designed to enable to get hands-on experience with AWS at no charge for 12 months after you sign up. After creating your AWS account you can use any of the 21 products and services (EC2 is one of them). You can sign up for the AWS’s free tier with the following steps:

Sign-up for an AWS account.
Enter your billing address and credit card information. You will not be charged unless your usage exceeds the free usage tiers.
Start using AWS choosing from any of the products listed below.
For XBeach simulations you need to select the Amazon EC2

dummy bla bla

Hydrodynamics in ports using XBeach¶

Introduction¶

This guideline describes how to use XBeach in harbour applications. The main focus of this application is to predict wave motions in harbours. XBeach has been developed to predict the impact of storms on coastal areas, where the long waves (i.e. surfbeat, infragravity waves) are relevant. These long wave motions are also relevant in harbours, because it can interrupt harbour operations or causes hazardous situations for vessels. XBeach surfbeat could be an alternative for the existing calculation models because of its reasonable computational time and the ability to fully resolve long waves. For example, it might serve as a first estimate to predict possible resonance in the harbour. If short waves are not to be neglected, a switch is easily made to the more complete non-hydrostatic mode within XBeach. This is also of interest because it is able to compute both the primary and (second order) long waves, but at the expense of the computational ease. Wong (2016) studied the applicability of XBeach (both surfbeat and non-hydrostatic) in predicting wave climates and the determination of application limits for hydrodynamics in harbours in general. Based on his study, this guideline will first elaborate on the model choise in various situations, next it will give the necessary tips and tricks for setting up a typical harbour model.

Decision tree¶

Figure Fig. 31 shows a decision tree set up by Wong in order to make a well-considered choise of the XBeach mode in various situations. The first step is to decide in which waves you are interested, short or long (surfbeat or infragravity waves). When the interest is on short waves, the surfbeat mode has appeared to be not applicable as this model lacks several processes that are of importance in harbour situations (diffraction, reflection). For short waves in shallow water (kd < 1), Wong has proved that XBeach non-hydrostatic works quite well. In deeper water (kd > 1) the model is not recommended as XBeach uses only 1 vertical layer.

Modeling wave attenuation by vegetation (1D)¶

Introduction¶

Many coastlines around the world are fronted by vegetation (e.g. seagrass, mangroves, kelp, salt marsh) and recent studies have shown that the presence of aquatic vegetation can result in wave attenuation and flow reduction. In addition, these ecosystems may play a very important role of the coastal morphodynamics. To be able to take into account the effect of vegetation on coastal hydrodynamics in XBeach a vegetation module was developed (Van Rooijen et al., 2016; Roelvink et al., 2015). The main objective of this tutorial is to get familiar with the vegetation module of XBeach (Fig. 1).

Fig. 1. Snapshot of XBeach-Veg.

Case description¶

The tutorial is based on a large scale laboratory experiment that was carried out in Norway as part of the PhD project of S.M. Løvås at the Norwegian University of Science and Technology (Løvås, 2000; Løvås & Tørum, 2001, see Fig.2). The experiments were carried out in a wave tank and tests were carried out with and without mimic kelp vegetation (Fig. 3). The goal was to study the effect of the mimic kelp on wave propagation, velocities and dune erosion. For more background on this study, reference is made to Løvås & Tørum (2001).

Tutorial¶

The tutorial considers one of the experiments of Løvås, which was carried out twice: with and without the kelp vegetation present. In the directory (https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/vegetation_lab) you can find a number of files that can be of use:

Løvås & Tørum, 2001, Coastal Engineering paper (files/Literature)
Løvås & Tørum, 2000, ICCE Proceedings conference paper (files/Literature)
measured wave heights for test 1 (lovas_waves_test1.txt), this is the case without vegetation (files/Data)
measured wave heights for test 2 (lovas_waves_test2.txt), this is the case with vegetation (files/Data)

Based on this information you can set up two seperate models that represent the experiments: one with vegetation and one without the vegetation. The resulting model files for both models are available in the ‘model_files’ directory (files/Model). In addition to the standard XBeach input files (e.g. params, grid, bathymetry, wave conditions), this directory contains the following vegetation files:

veggiefile (‘vegetation.txt’) - this file describes which vegetation types are present in the model (in this case only one)
veggiemapfile (‘kelpbed.txt’) - this file describes which vegetation type is present at each grid point (0 = no vegetation, 1 = type 1, 2 = type 2 etc.)
veggiecharsfile (‘kelp.txt’) - this files describes the characteristics of the specific vegetation type (number of sections, height, stem diameter, density, drag coefficient), each vegetation type should have its own veggiecharsfile.

Using the XBeach MATLAB Toolbox¶

For users that have access to MATLAB, it is recommended to download the XBeach MATLAB Toolbox, which can be accessed via the Open Earth initiative (https://publicwiki.deltares.nl/display/OET/OpenEarth). The toolbox contains a variety of handy functions that can help you set up your model. To give you an idea on how you can use the toolbox for this particular tutorial, a script was added that will generate all the model files itself (‘files/MatlabScripts/setup_lovas_model.m’, see screenshot Fig. 4). In addition, a script is added that can plot some of the results (‘files/MatlabScripts/plot_lovas.m’).

Please note that XBeach is entirely independent from MATLAB and you do not need MATLAB in order to use XBeach. It is, however, handy for pre- and postprocessing.

Fig.4. Screenshot of MATLAB script that can be used to set up the model (‘files/MatlabScripts/setup_lovas_model.m’).

References¶

Løvås, S. M., & Tørum, A. (2001). Effect of the kelp Laminaria hyperborea upon sand dune erosion and water particle velocities. Coastal Engineering, 44(1), 37-63.

Løvås, S. M. (2000). Hydro-physical conditions in kelp forests and the effect on wave damping and dune erosion: A case study on Laminaria hyperborea. Norwegian University of Science and Technology.

Roelvink, D., van Dongeren, A., McCall, R., Hoonhout, B., van Rooijen, A., Van Geer, P., De Vet, L., Nederhoff, K. & Quataert, E. (2015). XBeach Technical Reference: Kingsday Release.

van Rooijen, A. A., McCall, R. T., van Thiel de Vries, J. S. M., van Dongeren, A. R., Reniers, A. J. H. M., & Roelvink, J. A. (2016). Modeling the effect of wave?vegetation interaction on wave setup. Journal of Geophysical Research: Oceans.

Modeling wave attenuation by vegetation (2D)¶

Introduction¶

Many coastlines around the world are fronted by vegetation (e.g. seagrass, mangroves, kelp, salt marsh) and recent studies have shown that the presence of aquatic vegetation can result in wave attenuation and flow reduction. In addition, these ecosystems may play a very important role of the coastal morphodynamics. To be able to take into account the effect of vegetation on coastal hydrodynamics in XBeach a vegetation module was developed (Van Rooijen et al., 2016; Roelvink et al., 2015). The main objective of this tutorial is to get familiar with the vegetation module of XBeach. All files mentioned below can be found in https://github.com/openearth/xbeach-docs/tree/master/docs/tutorials/vegetation_field2d.

Tutorial¶

In this tutorial you will set up an idealized 2D XBeach model with mangrove vegetation, which is based on the study by Phan et al. (2014), see ‘files/Literature/Phan - 2014 - Coastal Mangrove Squeeze in the Mekong Delta.pdf’. The idealized case considers a coastal profile with the offshore boundary at z = -8 m and a constant slope of 1/150 up to z = 2 m. From there a sea dike with slope of 1/3 and height of 5 m characterizes the profile. The mangroves are located between MSL (z = 0 m) and z = 2 m. We furthermore assume a storm surge level of z = +3 m, a wave height Hm0 of 2m and a wave peak period of 6 second. The goal is to study the wave dissipation by the mangrove trees, for which the vegetation characteristics can be obtained from Phan et al. (2014). Fig. 1 shows a possible model setup, and the resulting model input files can be found under ‘files/Model’.

Fig. 1. XBeach-Veg model setup for 2D mangrove case.

MATLAB Toolbox for XBeach¶

For users that have access to MATLAB, it is recommended to download the XBeach MATLAB Toolbox, which can be accessed via the Open Earth initiative (https://publicwiki.deltares.nl/display/OET/OpenEarth). The toolbox contains a variety of handy functions that can help you set up your model. To give you an idea on how you can use the toolbox for this particular tutorial, a script was added that will generate all the model files itself (‘files/MatlabScripts/setup_xbveg_2D.m’). This script makes use of another file that defines the area with mangroves (‘files/MatlabScripts/mangrove_forest.txt’). In addition, a script is added that can plot some of the results (‘files/MatlabScripts/plot_waveheight.m’, see also Fig.2).

Please note that XBeach is entirely independent from MATLAB and you do not need MATLAB in order to use XBeach. It is, however, handy for pre- and postprocessing.

Fig. 2. Sea swell and infragravity wave height as computed by XBeach.

Holland Default¶

The Holland Default example simulates the response of the typical cross-shore profile of the Dutch coast to normative storm conditions. In this tutorial this simulation will be built up step by step. The resulting model schematization can be found here: https://svn.oss.deltares.nl/repos/xbeach/skillbed/input/holland_default/

For this tutorial, you should have XBeach Kingdsday release or later installed on your pc, as well as the XBeach open earth tools. Furthermore a measured or schematized cross shore profile is required as model geometry.

Grid and bathymetry¶

The starting point of any 1D XBeach computation is the depth profile mentioned above, it is recommended to either cut off or extend this to the 20 m depth contour. Based on this geometry, the computational grid and bathymetry can be constructed. Three files will have to be made:

x.grd

This is the cross-shore grid in plain ascii format. With default nautical direction conventions positive x direction is due east. In this case the grid is non-equidistant, with a coarse offshore resolution and increasing resolution towards shore. The x.grd can be generated automatically using the Matlab function xb_grid_xgrid.m found in the Open Earth Tools (see https://publicwiki.deltares.nl/display/OET/OpenEarth). The function helps to ensure that some numerical criteria such as grid points per wave length are met.
y.grd

This is the longshore grid, which in this case contains only zeroes (with a length equal to the x.grd). This type of simulation thus is of the ‘fast 1D’ type (see section ‘Grid and bathymetry’ of the manual.
bed.dep

In this file (which is also in plain ascii) the z-values (default positive upwards) corresponding to the grid points in x.grd are put. Note that for XBeach to work properly at the seaward boundary at least a single horizontal cell is required. Such an adaption to the profile will have to be added manually.

Example Matlab code to quickly generate these files:

[xgr zgr] = xb_grid_xgrid(Xin,Zin);
ygr = zeros(size(xgr));
save('y.grd','ygr','-ascii');
save('x.grd','xgr','-ascii');
save('bed.dep','zgr','-ascii');

Wave boundary input: jonswap.txt¶

In this example the model will be forced by a spectral condition, that is not varying in time. The parameters to describe this condition are written down in a single file, which may contain the following keywords (if omitted, default values are assumed):

Hm0 = 7.6000

Significant wave height.
fp = 0.0833

Peak frequency of the wave spectrum (=1/Tp)
mainang = 270.0000

Main incident wave angle. According to the XBeach direction conventions (default nautical) 270 degrees implies incident from the West.
gammajsp = 3.3000

Peak enhancement factor (default) corresponding in this case to a JONSWAP spectrum shape.
s = 10,000

Directional spreading. See the manual on how s is related to directional spreading in degrees (Input description/Waves input/Spectral wave boundary conditions). Note that in this simulation there is only a single directional wave bin (see next section). This implies that waves can only propagate in a single direction. Directional spreading in this case therefore does not influence the amount of losses of wave energy outside the domain, but it does influence the groupiness of the waves on th emodel boundaty and therefore infra-gravity wave generation. It is thus recommended to input a high directional spreading parameter in a 1D computation, corresponding to waves without significant directional spread.
fnyq = 1.0000

Nyquist frequency. Energy of waves with a frequency higher than this frequency is mirrored around the Nyquist frequency over the other frequencies. This value should not lie closely to the characteristic frequency of the spectrum.

Main input file: params.txt¶

The params file is the main input file of any XBeach simulation. A minimal set of default parameters, supplemented by your own case-specific settings, can be generated using the Matlab function xb_generate_settings.m. For this case the following keywords are included in the params file:

Grid parameters
- depfile = bed.dep
  
  Reference to the file with the bathymetry generated under section 1 of this tutorial.
- nx = 230
  
  Indicates that there are 230 grid cells (and thus 231) grid points (entrees in the x.grd file).
- ny = 0
  
  Indicating zero alongshore grid cells, which makes the model of the (fast) 1Dv type.
- alfa = 0
  
  The rotation of the grid. See the image in this paper for an explanation: https://oss.deltares.nl/documents/48999/59759/Roelvink_2009.pdf
- vardx = 1
  
  Indicating that the grid in x direction is non-equidistant.
- xfile = x.grd
  
  Reference to the cross-shore grid file.
- yfile = y.grd
  
  Reference to the alongshore grid file.
- xori = 0
  
  The world coordinate of the x origin (not relevant in this simulation)
- yori = 0
  
  The world coordinate of the y origin (not relevant in this simulation)
- thetamin = 225
  
  The lower directional dimension of the wave spectrum discretization.
- thetamax = 315
  
  The upper directional dimension of the wave spectrum discretization.
- dtheta = 90
  
  The size of the direction bins. In this case dtheta = thetamax – thetamin, which implies there is only a single directional bin. This makes the model in essence resemble a laboratory wave flume in which waves can propagate in one direction only and no wave energy is lost through the sides of the wave flume.
- thetanaut = 1
  
  Specifies that thetamin and thetamax are input according the nautical convention as opposed to the cartesian convention.
Initial conditions
- zs0 = 5
  
  Initial water level is at +5m. In the Netherlands this is typically at the toe of the dunes during storm set-up.
Model time
- tstop = 18000
  
  As an example a period of 5 hours is modeled.
Wave boundary condition parameters
- instat = jons
  
  The type of the wave boundary condition is JONSWAP. See http://xbeach.readthedocs.io/en/latest/_images/image24.png on how to arrive at the proper wave boundary type for your own simulation.
- random = 0
  
  XBeach generates a wave time series. With the switch random = 0 this time series does not have a randomness (i.e. it will always be the same time series for each repeat of the simulation).
Wave-spectrum boundary condition parameters
- bcfile = jonswap.txt
  
  The file containing the wave boundary conditions (see below).
- rt = 1800
  
  The reuse time of the generated wave time series. In this case a time series of a duration of half an hour is generated, which is reused 10 times to complete the entire (5 hour) simulation.
- dtbc = 1
  
  The discretization time step of the time series, which is 1s in this case. This should typically be a small value, taking into account the Nyquist frequency as well (see above).
Output variables
- tstart = 0
  
  The model output starts to be generated at t=0. If you for example have a spin-up time in which you are not interested in the output you can postpone output generation with this keyword.
- tintg = 3600
  
  Gap between which global (instantaneous) output is written to file. Also mean output can be saved, which is specified with tintm.
- outputformat = netcdf
  
  Format of the output.
- nglobalvar = 1
  
  The amount of global output variables that have to be written to file.
- zb
  
  The bed level is the only output variable. The output will contain 6 profiles (the initial and tstop/tintg = 5 other profiles).

Running the model¶

It is assumed here that you are running under windows (see [LINK] for other platforms). The XBeach executable that should be placed somewhere on your pc, for example on: d:\Software\XBeach\2015-10-22_XBeach_v1.22.4867_Kingsday_x64_netcdf\xbeach.exe

Which can be run via a batch file containing a reference to that path, like this:

>>> call d:\Software\XBeach\2015-10-22_XBeach_v1.22.4867_Kingsday_x64_netcdf\xbeach.exe

Or by navigating in a command window to your folder containing the model files and executing the above line.

Post-processing your model results¶

Results can be visualized using the following Matlab code. Note that you must have the Open Earth Tools loaded.

clear;
%read the output
xb = xb_read_output('xboutput.nc');
[zb, DIMS] = xs_get(xb,'zb','DIMS');
xgr = xs_get(DIMS,'x');

%plot the output
plot(xgr,zb,'linewidth',2);
legend({'Initial profile','t=1hr','t=2hr','t=3hr','t=4hr','t=5hr'},'location','northwest')
xlabel('x [m]'); ylabel('z [m]')
xlim([2200 3000]); ylim([-5 16])
grid on; title('Holland default XBeach simulation')

Advanced techniques¶

Traditionally, XBeach is used as a standalone executable that is ran on a single XBeach model schematization, possibly distributed over multiple processes through MPI. Nowadays, XBeach can also be used as a BMI-compatible library. A library can be part of a larger framework where XBeach interacts with other components during runtime. For example:

A graphical user interface (e.g. Morphan).
An interactive modeling tool that allow users to change the model while running (e.g. Sandbox).
A coupled model where XBeach runs simultaneously and interactively with other models (e.g. aeolian sediment transport model, ecological model or XBeach itself!).

The XBeach library (DLL) for Windows is shipped with the daily builds from the Deltares build server. A unix library is compiled alongside the XBeach executable.

Tools¶

XBeach Matlab Toolbox (tutorial)¶

Set-up model¶

XBeach is configured using a collection of files that hold information on the bathymertry, boundary conditions, model settings, etcetera. All files are plain text files that should be in a single directory, the model run directory. Running the XBeach executable in this directory, will make XBeach use those files and save the model output in the very same directory.

Using the Matlab Toolbox, setting up your model is made much easier. On this page we explain how to set-up a simple model using the Matlab Toolbox. The toolbox creates a bunch of files, which we will explain. Setting up a model manually, without the toolbox, implies creating these files in any other way of your preference. A collection of example models can be found in the Documentation section.

Generate model with xb_generate_model¶

Having started Matlab and incLuded the Matlab XBeach Toolbox to your path, you should be able to run the following command:

xbi = xb_generate_model;

When done, the xbo variable now contains a structure with a full XBeach model set-up. You can write the model to disk by running the following command:

xb_write_input('params.txt', xbi);

The file params.txt, which contains all model settings, is now written to your current directory along with several other files which are referred to from the params.txt file. The different files are listed below:

File	Description
params.txt	File with model settings. Each line containing an =-sign and not starting with a %-sign is interpreted as a model setting in the form “name = value”. This file is obligatory when running XBeach. It also refers to the other files.
bed.dep	File with bathymetry information. It simply contains the heights for all grid points. On row corresponds to one cross-shore transect. This file is obligatory when running XBeach.
x.grd	File with x-coordinates of the grid. This file is only used with a non-equidistant grid.
y.grd	File with y-coordinates of the grid. This file is only used with a non-equidistant two-dimensional grid.
jonswap.txt	File with boundary condition information. In this case the description of a JONSWAP spectrum. Severel flavours exist for this file. This one has a syntax similar to the params.txt file.

When we open the file params.txt with a text editor, we get the following content:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% XBeach parameter settings input file                                     %%%
%%%                                                                          %%%
%%% date:     29-Jun-2016 07:40:37                                           %%%
%%% function: xb_write_params                                                %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% Grid parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

depfile   = bed.dep
posdwn    = 0
nx        = 580
ny        = 0
alfa      = 0
vardx     = 1
xfile     = x.grd
yfile     = y.grd
xori      = 0
yori      = 0
thetamin  = 225
thetamax  = 315
dtheta    = 90
thetanaut = 1

%%% Initial conditions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

zs0       = 5

%%% Model time %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

tstop     = 2000

%%% Wave boundary condition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

instat    = jons

%%% Wave-spectrum boundary condition parameters %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

bcfile    = jonswap.txt
rt        = 1800
dtbc      = 1

%%% Output variables %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The files describe a simple one-dimensional model with a schematized dune profile (see Figure) and a statistically constant boundary conditions described by a JONSWAP spectrum with a significant wave height of 7.6m and a peak wave period of 12s.

Arguments of the xb_generate_model¶

See also

xb_generate_model

The model created in the previous example uses default settings only, which is not very interesting. Altering the model is done by supplying preferences to the function xb_generate_model as shown in the next example:

xbi = xb_generate_model( ...
         'bathy',    { 'x', x, 'z', z, 'xgrid', {'vardx', 0} }, ...
         'waves',    { 'Hm0', 9, 'Tp', 18 }, ...
         'tide',     { 'front', 5, 'back', 0 }, ...
         'wavegrid', { 'nbins', 5 }, ...
         'settings', { 'tstop', 7200, 'morfac', 5 });

Now, two vectors x and z with bathymetry information are supplied. The toolbox generates a grid based on the bathymetry and wave conditions. In this case the grid will not vary in x-direction (vardx=0). The boundary conditions in terms of significant wave height and peak wave period are changed and the tidal surge is now different for the offshore and onshore boundary. The number of wave direction grids is increased to 5 in order to support directional spreading. The simulation end time is set to 7200 seconds morphological time with a morphological factor of 5. For all possible settings is referred to the documentation of the Matlab Toolbox and the XBeach model.

In the next example the tidal surge and wave boundary conditions are made varying by supplying multiple values for several parameters:

xbi = xb_generate_model( ...
   'bathy',    { 'x', x, 'z', z, 'xgrid', {'vardx', 0} }, ...
   'waves',    { 'Hm0', [5 7 9 7 5], 'Tp', [12 14 18 14 12], 'duration', 1800 }, ...
   'tide',     { 'front', [4 5 4], 'back', 0, 'time', [0 3000 6000] }, ...
   'wavegrid', { 'nbins', 5 }, ...
   'settings', { 'tstop', 45000, 'morfac', 5 });

Be aware that the xb_generate_model function adapts different model parameters to eachother. Like it adapts the grid to the boundary conditions. Model settings can also be changed after a model is generated. In that case, the correlation between different parameters might be lost.

Run model¶

You can run your model by simply executing the XBeach executable in the directory where you wrote your models settings to. This is the directory where the params.txt file is located.

If your created your model using the Matlab Toolbox, you can run the model from within Matlab. As shown in the previous step, you can store an entire XBeach model setup in a single Matlab variable. To run this model, simply use one of the following commands:

xbr = xb_run(xbi);
xbr = xb_run(xbi, 'binary', 'xbeach.exe', 'name', 'MyFirstXBeachModel');

When you use the first command, a directory with a unique name is created in your current working directory. The model setup is written to that directory, the latest XBeach executable is downloaded from this open-source software portal and the model is run. The function returns a structure with information on the run just started.

When you want to use another executable, you can define the executable using the binary option. Also, you can give the run a name, which is used as directory name as well. This is shown in the second command.

If you have a UNIX cluster available running Sun Grid Engine (SGE), you might be able to use the remote version of the run command. The cluster should be able by SSH. The command looks like this:

xbr = xb_run_remote( ...``
         'binary', 'xbeach', 'name', 'MyFirstXBeachModel', ...
         'ssh_host', 'h4', 'ssh_prompt', true);

Visualize results¶

Once your model finished running, it is time to have a look at the model output. Two types of output can be generated: Fortran and netCDF. The former type generates a series of DAT files as output, while the latter generates a single NC file with all data in it. The Matlab Toolbox supports both and there are no significant differences in the usage of the commands shown.

To have a quick view on your model output, use the xb_view command. This command works as well while the model is still running. Just run the command in the model directory, supply the model directory or supply the result structure from the xb_run command:

xb_view;
xb_view('MyFirstXBeachModel/');
xb_view(xbr);

The result will be somethink like this:

If you need to manipulate the output data or the visualization a bit more than the xb_view command offers, you will need to load the output data. The output is read using the xb_read_output command, which stores the data in an XBeach structure. The xs_peel command converts this structure to a regular structure with matrices with dimensions time, y and x. The dimensions itself are read by the xb_read_dims command. Try the following commands to figure out how it all works:

xbo = xb_read_output;
xbo = xb_read_output('MyFirstXBeachModel/');
xbo = xb_read_output(xbr);

xbo = xb_read_output(pwd, 'vars', 'H');
xbo = xb_read_output(pwd, 'vars', {'H' 'zb'});
xbo = xb_read_output(pwd, 'vars', {'H' 'zb'}, 'length', 1);
xbo = xb_read_output(pwd, 'vars', {'H' 'zb'}, 'length', [1 1 -1]);
xbo = xb_read_output(pwd, 'vars', {'H' 'zb'}, 'length', [1 1 -1], 'start', 100);
xbo = xb_read_output(pwd, 'vars', {'H' 'zb'}, 'length', [1 1 -1], 'start', [100 2 1]);
xbo = xb_read_output(pwd, 'vars', {'H' 'zb'}, 'length', [1 1 -1], 'start', [100 2 1], 'stride', [1 1 5]);
xbo = xb_read_output(pwd, 'vars', '*_mean');
xbp = xs_peel(xbo);
xs_peel(xbo);

xbd = xb_read_dims;
xbd = xb_read_dims('MyFirstXBeachModel/');
xbd = xb_peel(xbp.DIMS);

plot(xbd.x, squeeze(xbp(end,1,:)));

Analyze results¶

What we did so far is setting-up and running a simple model and visualizing the results. The visualization was limited to a plain representation of the model output. Often, it is necessary to obtain insight in the overall characteristics of the model results in wave propagation and erosion progression in terms of volumes or retreat distances. This section describes a few simple tools to extract these characteristics from the model output.

Analysis methods for the following aspects of dune and beach morphology are currently available:

Profiles

Hydrodynamics

Sediment transports

Morphodynamics

The following collection of commands and screenshots provide an overview of what is possible. Of course, you are encouraged to write your own analysis scripts and, if generally applicable, provide it to the community!

Profiles¶

xb_plot_profile(xbo);

Hydrodynamics¶

xbh = xb_get_hydro(xbo);
xb_plot_hydro(xbh);
xb_plot_hydro2(xbh);

Sediment transports¶

xbs = xb_get_sedtrans(xbo);
xb_plot_sedtrans(xbs);

Morphology¶

xbm = xb_get_morpho(xbo);
xb_plot_morpho(xbm);

XBeach Matlab Toolbox (reference)¶

The XBeach Matlab toolboxes accomodates several frequantly used pre- and post-processing scripts for the XBeach model. Be aware that this toolbox is not exhaustive. XBeach has many more functionalities than exposed by this toolbox. Also note that this toolbox is not required to run XBeach. You can run XBeach by providing the right input text files in any way that suits your situation best

xb_analysis: Perform analysis on XBeach results
xb_gui: Simple gui to setup XBeach models (deprecated)
xb_io: Read and write XBeach files
xb_lib: General functions
xb_modelsetup: Facilitate model set-up, including grid optimization
xb_nesting: Routines to nest an XBeach model in another model (Delft3D or WW3)
xb_run: Routines to run XBeach models from Matlab, also support remote running on UNIX clusters
xb_testbed: Routines to facilitate XBeach testing in the testbed/skillbed
xb_visualise: Facilitate model output visualisation

xb_analysis¶

xb_get_activeprofile¶

XB_GET_ACTIVEPROFILE  Determines the range of the profile that is active

Determines the x-range of the profile that is active by locating the
area in which a certain percentage of the bed level change is located.
By default, this percentage is 90%.

Syntax:
[x ix] = xb_get_activeprofile(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = dzfrac:     Fraction of total profile change that should be
                        included in the range returned

Output:
x         = Array with minimum and maximum x-locations with in between
            the requested percentage of bed level change
xi        = Array with the corresponding indices in the x-grid

Example:
x = xb_get_activeprofile(xb)
[x xi] = xb_get_activeprofile(xb)
[x xi] = xb_get_activeprofile(xb, 'dzfrac', .8)

See also

xb_get_profilespecs

xb_get_coastline¶

XB_GET_COASTLINE  Determines coastline from 2D grid

Determines coastline based on 2D grid by first determining the
orientation of the grid and than finding the first grid cell that
exceeds a certain elevation (default 0).

TODO: add interpolation option

varargout = xb_get_coastline(varargin)

Syntax:

Input:
x           = x-coordinates of bathymetric grid
y           = y-coordinates of bathymetric grid
z           = elevations in bathymetric grid
varargin    = level:        Level that needs to be exceeded
              interpolate:  Boolean flag to determine whether result
                            should be interpolated to obtain a better
                            apporximation

Output:
xc          = x-coordinates of coastline
yc          = y-coordinates of coastline
dim         = cross-shore dimension (1 or 2)
dir         = landward direction (negative or positive)
idx         = logical matrix of the size of z indicating whether a cell
              is on the coastline or not (xc = x(idx) and yc = y(idx)
              if x and y are matrices of size of z)

Example:
xb_get_coastline

See also

xb_grid_orientation

xb_get_hydro¶

XB_GET_HYDRO  Compute hydrodynamic parameters from XBeach output structure

Compute hydrodynamic parameters like RMS wave heights over a
cross-section split in low and high freqnecy waves. The same is done
for orbital velocities and mean velocities. Also the water level setup
is computed, if possible. The results are stored in an XBeach
hydrodynamics structure and can be plotted with xb_plot_hydro.

Syntax:
xbo = xb_get_hydro(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = Trep:   repesentative wave period

Output:
xbo       = XBeach hydrodynamics structure

Example:
xbo = xb_get_hydro(xb)
xbo = xb_get_hydro(xb, 'Trep', 12)

xb_get_morpho¶

XB_GET_MORPHO  Compute morphological parameters from XBeach output structure

Compute morphological parameters like bed level change, erosion and
sedimentation volumes and retreat distances from XBeach output
structure. The results are stored in an XBeach morphology structure and
can be plotted with xb_plot_morpho.

Syntax:
xbo = xb_get_morpho(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = level:  assumed storm surge level

Output:
xbo       = XBeach morphology structure

Example:
xbo = xb_get_morpho(xb)
xbo = xb_get_morpho(xb, 'level', 0)

xb_get_profilespecs¶

XB_GET_PROFILESPECS  Determines a variety of profile characteristics from a dune profile

More detailed description goes here.

Syntax:
varargout = xb_get_profilespecs(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_get_profilespecs

See also

xb_get_sedbal¶

XB_GET_SEDBAL  Computes sediment balance from XBeach output structure

Computes total sedimentation, erosion and transports over domain
borders and determines total sediment budget continuity.

Syntax:
xbo = xb_get_sedbal(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = t:          time at which balance should be computed
                        (approximately)
            margin:     grid margin
            porosity:   porosity of bed
            morfac:     morphological factor between transports and bed

Output:
xbo       = XBeach sediment balance structure

Example:
xbo = xb_get_sedbal(xb);
xs_show(xbo);

See also

xb_read_output

xb_get_sedero¶

XB_GET_SEDERO  Compute sedimentation and erosion from profiles

Compute sedimentation and erosion from profile development in time. A
single x-axis and multiple z-axes are provided. Crossings with the
initial profile are computed and areas of erosion and sedimentation
distinguished. Based on a given surge level, the erosion volume and
retreat distance above surge level are computed.

Syntax:
[sed ero dz R Q P] = xb_get_sedero(x,z)

Input:
x         = x-axis vector
z         = z-axes matrix with time in first dimension
varargin  = level:      maximum surge level

Output:
sed       = total sedimentation volume
ero       = total erosion volume
dz        = profile change
R         = first profile crossing above surge level
Q         = last profile crossing below surge level
P         = one but last profile crossing below surge level

Example:
[sed ero] = xb_get_sedero(x, z, 'level, 5)

See also

xb_get_morpho

xb_get_sedtrans¶

XB_GET_SEDTRANS  Compute sediment transport parameters from XBeach output structure

Compute sediment transport parameters like sediment concentrations and
transport volumes from XBeach output structure. The results are stored
in an XBeach sedimenttransport structure and can be plotted with
xb_plot_sedtrans.

Syntax:
xbo = xb_get_sedtrans(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = Trep:   representative wave period
            rho:    sediment density
            por:    porosity

Output:
xbo       = XBeach sedimenttransport structure

Example:
xbo = xb_get_sedtrans(xb)

xb_get_spectrum¶

XB_GET_SPECTRUM  Computes a spectrum from a timeseries

Computes a spectrum from a timeseries. The result is stored in an
XBeach spectrum structure and can be plotted using the xb_plot_spectrum
function.

FUNCTION IS AN ADAPTED VERSION OF R.T. MCCALL'S MAKESPECTRUM FUNCTION
            WITH MODIFICATIONS FROM HIS SPECTRUMSIMPLE FUNCTION

Syntax:
xbo = xb_get_spectrum(ts, varargin)

Input:
ts        = Timeseries in columns
varargin  = sfreq:          sample frequency
            fsplit:         split frequency between high and low
                            frequency waves
            fcutoff:        cut-off frequency for high frequency waves
            detrend:        boolean to determine whether timeseries
                            should be linearly detrended before
                            computation
            filterlength:   smoothing window

Output:
xbo       = XBeach spectrum structure

Example:
xbo = xb_get_spectrum(ts)

xb_get_transect¶

XB_GET_TRANSECT  Squeezes an XBeach output structure to a single transect

Squeezes an XBeach output structure to a single transect

Syntax:
xb = xb_get_transect(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = transect:   transect number
            dim:        dimension that should be squeezed

Output:
xb        = squeezed XBeach output structure

Example:
xb = xb_get_transect(xb)
xb = xb_get_transect(xb, 'transect', 10)

xb_skill¶

XB_SKILL  Computes a variety skill scores

Computes a variety skill scores: R^2, Sci, Relative bias, Brier Skill
Score. Special feature: within the XBeach testbed, the results are
stored to be able to show the development of the different skill scores
in time.

Syntax:
[r2 sci relbias bss] = xb_skill(measured, computed, varargin)

Input:
measured  = Measured data where the first column contains independent
            values and the second column contains dependent values
computed  = Computed data where the first column contains independent
            values and the second column contains dependent values
initial   = Initial data where the first column contains independent
            values and the second column contains dependent values
varargin  = var:    Name of the variable that is supplied

Output:
r2        = R^2 skill score
sci       = Sci skill score
relbias   = Relative bias
bss       = Brier Skill Score

Example:
[r2 sci relbias bss] = xb_skill(measured, computed)
[r2 sci relbias bss] = xb_skill(measured, computed, 'var', 'zb')

xb_gui¶

XB_GUI  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_gui(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_gui

See also

xb_gui_crop¶

XB_GUI_CROP  Rotate and crop bathymetry

Aligns the coastline to the y-axis and enables the used to visually rop
the bathymetry. The result is the rotated, cropped bathymetry.

Syntax:
varargout = xb_gui_crop(x,y,z,varargin)

Input:
x         = matrix with x-values
y         = matrix with y-values
z         = matrix with z-values
varargin  = none

Output:
varargout = rotated and cropped versions of the x, y and z matrices

Example:
[xc yc zc] = xb_gui_crop(x,y,z)

See also

xb_gui_mergebathy

xb_gui_dragselect¶

XB_GUI_DRAGSELECT  Creates an drag and select interface

Creates an drag and select interface for maps. Can fire a function
after selection is complete. The function should take 5 arguments:
default object and event arguments, the drag-and-select object, the x
and y position of the selection.

Syntax:
xb_gui_dragselect(obj, varargin)

Input:
obj       = Object handle which should be drag-and-select enabled
varargin  = cursor:     Enables crosshair cursor
            select:     Enables area selection
            fcn:        Function handle to be fired after selection

Output:
none

Example:
xb_gui_dragselect(axes, 'select', true, 'cursor', false, 'fcn', @drawrectangle)

xb_gui_mergebathy¶

XB_GUI_MERGEBATHY  Merge bathymetries

Select JARKUS transects and Vaklodingen from a map, possible add some
ArcGIS files and XBeach bathymetries to this selection and generate a
merged bathymetry from these sources.

Syntax:
varargout = xb_gui_mergebathy

Input:
none

Output:
varargout = x:  x-coordinates
            y:  y-coordinates
            z:  z-coordinates

Example:
[x y z] = xb_gui_mergebathy

xb_gui_normconditions¶

XB_GUI_NORMCONDITIONS  Returns normative conditions based on location and frequency of exceedence

Returns normative conditions along the Dutch coast based on location
and frequency of exceedence according to probabilistic derivation of
hydraulic boundary conditions for VTV2006.
The location can be selected on a map or defined by a string that is
interpreted by Google Maps.

Syntax:
varargout = xb_gui_modelsetup_hydro_norm

Input:
none

Output:
varargout = h:      Storm surge level
            Hs:     Significant wave height
            Tp:     Peak wave period
            x:      x-coordinate of picked location (RD)
            y:      y-coordinate of picked location (RD)
            freq:   Selected frequency of exceedance

Example:
h = xb_gui_modelsetup_hydro_norm
[h Hs Tp] = xb_gui_modelsetup_hydro_norm
[h Hs Tp x y freq] = xb_gui_modelsetup_hydro_norm

See also

xb_gui_dragselect, xb_gui_mergebathy

xb_io¶

xb_dat2nc¶

XB_DAT2NC  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_dat2nc(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_dat2nc

See also

xb_get_dt¶

XB_GET_DT  Read series of (average) dt values from XBlog.txt file

Function to extract dt values from XBlog.txt file by means of regular
expression.

Syntax:
dt = xb_average_dt(XBlog, varargin)

Input:
XBlog  = filename including path of XBlog.txt

Output:
dt = array of dt values

Example:
xb_average_dt

See also

xb_get_output¶

XB_GET_OUTPUT  Reads the spaceparams.tmpl file from the XBeach source code into a struct

Reads the spaceparans.tmpl file from the XBeach source code into a
struct. The file contains information on the possible output variables,
their dimensions, name and description.

Syntax:
Input:
fpath   = Path to spaceparams.tmpl

Output:

Output:
output  = Structure array containing data from spaceparams.tmpl

output = xb_get_output
output = xb_get_output('spaceparams.tmpl')

Example:

See also

xb_get_params

xb_get_params¶

XB_GET_PARAMS  Reads XBeach parameter types and defaults from XBeach source code

Function to read XBeach params types and defaults from XBeach source
code (params.F90). Useful to link to latest trunk update.

Syntax:
[params params_array] = xb_get_params(xbdir)

Input:
xbdir           = Directory in which XBeach source code can be found.
                  If not given, an attempt is made to use a default
                  path.

Output:
params          = structure array with listing of every parameter in
                  XBeach, including type, name, units, comment,
                  parameter type, default, minimum recommended and
                  maximum recommended values data.
params_array    = array-version of params

Example:
[params params_array] = xb_get_params(xbdir)

See also

xb_read_params, xb_write_params

xb_get_varinfo¶

XB_GET_VARINFO  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_get_varinfo(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_get_varinfo

See also

xb_get_vars¶

XB_GET_VARS  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_get_vars(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_get_vars

See also

xb_get_wavefiletype¶

XB_GET_WAVEFILETYPE  Determines the type of wave definition file for XBeach input

Analyzes the contents of a wave definition file for XBeach input and
returns a string specifying the type of wave definition files.
Currently, the following types can be returned: unknown, filelist,
jonswap, jonswap_mtx, vardens, bcflist

Syntax:
type = xb_get_wavefiletype(filename)

Input:
filename  = filename of wave definition file to be analyzed

Output:
type      = string specifying the wave definition filetype
types     = wave definition filetypes available
counts    = matching scores of each filetype

Example:
type = xb_get_wavefiletype(filename)

See also

xb_read_params, xb_read_waves

xb_read_bathy¶

XB_READ_BATHY  Read xbeach bathymetry files

Routine to read xbeach bathymetry files.

Syntax:
xb = xb_read_bathy('xfile', <filename>, yfile, <filename>, depfile, <filename>, nefile, <filename>)

Input:
varargin    = xfile:    file name of x-coordinates file (cross-shore)
              yfile:    file name of y-coordinates file (alongshore)
              depfile:  file name of bathymetry file
              ne_layer: file name of non erodible layer file

Output:
xb          = XBeach structure array

Example:
xb = xb_read_bathy('xfile', xfile, 'yfile', yfile)

See also

xb_write_bathy, xb_read_input

xb_read_bcffile¶

XB_READ_BCFFILE  Reads a bcf file generated by XBeach

Reads a wave field realisation generated by XBeach.

Syntax:
data = xb_read_bcffile(filename, varargin)

Input:
filename  = Path to bcf file
varargin  = none

Output:
data      = Matrix with wave field data

Example:
xb_read_bcffile('E001.bcf')
xb_read_bcffile('Q001.bcf')

See also

xb_read_bcflist

xb_read_bcflist¶

XB_READ_BCFLIST  Reads bcflist files generated by XBeach

Reads ebcflist or qbcflist files generated by XBeach. The files contain
references to other files containing realized wave and flux fields. The
referred files are read as well. The result is retruned in the form of
a XBeach structure.

Syntax:
xb = xb_read_bcflist(filename, varargin)

Input:
filename    = filename of the ebcflist or qbcflist file to be read
varargin    = range:    unity-based numerical range of files to be read
                        (e.g. [4 5], 4 or [1 10])

Output:
xb          = XBeach structure array

Example:
xb = xb_read_bcflist(filename)

See also

xb_read_waves

xb_read_dat¶

XB_READ_DAT  Reads DAT formatted output files from XBeach

Reads DAT formatted output files from XBeach in the form of an XBeach
structure. Specific variables can be requested in the varargin by means
of an exact match, dos-like filtering or regular expressions (see
strfilter)

Syntax:
xb = xb_read_dat(fname, varargin)

Input:
fname       = directory name that contains the dat files.
varargin    = vars:     variable filters
              start:    Start positions for reading in each dimension,
                        first item is zero
              length:   Number of data items to be read in each
                        dimension, negative is unlimited
              stride:   Stride to be used in each dimension
              index:    Cell array with indices to read in each
                        dimension (overwrites start/length/stride)
              dims:     Force the use of certain dimensions in
                        xb_dat_read. These dimensions are used for all
                        requested variables!

Output:
xb          = XBeach structure array

Example:
xb = xb_read_dat('.')
xb = xb_read_dat('H.dat')
xb = xb_read_dat('path_to_model/')
xb = xb_read_dat('path_to_model/H.dat')
xb = xb_read_dat('.', 'vars', 'H')
xb = xb_read_dat('.', 'vars', 'H*')
xb = xb_read_dat('.', 'vars', '/_mean$')
xb = xb_read_dat('path_to_model/', 'vars', {'H', 'u*', '/_min$'})

See also

xb_read_output, xb_read_netcdf

xb_read_dims¶

XB_READ_DIMS  read dimensions from xbeach output

Routine to read the dimension from either netcdf of .dat xbeach output.
The input argument "filename" can be the directory of the xbeach
Syntax:
XBdims   = xb_read_dims(varargin)

Input:
filename = file name. This can either be a output folder, a dims.dat file
           or a xboutput.nc file.

Output:
"filename" is a directory, it is assumed that the dimensions should be
read from the "dims.dat" file inside the given directory.

Output:
XBdims   = structure containing the dimensions of xbeach output
           variables

Example:
xb_read_dims

See also

xb_read_input¶

XB_READ_INPUT  Read XBeach parameter file and all files referred in it

Reads the XBeach settings from the params.txt file and all files that
are mentioned in the settings, like grid and wave definition files. The
settings are stored in a XBeach structure. The referred files are
stored in a similar sub-structure.

Syntax:
xb = xb_read_input(filename)

Input:
filename   = params.txt file name
varargin   = read_paths:        flag to determine whether relative
                                paths should be read and included in
                                the result structure

Output:
xb         = XBeach structure array

Example:
xb = xb_read_input(filename)

See also

xb_read_params, xb_read_waves

xb_read_mpi_dims¶

XB_READ_MPI_DIMS  Reads the mpi dimensions from an XBlog file.

Scans the XBlog file and reads mpi domain dimensions when specified.
This function throws an exception when it was not possible to read the
dimensions (due to incorrect input or the fact that there is no
XBlog.txt file available, or the calculation was not run in mpi mode).

        For example:
                 0    1  107    1   63
                 1  106  106    1   63
                 2  210  106    1   63
                 3    1  107   62   62
                 4  106  106   62   62
                 5  210  106   62   62

Syntax:
dims = xb_read_mpi_dims(dr)

Input:
dr  = Directory where the XBlog file resides

Output:
dims = the n * 5 matrix included in the XBlog file that describes the
        mpi domain dimensions in which:
            First column:  domain number
            Second column: position of the left boundary in m direction (cross-shore)
            Third column:  Length of the domain in m direction (cross-shore)
            Fourth column: position of upper boundary in n direction (alongshore)
            Third column:  Length of the domain in n direction (alongshore)

Example:
dims = xb_read_mpi_dims('D:\testrun\');

See also

xb_plot_mpi

xb_read_netcdf¶

XB_READ_NETCDF  Reads NetCDF formatted output files from XBeach

Reads NetCDF formatted output file from XBeach in the form of an
XBeach structure. Specific variables can be requested in the varargin
by means of an exact match, dos-like filtering or regular expressions
(see strfilter)

Syntax:
variables = xb_read_netcdf(fname, varargin)

Input:
fname       = filename of the netcdf file
varargin    = vars:     variable filters
              start:    Start positions for reading in each dimension,
                        first item is zero
              length:   Number of data items to be read in each
                        dimension, negative is unlimited
              stride:   Stride to be used in each dimension
              index:    Cell array with indices to read in each
                        dimension (overwrites start/length/stride)

Output:
variables   = XBeach structure array

Example:
xb = xb_read_netcdf('xboutput.nc')
xb = xb_read_netcdf('xboutput.nc', 'vars', 'H')
xb = xb_read_netcdf('xboutput.nc', 'vars', 'H*')
xb = xb_read_netcdf('xboutput.nc', 'vars', '/_mean$')
xb = xb_read_netcdf('path_to_model/xboutput.nc', 'vars', {'H', 'u*', '/_min$'})

See also

xb_read_output, xb_read_dat

xb_read_output¶

XB_READ_OUTPUT  Reads output files from XBeach

Reads output files from XBeach. The actual work is done by either the
xb_read_dat or xb_read_netcdf function. This function only determines
which one to use. Specific variables can be requested in the varargin
by means of an exact match, dos-like filtering or regular expressions
(see strfilter)

Syntax:
varargout = xb_read_output(fname, varargin)

Input:
fname       = Path to the directory containing the dat files, a dat
              file or the netcdf file to be read. This can also be a
              XBeach run structure, which is translated to a path.
varargin    = vars:         variable filters

Output:
varargout = XBeach structure array

Example:
xb = xb_read_output('path_to_model/')
xb = xb_read_output('path_to_model/H.dat')
xb = xb_read_output('path_to_model/', 'vars', {'H', 'u*', '/_mean$'})
xb = xb_read_output('xboutput.nc')

xb_read_params¶

XB_READ_PARAMS  read XBeach params.txt file

Routine to read the xbeach settings from the params.txt file. The
settings are stored in a XBeach structure.

Syntax:
xb = xb_read_params(filename)

Input:
filename   = params.txt file name
varargin   = none

Output:
xb         = XBeach structure array

Example:
xb_read_params

See also

xb_read_input, xb_read_waves

xb_read_parlist¶

XB_READ_PARLIST  Read list of available parameters from output file or directory

Read list of available parameters from output file or directory.
Returns a cell array with names.

Syntax:
parlist = xb_read_parlist(fname, varargin)

Input:
fname     = output file or directory
varargin  = None

Output:
parlist   = cell array with parameter names

Example:
parlist = xb_read_parlist(pwd);

See also

xb_read_output

xb_read_ship¶

XB_READ_SHIP  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_read_ship(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_read_ship

See also

xb_read_tide¶

XB_READ_TIDE  Reads tide definition file for XBeach input

Reads a tide definition file containing a nx3 matrix of which the first
column is the time definition and the second and third column the water
level definition at respectively the seaward and landward boundary of
the model.

Syntax:
xb  = xb_read_tide(filename)

Input:
filename    = filename of tide definition file
varargin    = none

Output:
xb          = XBeach structure array

Example:
xb  = xb_read_tide(filename)

See also

xb_read_params, xb_write_tide

xb_read_waves¶

XB_READ_WAVES  Reads wave definition files for XBeach input

Determines the type of wave definition file and reads it into a XBeach
structure. If a filelist is given, also the underlying files are read
and stored. The resulting struct can be inserted into the generic
XBeach structure.

Syntax:
xb  = xb_read_waves(filename, varargin)

Input:
filename    = filename of wave definition file
varargin    = none

Output:
xb          = XBeach structure array

Example:
xb  = xb_read_waves(filename)

See also

xb_read_params, xb_write_waves

xb_write_bathy¶

XB_WRITE_BATHY  Writes XBeach bathymetry files from XBeach structure

Writes XBeach bathymetry files x, y, depth and non-erodable layers
based on a XBeach structure.

Syntax:
[xfile yfile depfile ne_layer] = xb_write_bathy(xb, varargin)

Input:
xb          = XBeach structure array
varargin    = path:         path to output directory
              xfile:        filename of x definition file
              yfile:        filename of y definition file
              depfile:      filename of depth definition file
              ne_layerfile: filename of non-erodable layer definition
                            file

Output:
varargout   = filenames of created definition files, if used

Example:
[xfile yfile depfile ne_layer] = xb_write_bathy(xb)

See also

xb_read_bathy, xb_write_input

xb_write_input¶

XB_WRITE_INPUT  Write XBeach params.txt file and all files referred in it

Writes the XBeach settings from a XBeach structure in a parameter file.
Also the files that are referred to in the parameter file are written,
like grid and wave definition files.

Syntax:
xb_write_input(filename, xb, varargin)

Input:
filename  = filename of parameter file
xb        = XBeach structure array
varargin  = write_paths:  flag to determine whether definition files
                          should be written or just referred
            xbdir:  option to parse xbeach code directory (to read
                    parameter info)

Output:
none

Example:
xb_write_input(filename, xb)

See also

xb_read_input, xb_write_params

xb_write_params¶

XB_WRITE_PARAMS  Write XBeach settings to params.txt file

Routine to create a XBeach settings file. The settings in the XBeach
structure are written to "filename". Optionally an alternative header
line or directory containing params.f90 can be defined.

Syntax:
varargout = xb_write_params(filename, xb, varargin)

Input:
filename   = file name of params file
xb         = XBeach structure array
varargin   = header:    option to parse an alternative header string
             xbdir :    option to parse an alternative xbeach code directory

Output:
none

Example:
xb_write_params(filename, xb)

See also

xb_write_input, xb_read_params

xb_write_plot¶

SAVEPLOT: provide figure handle, output directory and filename (without extension)

xb_write_ship¶

XB_WRITE_SHIP  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_write_ship(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_write_ship

See also

xb_write_tide¶

XB_WRITE_TIDE  Writes tide definition file for XBeach input

Writes a tide definition file containing a nx3 matrix of which the
first column is the time definition and the second and third column the
waterlevel definition at respectively the seaward and landward boundary
of the model. Returns the filename of the tide file.

Syntax:
filename = xb_write_tide(xb)

Input:
xb          = XBeach structure array
varargin    = path:     path to output directory
              filename: filename of tide definition file

Output:
filename    = filename to be referred in parameter file

Example:
filename = xb_read_tide(xb)

See also

xb_read_params, xb_read_tide

xb_write_waves¶

XB_WRITE_WAVES  Writes wave definition files for XBeach input

Writes JONSWAP or variance density spectrum files for XBeach input. In
case of conditions changing in time, a file list file is created
refering to multiple wave definition files. In case of a JONSWAP
spectrum, the file list file can be omitted and a single matrix
formatted file is created. Returns the filename of the file to be
referred in the params.txt file.

In order to generate time varying wave conditions, simply add an extra
dimension to the input arguments specifying the spectrum. The
single-valued parameters Hm0, Tp, dir, gammajsp, s fnyq, duration and
timestep then become one-dimensional. The one- and two-dimensional
parameters freqs, dirs and vardens then become two- and
three-dimensional respectively. It is not necessary to provide
time-varying values for all parameters. In case a specific parameter is
constant, simply provide the constant value. The value is reused in
each period of time. However, it is not possible to provide for one
parameter more than one value and for another too, while the number of
values is not the same.

Syntax:
filename = xb_write_waves(xb, varargin)

Input:
xb          = XBeach structure array that overwrites the
              default varargin options (optional)
varargin    = path:             path to output directory
              filelist_file:    name of filelist file without extension
              jonswap_file:     name of jonswap file without extension
              vardens_file:     name of vardens file without extension
              unknown_file:     name of unknown wave file without
                                extension
              omit_filelist:    flag to omit filelist generation in
                                case of jonswap spectrum

Output:
filename = filename to be referred in parameter file

Example:
filename = xb_write_waves(xb)

See also

xb_write_input, xb_read_waves

xb_io/xb_dat¶

xb_dat_dims¶

XB_DAT_DIMS  Returns the lengths of all dimensions of a XBeach DAT file

Returns an array with the lengths of all dimensions of a XBeach DAT
file. The functionality works similar to the Matlab size() function on
variables.

Syntax:
dims = xb_dat_dims(filename, varargin)

Input:
filename    = Filename of DAT file
varargin    = ftype:    datatype of DAT file (double/single)

Output:
dims        = Array with lengths of dimensions
names       = Cell array with names of dimensions (x/y/t/d/gd/theta)
type        = String identifying the type of DAT file
              (wave/sediment/graindist/bedlayers/point/drifter/2d)

Example:
dims = xb_dat_dims(filename)

See also

xb_dat_read, xb_read_dat

xb_dat_read¶

XB_DAT_READ  Bytewise reading of XBeach DAT files using strides

Reading of XBeach DAT files. Two read methods are available: minimal
reads and minimal memory. The former minimizes the number of fread
calls, while the latter minimizes the amount of data read into memory.
In case the number of reads is for both methods equal, the memory
method is used. This method is also used if the average number of reads
per item is less than with the read method. The method used can also be
forced. The requested data can be determined using start and end
indices for each dimension and strides. This approach is similar to the
netCDF toolbox. The dimensions of the DAT file provided are in general
in the order x,y,t. The dimension order of the output is t,y,x to match
the netCDF conventions. The start and end indices and strides should be
provided in t,y,x order. The result is a matrix containing the
requested data.

Preferences:
dat_method  = Force read method (read/memory)

            Preferences overwrite default options (not explicitly
            defined options) and can be set and retrieved using the
            xb_setpref and xb_getpref functions.

Syntax:
dat = xb_dat_read(fname, dims, varargin)

Input:
fname       = Filename of DAT file
dims        = Array with lengths of all dimensions in DAT file
varargin    = start:    Start positions for reading in each dimension,
                        first item is zero
              length:   Number of data items to be read in each
                        dimension, negative is unlimited
              stride:   Stride to be used in each dimension
              index:    Cell array with indices to read in each
                        dimension (overwrites start/length/stride)
              threshold:Fraction of items to read in order to switch to
                        read method
              maxreads: Maximum reads in memory method
              force:    Force read method (read/memory)

Output:
dat         = Matrix with dimensions defined in dims containing
              requested data from DAT file

Example:
dat = xb_dat_read(fname, [100 3 20]);
dat = xb_dat_read(fname, [100 3 20], 'start', 10, 'length', 90, 'stride', 2);
dat = xb_dat_read(fname, [100 3 20], 'start', [10 1 1], 'length', [20 -1 -1], 'stride', [2 2 2]);

xb_lib¶

xb_axes¶

XB_AXES  Returns the data axes corresponding to a certain variable

Returns all data axes corresponding to a certain variable, taking into
account the start, stride, length and index used.

Syntax:
varargout = xb_axes(xb, var, varargin)

Input:
xb        = XBeach output structure
var       = Variable name
varargin  = none

Output:
varargout = Data axes

Example:
[t y x] = xb_axes(xb, 'H');

See also

xb_view

xb_bathy2input¶

XB_BATHY2INPUT  Adds bathymetry to XBeach input structure

Adds bathymetry to XBeach input structure. Also supports non-erodible
layers.

Syntax:
xb = xb_bathy2input(xb, x, y, z, ne)

Input:
x   = x-coordinates of bathymetry
y   = y-coordinates of bathymetry
z   = z-coordinates of bathymetry
ne  = non-erodible layers in bathymetry

Output:
xb  = XBeach input structure array

Example:
xb = xb_bathy2input(xb, x, y, z)

xb_check_stagger¶

XB_CHECK_STAGGER  Compare xb_stagger output to xbeach spaceparams

More detailed description goes here.

Syntax:
varargout = xb_check_stagger(xb, varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb = xb_read_output('xboutput.nc', 'length', 1)
xb_check_stagger(xb)

See also

xb_defpref¶

XB_DEFPREF  Sets default preferences for XBeach Toolbox

Sets default preferences for XBeach Toolbox

Syntax:
xb_defpref()

Input:
none

Output:
none

Example:
xb_defpref;

See also

xb_setpref, xb_getpref

xb_dims2nc¶

XB_DIMS2NC  Convert DAT formatted dimensions to NC formatted dimensions

Does some dimension flipping.

Syntax:
[nc_dims dat_dims idx_dims] = xb_dims2nc(dat_dims)

Input:
dat_dims  = dimensions in DAT file

Output:
nc_dims   = dimensions in NC file
dat_dims  = dimensions in DAT file, guaranteed to have 3 or more items
idx_dims  = index vectors to convert DAT dims to NC dims

Example:
nc_dims = xb_dims2nc(dat_dims)

See also

xb_read_dims

xb_getpref¶

XB_GETPREF  Gets values for XBeach Toolbox preferences

Gets values for XBeach Toolbox preferences and initlises default
preferences if not done yet.

Syntax:
varargout = xb_getpref(varargin)

Input:
varargin  = list of preference names

Output:
varargout = list of corresponding preference values

Example:
version = xb_getpref('version');
[user pass] = xb_getpref('ssh_user', 'ssh_pass');

See also

xb_defpref, xb_setpref

xb_getprefdef¶

XB_GETPREFDEF  Gets values for XBeach Toolbox preferences or supplied default

Gets values for XBeach Toolbox preferences and initialises default
preferences if not done yet. Returns supplied default if no preference
is found.

Syntax:
varargout = xb_getprefdef(varargin)

Input:
varargin  = list of pairs with preference names and defaults

Output:
varargout = list of corresponding preference values

Example:
value = xb_getprefdef(name, default)

See also

xb_setpref

xb_index¶

XB_INDEX  Makes sure that start/len/stride are of equal and right len and contain no invalid values

Makes sure that start/len/stride are of equal and right len and
contain no negative or otherwise invalid values.

Syntax:
[start len stride] = xb_index(dims, start, len, stride)

Input:
dims      = Array with dimension sizes of original data (result of
            size())
start     = Starting indices per dimension
len       = Length per dimension
stride    = Strides per dimension

Output:
start     = Starting indices per dimension
len    = len per dimension
stride    = Strides per dimension

Example:
[start len stride] = xb_index(dims, start, len, stride)

See also

xb_dat_read, xb_read_netcdf

xb_input2bathy¶

XB_INPUT2BATHY  Reads bathymetry from XBeach input structure

Converts XBeach input structure to a bathymetry with x, y and z values.
Also supports reading of non-erodible layers.

Syntax:
[x y z ne] = xb_input2bathy(xb)

Input:
xb  = XBeach input structure array

Output:
x   = x-coordinates of bathymetry
y   = y-coordinates of bathymetry
z   = z-coordinates of bathymetry
ne  = non-erodible layers in bathymetry

Example:
[x y z] = xb_input2bathy(xb)

xb_reference¶

XB_REFERENCE  Creates a WIKI page with a params.txt reference

Creates a WIKI page with a params.txt reference

Syntax:
xb_reference(filename, varargin)

Input:
filename  = Filename of generated file
varargin  = type:       Type of file (wiki)

Output:
none

Example:
xb_reference('reference.txt')

See also

xb_get_params

xb_scale¶

XB_SCALE  Scales XBeach model input according to Vellings (1986)

Scales XBeach model input according to Vellings (1986). All scaling
dependent parameters should be present in the model input structure.

Syntax:
xb = xb_scale(xb, varargin)

Input:
xb          = XBeach input structure
varargin    = depthscale:   depthscale nd
              contraction:  horizontal contraction S
              zmin:         minimal z-value

Output:
xb          = Scaled XBeach input structure

Example:
xb = xb_scale(xb, 'depthscale', 40, 'contraction', 1.68)
xb = xb_scale(xb, 'depthscale', 40, 'contraction', 1.68, 'zmin', 0)

See also

xb_generate_model

xb_setpref¶

XB_SETPREF  Sets customised preferences for XBeach Toolbox

Sets customised preferences for XBeach Toolbox and initialises default
preferences if not done yet.

Syntax:
xb_setpref(varargin)

Input:
varargin  = name/value pairs of preferences

Output:
none

Example:
xb_setpref('interactive', false);
xb_setpref('interactive', false, 'ssh_user', ' ... ', 'ssh_pass', ' ... ');

See also

xb_defpref, xb_getpref

xb_stagger¶

XB_STAGGER  Computes staggered grids and gridcell properties from XBeach grid

Computes staggered grids for u-, v- and c-points and gridcell
properties like boundary lengths, cell areas and orientations from
XBeach grid. Works similar to the gridprops function from XBeach
itself.

The last character of each variable name indicates the location within
a grid cell for which the value is computed (z, u, v or c, see
illustration). The variable name further consists of x or y,
indicating a location in world coordinates, or of ds or dn, indicating
distances or surfaces in grid coordinates. The dsdn* variables are grid
cell surfaces. The alfa* variables are orientations of the specified
points.

     coast

   |   |   |
---+---c-u-+---  ^     ^
   |   v z |     | ds  |
---+---+---+---  v     | s
   |   |   |           |
---+---+---+---
   |   |   |

       <--->
         dn

   <-------
       n

      sea

Syntax:
g = xb_stagger(x, y)

Input:
x       = x-coordinates of z-points
y       = y-coordinates of z-points

Output:
g       = structure with grid information

Example:
g = xb_stagger(x,y);

See also

xb_generate_bathy

xb_swap¶

XB_SWAP  Swap dimensions of XBeach output matrices from new to old convention and back

Swaps dimensions of matrices in XBeach output structure from the order
t,y,x to x,y,t and back. Current order is determined based on dimension
information included in the XBeach structure (DIMS). If the current
dimension order cannot be determined, the given order is used. Usage of
the given order can also be forced. Returns the modified XBeach
structure.

Syntax:
xb = xb_swap(xb, varargin)

Input:
xb          = XBeach output structure
varargin    = order:        Current dimension order (tyx/xyt)
              force:        Boolean to determine whether given order
                            should be used in all cases or not

Output:
xb          = Modified XBeach output structure

Example:
xb = xb_swap(xb)
xb = xb_swap(xb, 'order', 'xyt', 'force', true)

See also

xb_read_output

xb_transects2grid¶

UNTITLED  Interpolate Jarkus transects on grid to efficiently setup XBeach model.

Jarkus resolution is much higher in cross shore direction than in longshore
direction. This script spans a grid with y-direction parallel to the
mean coastline and the x-axis shore normal to it. The resulting grid with
course lonsghore resolution and fine crosshore resolution is used in griddata
to efficiently interpolate transects measurments on a grid.

Syntax:
[xJ,yJ,zJ] = xb_transects2grid(transects)

Input:
varargin  = transects structure

Output:
varargout = gridded Jarkus data

Example:
transects = jarkus_transects('id', [6002000:6002900],'output',{'id','time','x','y','cross_shore','altitude','angle'}); %
transects2 = jarkus_interpolatenans(transects);
transects3 = jarkus_merge(transects2,'dim','time');
[xJ,yJ,zJ] = xb_transects2grid(transects3)

See also

xb_upgrade_1d¶

XB_UPGRADE_1D  Converts an old 1D model to a superfast 1D model

Converts an old 1D model with 2 lateral grids to a superfast 1D model
withou lateral grids. An XBeach input structure or path to an XBeach
model can be supplied. In the latter case, the model is overwritten
with the new setup.

Syntax:
xb = xb_upgrade_1d(xb, varargin)

Input:
xb        = XBeach input structure or path to XBeach model
varargin  = none

Output:
xb        = modified XBeach input structure

Example:
xb = xb_upgrade_1d(xb)
xb = xb_upgrade_1d(path)

See also

xb_write_input

xb_verbose¶

XB_VERBOSE  Writes verbose messages fro XBeach toolbox

Writes verbose messages fro XBeach toolbox. Excepts any fprintf like
Syntax:
xb_verbose(varargin)

Input:

Input:
varargin  = fprintf like input

Output:
none

Example:
xb_verbose('File not found [%s]', filename)

See also fprintf

xb_modelsetup¶

xb_generate_model¶

XB_GENERATE_MODEL  Generates a XBeach structure with a full model setup

Generates a XBeach structure with a full model setup. By default this
is a minimal setup with default bathymetry, boundary conditions and
settings. The defaults can be overwritten by supplying cell arrays with
settings for either the bathymetry, waves, tide or model settings. The
result is a XBeach structure, which can be written to disk easily.

Syntax:
varargout = xb_generate_model(varargin)

Input:
varargin  = bathy:      cell array of name/value pairs of bathymetry
                        settings supplied to xb_generate_bathy
            waves:      cell array of name/value pairs of waves
                        settings supplied to xb_generate_waves
            tide:       cell array of name/value pairs of tide
                        settings supplied to xb_generate_tide
            wavegrid:   cell array of name/value pairs of tide
                        settings supplied to xb_generate_wavedirgrid
            settings:   cell array of name/value pairs of model
                        settings supplied to xb_generate_settings
            write:      boolean that indicates whether model setup
                        whould be written to disk (default: false)
            path:       destination directory of model setup, if
                        written to disk
            createwavegrid: bool used to determine whether this
                        function calls the xb_generate_wavegrid
                        function. In case of long crested waves one can
                        think of turning off automatic generation of
                        the wave grid.

Output:
xb        = XBeach structure array

Example:
xb = xb_generate_model();
xb = xb_generate_model('write', false);
xb = xb_generate_model('bathy', {'x', [ ... ], 'z', [ ... ]}, 'waves', {'Hm0', 9, 'Tp', 18});

xb_generate_settings¶

XB_GENERATE_SETTINGS  Generates a XBeach structure with model settings

Generates a XBeach structure with model settings. A minimal set of
default settings is used, unless otherwise provided. Settings can be
provided by a varargin list of name/value pairs.

Syntax:
xb = xb_generate_settings(varargin)

Input:
varargin  = Name/value pairs of model settings (e.g. 'nx',100,'ny',200)

Output:
xb        = XBeach structure array

Example:
xb = xb_generate_settings()
xb = xb_generate_settings('nx', 100, 'ny', 200)

See also

xb_generate_model

xb_modelsetup/xb_bc¶

xb_bc_extracttp¶

XB_BC_EXTRACTTP  Extracts wave period from XBeach input structure

Extracts wave period from XBeach input structure

Syntax:
Tp = xb_bc_extracttp(xb)

Input:
xb          = XBeach input structure

Output:
Tp          = peak wave period

Example:
Tp = xb_bc_extracttp(xb)

See also

xb_bc_extractwl, xb_generate_model

xb_bc_extractwl¶

XB_BC_EXTRACTWL  Extracts water level from XBeach input structure

Extracts water level from XBeach input structure

Syntax:
wl = xb_bc_extractwl(xb)

Input:
xb          = XBeach input structure

Output:
wl          = water level

Example:
wl = xb_bc_extractwl(xb)

See also

xb_bc_extracttp, xb_generate_model

xb_generate_tide¶

XB_GENERATE_TIDE  Generates XBeach structure with tide data

Generates a XBeach input structure with tide settings. A minimal set of
default settings is used, unless otherwise provided. Settings can be
provided by a varargin list of name/value pairs.

WARNING: to define two different timeseries on the lateral boundaries
         without specifying waterlevels at the back, set the paulrevere
         option in your parameter setting to 1 and define the lateral
         boundary conditions as if front and back in this function.

Syntax:
xb = xb_generate_tide(varargin)

Input:
varargin  = time:   array of starttimes of tide period in seconds
            front:  array of waterlevels at seaward model border
            back:   array of waterlevels at landward model border

Output:
xb        = XBeach structure array

Example:
xb = xb_generate_tide()
xb = xb_generate_tide('front', 10, 'back', 5)
xb = xb_generate_tide('time', [0 1800 3600], 'front', [5 10 5], 'back', [5 5 5])
xb = xb_generate_tide('time', [0 1800 3600], 'front', [5 10 5; 4 10 4]', 'back', [5 5 5; 5 5 5]')

See also

xb_generate_model

xb_generate_waves¶

XB_GENERATE_WAVES  Generates XBeach structure with waves data

Generates a XBeach input structure with waves settings. A minimal set
of default settings is used, unless otherwise provided. Settings can be
provided by a varargin list of name/value pairs. The settings depend on
the type of waves genarated (jonswap or vardens), which is indicated by
the type parameter. The result is a XBeach structure, an instat number
and, if necessary another XBeach structure containing the swtable.

            options for jonswap:
            Hm0:        significant wave height (default: 7.6)
            Tp:         peak wave period (default: 12)
            mainang     main wave direction (default: 270)
            gammajsp:   peak-enhancement factor (default: 3.3)
            s:          power in cosinus wave spreading (default: 20)
            fnyq:       Nyquist frequency (default: 1)

            options for vardens:
            freqs:      array of frequencies
            dirs:       array of directions
            vardens:    matrix of the size [length(dirs) length(freqs)]
                        containing variance densities

Syntax:
[xb instat swtable] = xb_generate_waves(varargin)

Input:
varargin  = type:       type of waves to be generated (jonswap/vardens)
            duration:   array with durations in seconds
            timestep:   array with timesteps in seconds

Output:
xb        = XBeach structure array

Example:
xb = xb_generate_waves()
xb = xb_generate_waves('Hm0', 9, 'Tp', 18)
xb = xb_generate_waves('Hm0', [7 9 7], 'Tp', [12 18 12], 'duration', [1800 3600 1800])
xb = xb_generate_waves('type', 'vardens', 'freqs', [ ... ], 'dirs', [ ... ])

See also

xb_generate_model

xb_set_start_time¶

XB_SET_START_TIME  sets the required start and stop times

Routine to estimate the time needed for the waves to reach te coast.
Based on that the tstart, morstart and tstop can be adjusted. The
required time is estimated assuming a wave celerity of sqrt(gh).

Syntax:
varargout = xb_set_start_time(varargin)

Input:
xb        = XBeach input structure
varargin  = propertyname-propertyvaluepairs
            - waterlevel : maximum water level during the simulation

Output:
xb        = XBeach input structure

Example:
xb_set_start_time

See also

xb_modelsetup/xb_grid¶

xb_generate_bathy¶

XB_GENERATE_BATHY  Creates a model bathymetry

Creates a model bathymetry in either one or two dimensions based on a
given bathymetry. The result is a XBeach input structure containing
three matrices of equal size containing a rectilinear grid in x, y and
z coordinates.

Syntax:
xb = xb_generate_bathy(varargin)

Input:
varargin  = x:          x-coordinates of bathymetry
            y:          y-coordinates of bathymetry
            z:          z-coordinates of bathymetry
            ne:         vector or matrix of the size of z containing
                        either booleans indicating if a cell is
                        non-erodable or a numeric value indicating the
                        thickness of the erodable layer on top of a
                        non-erodable layer
            xgrid:      options for xb_grid_xgrid
            ygrid:      options for xb_grid_ygrid
            rotate:     boolean flag that determines whether the
                        coastline is located in line with y-axis
            crop:       either a boolean indicating if grid should be
                        cropped to obtain a rectangle or a [x y w h]
                        array indicating how the grid should be cropped
            finalise:   either a boolean indicating if grid should be
                        finalised using default settings or a cell
                        array indicating the finalisation actions to
                        perform
            posdwn:     boolean flag that determines whether positive
                        z-direction is down
            zdepth:     extent of model below mean sea level, which is
                        used if non-erodable layers are defined
            optimize:   boolean to enable optimization of the grid, if
                        switched on, the provided grid is interpreted as
                        bathymetry and an optimal grid is defined, if
                        switched off, the provided grid is used as is.
            world_coordinates:
                        boolean to enable a grid defined in
                        world coordinates rather than XBeach model
                        coordinates
            superfast:  boolean to enable superfast 1D mode

Output:
xb        = XBeach structure array

Example:
xb = xb_generate_bathy('x', x, 'y', y, 'z', z)

xb_generate_wavedirgrid¶

UNTITLED  Generates wave directional grid for wave action balance.

More detailed description goes here.

Syntax:
xb          = xb_directional_wavegrid(xb,varargin)

Input:
varthr      = threshold (percentage of maximum variance) that is taken into account to set-up wavedir grid
nbins       = number of directional bins
normal      = direction normal to the shore line (optional)
plot        = 0 = no plot, 1 = plot of directional wave grid

Output:
xb          = XBeach structure array (with adapted theta

Example:
%
waves = xb_generate_waves
xb = xs_join(xb, waves);
exmaple 1
xb = xs_empty(); xb = xs_set(xb,'alpha',0,'dir',[270],'s',[5]); xb = xb_generate_wavedirgrid(xb);
example 2
xb = xs_empty(); xb = xs_set(xb,'alpha',-33,'dir',[273],'s',[5]); xb = xb_generate_wavedirgrid(xb);
example 3
xb = xs_empty(); xb = xs_set(xb,'alpha',-33,'dir',[231 241 258 273],'s',[2 10 2 5]); xb = xb_generate_wavedirgrid(xb);

See also

xb_grid_add¶

XB_GRID_ADD  Finalise grid and determine properties

Finalizes a given grid and determines dimensions and other properties.
The result is stored in an XBeach structure that can be used as model
Syntax:
xb = xb_grid_add(varargin)

Input:

Input:
varargin  = x:          x-coordinates of bathymetry
            y:          y-coordinates of bathymetry
            z:          z-coordinates of bathymetry
            ne:         vector or matrix of the size of z containing
                        either booleans indicating if a cell is
                        non-erodable or a numeric value indicating the
                        thickness of the erodable layer on top of a
                        non-erodable layer
            posdwn:     boolean flag that determines whether positive
                        z-direction is down
            zdepth:     extent of model below mean sea level, which is
                        used if non-erodable layers are defined
            superfast:  boolean to enable superfast 1D mode

Output:
xb        = XBeach structure array

Example:
xb = xb_grid_add('x', x, 'y', y, 'z', z);

See also

xb_generate_bathy, xb_grid_optimize

xb_grid_crop¶

XB_GRID_CROP  Automatically crops grid minimzing the number of NaN's and specifies extent of cropped area

Returns the extent of a cropped grid within a supplied grid. The
cropped area can be supplied by a vector indicating the origin, width
and height of the area. If no area is supplied, the largest area with a
minimum of NaN's (approximately) is used.

TODO: optimize the auto-crop algorithm

Syntax:
[xmin xmax ymin ymax] = xb_grid_crop(x, y, z, varargin)

Input:
x           = x-coordinates of grid to be cropped
y           = y-coordinates of grid to be cropped
z           = elevations of grid to be cropped
varargin    = crop:     vector like [x y w h] containing the origin,
                        width and height of the cropped area

Output:
xmin        = minimum x-coordinate of cropped area
xmax        = maximum x-coordinate of cropped area
ymin        = minimum y-coordinate of cropped area
xmax        = maximum y-coordinate of cropped area

Example:
[xmin xmax ymin ymax] = xb_grid_crop(x, y, z)
[xmin xmax ymin ymax] = xb_grid_crop(x, y, z, 'crop', [x0 y0 w h])

See also

xb_generate_bathy, xb_grid_extent

xb_grid_delft3d¶

XB_GRID_DELFT3D  Convert XBeach grid to Delft3D and back

Accepts a path to an XBeach model or an XBeach input structure. Either
way it returns an XBeach structure with the grid definition swapped
from XBeach format to Delft3D format or vice versa. In case a path is
given, the written model is updated as well.

Syntax:
xb = xb_grid_delft3d(varargin)

Input:
varargin  = Either an XBeach input structure or path to XBeach model

Output:
xb        = Modified XBeach input structure

Example:
xb_grid_delft3d('path_to_model/')
xb_grid_delft3d('path_to_model/')
xb = xb_grid_delft3d('path_to_model/')
xb = xb_grid_delft3d(xb)

See also

xb_generate_bathy

xb_grid_extent¶

XB_GRID_EXTENT  Determines the extent and minimum cellsize of a specified grid

Determines the minimum and maximum values of the x and y coordinates of
a specified grid and the minimum cell size as well.

Syntax:
[xmin xmax ymin ymax cellsize] = xb_grid_extent(x, y, varargin)

Input:
x           = x-coordinates of grid to be cropped
y           = y-coordinates of grid to be cropped
varargin    = none

Output:
xmin        = minimum x-coordinate of grid
xmax        = maximum x-coordinate of grid
ymin        = minimum y-coordinate of grid
xmax        = maximum y-coordinate of grid
cellsize    = minimum cellsize in grid

Example:
[xmin xmax ymin ymax cellsize] = xb_grid_extent(x, y)

See also

xb_grid_resolution

xb_grid_finalise¶

XB_GRID_FINALISE  Performs several finalisation actions on an XBeach grid

Performs several finalisation actions on an XBeach grid, like extending
and flattening boundaries to prevent numerical instabilities in the
calculation.

                        currently available actions:
                            lateral_extend:     copy lateral boundaries
                            lateral_seawalls:   close dry lateral
                                                boundaries with
                                                sandwalls
                            seaward_flatten:    flatten offshore
                                                boundary
                            landward_extend:    extend lanward border
                                                with specified
                                                elevation
                            seaward_extend:     extend seaward border
                                                to a certain depth

              cells:    number of cells to use in each action

Preferences:
grid_finalise   = Cell array with finalisation options (see options)

            Preferences overwrite default options (not explicitly
            defined options) and can be set and retrieved using the
            xb_setpref and xb_getpref functions.

Syntax:
[x y z] = xb_grid_finalise(x, y, z, varargin)

Input:
x           = x-coordinates of grid to be finalised
y           = y-coordinates of grid to be finalised
z           = elevations of grid to be finalised
varargin    = actions:  cell array containing strings indicating the
                        order and actions to be performed

Output:
x           = x-coordinates of finalised grid
y           = y-coordinates of finalised grid
z           = elevations of finalised grid

Example:
[x y z] = xb_grid_finalise(x, y, z)
[x y z] = xb_grid_finalise(x, y, z, 'actions', {'landward_polder' 'lateral_sandwalls' 'lateral_extend' 'seaward_flatten'})

See also

xb_generate_bathy

xb_grid_interpolate¶

XB_GRID_INTERPOLATE  Interpolates a 2D grid on another

This function is equal to the INTERP2 function in case of an not
rotated orthogonal input grid. However, if the input grid is rotated,
the INTERP2 function fails. This function rotates both the input as the
Syntax:
zi = xb_grid_interpolate(x, y, z, zi, yi, varargin)

Input:
x           = x-coordinates of input grid
y           = y-coordinates of input grid
z           = elevations of input grid
xi          = x-coordinates of output grid
yi          = y-coordinates of output grid
varargin    = precision:    Rotation precision in case of rotated grids

Output:
aligned with the coordinate axes. Subsequently, the INTERP2 function is
used for interpolation.

Output:
zi          = elevations of output grid

Example:
zi = xb_grid_interpolate(x, y, z, xi, yi)

See also

xb_grid_merge

xb_grid_merge¶

XB_GRID_MERGE  Merges two or more 2D grids together

Merges two or more 2D grids together by defining an output rectangular,
orthogonal and equidistant output grid based on the smallest grid size
in the input grids. The input grids are then interpolated on the output
grid. The first grid will end up below the others, the last grid will
end up on top of the others.

Syntax:
[x y z] = xb_grid_merge(varargin)

Input:
varargin  = x:          cell array with x-coordinate vectors or
                        matrices of input grids
            y:          cell array with y-coordinate vectors or
                        matrices of input grids
            z:          cell array with elevation matrices of input
                        grids

Output:
x           = x-coordinates of merged grid
y           = y-coordinates of merged grid
z           = elevations in merged grid

Example:
[x y z] = xb_grid_merge('x',{x1 x2 x3},'y',{y1 y2 y3},'z',{z1 z2 z3})

See also

xb_grid_rotate

xb_grid_optimize¶

XB_GRID_OPTIMIZE  Creates a model grid based on a given bathymetry

Creates a model grid in either one or two dimensions based on a given
bathymetry. The result is three matrices of equal size containing a
rectilinear grid in x, y and z coordinates.

Syntax:
xb = xb_grid_optimize(varargin)

Input:
varargin  = x:          x-coordinates of bathymetry
            y:          y-coordinates of bathymetry
            z:          z-coordinates of bathymetry
            ne:         vector or matrix of the size of z containing
                        either booleans indicating if a cell is
                        non-erodable or a numeric value indicating the
                        thickness of the erodable layer on top of a
                        non-erodable layer
            xgrid:      options for xb_grid_xgrid
            ygrid:      options for xb_grid_ygrid
            rotate:     boolean flag that determines whether the
                        coastline is located in line with y-axis
            crop:       either a boolean indicating if grid should be
                        cropped to obtain a rectangle or a [x y w h]
                        array indicating how the grid should be cropped
            finalise:   either a boolean indicating if grid should be
                        finalised using default settings or a cell
                        array indicating the finalisation actions to
                        perform
            posdwn:     boolean flag that determines whether positive
                        z-direction is down
            world_coordinates:
                        boolean to enable a grid defined in
                        world coordinates rather than XBeach model
                        coordinates
            zdepth:     extent of model below mean sea level, which is
                        used if non-erodable layers are defined

Output:
xb        = XBeach structure array

Example:
xb = xb_grid_optimize('x', x, 'y', y, 'z', z)

xb_grid_orientation¶

XB_GRID_ORIENTATION  Determines the orientation of a 2D bathymetric grid

Determines the dimension and direction which runs from sea landward in
a 2D bathymetric grid. Based on the maximum mean minimum slope, the
dimension which runs cross-shore is chosen. Subsequently, the direction
is determined. If the grid runs from sea landward in negative
direction, the direction is negative, otherwise positive.

Syntax:
[dim dir] = xb_grid_orientation(x, y, z, varargin)

Input:
x           = x-coordinates of bathymetric grid
y           = y-coordinates of bathymetric grid
z           = elevations in bathymetric grid
varargin    = none

Output:
dim         = corss-shore dimension in bathymetric grid (1/2)
dir         = direction in bathymetric grid that runs from sea landward
              (1/-1)

Example:
[dim dir] = xb_grid_orientation(x, y, z)

See also

xb_generate_bathy

xb_grid_resolution¶

XB_GRID_RESOLUTION  Determines the maximum cellsize of a regular grid of a certain size fitting the extent of the specified grid

Determines the extent of the specified grid and the maximum cellsize to
generate a regular grid spanning this extent without exceeding a
certain size (bytes).

Syntax:
[cellsize xmin xmax ymin ymax] = xb_grid_resolution(x, y, varargin)

Input:
x           = x-coordinates of grid to be cropped
y           = y-coordinates of grid to be cropped
varargin    = maxsize:  maximum grid size in bytes (default 10MB), in
                        case the value is 'max' the maximum size in the
                        currently available memory space is used.

Output:
cellsize    = maximum cellsize in regular grid
xmin        = minimum x-coordinate of regular grid
xmax        = maximum x-coordinate of regular grid
ymin        = minimum y-coordinate of regular grid
xmax        = maximum y-coordinate of regular grid

Example:
[cellsize xmin xmax ymin ymax] = xb_grid_resolution(x, y)
[cellsize xmin xmax ymin ymax] = xb_grid_resolution(x, y, 'maxsize', 1024^3)

See also

xb_grid_extent

xb_grid_rotate¶

XB_GRID_ROTATE  Rotates a grid around an origin

Rotates a grid around an origin. The origin can be specified.

Syntax:
[xr yr] = xb_grid_rotate(x, y, alpha, varargin)

Input:
x           = x-coordinates of bathymetric grid
y           = y-coordinates of bathymetric grid
alpha       = rotation angle
varargin    = origin:   origin for rotation
              units:    input units (degrees/radians)

Output:
xr          = x-coordinates of rotated grid
yr          = y-coordinates of rotated grid

Example:
[xr yr] = xb_grid_rotate(x, y, alpha)

See also

xb_grid_rotation

xb_grid_rotation¶

XB_GRID_ROTATION  Determines rotation of a 2D grid based on the coastline

Determines the location of a 2D grid based on the coastline by
detecting the coastline and determining the angle of the coastline.

Syntax:
[alpha a b] = xb_grid_rotation(x, y, z, varargin)

Input:
x           = x-coordinates of bathymetric grid
y           = y-coordinates of bathymetric grid
z           = elevations in bathymetric grid
varargin    = units:    output units (degrees/radians)

Output:
alpha       = rotation of grid
a           = linear regression parameter of coastline (y=a+b*x)
b           = linear regression parameter of coastline (y=a+b*x)

Example:
alpha = xb_grid_rotation(x, y, z)

See also

xb_grid_rotate

xb_grid_trim¶

XB_GRID_TRIM  Removes all empty rows and columns from a 2D grid

Removes all rows and columns in a 2D grid containing NaN's only.

Syntax:
[x y z] = xb_grid_trim(x, y, z, varargin)

Input:
x           = x-coordinates of grid to be trimmed
y           = y-coordinates of grid to be trimmed
z           = elevations of grid to be trimmed
varargin    = none

Output:
x           = x-coordinates of trimmed grid
y           = y-coordinates of trimmed grid
z           = elevations of trimmed grid

Example:
[x y z] = xb_grid_trim(x, y, z)

See also

xb_grid_extent

xb_grid_world2xb¶

XB_GRID_WORLD2XB  Rotates a grid in world coordinates to XBeach coordinates

Rotates a grid in world coordinates to XBeach coordinates

Syntax:
[x y] = xb_grid_world2xb(x, y, xori, yori, alpha)

Input:
x           = x-coordinates
y           = y-coordinates
xori        = x-origin
yori        = y-origin
alpha       = grid rotation

Output:
x           = x-coordinates
y           = y-coordinates

Example:
[x y] = xb_grid_world2xb(x, y, xori, yori, alpha)

See also

xb_grid_xb2world

xb_grid_xb2world¶

XB_GRID_XB2WORLD  Rotates a grid in XBeach coordinates to world coordinates

Rotates a grid in XBeach coordinates to world coordinates

Syntax:
[x y] = xb_grid_xb2world(x, y, xori, yori, alpha)

Input:
x           = x-coordinates
y           = y-coordinates
xori        = x-origin
yori        = y-origin
alpha       = grid rotation

Output:
x           = x-coordinates
y           = y-coordinates

Example:
[x y] = xb_grid_xb2world(x, y, xori, yori, alpha)

See also

xb_grid_world2xb

xb_grid_xgrid¶

XB_GRID_XGRID  Creates a model grid in x-direction based on bathymetry

Function to interpolate (no extrapolation) profile measurements to
cross shore consant or varying grid for an XBeach profile model. Cross
shore grid size is limited by user-defined minimum grid size in shallow
water and land, long wave resolution on offshore boundary, depth to
grid size ratio and grid size smoothness constraints. The function uses
the Courant condition to find the optimal grid size given these
constraints.

Optional input in keyword,value pairs
  - xgrid    :: [m] vector which defines the variable xgrid
  - Tm       :: [s] incident short wave period (used for maximum grid size at offshore boundary)
                    if you impose time series of wave conditions use the min(Tm) as input (default = 5)
  - dxmin    :: [m] minimum required cross shore grid size (usually over land) (default = 1)
  - dxmax    :: [m] user-specified maximum grid size, when usual wave
                    period / CFL condition does not suffice (default Inf)
  - vardx    :: [-] 0 = constant dx, 1 = varying dx (default = 1)
  - g        :: [ms^-2] gravity constant (default = 9.81)
  - CFL      :: [-] Courant number in grid generator (default = 0.9)
  - dtref    :: [-] Ref value for dt in computing dx from CFL (default = 4)
  - maxfac   :: [-] Maximum allowed grid size ratio between adjacent cells (default = 1.15)
  - dy, 5    :: [m] dy (default = 5)
  - wl,0     :: [m] water level elevation relative to bathymetry used to estimate water depth (default = 0)
  - depthfac :: [-] Maximum gridsize to water depth ratio (default = 2)

Syntax:
[xgr zgr] = xb_grid_xgrid(xin, zin, varargin)

Input:
xin   = vector with cross-shore coordinates; increasing from zero
towards shore
zin   = vector with bed levels; positive up

Output:
xgr   = x-grid coordinates
zgr   = bed elevations

Example:
[xgr zgr] = xb_grid_xgrid([0:1:200], 0.1*[0:1:200]-15);

See also

xb_generate_bathy, xb_grid_ygrid

xb_grid_ygrid¶

XB_GRID_YGRID  Creates a model grid in y-direction based on minimum and maximum cell size and area of interest

Generates a model grid in y-direction using two grid cellsizes. The
minimum grid cellsize is used for the area of interest. The maximum is
used near the lateral borders. A gradual transition between the grid
cellsizes over a specified distance is automatically generated. The
area of interest can be defined in several manners. By default, this is
a distance of 100m in the center of the model.

Syntax:
ygr = xb_grid_ygrid(yin, varargin)

Input:
yin       = range of y-coordinates to be included in the grid
varargin  = dymin:                  minimum grid cellsize
            dymax:                  maximum grid cellsize
            area_type:              type of definition of the area of
                                    interest (center/range)
            area_size:              size of the area of interest
                                    (length or fraction in case of
                                    area_type center, from/to range in
                                    case of area_type range)
            transition_distance:    distance over which the grid
                                    cellsize is gradually changed from
                                    mimumum to maximum, a negative
                                    value means the distance may be
                                    adapted to limit the error made in
                                    the fit

Output:
ygr       = generated grid in y_direction

Example:
ygr = xb_grid_ygrid(yin)

See also

xb_generate_bathy, xb_grid_xgrid

xb_modelsetup/xb_grid/xb_delft3d¶

xb_delft3d_addpath¶

XB_DELFT3D_ADDPATH  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_addpath(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_addpath

See also

xb_delft3d_wldep2xb¶

XB_DELFT3D_WLDEP2XB  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_wldep2xb(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_wldep2xb

See also

xb_delft3d_wlgrid2xb¶

XB_DELFT3D_WLGRID2XB  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_wlgrid2xb(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_wlgrid2xb

See also

xb_delft3d_xb2wldep¶

XB_DELFT3D_XB2WLDEP  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_xb2wldep(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_xb2wldep

See also

xb_delft3d_xb2wlgrid¶

XB_DELFT3D_XB2WLGRID  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_xb2wlgrid(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_xb2wlgrid

See also

xb_nesting¶

xb_nest_delft3d¶

%XB_NEST_DELFT3D  Obtain Delft3D boundary conditions and bathymetry from another model

Obtain Delft3D boundary conditions and/or bathymetry from a WW3,
Delft3D. This information can be used for nesting a Delft3D model into
one of these two models.

Syntax:
info = xb_nest_delft3d(varargin)

Input:
varargin  = type:   Model type to nest into (ww3/delft3d)
            flow:   Cell array with parameters for the flow nest
                    procedure
            wave:   Cell array with parameters for the wave nest
                    procedure
            bathy:  Cell array with parameters for the bathymetry nest
                    procedure

Output:
info      = Struct with filenames of boundary condition and bathymetry
            files

Example:
info = xb_nest_delft3d('delft3d', 'flow', { ... })

xb_nest_xbeach¶

XB_NEST_XBEACH  Obtain XBeach boundary conditions and bathymetry from another model

Obtain XBeach boundary conditions and/or bathymetry from a WW3, Delft3D
or another XBeach model. This information can be used for nesting an
XBeach model into one of these three models.

Syntax:
info = xb_nest_xbeach(varargin)

Input:
varargin  = type:   Model type to nest into (ww3/delft3d/xbeach)
            flow:   Cell array with parameters for the flow nest
                    procedure
            wave:   Cell array with parameters for the wave nest
                    procedure
            bathy:  Cell array with parameters for the bathymetry nest
                    procedure

Output:
info      = Struct with filenames of boundary condition and bathymetry
            files

Example:
info = xb_nest_xbeach('delft3d', 'flow', { ... })

xb_nesting/xb_delft3d¶

xb_bct2xb¶

XB_BCT2XB  Converts Delft3D-FLOW BCT file to an XBeach tide file

Converts Delft3D-FLOW BCT file to an XBeach tide file, possibly
cropping the timeseries.

Syntax:
[tidefile tidelen tideloc] = xb_bct2xb(fname, varargin)

Input:
fname     = Path to BCT file
varargin  = tidefile:       Path to output file
            tstart:         Datenum indicating simulation start time
            tlength:        Datenum indicating simulation length

Output:
tidefile  = Path to output file
tidelen   = Length of timeseries in output file
tideloc   = Number of locations in output file

Example:
[tidefile tidelen tideloc] = xb_bct2xb(fname)
[tidefile tidelen tideloc] = xb_bct2xb(fname, 'tstart', datenum('2007-11-05'))

See also

xb_delft3d_flow, xb_sp22xb

xb_delft3d_bathy¶

XB_DELFT3D_BATHY  Nest Delft3D or XBeach bathymetry in another Delft3D model

Nests a Delft3D bathymetry.

Syntax:
varargout = xb_delft3d_bathy(depfile, varargin)

Input:
depfile   = Path to bathymetry file
varargin  = type:           Type of output (delft3d/xbeach)
            file:           Path to output file

Output:
varargout   = Path to output file

Example:
file = xb_delft3d_bathy(depfile)

xb_delft3d_depth¶

XB_DELFT3D_DEPTH  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_depth(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_depth

See also

xb_delft3d_flow¶

XB_DELFT3D_FLOW  Nest Delft3D-FLOW or XBeach model in another Delft3D-FLOW

Nests a Delft3D-FLOW model based on the trih-*, BND and NST files.

Syntax:
varargout = xb_delft3d_flow(trihfile, bndfile, nstfile, varargin)

Input:
trihfile  = Path to the trih-* file to use
bndfile   = Path to the BND file to use
nstfile   = Path to the NST file to use
varargin  = type:       Type of output (delft3d/xbeach)
            file:       Path to output file
            zcorr:      Water level correction
            tstart:     Datenum indicating simulation start time
            tlength:    Datenum indicating simulation length

Output:
varargout = Path to output file and dimensions of file, if applicable

Example:
file = xb_delft3d_flow(trihfile, bndfile, nstfile)
[file tidelen tideloc] = xb_delft3d_flow('trih-csm.dat', 'kuststrook.bnd', 'kuststrook.nst', 'type', 'xbeach')

xb_delft3d_grid¶

XB_DELFT3D_GRID  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_delft3d_grid(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_delft3d_grid

See also

xb_delft3d_wave¶

XB_DELFT3D_WAVE  Nest Delft3D-WAVE or XBeach model in another Delft3D-WAVE model

Nests a Delft3D-WAVE model by simply joining the output SP2 files into
a single input SP2 file.

Syntax:
varargout = xb_delft3d_wave(sp2files, varargin)

Input:
sp2files  = Path to SP2 files to be joined
varargin  = type:           Type of output (delft3d/xbeach)
            file:           Path to output file
            coordsys_in     Coordinate system of input
            coordtype_in    Coordinate system type of input
            coordsys_out    Coordinate system of output
            coordtype_out   Coordinate system type of output
            tstart:         Datenum indicating simulation start time
            tlength:        Datenum indicating simulation length

Output:
varargout   = Path to output file

Example:
file = xb_delft3d_wave(sp2files)
file = xb_delft3d_wave('pet.loct*.sp2')

xb_sp22xb¶

XB_SP22XB  Converts a set of Delft3D-WAVE SP2 files into XBeach wave boundary conditions

Converts a set of Delft3D-WAVE SP2 files into XBeach wave boundary
conditions by cropping the timeseries, writing the corresponding SP2
files and a filelist file.

Syntax:
wavefile = xb_sp22xb(fnames, varargin)

Input:
fnames    = Path to Delft3D-WAVE SP2 files
varargin  = wavefile:       Path to output file
            tstart:         Datenum indicating simulation start time
            tlength:        Datenum indicating simulation length

Output:
wavefile  = Path to output file

Example:
wavefile = xb_sp22xb('*.sp2')

See also

xb_delft3d_wave, xb_bct2xb

xb_nesting/xb_swan¶

xb_swan_coords¶

XB_SWAN_COORDS  Convert coordinates in SWAN struct

Convert coordinates in SWAN struct

Syntax:
sp2 = xb_swan_coords(sp2, cs_in, ct_in, cs_out, ct_out, varargin)

Input:
sp2       = SWAN struct to be converted
cs_in     = Coordinate system of input
ct_in     = Coordinate system type of input
cs_out    = Coordinate system of output
ct_out    = Coordinate system type of output
varargin  = none

Output:
sp2       = Converted SWAN struct

Example:
sp2 = xb_swan_coords(sp2, ... )

See also

xb_swan_read

xb_swan_join¶

XB_SWAN_JOIN  Join multiple files in SWAN struct to a single file

Join multiple files in SWAN struct to a single file

Syntax:
sp2 = xb_swan_join(sp2, varargin)

Input:
sp2       = SWAN struct with multiple files
varargin  = none

Output:
sp2       = SWAN struct with a single file

Example:
sp2 = xb_swan_join(sp2)

See also

xb_swan_split

xb_swan_read¶

XB_SWAN_READ  Read a SWAN file into a struct

Read one or more SWAN files into a struct

Syntax:
sp2 = xb_swan_read(fname, varargin)

Input:
fname     = Path to SWAN file
varargin  = none

Output:
sp2       = SWAN struct

Example:
sp2 = xb_swan_read('waves.sp2')
sp2 = xb_swan_read('*.sp2')

See also

xb_swan_write, xb_swan_struct

xb_swan_split¶

XB_SWAN_SPLIT  Split a SWAN struct with a single file into a struct with multiple files

Split a SWAN struct with a single file into a struct with multiple
files.

Syntax:
sp2 = xb_swan_split(sp2, dim, varargin)

Input:
sp2       = SWAN struct with single file
dim       = Dimension to be splitted (time/location/etc)
varargin  = none

Output:
sp2       = SWAN struct with multiple files

Example:
sp2 = xb_swan_split(sp2, 'time')

See also

xb_swan_join

xb_swan_struct¶

XB_SWAN_STRUCT  Create empty SWAN structure

Create empty SWAN structure

Syntax:
sp2 = xb_swan_struct()

Input:
none

Output:
sp2       = Empty SWAN structure

Example:
sp2 = xb_swan_struct

See also

xb_swan_read, xb_swan_write

xb_swan_write¶

XB_SWAN_WRITE  Write SWAN file from struct

Write one or more SWAN files from struct. In case of multiple files,
the filename is extended with an indexing number.

Syntax:
fnames = xb_swan_write(fname, sp2, varargin)

Input:
fname     = Path to output file
sp2       = SWAN struct to write
varargin  = none

Output:
fnames    = Path(s) to output file(s)

Example:
fnames = xb_swan_write('waves.sp2', sp2)

See also

xb_swan_read, xb_swan_struct

xb_run¶

xb_check_list¶

XB_CHECK_LIST  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_check_list(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_check_list

See also

xb_check_run¶

XB_CHECK_RUN  Checks whether a run from an XBeach input structure is still running

Checks whether a run started using either xb_run or xb_run_remote is
still running. The check can be repeated using a certain time interval
to get a warning once the run is finished.

Syntax:
runs = xb_check_run(xb, varargin)

Input:
xb        = XBeach run structure
varargin  = repeat:     boolean flag to determine if the check is
                        repeated
            interval:   seconds between checks, if repeated
            display:    boolean to determine whether a message is
                        displayed after process has finished
            sound:      boolean to determine whether a sound is made
                        after process has finished
            callback:   callback function fired after process has
                        finished

Output:
runs      = boolean that indicates whether the job is still running

Example:
xb_check_run(xb)

See also

xb_run, xb_run_remote

xb_get_bin¶

XB_GET_BIN  Retrieves a XBeach binary from a remote source

Retrieves a XBeach binary from a remote source. By default this is the
latest binary from the TeamCity build server. Several flavours of
binaries exist. By default the normal win32 binary is downloaded. A
custom host can be provided as well. Returns the location where the
downloaded binary can be found.

WARNING: SOME BINARY TYPES ARE STILL MISSING, SINCE NOT AVAILABLE IN
TEAMCITY YET

Syntax:
fpath = xb_get_bin(varargin)

Input:
varargin  = type:       Type of binary (win32/unix/mpi/netcdf).
                        Multiple qualifiers separated by a space can be
                        used. Specifying "custom" will use the host
                        provided in the equally named varargin
                        parameter.
            host:       Host to be used in case of custom type.

Output:
fpath     = Path to downloaded executable

Example:
fpath = xb_get_bin()
fpath = xb_get_bin('type', 'win32 mpi')
fpath = xb_get_bin('type', 'win32 netcdf')
fpath = xb_get_bin('type', 'win32 netcdf mpi')
fpath = xb_get_bin('type', 'unix netcdf mpi')
fpath = xb_get_bin('type', 'custom', 'host', ' ... ')

See also

xb_run

xb_resume¶

XB_RESUME  Resumes XBeach model run from certain moment

Combines an existing model setup with a bathymetry from the
corresponding model output into a new model setup. Given a certain
simulation time, the bathymetry closest to this time is obtained from
the model output. The input bathymetry from the existing model setup is
replaced with this evolved bathymetry. The boundary conditions and
simulation times are adjusted to fit the bathymetry used.
If the given simulation time is not present in the model output, the
available simulation time closest to the given value is used.

Syntax:
xb = xb_resume(xb, varargin)

Input:
xb        = XBeach run structure or path to model setup
varargin  = t:      simulation time at which bathymetry is read
            spinup: spinup time to use in newly generated model setup

Output:
xb        = New model setup with evolved bathymetry

Example:
xbm = xb_resume(xbr, 't', 1000)
xbm = xb_resume(xbr, 't', 1000, 'spinup', 100)
xbm = xb_resume('path/to/model/setup, 't', Inf)

xb_run¶

XB_RUN  Runs a XBeach model locally

Writes a XBeach structure to disk, retrieves a XBeach binary file and
runs it at a certain location. Supports the use of MPI using MPICH2.

TODO: MPI support

Syntax:
xb_run(xb)

Input:
xb        = XBeach input structure
varargin  = binary:     XBeach binary to use
            nodes:      Number of nodes to use in MPI mode (1 = no mpi)
            netcdf:     Flag to use netCDF output (default: false)
            path:       Path to the XBeach model

Output:
xb        = XBeach structure array

Example:
xb_run(xb)
xb_run(xb, 'path', 'path_to_model/')

See also

xb_run_remote, xb_get_bin

xb_run_list¶

XB_RUN_LIST  Lists registered runs

Lists runs registered by the xb_run_register function.

Syntax:
xb_run_list(varargin)

Input:
varargin  = n:      Number of log lines to show

Output:
none

Example:
xb_run_list
xb_run_list('n', 10)

See also

xb_run, xb_run_remote, xb_run_register

xb_run_parselog¶

XB_RUN_PARSELOG  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_run_parselog(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_run_parselog

See also

xb_run_queue¶

XB_RUN_QUEUE  Queues XBeach runs for local execution

Queues XBeach runs for local execution. All models are executed one at
a time, unless set otherwise. Runs are stored in an XBeach preference
variable and monitored using the xb_check_run function. A callback to
this function will fire the next model.

Syntax:
xb_run_queue(varargin)

Input:
varargin  = First argument may be an XBeach input structure to be
            queued. Other arguments are expected to be from the
            following list:
            action:     Queue action to perform (add/start/next/clear)
            options:    Options to be passed to the xb_run function
            nr:         Number of parallel runs

Output:
none

Example:
xb_run_queue(xb)
xb_run_queue(xb, 'options', {'binary', 'C:\xbeach.exe'})
xb_run_queue
xb_run_queue('action', 'next')
xb_run_queue('action', 'clear')

See also

xb_run, xb_check_run

xb_run_register¶

XB_RUN_REGISTER  Registers XBeach run in preferences database

Registers an XBeach run started from xb_run or xb_run_remote in a
preference database for future use.

Syntax:
xb_run_register(xb, varargin)

Input:
xb        = XBeach struct resulting from xb_run or xb_run_remote
varargin  = none

Output:
none

Example:
xb_run_register(xb)

See also

xb_run, xb_run_remote, xb_run_list

xb_run_remote¶

XB_RUN_REMOTE  Runs a XBeach model remote on the H4 cluster

Writes a XBeach structure to disk, retrieves a XBeach binary file and
runs it at a remote location accessed by SSH (by default, H4 cluster).
Supports the use of MPI.

TODO: UNIX SUPPORT

Preferences:
ssh_user        = Username for remote computer
ssh_pass        = Password for remote computer
path_local      = Local path to the XBeach model
path_remote     = Path to XBeach model seen from remote computer

            Preferences overwrite default options (not explicitly
            defined options) and can be set and retrieved using the
            xb_setpref and xb_getpref functions.

Syntax:
xb_run_remote(xb)

Input:
xb        = XBeach structure array
varargin  = name:       Name of the model run
            binary:     XBeach binary to use
            nodes:      Number of nodes to use in MPI mode (1 = no mpi)
            netcdf:     Flag to use netCDF output (default: false)
            ssh_host:   Host name of remote computer
            ssh_user:   Username for remote computer
            ssh_pass:   Password for remote computer
            ssh_prompt: Boolean indicating if password prompt should be
                        used
            path_local: Local path to the XBeach model
            path_remote:Path to XBeach model seen from remote computer

Output:
xb        = XBeach structure array

Example:
xb_run_remote(xb)
xb_run_remote(xb, 'path_local', 'u:\', 'path_remote', '~/')

See also

xb_run, xb_get_bin

xb_run_sh_scripts¶

XB_RUN_SH_SCRIPTS  Run SH scripts on H4 cluster

Run SH scripts on H4 cluster

Preferences:
ssh_user        = Username for remote computer
ssh_pass        = Password for remote computer

            Preferences overwrite default options (not explicitly
            defined options) and can be set and retrieved using the
            xb_setpref and xb_getpref functions.

Syntax:
[job_id job_name messages] = xb_run_sh_scripts(rpath, script, varargin)

Input:
rpath     = Path where script is located seen from remote source
script    = Name of the script to run
varargin  = ssh_host:   Host name of remote computer
            ssh_user:   Username for remote computer
            ssh_pass:   Password for remote computer
            ssh_prompt: Boolean indicating if password prompt should be
                        used
            cd:         Boolean flag to determine if directory should
                        be changed to rpath

Output:
job_id    = Job number of process started
job_name  = Name of process started
messages  = Messages returned by remote source

Example:
job_id = xb_run_sh_scripts('~/', 'run.sh', 'ssh_prompt', true)

See also

xb_run_remote, xb_write_sh_scripts

xb_run_unregister¶

XB_RUN_UNREGISTER  Unregister registered run

Unregister run registered by xb_run_register

Syntax:
xb_run_unregister(id)

Input:
id        = Run index to be unregistered

Output:
none

Example:
xb_run_unregister(1234)

See also

xb_run_register

xb_write_sh_scripts¶

XB_WRITE_SH_SCRIPTS  Writes SH scripts to run applications on H4 cluster using MPI

Writes SH scripts to run applications on H4 cluster. Optionally
includes statements to run applications using MPI.

Preferences:
mpitype   = Type of MPI application (MPICH2/OpenMPI)

            Preferences overwrite default options (not explicitly
            defined options) and can be set and retrieved using the
            xb_setpref and xb_getpref functions.

Syntax:
fname = xb_write_sh_scripts(lpath, rpath, varargin)

Input:
lpath     = Local path to store scripts
rpath     = Path to store scripts seen from h$ cluster
varargin  = name:       Name of the run
            binary:     Binary to use
            nodes:      Number of nodes to use (1 = no MPI)
            mpitype:    Type of MPI application (MPICH2/OpenMPI)

Output:
fname     = Name of start script

Example:
fname = xb_write_sh_scripts(lpath, rpath, 'binary', 'bin/xbeach')
fname = xb_write_sh_scripts(lpath, rpath, 'binary', 'bin/xbeach', 'nodes', 4)

See also

xb_run_remote

xb_testbed¶

xb_testbed_check¶

XB_TESTBED_CHECK  Checks if running as part of the XBeach testbed

Checks if running as part of the XBeach testbed by checking if
preferences are set.

Syntax:
istestbed = xb_testbed_check()

Input:
none

Output:
istestbed = Boolean indicating if testbed is running

Example:
if xb_testbed_check; disp('YES!'); end;

xb_testbed_getpref¶

XB_TESTBED_GETPREF  Read testbed preferences

Read testbed preferences

Syntax:
pref = xb_testbed_getpref()

Input:
none

Output:
pref    = Struct with testbed preferences

Example:
pref = xb_testbed_getpref

See also

xb_testbed_check

xb_testbed_includes¶

XB_TESTBED_INCLUDES  Dummy function to automatically include OET functions in XBeach toolbox release

Dummy function to automatically include OET functions in XBeach toolbox
release. These functions can be used in the XBeach testbed, for
Syntax:
varargout = xb_testbed_includes(varargin)

Input:
varargin  = none

Output:
varargout = none
Example:

xb_testbed_loadskill¶

XB_TESTBED_LOADSKILL  Loads testbed skill history of specific variable

Loads testbed skill history of specific variable

Syntax:
s = xb_testbed_loadskill(var)

Input:
var       = Variable name

Output:
s         = Struct with skill history

Example:
s = xb_testbed_loadskill('zb')

See also

xb_testbed_storeskill

xb_testbed_plotskill¶

XB_TESTBED_PLOTSKILL  Plot testbed skill history

Plot testbed skill history

Syntax:
xb_testbed_plotskill(var)

Input:
var       = Variable to plot
varargin  = r2:         Boolean indicating whether r^2 score should be
                        plotted
            sci:        Boolean indicating whether Sci score should be
                        plotted
            relbias:    Boolean indicating whether realtive bias should
                        be plotted
            bss:        Boolean indicating whether Brier Skill Score
                        should be plotted

Output:
none

Example:
xb_testbed_plotskill(var)

xb_testbed_storeskill¶

XB_TESTBED_STORESKILL  Updates testbed skill history for specific variable

Updates testbed skill history for specific variable

Syntax:
xb_testbed_storeskill(var, r2, sci, relbias, bss)

Input:
var       = Variable name
r2        = R^2 score
sci       = Sci score
relbias   = Relative bias
bss       = Brier Skill score

Output:
none

Example:
xb_testbed_storeskill('zb', r2, sci, relbias, bss)

See also

xb_testbed_loadskill

xb_visualise¶

xb_get_handles¶

XB_GET_HANDLES  Return valid axes handles for creating plots

Return valid axes handles for creating plots. By default, a single
figure window is created with the requested number of axes as subplots.
If a specific figure handle is provided, this figure window is used. If
a list of specific axes handles are provided, these are checked for
validity and appended with another figure window with subplots to
arrive at the requested number of axes.

Syntax:
ax = xb_get_handles(n, varargin)

Input:
n         = Number of axes needed
varargin  = handles:    Figure handle or list of axes handles

Output:
ax        = List with axes handles

Example:
ax = xb_get_handles(4)
ax = xb_get_handles(4, 'handles', gcf)
ax = xb_get_handles(2, 'handles', [ax1 ax2])

xb_plot¶

XB_PLOT  Basic visualisation tool for XBeach output structure

Creates a basic interface to visualise contents of a XBeach output
structure. The function is meant to be basic and provide first
visualisations of model results.

Syntax:
varargout = xb_plot(xb, varargin)

Input:
xb        = XBeach structure array
varargin  = none

Output:
none

Example:
xb_plot(xb)

See also

xb_read_dat

xb_plot_hydro¶

XB_PLOT_HYDRO  Create uniform wave transformation plots

Create uniform wave transformation plots from an XBeach hydrodynamics
structure. Depending on the amount of information provided, different
plots over the x-axis are plotted. Measurements are provided in a nx2
matrix in which the first column is the x-axis and the second the data
axis.

Syntax:
fh = xb_plot_hydro(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = handles:    Figure handle or list of axes handles
            zb:         Measured final profile
            Hrms_hf:    Measured high frequency wave height
            Hrms_lf:    Measured low frequency wave height
            Hrms_t:     Measured total wave height
            s:          Measured water level setup
            urms_hf     Measured high frequency oribtal velocity
            urms_lf     Measured low frequency oribtal velocity
            urms_t      Measured total oribtal velocity
            umean       Measured mean cross-shore flow velocity
            vmean       Measured mean longshore flow velocity
            units_dist: Units used for x- and z-axis
            units_vel:  Units used for secondary z-axis
            showall:    Show all data available instead of only show
                        data matched by measurements

Output:
none

Example:
xb_plot_hydro(xb)
xb_plot_hydro(xb, 'zb', zb, 'Hrms_t', H)

xb_plot_hydro2¶

XB_PLOT_HYDRO2  Create uniform wave transformation plots (advanced)

Create uniform wave transformation plots from an XBeach hydrodynamics
structure. Depending on the amount of information provided, different
plots over the x-axis are plotted. Measurements are provided in a nx2
matrix in which the first column is the x-axis and the second the data
axis. This function plots information additional to the xb_plot_hydro
function and can be seen as the advanced part of the hydrodynamic
analysis.

Syntax:
fh = xb_plot_hydro2(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = handles:    Figure handle or list of axes handles
            urms_hf     Measured high frequency oribtal velocity
            urms_lf     Measured low frequency oribtal velocity
            urms_t      Measured total oribtal velocity
            uavg        Measured mean undertow velocity
            rho         Measured correlation between short wave
                        variance and long wave surface elevation
            SK          Measured wave skewness
            AS          Measured wave asymmetry
            B           Measured wave nonlinearity
            beta        Measured wave phase
            units_dist: Units used for x- and z-axis
            units_corr: Units used for correlation z-axis
            units_skas: Units used for wave shape z-axis
            units_b:    Units used for wave nonlinearity z-axis
            units_vel:  Units used for flow velocity z-axis
            showall:    Show all data available instead of only show
                        data matched by measurements

Output:
none

Example:
xb_plot_hydro2(xb)
xb_plot_hydro2(xb, 'zb', zb, 'Hrms_t', H)

xb_plot_klopman¶

XB_PLOT_KLOPMAN  Plots LF spectrum based on HF spectrum

Implementation of the Klopman and Dingemans (2000) paper based on the
original secspecorg function made by Ap van Dongeren in 2001. The
function computes a low-frequency spectrum from a JONSWAP spectrum.

Syntax:
varargout = xb_plot_klopman(varargin)

Input:
varargin  = Hm0:        significant wave height
            fp:         peak frequency
            df:         frequency resolution
            gamma:      peak-enhancement factor
            h:          water depth
            s:          directional spreading
            K:          number of wave components
            ntheta:     number of directions
            g:          gravitational acceleration
            plot:       boolean flag to enable plotting

Output:
f1        = LF frequencies
S1        = LF energy density
f2        = HF frequencies
S2        = HF energy density

Example:
xb_plot_klopman;
xb_plot_klopman('Hm0', 9, 'fp', 14);

See also

xb_plot_spectrum

xb_plot_morpho¶

XB_PLOT_MORPHO  Create uniform morphology plots

Create uniform morphology plots from an XBeach morphology
structure. Depending on the amount of information provided, different
plots over the x-axis and time are plotted. Measurements are provided
in a nx2 matrix in which the first column is the x-axis and the second
the data axis.

Syntax:
fh = xb_plot_morpho(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = handles:    Figure handle or list of axes handles
            dz:         Measured bed level change
            sed:        Measured sedimentation volume in time
            ero:        Measured erosion volume in time
            R:          Measured retreat distance
            Q:          Measured separation point between erosion and
                        accretion
            P:          Measured delimitation of active zone
            units_dist: Units used for distance axes
            units_vol:  Units used for volume axis
            units_time: Units used for time axis
            showall:    Show all data available instead of only show
                        data matched by measurements

Output:
none

Example:
xb_plot_morpho(xb)
xb_plot_morpho(xb, 'dz', dz, 'sed', sed)

xb_plot_mpi¶

XB_PLOT_MPI  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_plot_mpi(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_plot_mpi

See also

xb_plot_profile¶

XB_PLOT_PROFILE  Create uniform profile plots

Create uniform profile plots from XBeach output structure and other
sources. Standardized coloring is used per source. Automatically
computes Brier Skill Scores and makes sure the dune is located right on
the figure. Additional profiles are supplied in the form of matrices
from which the first column contains x-coordinates and successive
columns contain z-values.

Syntax:
xb_plot_profile(xb, varargin)

Input:
xb       =  XBeach output structure
varargin =  handle:         Figure or axes handle
            measured:       Measured post storm profile
            xbeach:         Profile computed by another version of
                            XBeach
            durosta:        Profile computed by DurosTA
            duros:          Profile computed by DUROS
            duros_p:        Profile computed by DUROS+
            duros_pp:       Profile computed by D++
            nonerodible:    Non-erodible layer
            units:          Units used for x- and z-axis
            BSS:            Boolean indicating whether BSS should be
                            included
            flip:           Boolean indicated whether figure should be
                            flipped in case dune is located left

Output:
none

Example:
xb_plot_profile(xb, 'initial', profile0, 'measured', profile1)

See also

xb_plot_hydro, xb_plot_morpho

xb_plot_sedtrans¶

XB_PLOT_SEDTRANS  Create uniform wave sediment transport plots

Create uniform sediment transport transformation plots from an XBeach
sediment transport structure. Depending on the amount of information
provided, different plots over the x-axis are plotted. Measurements are
provided in a nx2 matrix in which the first column is the x-axis and
the second the data axis.

Syntax:
fh = xb_plot_sedtrans(xb, varargin)

Input:
xb        = XBeach output structure
varargin  = handles:    Figure handle or list of axes handles
            c:          Measured sediment concentration
            k_wavg:     Measured wave averaged turbulence
            k_bavg:     Measured bore averaged turbulence
            k_bavg_nb:  Measured bore averaged near-bed tubulence
            S_dz:       Measured sediment transport from bed level changes
            S_av:       Measured sediment transport from avalancing
            S_s:        Measured suspended sediment transports
            S_b:        Measured bedload sediment transports
            S_lf:       Measured low frequency related sediment
                        transports
            S_ut:       Measured short wave undertow related sediment
                        transports
            S_as:       Measured sediment transports related to wave
                        asymmetry
            units_dist: Units used for x- and z-axis
            units_vol:  Units used for transport z-axis
            showall:    Show all data available instead of only show
                        data matched by measurements

Output:
none

Example:
xb_plot_sedtrans(xb)
xb_plot_sedtrans(xb, 'zb', zb, 'Hrms_t', H)

xb_plot_spectrum¶

XB_PLOT_SPECTRUM  Create uniform spectrum plots

Create uniform spectrum plots from XBeach spectrum structure. Creates a
subplot per location.

Syntax:
fh = xb_plot_spectrum(xb, varargin)

Input:
xb        = XBeach spectrum structure
varargin  = measured:   Measured spectra
            units:      Units used for x- and z-axis
            units2:     Units used for secondary z-axis

Output:
fh        = Figure handle

Example:
fh = xb_plot_spectrum(xb)

xb_select_crop¶

function to draw a rubberband line and return the start and end points
Usage: [xi,yi] = select_oblique_rectangle;     uses current axes
or    [xi,yi] = select_oblique_rectangle(h);  uses axes refered to by handle, h

xb_view¶

XB_VIEW  Generic GUI to visualize XBeach input and output

Graphical User Interface to visualize input and output. The viewer is
*complementary* to the Delft3D QuickPlot (QP) viewer. Most options you
find in this viewer are lacking in QP and vise versa.

This viewer accepts XBeach input, output and run structures or a path
string to an XBeach output directory. In case no input is given, the
current directory is assumed to contain XBeach output. It is also
possible to provide a cell array with different datasources. These
sources can be a mix of types (structures and paths), but need to have
the same spatial grid and equal timestep.

The most important options are:
    * 1D, 2D and 3D plots
    * Multiple variable selection
    * Time sliders and animation
    * Time difference plots
    * Time comparison plots
    * Multiple datasource comparison plots
    * Transect view for 2D models with transect slider
    * Fixation and alignment of caxis
    * Measurement tool

xb_view;
xb_view(xbi);
xb_view(xbr);
xb_view(xbo);
xb_view('path/to/output/dir');
xb_view(pwd, 'width', 1024, 'height', 768, 'modal', true);

Syntax:
xb_view(data, varargin)

Input:
data      = XBeach structure (input, output or run) or path to XBeach
Output:
varargin  = width:  Width of window at startup (inf = screensize)
            height: Height of window at startup (inf = screensize)
            model:  Boolean indicating modal state

Output:
none

Example:
xbi = xb_generate_model;
xbr = xb_run(xbi, 'path', 'path/to/output/dir');
xbo = xb_read_output('path/to/output/dir');

See also

xb_plot_profile

xb_visualize_modelsetup¶

XB_VISUALIZE_MODELSETUP  One line description goes here.

More detailed description goes here.

Syntax:
varargout = xb_visualize_modelsetup(varargin)

Input:
varargin  =

Output:
varargout =

Example:
xb_visualize_modelsetup

See also

xb_write_skilltable¶

XB_WRITE_SKILLTABLE  Writes Latex table with skills to file

Writes Latex table with skills to file

Syntax:
varargout = xb_write_skilltable(xb, measured, varargin)

Input:
xb        = XBeach output structure
measured  = Cell array containing measurement data with in the first
            column the x-axis values and the second column z-axis
            values
initial   = Cell array containing initial data with in the first
            column the x-axis values and the second column z-axis
            values
varargin  = file:   Filename
            title:  Table title
            vars:   Cell array with variable names to plot

Output:
none

Example:
xb_write_skilltable(xb, measured, initial)

See also

xb_skill

QuickPlot¶

RFGrid¶

Sphinx cheatsheet¶

Sphinx source files are plain text files. You can simply write your text in a text editor of your choice. Separate paragraphs by a blank line and you will do ok.

Some simple markup code is available to set text formatting, insert headers, figures and tables and make cross-references throughout the document. The most important markup code is listed below.

Text formatting¶

Simple text formatting is available:

*italic*
**bold**

Bullet lists:
* bullet 1
* bullet 2
* bullet 3

Numbered lists:
#. item 1
#. item 2
#. item 3

Headers¶

Headers can be added by using different underlining. Optionally, an
header can have a label. You can make references to a header using
its label as follows: Section :ref:`sec-heading`.

Heading 1
=========

Heading 2
---------

Heading 3
^^^^^^^^^

Heading 4
~~~~~~~~~

.. _sec-heading:

Heading with label
------------------

Figures¶

Figure are created using the following code. A figure points to a
filename and has a caption. Optionally, you can add a label and set
the width, alignment and other common figure properties. You can
make references to a figure using its label as follows: Figure
:numref:`fig-coordsys-rect`.

.. _fig-coordsys-rect:

.. figure:: image8.png
   :width: 400px
   :align: center

   Rectangular coordinate system of XBeach

Tables¶

Tables are created using the following code. A table has a
captionfigure points to a filename and has a caption. Optionally,
you can add a label. You can make references to a table using its
label as follows: Table :numref:`tab-wave-breaking`.

.. _tab-wave-breaking:

.. table:: Different wave breaking formulations implemented

   +-----------------------------+-----------------+------------------+
   | Wave breaking formula       | Type of waves   | keyword          |
   +=============================+=================+==================+
   | Roelvink (1993a)            | Instationary    | roelvink1        |
   +-----------------------------+-----------------+------------------+
   | Roelvink (1993a) extended   | Instationary    | roelvink2        |
   +-----------------------------+-----------------+------------------+
   | Daly et al. (2010)          | Instationary    | roelvink_daly    |
   +-----------------------------+-----------------+------------------+
   | Baldock et al. (1998)       | Stationary      | baldock          |
   +-----------------------------+-----------------+------------------+
   | Janssen & Battjes (2007)    | Stationary      | janssen          |
   +-----------------------------+-----------------+------------------+

Equations¶

Equations can be created using Latex math code or by copying and
pasting from MathType. An equation is created using the following
code. An equation has a label. You can make references to an
equation using its label as follows: Equation :eq:`eq-eikonal`.

.. math::
   :label: eikonal

   \begin{array}{l}
   {k_{x} =k_{x}^{n-1} +k_{x}^{:} } \\
   {k_{y} =k_{y}^{n-1} +k_{y}^{:} } \\
   \end{array}

Inline math can be added as follows: :math:`k_x`.

Citations¶

Literature references are added using a BibTeX file maintained
through the Mendeley XBeach group. You can cite a reference using
:cite:`Roelvink2009`.

Parameter lists¶

Parameter lists can be exported using the XBeach maintainance
toolbox. These exports have syntax according to the following
code. This code is rendered as a normal table. References to
individual parameters can be made as follows: :par:`<Brfac>`.

.. partable:: Overview of available keywords

   ARC
     :advanced:
     :description:   Switch for active reflection compensation at seaward boundary
     :units:         -
     :default:       1
     :range:         0 - 1
   Brfac
     :advanced:
     :description:   Calibration factor surface slope
     :units:         -
     :default:       1.0
     :range:         0.0 - 1.0
   C
     :description:   Chezy coefficient
     :units:         m^0.5s^-1
     :default:       55.0
     :range:         20.0 - 100.0

Source code references¶References to the Fortran source code can be made with the
following code. Note that the references are made to the actual
name of the module, which is not necessarily the same as the
filename.

Module: :f:mod:`flow_timestep_module`

Function: :f:mod:`flow_timestep_module/visc_smagorinsky`

Includes¶

Other RST files can be included with the following code. Including
files is used to embed the automatically generated parameter lists
into the documentation.

.. include:: tables/partable_all.tab

File contents¶

Literal file contents can be added using the following code.

**jonswap.txt**

.. code-block:: text

   Hm0 = 0.8
   Tp = 8
   mainang = 285.
   gammajsp = 3.3
   s = 10.
   fnyq = 0.3

Footnotes and URL’s¶

References to footnotes and URL's are made using the following code:

Footnote: [#1]_

URL: [http://www.xbeach.org]_

The footnote itself is made as follows:

.. [#1] This is a footnote