Oceananigans.jl

Oceananigans provides three primary ways to save simulation data to disk using AbstractOutputWriters:

1. NetCDFWriter: Best for saving arrays and scalars to NetCDF files (uses NCDatasets.jl). Ideal for standard scientific data formats.
2. JLD2Writer: Best for saving arbitrary Julia data structures (uses JLD2.jl). These files are HDF5-compatible and can be opened in Julia with JLD2.jl or in Python with h5py.
3. Checkpointer: Automatically saves as much model data as possible for simulation recovery (uses JLD2.jl).

To use a writer, create the instance and add it to the simulation.output_writers dictionary before calling run!(simulation).

In bounded, non-periodic directions, you can impose several types of boundary conditions. Note that for a velocity field, the only available boundary condition for the component normal to the bounded direction is no-penetration.

Available boundary condition types:

• Flux: Prescribes the flux of a quantity normal to the boundary.
• Gradient (Neumann): Prescribes the gradient of a field normal to the boundary.
• Value (Dirichlet): Prescribes the specific value of a field on the boundary.
• No penetration: Prescribes the velocity component normal to the boundary to be 0.

Oceananigans provides different explicit time-stepping schemes depending on the model being used. The TimeSteppers module handles the time integration of prognostic fields, while the model itself is responsible for computing tendencies.

In Oceananigans, RectilinearGrid uses a Cartesian coordinate system. This provides a local, flat (Euclidean) representation of space using coordinates $(x, y, z)$ and unit vectors $\boldsymbol{\hat x}$, $\boldsymbol{\hat y}$, and $\boldsymbol{\hat z}$.

Conventions:

• $\boldsymbol{\hat x}$: Points East.
• $\boldsymbol{\hat y}$: Points North.
• $\boldsymbol{\hat z}$: Points "upward" (opposite to the direction of gravitational acceleration).

Velocity Representation: Three-dimensional velocity is $\boldsymbol{v} = u \boldsymbol{\hat x} + v \boldsymbol{\hat y} + w \boldsymbol{\hat z}$, where $u, v, w$ are the velocity components in the $x, y, z$ directions respectively. Horizontal velocity is denoted as $\boldsymbol{u} = u \boldsymbol{\hat x} + v \boldsymbol{\hat y}$.

Momentum Conservation

The model solves for momentum in a rotating fluid with buoyancy via the Boussinesq approximation. The momentum equation includes:

• Momentum advection: (v · ∇) u
• Coriolis force: f × u
• Baroclinic kinematic pressure gradient: ∇ p
• Barotropic kinematic pressure gradient: ∇ (g η)
• Viscous stress: ∇ · τ
• Internal forcing: F_u

Note: For curvilinear grids like LatitudeLongitudeGrid, the advection term is implemented in vector-invariant form using vertical relative vorticity ζ.

Tracer Conservation

Tracer equations follow the form:

∂t c = - v · ∇ c - ∇ · q_c + F_c

Where:

• v · ∇ c is tracer advection
• ∇ · q_c is molecular or turbulent diffusion
• F_c is an arbitrary internal source term

The choice of grid depends on the physical shape of your domain:

1. RectilinearGrid: Used for lines, rectangles, and boxes (Cartesian coordinates x, y, z).
2. LatitudeLongitudeGrid: Used for sectors of thin spherical shells with cells bounded by constant latitude and longitude (Geographic coordinates λ, φ, z).
3. OrthogonalSphericalShellGrid: Used for sectors of thin spherical shells with arbitrary mesh lines that intersect at right angles.

Note that LatitudeLongitudeGrid and OrthogonalSphericalShellGrid use geographic coordinates (λ, φ, z), where λ is longitude, φ is latitude, and z is height. You can inspect these using λnodes, φnodes, λspacings, and φspacings.

The SplitRungeKuttaTimeStepper is designed for split-explicit computations (e.g., treating barotropic and baroclinic modes separately in a HydrostaticFreeSurfaceModel).

At the start of each time step, prognostic fields are cached. Subsequent substeps then compute the update using the cached initial state and stage coefficients $\beta$. The default three-stage scheme uses $\beta = (3, 2, 1)$.