shallowwater

Module: fridom.shallowwater

Submodules

exceptions	exceptions.py - Custom exceptions for the framework.
projection	Projection.
time_steppers	Time Steppers.
utils	Utility functions and classes for the FRIDOM framework.
grid	Grids for the shallow water model.
modules	A collection of modules for the shallow water model.
initial_conditions	Initial Conditions for the shallow water model.

Classes, Functions, and Variables

config

Configuration class for the fridom framework.

log	Instances of the Logger class represent a single logging channel.

ModelSettings(grid, **kwargs)

Model settings for the 2D shallow water model.

State(mset, **kwargs)

State vector of the 2D shallow water model.

FieldMetadata(name, long_name, units, ...)

Metadata for the ScalarField.

ScalarField(mset[, mdata, arr])

A scalar mapping from grid space to real / complex numbers.

VectorField(mset[, field_list, vector_dim])

A vector mapping from grid space to the vector space.

TensorField(mset)

ModelState(mset[, clock])

Stores the model state variables and the time information.

Model(mset)

The main model class.

Clock([start_date, start_time])	A clock to keep track of the model time.
TimingFormat(value[, names, module, ...])	The timing format for the model clock.

ClockTrigger([start_date, start_step, ...])

Emits signals based on the state of a clock.

A 2D scaled rotating shallow water model.

System of equations

\[\partial_t \boldsymbol{u} + Ro~\, \boldsymbol{u} \cdot \nabla \boldsymbol{u} = - f \underset{\neg}{\boldsymbol u} - \nabla p + \boldsymbol{F}_\boldsymbol{u}\]

\[\partial_t p + Ro~\, \nabla \cdot \left( p \boldsymbol{u} \right) = - c^2 \nabla \cdot \boldsymbol{u} + \boldsymbol{F}_h\]

with:

• \(\boldsymbol{u} = (u,v)\) the horizontal velocity vector, the hook operator rotates the vector by 90 degrees: \(\underset{\neg}{\boldsymbol u} = (-v,u)\)

• \(p=g \eta\) is the pressure perturbation. (\(\eta\) is the free surface displacement, \(g\) is the acceleration due to gravity)

• \(\boldsymbol{F}\) are source and sink terms

• \(f\) is the Coriolis parameter

• \(c^2\) is the phase speed of the gravity waves (\(c^2 = g H\)) in the unscaled system (with \(H\) the depth of the fluid). In the scaled system \(c^2\) corresponds to the Burger number

• \(Ro = \frac{U}{f L}\) is the Rossby number (only for the scaled system, in unscaled system it is \(Ro=1\))

Derivation

Start with the hydrostatic Navier Stokes equations with constant density and neglect the source terms:

\[D_t \boldsymbol{u} = - f \underset{\neg}{\boldsymbol u} - \frac{1}{\rho_0} \nabla p' ~, \quad \partial_z p' = - \rho_0 g ~, \quad \nabla \cdot \boldsymbol{u} + \partial_z w = 0\]

where \(D_t = \partial_t + \boldsymbol{u} \cdot \nabla\) is the material derivative and \(p'\) is the pressure. Let the free surface displacement be given by \(\eta(x,y,t)\). By integrating the hydrostatic equation from some depth level \(z\) to the surface, we obtain the pressure:

\[p'(\boldsymbol{x},z) = p'(\boldsymbol{x}, \eta) + \int_{\eta}^z \partial_{z'} p' dz' = p'(\boldsymbol{x}, \eta) + \int_z^{\eta} \rho_0 g dz' = p'(\boldsymbol{x}, \eta) + \rho_0 g (\eta + z)\]

Define new pressure variable \(p = g \eta\) and assume constant atmospheric pressure, i.e. \(\nabla p'(\boldsymbol{x}, \eta) = 0\). Then the horizontal pressure gradient is:

\[\frac{1}{\rho_0} \nabla p' = \nabla p\]

Inserting the new pressure variable into the momentum equation yields the momentum equation in the form given above (with \(Ro=1\)). To derive an equation for the new pressure variable, we first need to derive an equation for the free surface displacement. For that, we need the differential of the free surface displacement:

\[d\eta = \nabla \eta \cdot d\boldsymbol{x} + \partial_t \eta dt\]

The total time derivative of the surface displacement should be equal to the vertical velocity at the surface, while the vertical velocity at the bottom (\(z=-H\)) should be zero:

\[w|_{z=\eta} = \frac{d\eta}{dt} = (\nabla \eta) \cdot \boldsymbol{u} + \partial_t \eta = D_t \eta ~, \quad w|_{z=-H} = 0\]

Now we relate the vertical velocity at the top to the horziontal velocity field. For this, we integrate the continuity equation from the bottom to the surface and assume barotropic conditions (i.e. \(\partial_z \boldsymbol{u} = 0\)):

\[ \begin{align}\begin{aligned}0 = \int_{-H}^{\eta} \nabla \cdot \boldsymbol{u} + \partial_z w dz = (\eta + H) \nabla \cdot \boldsymbol{u} + w|_{z=\eta} - w|_{z=-H}\\\Rightarrow \quad D_t \eta + (\eta + H) \nabla \cdot \boldsymbol{u} = 0\end{aligned}\end{align} \]

multiply with the gravitational acceleration \(g\) yields

\[D_t p + (p + c^2) \nabla \cdot \boldsymbol{u} = 0 \quad \Longleftrightarrow \quad \partial_t p + \nabla \cdot (p \boldsymbol{u}) = - c^2 \nabla \cdot \boldsymbol{u}\]

with \(p = g \eta\) and \(c^2 = g H\).

Scaling

We start with the unscaled shallow water equations from above:

\[\partial_t \boldsymbol{u} + \boldsymbol{u} \cdot \nabla \boldsymbol{u} = - f \underset{\neg}{\boldsymbol u} - \nabla p ~, \quad \partial_t p + \nabla \cdot \left( p \boldsymbol{u} \right) = - c^2 \nabla \cdot \boldsymbol{u}\]

and introduce the following scaling:

\[t = \frac{1}{\Omega} t' ~, \quad \boldsymbol{x} = L \boldsymbol{x}' ~, \quad f = \Omega f' ~, \quad \boldsymbol{u} = U \boldsymbol{u}' ~, \quad p = P p'\]

where the variables with a prime are the nondimensional variables. we further introduce the Rossby number \(Ro\), the Froude number \(Fr\), and assume geostrophic balance on first order:

\[Ro = \frac{U}{\Omega L} ~, \quad Fr = \frac{U}{c} ~, \quad \Omega U = \frac{P}{L}\]

Inserting the nondimensional variables into the shallow water equations yields:

\[\partial_{t'} \boldsymbol{u}' + Ro~\, \boldsymbol{u}' \cdot \nabla' \boldsymbol{u}' = - f' \underset{\neg}{\boldsymbol u}' - \nabla' p' ~, \quad \partial_{t'} p' + Ro~\, \nabla' \cdot \left( p' \boldsymbol{u}' \right) = - \frac{{Ro}^2}{{Fr}^2} \nabla' \cdot \boldsymbol{u}'\]

Drop the primes, and use the Burger number \(Bu = \frac{{Ro}^2}{{Fr}^2}\) yields the scaled shallow water equations.