Coordinate system and notation

Oceananigans.jl is formulated in a Cartesian coordinate system $\bm{x} = (x, y, z)$ with unit vectors $\bm{\hat x}$, $\bm{\hat y}$, and $\bm{\hat z}$, where $\bm{\hat x}$ points east, $\bm{\hat y}$ points north, and $\bm{\hat z}$ points 'upward', opposite the direction of gravitational acceleration. We denote time with $t$, partial derivatives with respect to time $t$ or a coordinate $x$ with $\partial_t$ or $\partial_x$, and denote the gradient operator $\bm{\nabla} \equiv \partial_x \bm{\hat x} + \partial_y \bm{\hat y} + \partial_z \bm{\hat z}$. We use $u$, $v$, and $w$ to denote the east, north, and vertical velocity components, such that $\bm{u} = u \bm{\hat x} + v \bm{\hat y} + w \bm{\hat z}$.

The Boussinesq Navier-Stokes equations and tracer conservation equations

Oceananigans.jl solves the incompressible Navier-Stokes equations under the Boussinesq approximation^[1] and an arbitrary number of tracer conservation equations. Physics associated with individual terms in the momentum and tracer conservation equations –- the background rotation rate of the equation's reference frame, gravitational effects associated with buoyant tracers under the Boussinesq approximation, generalized stresses and tracer fluxes associated with viscous and diffusive physics, and arbitrary "forcing functions" –- are determined by the whims of the user.

The fluid density $\rho$ in Oceananigans.jl is, in general, decomposed into three components:

\[ \rho(\bm{x}, t) = \rho_0 + \rho_*(z) + \rho'(\bm{x}, t) \, ,\]

where $\rho_0$ is a constant 'reference' density, $\rho_*(z)$ is a background density profile which, when non-zero, is typically associated with the hydrostatic compression of seawater in the deep ocean, and $\rho'(\bm{x}, t)$ is the dynamic component of density corresponding to inhomogeneous distributions of a buoyant tracer such as temperature or salinity. The fluid buoyancy, associated with the buoyant acceleration of fluid, is defined in terms of $\rho'$ as

\[ b = - \frac{g \rho'}{\rho_0} \, ,\]

where $g$ is gravitational acceleration.

The Boussinesq approximation is valid when $\rho_* + \rho' \ll \rho_0$, which implies the fluid is approximately incompressible, and thus does not support acoustic waves. In this case, the mass conservation equation reduces to the continuity equation

\[ \bm{\nabla} \bm{\cdot} \bm{u} = \partial_x u + \partial_y v + \partial_z w = 0 \, . \tag{eq:continuity}\]

The momentum conservation equation

The equations governing the conservation of momentum in a rotating fluid, including buoyancy via the Boussinesq approximation and including the averaged effects of surface gravity waves at the top of the domain via the Craik-Leibovich approximation are

\[ \partial_t \bm{u} = - \left ( \bm{u} \bm{\cdot} \bm{\nabla} \right ) \bm{u} - \left ( \bm{U} \bm{\cdot} \bm{\nabla} \right ) \bm{u} - \left ( \bm{u} \bm{\cdot} \bm{\nabla} \right ) \bm{U} - \left ( \bm{f} - \bm{\nabla} \times \bm{u}^S \right ) \times \bm{u} - \bm{\nabla} \phi + b \bm{\hat z} - \bm{\nabla} \bm{\cdot} \bm{\tau} + \partial_t \bm{u}^S + \bm{F_u} \, , \tag{eq:momentum}\]

where $b$ is buoyancy, $\bm{\tau}$ is the kinematic stress tensor, $\bm{F_u}$ denotes an internal forcing of the velocity field $\bm{u}$, $\phi$ is the potential associated with kinematic and constant hydrostatic contributions to pressure, $\bm{u}^S$ is the 'Stokes drift' velocity field associated with surface gravity waves, and $\bm{f}$ is Coriolis parameter, or the background vorticity associated with the specified rate of rotation of the frame of reference.

From left to right, the terms that appear on the right-hand side of the momentum conservation equation are:

• momentum advection, $\left ( \bm{u} \bm{\cdot} \bm{\nabla} \right ) \bm{u}$,
• advection of resolved momentum by the background velocity field $\bm{U}$, $\left ( \bm{U} \bm{\cdot} \bm{\nabla} \right ) \bm{u}$,
• advection of background momentum by resolved velocity, $\left ( \bm{u} \bm{\cdot} \bm{\nabla} \right ) \bm{U}$,
• coriolis, $\bm{f} \times \bm{u}$
• the effective background rotation rate due to surface waves, $\bm{\nabla} \times \bm{u}^S \right ) \times \bm{u}$
• pressure, $\bm{\nabla} \phi$,
• buoyant acceleration, $b \bm{\hat z}$
• molecular or turbulence viscous stress, $\bm{\nabla} \bm{\cdot} \bm{\tau}$
• a source of momentum due to forcing or damping of surface waves, $\partial_t \bm{u}^S$
• an arbitrary internal source of momentum, $\bm{F_u}$

The tracer conservation equation

The conservation law for tracers in Oceananigans.jl is

\[ \partial_t c = - \bm{u} \bm{\cdot} \bm{\nabla} c - \bm{U} \bm{\cdot} \bm{\nabla} c - \bm{u} \bm{\cdot} \bm{\nabla} C - \bm{\nabla} \bm{\cdot} \bm{q}_c + F_c \, , \tag{eq:tracer}\]

where $\bm{q}_c$ is the diffusive flux of $c$ and $F_c$ is an arbitrary source term. Oceananigans.jl permits arbitrary tracers and thus an arbitrary number of tracer equations to be solved simultaneously with the momentum equations.

From left to right, the terms that appear on the right-hand side of the tracer conservation equation are

• tracer advection, $\bm{u} \bm{\cdot} \bm{\nabla} c$
• tracer advection by the background velocity field, $U$, $\bm{U} \bm{\cdot} \bm{\nabla} c$
• advection of the background tracer field, $C$, by the resolved velocity field, $\bm{u} \bm{\cdot} \bm{\nabla} C$
• molecular or turbulent diffusion, $\bm{\nabla} \bm{\cdot} \bm{q}_c$
• an arbitrary internal source of tracer, $F_c$

The following subsections provide more details on the possible forms that each individual term in the momentum and tracer equations can take in Oceananigans.jl.