# Library

Documenting the public user interface.

## Oceananigans.jl

`Oceananigans.Oceananigans`

— ModuleMain module for `Oceananigans.jl`

– a Julia software for fast, friendly, flexible, data-driven, ocean-flavored fluid dynamics on CPUs and GPUs.

## Abstract operations

`Oceananigans.AbstractOperations.volume`

— Constant`volume = VolumeMetric()`

Instance of `VolumeMetric`

that generates `BinaryOperation`

s between `AbstractField`

s and their cell volumes. Summing this `BinaryOperation`

yields an integral of `AbstractField`

over the domain.

**Example**

```
julia> using Oceananigans
julia> using Oceananigans.AbstractOperations: volume
julia> grid = RectilinearGrid(size=(2, 2, 2), extent=(1, 2, 3)); c = CenterField(grid);
julia> c .= 1;
julia> c_dV = c * volume
BinaryOperation at (Center, Center, Center)
├── grid: 2×2×2 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
└── tree:
* at (Center, Center, Center)
├── 2×2×2 Field{Center, Center, Center} on RectilinearGrid on CPU
└── Vᶜᶜᶜ at (Center, Center, Center)
julia> c_dV[1, 1, 1]
0.75
julia> sum(c_dV)
6.0
```

`Oceananigans.AbstractOperations.Δz`

— Constant`Δz = ZSpacingMetric()`

Instance of `ZSpacingMetric`

that generates `BinaryOperation`

s between `AbstractField`

s and the vertical grid spacing evaluated at the same location as the `AbstractField`

.

`Δx`

and `Δy`

play a similar role for horizontal grid spacings.

**Example**

```
julia> using Oceananigans
julia> using Oceananigans.AbstractOperations: Δz
julia> grid = RectilinearGrid(size=(1, 1, 1), extent=(1, 2, 3)); c = CenterField(grid);
julia> c_dz = c * Δz # returns BinaryOperation between Field and GridMetricOperation
BinaryOperation at (Center, Center, Center)
├── grid: 1×1×1 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
└── tree:
* at (Center, Center, Center)
├── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
└── Δzᶜᶜᶜ at (Center, Center, Center)
julia> c .= 1;
julia> c_dz[1, 1, 1]
3.0
```

`Oceananigans.AbstractOperations.Average`

— Method`Average(field::AbstractField; condition = nothing, mask = 0, dims=:)`

Return `Reduction`

representing a spatial average of `field`

over `dims`

.

Over regularly-spaced dimensions this is equivalent to a numerical `mean!`

.

Over dimensions of variable spacing, `field`

is multiplied by the appropriate grid length, area or volume, and divided by the total spatial extent of the interval.

`Oceananigans.AbstractOperations.BinaryOperation`

— Method`BinaryOperation{LX, LY, LZ}(op, a, b, ▶a, ▶b, grid)`

Return an abstract representation of the binary operation `op(▶a(a), ▶b(b))`

on `grid`

, where `▶a`

and `▶b`

interpolate `a`

and `b`

to locations `(LX, LY, LZ)`

.

`Oceananigans.AbstractOperations.ConditionalOperation`

— Method```
ConditionalOperation(operand::AbstractField;
func = identity,
condition = nothing,
mask = 0)
```

Return an abstract representation of a masking procedure applied when `condition`

is satisfied on a field described by `func(operand)`

.

**Positional arguments**

`operand`

: The`AbstractField`

to be masked (it must have a`grid`

property!)

**Keyword arguments**

`func`

: A unary transformation applied element-wise to the field`operand`

at locations where`condition == true`

. Default is`identity`

.`condition`

: either a function of`(i, j, k, grid, operand)`

returning a Boolean, or a 3-dimensional Boolean`AbstractArray`

. At locations where`condition == false`

, operand will be masked by`mask`

`mask`

: the scalar mask

`condition_operand`

is a convenience function used to construct a `ConditionalOperation`

`condition_operand(func::Function, operand::AbstractField, condition, mask) = ConditionalOperation(operand; func, condition, mask)`

**Example**

```
julia> using Oceananigans
julia> using Oceananigans.Fields: condition_operand
julia> c = CenterField(RectilinearGrid(size=(2, 1, 1), extent=(1, 1, 1)));
julia> f(i, j, k, grid, c) = i < 2; d = condition_operand(cos, c, f, 10)
ConditionalOperation at (Center, Center, Center)
├── operand: 2×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
├── grid: 2×1×1 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── func: cos (generic function with 26 methods)
├── condition: f (generic function with 1 method)
└── mask: 10
julia> d[1, 1, 1]
1.0
julia> d[2, 1, 1]
10
```

`Oceananigans.AbstractOperations.Derivative`

— Method`Derivative{LX, LY, LZ}(∂, arg, ▶, grid)`

Return an abstract representation of the derivative `∂`

on `arg`

, and subsequent interpolation by `▶`

on `grid`

.

`Oceananigans.AbstractOperations.Integral`

— Method`Integral(field; dims=:)`

Return a `Reduction`

representing a spatial integral of `field`

over `dims`

.

`Oceananigans.AbstractOperations.KernelFunctionOperation`

— Method```
KernelFunctionOperation{LX, LY, LZ}(kernel_function, grid;
computed_dependencies=(), parameters=nothing)
```

Construct a `KernelFunctionOperation`

at location `(LX, LY, LZ)`

on `grid`

an with an optional iterable of `computed_dependencies`

and arbitrary `parameters`

.

With `isnothing(parameters)`

(the default), `kernel_function`

is called with

`kernel_function(i, j, k, grid, computed_dependencies...)`

Otherwise `kernel_function`

is called with

`kernel_function(i, j, k, grid, computed_dependencies..., parameters)`

**Examples**

Construct a kernel function operation that returns random numbers:

```
random_kernel_function(i, j, k, grid) = rand() # use CUDA.rand on the GPU
kernel_op = KernelFunctionOperation{Center, Center, Center}(random_kernel_function, grid)
```

Construct a kernel function operation using the vertical vorticity operator valid on curvilinear and cubed sphere grids:

```
using Oceananigans.Operators: ζ₃ᶠᶠᶜ # called with signature ζ₃ᶠᶠᶜ(i, j, k, grid, u, v)
grid = model.grid
u, v, w = model.velocities
ζ_op = KernelFunctionOperation{Face, Face, Center}(ζ₃ᶠᶠᶜ, grid, computed_dependencies=(u, v))
```

`Oceananigans.AbstractOperations.UnaryOperation`

— Method`UnaryOperation{LX, LY, LZ}(op, arg, ▶, grid)`

Returns an abstract `UnaryOperation`

representing the action of `op`

on `arg`

, and subsequent interpolation by `▶`

on `grid`

.

`Oceananigans.AbstractOperations.∂x`

— MethodReturn the $x$-derivative function acting at (`X`

, `Y`

, `Any`

).

`Oceananigans.AbstractOperations.∂x`

— Method`∂x(L::Tuple, arg::AbstractField)`

Return an abstract representation of an $x$-derivative acting on field `arg`

followed by interpolation to `L`

, where `L`

is a 3-tuple of `Face`

s and `Center`

s.

`Oceananigans.AbstractOperations.∂x`

— Method`∂x(arg::AbstractField)`

Return an abstract representation of a $x$-derivative acting on field `arg`

.

`Oceananigans.AbstractOperations.∂y`

— MethodReturn the $y$-derivative function acting at (`X`

, `Y`

, `Any`

).

`Oceananigans.AbstractOperations.∂y`

— Method`∂y(L::Tuple, arg::AbstractField)`

Return an abstract representation of a $y$-derivative acting on field `arg`

followed by interpolation to `L`

, where `L`

is a 3-tuple of `Face`

s and `Center`

s.

`Oceananigans.AbstractOperations.∂y`

— Method`∂y(arg::AbstractField)`

Return an abstract representation of a $y$-derivative acting on field `arg`

.

`Oceananigans.AbstractOperations.∂z`

— MethodReturn the $z$-derivative function acting at (`Any`

, `Any`

, `Z`

).

`Oceananigans.AbstractOperations.∂z`

— Method`∂z(L::Tuple, arg::AbstractField)`

Return an abstract representation of a $z$-derivative acting on field `arg`

followed by interpolation to `L`

, where `L`

is a 3-tuple of `Face`

s and `Center`

s.

`Oceananigans.AbstractOperations.∂z`

— Method`∂z(arg::AbstractField)`

Return an abstract representation of a $z$-derivative acting on field `arg`

.

`Oceananigans.AbstractOperations.@at`

— Macro`@at location abstract_operation`

Modify the `abstract_operation`

so that it returns values at `location`

, where `location`

is a 3-tuple of `Face`

s and `Center`

s.

`Oceananigans.AbstractOperations.@binary`

— Macro`@binary op1 op2 op3...`

Turn each binary function in the list `(op1, op2, op3...)`

into a binary operator on `Oceananigans.Fields`

for use in `AbstractOperations`

.

Note: a binary function is a function with two arguments: for example, `+(x, y)`

is a binary function.

Also note: a binary function in `Base`

must be imported to be extended: use `import Base: op; @binary op`

.

**Example**

```
julia> using Oceananigans, Oceananigans.AbstractOperations
julia> using Oceananigans.AbstractOperations: BinaryOperation, AbstractGridMetric, choose_location
julia> plus_or_times(x, y) = x < 0 ? x + y : x * y
plus_or_times (generic function with 1 method)
julia> @binary plus_or_times
Set{Any} with 6 elements:
:+
:/
:^
:-
:*
:plus_or_times
julia> c, d = (CenterField(RectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1))) for i = 1:2);
julia> plus_or_times(c, d)
BinaryOperation at (Center, Center, Center)
├── grid: 1×1×1 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
└── tree:
plus_or_times at (Center, Center, Center)
├── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
└── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
```

`Oceananigans.AbstractOperations.@multiary`

— Macro`@multiary op1 op2 op3...`

Turn each multiary operator in the list `(op1, op2, op3...)`

into a multiary operator on `Oceananigans.Fields`

for use in `AbstractOperations`

.

Note that a multiary operator:

- is a function with two or more arguments: for example,
`+(x, y, z)`

is a multiary function; - must be imported to be extended if part of
`Base`

: use`import Base: op; @multiary op`

; - can only be called on
`Oceananigans.Field`

s if the "location" is noted explicitly; see example.

**Example**

```
julia> using Oceananigans, Oceananigans.AbstractOperations
julia> harmonic_plus(a, b, c) = 1/3 * (1/a + 1/b + 1/c)
harmonic_plus (generic function with 1 method)
julia> c, d, e = Tuple(CenterField(RectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1))) for i = 1:3);
julia> harmonic_plus(c, d, e) # before magic @multiary transformation
BinaryOperation at (Center, Center, Center)
├── grid: 1×1×1 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
└── tree:
* at (Center, Center, Center)
├── 0.3333333333333333
└── + at (Center, Center, Center)
├── / at (Center, Center, Center)
│ ├── 1
│ └── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
├── / at (Center, Center, Center)
│ ├── 1
│ └── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
└── / at (Center, Center, Center)
├── 1
└── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
julia> @multiary harmonic_plus
Set{Any} with 3 elements:
:+
:harmonic_plus
:*
julia> harmonic_plus(c, d, e)
MultiaryOperation at (Center, Center, Center)
├── grid: 1×1×1 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
└── tree:
harmonic_plus at (Center, Center, Center)
├── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
├── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
└── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
```

`Oceananigans.AbstractOperations.@unary`

— Macro`@unary op1 op2 op3...`

Turn each unary function in the list `(op1, op2, op3...)`

into a unary operator on `Oceananigans.Fields`

for use in `AbstractOperations`

.

Note: a unary function is a function with one argument: for example, `sin(x)`

is a unary function.

Also note: a unary function in `Base`

must be imported to be extended: use `import Base: op; @unary op`

.

**Example**

```
julia> using Oceananigans, Oceananigans.Grids, Oceananigans.AbstractOperations
julia> square_it(x) = x^2
square_it (generic function with 1 method)
julia> @unary square_it
Set{Any} with 10 elements:
:+
:sqrt
:square_it
:cos
:exp
:interpolate_identity
:-
:tanh
:sin
:abs
julia> c = CenterField(RectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1)));
julia> square_it(c)
UnaryOperation at (Center, Center, Center)
├── grid: 1×1×1 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
└── tree:
square_it at (Center, Center, Center) via identity
└── 1×1×1 Field{Center, Center, Center} on RectilinearGrid on CPU
```

## Advection

`Oceananigans.Advection.Centered`

— Type`struct Centered{N, FT, XT, YT, ZT, CA} <: AbstractCenteredAdvectionScheme{N, FT}`

Centered reconstruction scheme.

`Oceananigans.Advection.UpwindBiased`

— Type`struct UpwindBiasedFifthOrder <: AbstractUpwindBiasedAdvectionScheme{3}`

Upwind-biased fifth-order advection scheme.

`Oceananigans.Advection.WENO`

— Type```
WENO([FT=Float64;]
order = 5,
grid = nothing,
zweno = true,
vector_invariant = nothing,
bounds = nothing)
```

Construct a weigthed essentially non-oscillatory advection scheme of order `order`

.

**Keyword arguments**

`order`

: The order of the WENO advection scheme. Default: 5`grid`

: (defaults to`nothing`

)`vector_invariant`

: The stencil for which the vector-invariant form of the advection scheme would use. Options`VelocityStencil()`

or`VorticityStencil()`

; defaults to`nothing`

.`zweno`

: When`true`

implement a Z-WENO formulation for the WENO weights calculation. (defaults to`true`

)

**Examples**

```
julia> using Oceananigans;
julia> WENO()
WENO reconstruction order 5 in Flux form
Smoothness formulation:
└── Z-weno
Boundary scheme:
└── WENO reconstruction order 3 in Flux form
Symmetric scheme:
└── Centered reconstruction order 4
Directions:
├── X regular
├── Y regular
└── Z regular
```

```
julia> using Oceananigans;
julia> Nx, Nz = 16, 10;
julia> Lx, Lz = 1e4, 1e3;
julia> chebychev_spaced_z_faces(k) = - Lz/2 - Lz/2 * cos(π * (k - 1) / Nz);
julia> grid = RectilinearGrid(size = (Nx, Nz), halo = (4, 4), topology=(Periodic, Flat, Bounded),
x = (0, Lx), z = chebychev_spaced_z_faces);
julia> WENO(grid; order=7)
WENO reconstruction order 7 in Flux form
Smoothness formulation:
└── Z-weno
Boundary scheme:
└── WENO reconstruction order 5 in Flux form
Symmetric scheme:
└── Centered reconstruction order 6
Directions:
├── X regular
├── Y regular
└── Z stretched
```

`Oceananigans.Advection.div_Uc`

— Method`div_uc(i, j, k, grid, advection, U, c)`

Calculate the divergence of the flux of a tracer quantity $c$ being advected by a velocity field, $𝛁⋅(𝐯 c)$,

`1/V * [δxᶜᵃᵃ(Ax * u * ℑxᶠᵃᵃ(c)) + δyᵃᶜᵃ(Ay * v * ℑyᵃᶠᵃ(c)) + δzᵃᵃᶜ(Az * w * ℑzᵃᵃᶠ(c))]`

which ends up at the location `ccc`

.

`Oceananigans.Advection.div_𝐯u`

— Method`div_𝐯u(i, j, k, grid, advection, U, u)`

Calculate the advection of momentum in the $x$-direction using the conservative form, $𝛁⋅(𝐯 u)$,

`1/Vᵘ * [δxᶠᵃᵃ(ℑxᶜᵃᵃ(Ax * u) * ℑxᶜᵃᵃ(u)) + δy_fca(ℑxᶠᵃᵃ(Ay * v) * ℑyᵃᶠᵃ(u)) + δz_fac(ℑxᶠᵃᵃ(Az * w) * ℑzᵃᵃᶠ(u))]`

which ends up at the location `fcc`

.

`Oceananigans.Advection.div_𝐯v`

— Method`div_𝐯v(i, j, k, grid, advection, U, v)`

Calculate the advection of momentum in the $y$-direction using the conservative form, $𝛁⋅(𝐯 v)$,

`1/Vʸ * [δx_cfa(ℑyᵃᶠᵃ(Ax * u) * ℑxᶠᵃᵃ(v)) + δyᵃᶠᵃ(ℑyᵃᶜᵃ(Ay * v) * ℑyᵃᶜᵃ(v)) + δz_afc(ℑxᶠᵃᵃ(Az * w) * ℑzᵃᵃᶠ(w))]`

which ends up at the location `cfc`

.

`Oceananigans.Advection.div_𝐯w`

— Method`div_𝐯w(i, j, k, grid, advection, U, w)`

Calculate the advection of momentum in the $z$-direction using the conservative form, $𝛁⋅(𝐯 w)$,

`1/Vʷ * [δx_caf(ℑzᵃᵃᶠ(Ax * u) * ℑxᶠᵃᵃ(w)) + δy_acf(ℑzᵃᵃᶠ(Ay * v) * ℑyᵃᶠᵃ(w)) + δzᵃᵃᶠ(ℑzᵃᵃᶜ(Az * w) * ℑzᵃᵃᶜ(w))]`

which ends up at the location `ccf`

.

## Architectures

`Oceananigans.Architectures.AbstractArchitecture`

— Type`AbstractArchitecture`

Abstract supertype for architectures supported by Oceananigans.

`Oceananigans.Architectures.AbstractMultiArchitecture`

— Type`AbstractMultiArchitecture`

Abstract supertype for Distributed architectures supported by Oceananigans.

`Oceananigans.Architectures.CPU`

— Type`CPU <: AbstractArchitecture`

Run Oceananigans on one CPU node. Uses multiple threads if the environment variable `JULIA_NUM_THREADS`

is set.

`Oceananigans.Architectures.GPU`

— Type`GPU <: AbstractArchitecture`

Run Oceananigans on a single NVIDIA CUDA GPU.

## Boundary conditions

`Oceananigans.BoundaryConditions.BoundaryCondition`

— Type`struct BoundaryCondition{C<:AbstractBoundaryConditionClassification, T}`

Container for boundary conditions.

`Oceananigans.BoundaryConditions.BoundaryCondition`

— Method`BoundaryCondition(Classification::DataType, condition)`

Construct a boundary condition of type `BC`

with a number or array as a `condition`

.

Boundary condition types include `Periodic`

, `Flux`

, `Value`

, `Gradient`

, and `Open`

.

`Oceananigans.BoundaryConditions.BoundaryCondition`

— Method```
BoundaryCondition(Classification::DataType, condition::Function;
parameters = nothing,
discrete_form = false,
field_dependencies=())
```

Construct a boundary condition of type `Classification`

with a function boundary `condition`

.

By default, the function boudnary `condition`

is assumed to have the 'continuous form' `condition(ξ, η, t)`

, where `t`

is time and `ξ`

and `η`

vary along the boundary. In particular:

- On
`x`

-boundaries,`condition(y, z, t)`

. - On
`y`

-boundaries,`condition(x, z, t)`

. - On
`z`

-boundaries,`condition(x, y, t)`

.

If `parameters`

is not `nothing`

, then function boundary conditions have the form `func(ξ, η, t, parameters)`

, where `ξ`

and `η`

are spatial coordinates varying along the boundary as explained above.

If `discrete_form = true`

, the function `condition`

is assumed to have the "discrete form",

`condition(i, j, grid, clock, model_fields)`

where `i`

, and `j`

are indices that vary along the boundary. If `discrete_form = true`

and `parameters`

is not `nothing`

, the function `condition`

is called with

`condition(i, j, grid, clock, model_fields, parameters)`

`Oceananigans.BoundaryConditions.FieldBoundaryConditions`

— Type```
FieldBoundaryConditions(grid, location, indices=(:, :, :);
west = default_auxiliary_bc(topology(grid, 1)(), location[1]()),
east = default_auxiliary_bc(topology(grid, 1)(), location[1]()),
south = default_auxiliary_bc(topology(grid, 2)(), location[2]()),
north = default_auxiliary_bc(topology(grid, 2)(), location[2]()),
bottom = default_auxiliary_bc(topology(grid, 3)(), location[3]()),
top = default_auxiliary_bc(topology(grid, 3)(), location[3]()),
immersed = NoFluxBoundaryCondition())
```

Return boundary conditions for auxiliary fields (fields whose values are derived from a model's prognostic fields) on `grid`

and at `location`

.

**Keyword arguments**

Keyword arguments specify boundary conditions on the 6 possible boundaries:

`west`

, left end point in the`x`

-direction where`i = 1`

`east`

, right end point in the`x`

-direction where`i = grid.Nx`

`south`

, left end point in the`y`

-direction where`j = 1`

`north`

, right end point in the`y`

-direction where`j = grid.Ny`

`bottom`

, right end point in the`z`

-direction where`k = 1`

`top`

, right end point in the`z`

-direction where`k = grid.Nz`

`immersed`

: boundary between solid and fluid for immersed boundaries

If a boundary condition is unspecified, the default for auxiliary fields and the topology in the boundary-normal direction is used:

`PeriodicBoundaryCondition`

for`Periodic`

directions`GradientBoundaryCondition(0)`

for`Bounded`

directions and`Centered`

-located fields`nothing`

for`Bounded`

directions and`Face`

-located fields`nothing`

for`Flat`

directions and/or`Nothing`

-located fields

`Oceananigans.BoundaryConditions.FieldBoundaryConditions`

— Type`FieldBoundaryConditions(; kwargs...)`

Return a template for boundary conditions on prognostic fields.

**Keyword arguments**

Keyword arguments specify boundary conditions on the 7 possible boundaries:

`west`

: left end point in the`x`

-direction where`i = 1`

`east`

: right end point in the`x`

-direction where`i = grid.Nx`

`south`

: left end point in the`y`

-direction where`j = 1`

`north`

: right end point in the`y`

-direction where`j = grid.Ny`

`bottom`

: right end point in the`z`

-direction where`k = 1`

`top`

: right end point in the`z`

-direction where`k = grid.Nz`

`immersed`

: boundary between solid and fluid for immersed boundaries

If a boundary condition is unspecified, the default for prognostic fields and the topology in the boundary-normal direction is used:

`PeriodicBoundaryCondition`

for`Periodic`

directions`NoFluxBoundaryCondition`

for`Bounded`

directions and`Centered`

-located fields`ImpenetrableBoundaryCondition`

for`Bounded`

directions and`Face`

-located fields`nothing`

for`Flat`

directions and/or`Nothing`

-located fields

`Oceananigans.BoundaryConditions.Flux`

— Type`struct Flux <: AbstractBoundaryConditionClassification`

A classification specifying a boundary condition on the flux of a field.

The sign convention is such that a positive flux represents the flux of a quantity in the positive direction. For example, a positive vertical flux implies a quantity is fluxed upwards, in the $+z$ direction.

Due to this convention, a positive flux applied to the top boundary specifies that a quantity is fluxed upwards across the top boundary and thus out of the domain. As a result, a positive flux applied to a top boundary leads to a reduction of that quantity in the interior of the domain; for example, a positive, upwards flux of heat at the top of the domain acts to cool the interior of the domain. Conversely, a positive flux applied to the bottom boundary leads to an increase of the quantity in the interior of the domain. The same logic holds for east, west, north, and south boundaries.

`Oceananigans.BoundaryConditions.Gradient`

— Type`struct Gradient <: AbstractBoundaryConditionClassification`

A classification specifying a boundary condition on the derivative or gradient of a field. Also called a Neumann boundary condition.

`Oceananigans.BoundaryConditions.Open`

— Type`struct Open <: AbstractBoundaryConditionClassification`

A classification that specifies the halo regions of a field directly.

For fields located at Faces, Open also specifies field value *on* the boundary.

Open boundary conditions are used to specify the component of a velocity field normal to a boundary and can also be used to describe nested or linked simulation domains.

`Oceananigans.BoundaryConditions.Value`

— Type`struct Value <: AbstractBoundaryConditionClassification`

A classification specifying a boundary condition on the value of a field. Also called a Dirchlet boundary condition.

`Oceananigans.BoundaryConditions.apply_x_bcs!`

— MethodApply flux boundary conditions to a field `c`

by adding the associated flux divergence to the source term `Gc`

at the left and right.

`Oceananigans.BoundaryConditions.apply_y_bcs!`

— MethodApply flux boundary conditions to a field `c`

by adding the associated flux divergence to the source term `Gc`

at the left and right.

`Oceananigans.BoundaryConditions.apply_z_bcs!`

— MethodApply flux boundary conditions to a field `c`

by adding the associated flux divergence to the source term `Gc`

at the top and bottom.

`Oceananigans.BoundaryConditions.fill_halo_regions!`

— MethodFill halo regions in $x$, $y$, and $z$ for a given field's data.

## BuoyancyModels

`Oceananigans.BuoyancyModels.Buoyancy`

— Method`Buoyancy(; model, gravity_unit_vector=ZDirection())`

Uses a given buoyancy `model`

to create buoyancy in a model. The optional keyword argument `gravity_unit_vector`

can be used to specify the direction opposite to the gravitational acceleration (which we take here to mean the "vertical" direction).

**Example**

```
using Oceananigans
grid = RectilinearGrid(size=(1, 8, 8), extent=(1, 1000, 100))
θ = 45 # degrees
g̃ = (0, sind(θ), cosd(θ))
buoyancy = Buoyancy(model=BuoyancyTracer(), gravity_unit_vector=g̃)
model = NonhydrostaticModel(grid=grid, buoyancy=buoyancy, tracers=:b)
```

`Oceananigans.BuoyancyModels.BuoyancyTracer`

— Type`BuoyancyTracer <: AbstractBuoyancyModel{Nothing}`

Type indicating that the tracer `b`

represents buoyancy.

`Oceananigans.BuoyancyModels.LinearEquationOfState`

— Type`LinearEquationOfState([FT=Float64;] thermal_expansion=1.67e-4, haline_contraction=7.80e-4)`

Return `LinearEquationOfState`

for `SeawaterBuoyancy`

with `thermal_expansion`

coefficient and `haline_contraction`

coefficient. The buoyancy perturbation $b$ for `LinearEquationOfState`

is

\[ b = g (α T - β S),\]

where $g$ is gravitational acceleration, $α$ is `thermal_expansion`

, $β$ is `haline_contraction`

, $T$ is temperature, and $S$ is practical salinity units.

Default constants in units inverse Kelvin and practical salinity units for `thermal_expansion`

and `haline_contraction`

, respectively, are taken from Table 1.2 (page 33) of Vallis, "Atmospheric and Oceanic Fluid Dynamics: Fundamentals and Large-Scale Circulation" (2nd ed, 2017).

`Oceananigans.BuoyancyModels.LinearEquationOfState`

— Type`LinearEquationOfState{FT} <: AbstractEquationOfState`

Linear equation of state for seawater.

`Oceananigans.BuoyancyModels.SeawaterBuoyancy`

— Type```
SeawaterBuoyancy([FT = Float64;]
gravitational_acceleration = g_Earth,
equation_of_state = LinearEquationOfState(FT),
constant_temperature = false,
constant_salinity = false)
```

Returns parameters for a temperature- and salt-stratified seawater buoyancy model with a `gravitational_acceleration`

constant (typically called $g$), and an `equation_of_state`

that related temperature and salinity (or conservative temperature and absolute salinity) to density anomalies and buoyancy.

`constant_temperature`

indicates that buoyancy depends only on salinity. For a nonlinear equation of state, `constant_temperature`

is used as the temperature of the system. The same logic, with the roles of salinity and temperature reversed, holds when `constant_salinity`

is provided.

For a linear equation of state, the values of `constant_temperature`

or `constant_salinity`

are irrelevant; in this case, `constant_temperature=true`

(and similar for `constant_salinity`

) is valid input.

`Oceananigans.BuoyancyModels.SeawaterBuoyancy`

— Type`SeawaterBuoyancy{FT, EOS, T, S} <: AbstractBuoyancyModel{EOS}`

BuoyancyModels model for seawater. `T`

and `S`

are either `nothing`

if both temperature and salinity are active, or of type `FT`

if temperature or salinity are constant, respectively.

`Oceananigans.BuoyancyModels.∂x_b`

— Method`∂x_b(i, j, k, grid, b::SeawaterBuoyancy, C)`

Returns the $x$-derivative of buoyancy for temperature and salt-stratified water,

\[∂_x b = g ( α ∂_x T - β ∂_x S ) ,\]

where $g$ is gravitational acceleration, $α$ is the thermal expansion coefficient, $β$ is the haline contraction coefficient, $T$ is conservative temperature, and $S$ is absolute salinity.

Note: In Oceananigans, `model.tracers.T`

is conservative temperature and `model.tracers.S`

is absolute salinity.

Note that $∂_x T$ (`∂x_T`

), $∂_x S$ (`∂x_S`

), $α$, and $β$ are all evaluated at cell interfaces in `x`

and cell centers in `y`

and `z`

.

`Oceananigans.BuoyancyModels.∂y_b`

— Method`∂y_b(i, j, k, grid, b::SeawaterBuoyancy, C)`

Returns the $y$-derivative of buoyancy for temperature and salt-stratified water,

\[∂_y b = g ( α ∂_y T - β ∂_y S ) ,\]

where $g$ is gravitational acceleration, $α$ is the thermal expansion coefficient, $β$ is the haline contraction coefficient, $T$ is conservative temperature, and $S$ is absolute salinity.

Note: In Oceananigans, `model.tracers.T`

is conservative temperature and `model.tracers.S`

is absolute salinity.

Note that $∂_y T$ (`∂y_T`

), $∂_y S$ (`∂y_S`

), $α$, and $β$ are all evaluated at cell interfaces in `y`

and cell centers in `x`

and `z`

.

`Oceananigans.BuoyancyModels.∂z_b`

— Method`∂z_b(i, j, k, grid, b::SeawaterBuoyancy, C)`

Returns the vertical derivative of buoyancy for temperature and salt-stratified water,

\[∂_z b = N^2 = g ( α ∂_z T - β ∂_z S ) ,\]

where $g$ is gravitational acceleration, $α$ is the thermal expansion coefficient, $β$ is the haline contraction coefficient, $T$ is conservative temperature, and $S$ is absolute salinity.

Note: In Oceananigans, `model.tracers.T`

is conservative temperature and `model.tracers.S`

is absolute salinity.

Note that $∂_z T$ (`∂z_T`

), $∂_z S$ (`∂z_S`

), $α$, and $β$ are all evaluated at cell interfaces in `z`

and cell centers in `x`

and `y`

.

## Coriolis

`Oceananigans.Coriolis.BetaPlane`

— Type```
BetaPlane([T=Float64;] f₀=nothing, β=nothing,
rotation_rate=Ω_Earth, latitude=nothing, radius=R_Earth)
```

Return a $β$-plane Coriolis parameter, $f = f₀ + β y$.

The user may specify both `f₀`

and `β`

, or the three parameters `rotation_rate`

, `latitude`

(in degrees), and `radius`

that specify the rotation rate and radius of a planet, and the central latitude (where $y = 0$) at which the `β`

-plane approximation is to be made.

If `f₀`

and `β`

are not specified, they are calculated from `rotation_rate`

, `latitude`

, and `radius`

according to the relations `f₀ = 2 * rotation_rate * sind(latitude)`

and `β = 2 * rotation_rate * cosd(latitude) / radius`

.

By default, the `rotation_rate`

and planet `radius`

are assumed to be Earth's.

`Oceananigans.Coriolis.BetaPlane`

— Type`struct BetaPlane{T} <: AbstractRotation`

A parameter object for meridionally increasing Coriolis parameter (`f = f₀ + β y`

) that accounts for the variation of the locally vertical component of the rotation vector with latitude.

`Oceananigans.Coriolis.ConstantCartesianCoriolis`

— Type```
ConstantCartesianCoriolis([FT=Float64;] fx=nothing, fy=nothing, fz=nothing,
f=nothing, rotation_axis=ZDirection(),
rotation_rate=Ω_Earth, latitude=nothing)
```

Return a parameter object for a constant rotation decomposed into the `x`

, `y`

, and `z`

directions. In oceanography the components `x`

, `y`

, `z`

correspond to the directions east, north, and up. This constant rotation can be specified in three different ways:

- Specifying all components
`fx`

,`fy`

and`fz`

directly. - Specifying the Coriolis parameter
`f`

and (optionally) a`rotation_axis`

(which defaults to the`z`

direction if not specified). - Specifying
`latitude`

(in degrees) and (optionally) a`rotation_rate`

in radians per second (which defaults to Earth's rotation rate).

`Oceananigans.Coriolis.ConstantCartesianCoriolis`

— Type`struct ConstantCartesianCoriolis{FT} <: AbstractRotation`

A Coriolis implementation that accounts for the locally vertical and possibly both local horizontal components of a constant rotation vector. This is a more general implementation of `FPlane`

, which only accounts for the locally vertical component.

`Oceananigans.Coriolis.FPlane`

— Type`FPlane([FT=Float64;] f=nothing, rotation_rate=Ω_Earth, latitude=nothing)`

Return a parameter object for constant rotation at the angular frequency `f/2`

, and therefore with background vorticity `f`

, around a vertical axis. If `f`

is not specified, it is calculated from `rotation_rate`

and `latitude`

(in degrees) according to the relation `f = 2 * rotation_rate * sind(latitude)`

.

By default, `rotation_rate`

is assumed to be Earth's.

Also called `FPlane`

, after the "f-plane" approximation for the local effect of a planet's rotation in a planar coordinate system tangent to the planet's surface.

`Oceananigans.Coriolis.FPlane`

— Type`struct FPlane{FT} <: AbstractRotation`

A parameter object for constant rotation around a vertical axis.

`Oceananigans.Coriolis.HydrostaticSphericalCoriolis`

— Type`struct HydrostaticSphericalCoriolis{S, FT} <: AbstractRotation`

A parameter object for constant rotation around a vertical axis on the sphere.

`Oceananigans.Coriolis.HydrostaticSphericalCoriolis`

— Method```
HydrostaticSphericalCoriolis([FT=Float64;]
rotation_rate = Ω_Earth,
scheme = EnergyConservingScheme())
```

Return a parameter object for Coriolis forces on a sphere rotating at `rotation_rate`

. By default, `rotation_rate`

is assumed to be Earth's.

**Keyword arguments**

`scheme`

: Either`EnergyConservingScheme()`

(default),`EnstrophyConservingScheme()`

, or`WetCellEnstrophyConservingScheme()`

.

`Oceananigans.Coriolis.NonTraditionalBetaPlane`

— Type```
NonTraditionalBetaPlane(FT=Float64;
fz=nothing, fy=nothing, β=nothing, γ=nothing,
rotation_rate=Ω_Earth, latitude=nothing, radius=R_Earth)
```

The user may directly specify `fz`

, `fy`

, `β`

, `γ`

, and `radius`

or the three parameters `rotation_rate`

, `latitude`

(in degrees), and `radius`

that specify the rotation rate and radius of a planet, and the central latitude (where $y = 0$) at which the non-traditional `β`

-plane approximation is to be made.

If `fz`

, `fy`

, `β`

, and `γ`

are not specified, they are calculated from `rotation_rate`

, `latitude`

, and `radius`

according to the relations `fz = 2 * rotation_rate * sind(latitude)`

, `fy = 2 * rotation_rate * cosd(latitude)`

, `β = 2 * rotation_rate * cosd(latitude) / radius`

, and `γ = - 4 * rotation_rate * sind(latitude) / radius`

.

By default, the `rotation_rate`

and planet `radius`

is assumed to be Earth's.

`Oceananigans.Coriolis.NonTraditionalBetaPlane`

— Type`struct NonTraditionalBetaPlane{FT} <: AbstractRotation`

A Coriolis implementation that accounts for the latitudinal variation of both the locally vertical and the locally horizontal components of the rotation vector. The "traditional" approximation in ocean models accounts for only the locally vertical component of the rotation vector (see `BetaPlane`

).

This implementation is based off of section 5 of Dellar (2011). It conserve energy, angular momentum, and potential vorticity.

**References**

Dellar, P. (2011). Variations on a beta-plane: Derivation of non-traditional beta-plane equations from Hamilton's principle on a sphere. Journal of Fluid Mechanics, 674, 174-195. doi:10.1017/S0022112010006464

`Oceananigans.Coriolis.WetCellEnstrophyConservingScheme`

— Type`struct WetCellEnstrophyConservingScheme`

A parameter object for an enstrophy-conserving Coriolis scheme that excludes dry edges (indices for which `peripheral_node == true`

) from the velocity interpolation.

## Diagnostics

`Oceananigans.Diagnostics.CFL`

— Type`struct CFL{D, S}`

An object for computing the Courant-Freidrichs-Lewy (CFL) number.

`Oceananigans.Diagnostics.CFL`

— Method`CFL(Δt [, timescale = Oceananigans.cell_advection_timescale])`

Return an object for computing the Courant-Freidrichs-Lewy (CFL) number associated with time step `Δt`

or `TimeStepWizard`

and `timescale`

.

See also `AdvectiveCFL`

and `DiffusiveCFL`

.

`Oceananigans.Diagnostics.StateChecker`

— Method`StateChecker(; schedule, fields)`

Returns a `StateChecker`

that logs field information (minimum, maximum, mean) for each field in a named tuple of `fields`

when `schedule`

actuates.

`Oceananigans.Diagnostics.AdvectiveCFL`

— Method`AdvectiveCFL(Δt)`

Return an object for computing the Courant-Freidrichs-Lewy (CFL) number associated with time step `Δt`

or `TimeStepWizard`

and the time scale for advection across a cell. The advective CFL is, e.g., $U Δt / Δx$.

**Example**

```
julia> using Oceananigans
julia> model = NonhydrostaticModel(grid = RectilinearGrid(size=(16, 16, 16), extent=(8, 8, 8)));
julia> Δt = 1.0;
julia> cfl = AdvectiveCFL(Δt);
julia> model.velocities.u .= π;
julia> cfl(model)
6.283185307179586
```

`Oceananigans.Diagnostics.DiffusiveCFL`

— Method`DiffusiveCFL(Δt)`

Returns an object for computing the diffusive Courant-Freidrichs-Lewy (CFL) number associated with time step `Δt`

or `TimeStepWizard`

and the time scale for diffusion across a cell associated with `model.closure`

. The diffusive CFL, e.g., for viscosity is $ν Δt / Δx²$.

The maximum diffusive CFL number among viscosity and all tracer diffusivities is returned.

**Example**

```
julia> using Oceananigans
julia> model = NonhydrostaticModel(grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1)),
closure = ScalarDiffusivity(; ν = 1e-2));
julia> Δt = 0.1;
julia> dcfl = DiffusiveCFL(Δt);
julia> dcfl(model)
0.256
```

## Distributed

`Oceananigans.Distributed.DistributedFFTBasedPoissonSolver`

— Method`DistributedFFTBasedPoissonSolver(global_grid, local_grid)`

Return a FFT-based solver for the Poisson equation,

\[∇²x = b\]

for `MultiArch`

itectures.

**Supported configurations**

We support two "modes":

```
1. Vertical pencil decompositions: two-dimensional decompositions in (x, y)
for three dimensional problems that satisfy either `Nz > Rx` or `Nz > Ry`.
2. One-dimensional decompositions in either x or y.
```

Above, `Nz = size(global_grid, 3)`

and `Rx, Ry, Rz = architecture(local_grid).ranks`

.

Other configurations that are decomposed in (x, y) but have too few `Nz`

, or any configuration decomposed in z, are not supported.

**Algorithm for two-dimensional decompositions**

For two-dimensional decompositions (useful for three-dimensional problems), there are three forward transforms, three backward transforms, and four transpositions requiring MPI communication. In the schematic below, the first dimension is always the local dimension. In our implementation of the PencilFFTs algorithm, we require *either* `Nz >= Rx`

, *or* `Nz >= Ry`

, where `Nz`

is the number of vertical cells, `Rx`

is the number of ranks in x, and `Ry`

is the number of ranks in `y`

. Below, we outline the algorithm for the case `Nz >= Rx`

. If `Nz < Rx`

, but `Nz > Ry`

, a similar algorithm applies with x and y swapped:

`first(storage)`

is initialized with layout (z, x, y).- Transform along z.

3 Transpose + communicate to storage[2] in layout (x, z, y), which is distributed into `(Rx, Ry)`

processes in (z, y).

- Transform along x.
- Transpose + communicate to last(storage) in layout (y, x, z), which is distributed into
`(Rx, Ry)`

processes in (x, z). - Transform in y.

At this point the three in-place forward transforms are complete, and we solve the Poisson equation by updating `last(storage)`

. Then the process is reversed to obtain `first(storage)`

in physical space and with the layout (z, x, y).

**Restrictions**

The algorithm for two-dimensional decompositions requires that `Nz = size(global_grid, 3)`

is larger than either `Rx = ranks[1]`

or `Ry = ranks[2]`

, where `ranks`

are configured when building `MultiArch`

. If `Nz`

does not satisfy this condition, we can only support a one-dimensional decomposition.

**Algorithm for one-dimensional decompositions**

This algorithm requires a one-dimensional decomposition with *either* `Rx = 1`

*or* `Ry = 1`

, and is important to support two-dimensional transforms.

For one-dimensional decompositions, we place the decomposed direction *last*. If the number of ranks is `Rh = max(Rx, Ry)`

, this algorithm requires that *both* `Nx > Rh`

*and* `Ny > Rh`

. The resulting flow of transposes and transforms is similar to the two-dimensional case. It remains somewhat of a mystery why this succeeds (ie, why the last transform is correctly decomposed).

## Fields

`Oceananigans.Fields.AbstractField`

— Type`AbstractField{LX, LY, LZ, G, T, N}`

Abstract supertype for fields located at `(LX, LY, LZ)`

and defined on a grid `G`

with eltype `T`

and `N`

dimensions.

Note: we need the parameter `T`

to subtype AbstractArray.

`Oceananigans.Fields.BackgroundField`

— Type`BackgroundField{F, P}`

Temporary container for storing information about `BackgroundFields`

.

`Oceananigans.Fields.BackgroundField`

— Method`BackgroundField(func; parameters=nothing)`

Returns a `BackgroundField`

to be passed to `NonhydrostaticModel`

for use as a background velocity or tracer field.

If `parameters`

is not provided, `func`

must be callable with the signature

`func(x, y, z, t)`

If `parameters`

is provided, `func`

must be callable with the signature

`func(x, y, z, t, parameters)`

`Oceananigans.Fields.Field`

— Method```
Field{LX, LY, LZ}(grid::AbstractGrid,
T::DataType=eltype(grid); kw...) where {LX, LY, LZ}
```

Construct a `Field`

on `grid`

with data type `T`

at the location `(LX, LY, LZ)`

. Each of `(LX, LY, LZ)`

is either `Center`

or `Face`

and determines the field's location in `(x, y, z)`

respectively.

**Keyword arguments**

`data :: OffsetArray`

: An offset array with the fields data. If nothing is provided the field is filled with zeros.`boundary_conditions`

: If nothing is provided, then field is created using the default

`FieldBoundaryConditions`

.`indices`

: Used to prescribe where a reduced field lives on. For example, at which`k`

index does a two-dimensional $x$-$y$ field lives on. Default:`(:, :, :)`

.

**Example**

A field at location `(Face, Face, Center)`

.

```
julia> using Oceananigans
julia> grid = RectilinearGrid(size=(2, 3, 4), extent=(1, 1, 1));
julia> ω = Field{Face, Face, Center}(grid)
2×3×4 Field{Face, Face, Center} on RectilinearGrid on CPU
├── grid: 2×3×4 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── boundary conditions: FieldBoundaryConditions
│ └── west: Periodic, east: Periodic, south: Periodic, north: Periodic, bottom: ZeroFlux, top: ZeroFlux, immersed: ZeroFlux
└── data: 8×9×10 OffsetArray(::Array{Float64, 3}, -2:5, -2:6, -2:7) with eltype Float64 with indices -2:5×-2:6×-2:7
└── max=0.0, min=0.0, mean=0.0
```

Now, using `indices`

we can create a two dimensional $x$-$y$ field at location `(Face, Face, Center)`

to compute, e.g., the vertical vorticity $∂v/∂x - ∂u/∂y$ at the fluid's surface $z = 0$, which for `Center`

corresponds to `k = Nz`

.

```
julia> u = XFaceField(grid); v = YFaceField(grid);
julia> ωₛ = Field(∂x(v) - ∂y(u), indices=(:, :, grid.Nz))
2×3×1 Field{Face, Face, Center} on RectilinearGrid on CPU
├── grid: 2×3×4 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── boundary conditions: FieldBoundaryConditions
│ └── west: Periodic, east: Periodic, south: Periodic, north: Periodic, bottom: Nothing, top: Nothing, immersed: ZeroFlux
├── operand: BinaryOperation at (Face, Face, Center)
├── status: time=0.0
└── data: 8×9×1 OffsetArray(::Array{Float64, 3}, -2:5, -2:6, 4:4) with eltype Float64 with indices -2:5×-2:6×4:4
└── max=0.0, min=0.0, mean=0.0
julia> compute!(ωₛ)
2×3×1 Field{Face, Face, Center} on RectilinearGrid on CPU
├── grid: 2×3×4 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── boundary conditions: FieldBoundaryConditions
│ └── west: Periodic, east: Periodic, south: Periodic, north: Periodic, bottom: Nothing, top: Nothing, immersed: ZeroFlux
├── operand: BinaryOperation at (Face, Face, Center)
├── status: time=0.0
└── data: 8×9×1 OffsetArray(::Array{Float64, 3}, -2:5, -2:6, 4:4) with eltype Float64 with indices -2:5×-2:6×4:4
└── max=0.0, min=0.0, mean=0.0
```

`Oceananigans.Fields.Reduction`

— Method`Reduction(reduce!, operand; dims)`

Return a `Reduction`

of `operand`

with `reduce!`

, along `dims`

. Note that `Reduction`

expects `reduce!`

to operate in-place.

**Example**

```
using Oceananigans
Nx, Ny, Nz = 3, 3, 3
grid = RectilinearGrid(size=(Nx, Ny, Nz), x=(0, 1), y=(0, 1), z=(0, 1),
topology=(Periodic, Periodic, Periodic))
c = CenterField(grid)
set!(c, (x, y, z) -> x + y + z)
max_c² = Field(Reduction(maximum!, c^2, dims=3))
compute!(max_c²)
max_c²[1:Nx, 1:Ny]
# output
3×3 Matrix{Float64}:
1.36111 2.25 3.36111
2.25 3.36111 4.69444
3.36111 4.69444 6.25
```

`Oceananigans.Fields.CenterField`

— Function`CenterField(grid; kw...)`

Return a `Field{Center, Center, Center}`

on `grid`

. Additional keyword arguments are passed to the `Field`

constructor.

`Oceananigans.Fields.PressureFields`

— Function`PressureFields(grid, bcs::NamedTuple)`

Return a `NamedTuple`

with pressure fields `pHY′`

and `pNHS`

initialized as `CenterField`

s on `grid`

. Boundary conditions `bcs`

may be specified via a named tuple of `FieldBoundaryCondition`

s.

`Oceananigans.Fields.PressureFields`

— Method`PressureFields(proposed_pressures::NamedTuple{(:pHY′, :pNHS)}, grid, bcs)`

Return a `NamedTuple`

of pressure fields with, overwriting boundary conditions in `proposed_tracer_fields`

with corresponding fields in the `NamedTuple`

`bcs`

.

`Oceananigans.Fields.TendencyFields`

— Method```
TendencyFields(grid, tracer_names;
u = XFaceField(grid),
v = YFaceField(grid),
w = ZFaceField(grid),
kwargs...)
```

Return a `NamedTuple`

with tendencies for all solution fields (velocity fields and tracer fields), initialized on `grid`

. Optional `kwargs`

can be specified to assign data arrays to each tendency field.

`Oceananigans.Fields.TracerFields`

— Method`TracerFields(tracer_names, grid, user_bcs)`

Return a `NamedTuple`

with tracer fields specified by `tracer_names`

initialized as `CenterField`

s on `grid`

. Boundary conditions `user_bcs`

may be specified via a named tuple of `FieldBoundaryCondition`

s.

`Oceananigans.Fields.TracerFields`

— Method`TracerFields(tracer_names, grid; kwargs...)`

Return a `NamedTuple`

with tracer fields specified by `tracer_names`

initialized as `CenterField`

s on `grid`

. Fields may be passed via optional keyword arguments `kwargs`

for each field.

This function is used by `OutputWriters.Checkpointer`

and `TendencyFields`

. ```

`Oceananigans.Fields.TracerFields`

— Method`TracerFields(proposed_tracers::NamedTuple, grid, bcs)`

Return a `NamedTuple`

of tracers, overwriting boundary conditions in `proposed_tracers`

with corresponding fields in the `NamedTuple`

`bcs`

.

`Oceananigans.Fields.TracerFields`

— MethodShortcut constructor for empty tracer fields.

`Oceananigans.Fields.VelocityFields`

— Function`VelocityFields(grid, user_bcs = NamedTuple())`

Return a `NamedTuple`

with fields `u`

, `v`

, `w`

initialized on `grid`

. Boundary conditions `bcs`

may be specified via a named tuple of `FieldBoundaryCondition`

s.

`Oceananigans.Fields.VelocityFields`

— Method`VelocityFields(proposed_velocities::NamedTuple{(:u, :v, :w)}, grid, bcs)`

Return a `NamedTuple`

of velocity fields, overwriting boundary conditions in `proposed_velocities`

with corresponding fields in the `NamedTuple`

`bcs`

.

`Oceananigans.Fields.XFaceField`

— Function`XFaceField(grid; kw...)`

Return a `Field{Face, Center, Center}`

on `grid`

. Additional keyword arguments are passed to the `Field`

constructor.

`Oceananigans.Fields.YFaceField`

— Function`YFaceField(grid; kw...)`

Return a `Field{Center, Face, Center}`

on `grid`

. Additional keyword arguments are passed to the `Field`

constructor.

`Oceananigans.Fields.ZFaceField`

— Function`ZFaceField(grid; kw...)`

Return a `Field{Center, Center, Face}`

on `grid`

. Additional keyword arguments are passed to the `Field`

constructor.

`Oceananigans.Fields.compute!`

— Function`compute!(field)`

Computes `field.data`

from `field.operand`

.

`Oceananigans.Fields.field`

— Method`field(loc, a, grid)`

Build a field from `a`

at `loc`

and on `grid`

.

`Oceananigans.Fields.interior`

— Method`interior(f::Field)`

Returns a view of `f`

that excludes halo points."

`Oceananigans.Fields.interpolate`

— Method`interpolate(field, x, y, z)`

Interpolate `field`

to the physical point `(x, y, z)`

using trilinear interpolation.

`Oceananigans.Fields.regrid!`

— Method`regrid!(a, b)`

Regrid field `b`

onto the grid of field `a`

.

Currently `regrid!`

only regrids in the vertical $z$ direction and works only on fields that have data only in $z$ direction.

**Example**

Generate a tracer field on a vertically stretched grid and regrid it on a regular grid.

```
using Oceananigans
Nz, Lz = 2, 1.0
topology = (Flat, Flat, Bounded)
input_grid = RectilinearGrid(size=Nz, z = [0, Lz/3, Lz], topology=topology, halo=1)
input_field = CenterField(input_grid)
input_field[1, 1, 1:Nz] = [2, 3]
output_grid = RectilinearGrid(size=Nz, z=(0, Lz), topology=topology, halo=1)
output_field = CenterField(output_grid)
regrid!(output_field, input_field)
output_field[1, 1, :]
# output
4-element OffsetArray(::Vector{Float64}, 0:3) with eltype Float64 with indices 0:3:
0.0
2.333333333333334
3.0
0.0
```

`Oceananigans.location`

— MethodReturns the location `(LX, LY, LZ)`

of an `AbstractField{LX, LY, LZ}`

.

`Oceananigans.Fields.@compute`

— Macro`@compute(exprs...)`

Call `compute!`

on fields after defining them.

## Forcings

`Oceananigans.Forcings.AdvectiveForcing`

— Type`AdvectiveForcing(scheme=UpwindBiasedFifthOrder(), u=ZeroField(), v=ZeroField(), w=ZeroField())`

Build a forcing term representing advection by the velocity field `u, v, w`

with an advection `scheme`

.

**Example**

**Using a tracer field to model sinking particles**

```
using Oceananigans
# Physical parameters
gravitational_acceleration = 9.81 # m s⁻²
ocean_density = 1026 # kg m⁻³
mean_particle_density = 2000 # kg m⁻³
mean_particle_radius = 1e-3 # m
ocean_molecular_kinematic_viscosity = 1.05e-6 # m² s⁻¹
# Terminal velocity of a sphere in viscous flow
Δb = gravitational_acceleration * (mean_particle_density - ocean_density) / ocean_density
ν = ocean_molecular_kinematic_viscosity
R = mean_particle_radius
w_Stokes = - 2/9 * Δb / ν * R^2 # m s⁻¹
settling = AdvectiveForcing(UpwindBiasedFifthOrder(), w=w_Stokes)
# output
AdvectiveForcing with the UpwindBiased scheme:
├── u: ZeroField{Int64}
├── v: ZeroField{Int64}
└── w: ConstantField(-1.97096)
```

`Oceananigans.Forcings.ContinuousForcing`

— Type`ContinuousForcing{LX, LY, LZ, P, F, D, I, ℑ}`

A callable object that implements a "continuous form" forcing function on a field at the location `LX, LY, LZ`

with optional parameters.

`Oceananigans.Forcings.ContinuousForcing`

— Method`ContinuousForcing(func; parameters=nothing, field_dependencies=())`

Construct a "continuous form" forcing with optional `parameters`

and optional `field_dependencies`

on other fields in a model.

If neither `parameters`

nor `field_dependencies`

are provided, then `func`

must be callable with the signature

`func(x, y, z, t)`

where `x, y, z`

are the east-west, north-south, and vertical spatial coordinates, and `t`

is time.

If `field_dependencies`

are provided, the signature of `func`

must include them. For example, if `field_dependencies=(:u, :S)`

(and `parameters`

are *not* provided), then `func`

must be callable with the signature

`func(x, y, z, t, u, S)`

where `u`

is assumed to be the `u`

-velocity component, and `S`

is a tracer. Note that any field which does not have the name `u`

, `v`

, or `w`

is assumed to be a tracer and must be present in `model.tracers`

.

If `parameters`

are provided, then the *last* argument to `func`

must be `parameters`

. For example, if `func`

has no `field_dependencies`

but does depend on `parameters`

, then it must be callable with the signature

`func(x, y, z, t, parameters)`

With `field_dependencies=(:u, :v, :w, :c)`

and `parameters`

, then `func`

must be callable with the signature

`func(x, y, z, t, u, v, w, c, parameters)`

`Oceananigans.Forcings.DiscreteForcing`

— Type`struct DiscreteForcing{P, F}`

Wrapper for "discrete form" forcing functions with optional `parameters`

.

`Oceananigans.Forcings.DiscreteForcing`

— Method`DiscreteForcing(func; parameters=nothing)`

Construct a "discrete form" forcing function with optional parameters. The forcing function is applied at grid point `i, j, k`

.

When `parameters`

are not specified, `func`

must be callable with the signature

`func(i, j, k, grid, clock, model_fields)`

where `grid`

is `model.grid`

, `clock.time`

is the current simulation time and `clock.iteration`

is the current model iteration, and `model_fields`

is a `NamedTuple`

with `u, v, w`

and the fields in `model.tracers`

.

*Note* that the index `end`

does *not* access the final physical grid point of a model field in any direction. The final grid point must be explicitly specified, as in `model_fields.u[i, j, grid.Nz]`

.

When `parameters`

*is* specified, `func`

must be callable with the signature.

`func(i, j, k, grid, clock, model_fields, parameters)`

Above, `parameters`

is, in principle, arbitrary. Note, however, that GPU compilation can place constraints on `typeof(parameters)`

.

`Oceananigans.Forcings.GaussianMask`

— Type`GaussianMask{D}(center, width)`

Callable object that returns a Gaussian masking function centered on `center`

, with `width`

, and varying along direction `D`

, i.e.,

`exp(-(D - center)^2 / (2 * width^2))`

**Examples**

- Create a Gaussian mask centered on
`z=0`

with width`1`

meter.

`julia> mask = GaussianMask{:z}(center=0, width=1)`

`Oceananigans.Forcings.LinearTarget`

— Type`LinearTarget{D}(intercept, gradient)`

Callable object that returns a Linear target function with `intercept`

and `gradient`

, and varying along direction `D`

, i.e.,

`intercept + D * gradient`

**Examples**

Create a linear target function varying in

`z`

, equal to`0`

at`z=0`

and with gradient 10⁻⁶:`julia> target = LinearTarget{:z}(intercept=0, gradient=1e-6)`

`Oceananigans.Forcings.Relaxation`

— Type`struct Relaxation{R, M, T}`

Callable object for restoring fields to a `target`

at some `rate`

and within a `mask`

ed region in `x, y, z`

.

`Oceananigans.Forcings.Relaxation`

— Method`Relaxation(; rate, mask=onefunction, target=zerofunction)`

Returns a `Forcing`

that restores a field to `target(x, y, z, t)`

at the specified `rate`

, in the region `mask(x, y, z)`

.

The functions `onefunction`

and `zerofunction`

always return 1 and 0, respectively. Thus the default `mask`

leaves the whole domain uncovered, and the default `target`

is zero.

**Example**

- Restore a field to zero on a timescale of "3600" (equal to one hour if the time units of the simulation are seconds).

```
using Oceananigans
damping = Relaxation(rate = 1/3600)
# output
Relaxation{Float64, typeof(Oceananigans.Forcings.onefunction), typeof(Oceananigans.Forcings.zerofunction)}
├── rate: 0.0002777777777777778
├── mask: 1
└── target: 0
```

- Restore a field to a linear z-gradient within the bottom 1/4 of a domain on a timescale of "60" (equal to one minute if the time units of the simulation are seconds).

```
dTdz = 0.001 # ⁰C m⁻¹, temperature gradient
T₀ = 20 # ⁰C, surface temperature at z=0
Lz = 100 # m, depth of domain
bottom_sponge_layer = Relaxation(; rate = 1/60,
target = LinearTarget{:z}(intercept=T₀, gradient=dTdz),
mask = GaussianMask{:z}(center=-Lz, width=Lz/4))
# output
Relaxation{Float64, GaussianMask{:z, Float64}, LinearTarget{:z, Float64}}
├── rate: 0.016666666666666666
├── mask: exp(-(z + 100.0)^2 / (2 * 25.0^2))
└── target: 20.0 + 0.001 * z
```

`Oceananigans.Forcings.Forcing`

— Method`Forcing(func; parameters=nothing, field_dependencies=(), discrete_form=false)`

Returns a forcing function added to the tendency of an Oceananigans model field.

If `discrete_form=false`

(the default), and neither `parameters`

nor `field_dependencies`

are provided, then `func`

must be callable with the signature

`func(x, y, z, t)`

where `x, y, z`

are the east-west, north-south, and vertical spatial coordinates, and `t`

is time. Note that this form is also default in the constructor for `NonhydrostaticModel`

, so that `Forcing`

is not needed.

If `discrete_form=false`

(the default), and `field_dependencies`

are provided, the signature of `func`

must include them. For example, if `field_dependencies=(:u, :S)`

(and `parameters`

are *not* provided), then `func`

must be callable with the signature

`func(x, y, z, t, u, S)``

where `u`

is assumed to be the `u`

-velocity component, and `S`

is a tracer. Note that any field which does not have the name `u`

, `v`

, or `w`

is assumed to be a tracer and must be present in `model.tracers`

.

If `discrete_form=false`

(the default) and `parameters`

are provided, then the *last* argument to `func`

must be `parameters`

. For example, if `func`

has no `field_dependencies`

but does depend on `parameters`

, then it must be callable with the signature

`func(x, y, z, t, parameters)`

The object `parameters`

is arbitrary in principle, however GPU compilation can place constraints on `typeof(parameters)`

.

With `field_dependencies=(:u, :v, :w, :c)`

and `parameters`

, then `func`

must be callable with the signature

`func(x, y, z, t, u, v, w, c, parameters)`

If `discrete_form=true`

then `func`

must be callable with the "discrete form"

`func(i, j, k, grid, clock, model_fields)`

where `i, j, k`

is the grid point at which the forcing is applied, `grid`

is `model.grid`

, `clock.time`

is the current simulation time and `clock.iteration`

is the current model iteration, and `model_fields`

is a `NamedTuple`

with `u, v, w`

, the fields in `model.tracers`

, and the fields in `model.diffusivity_fields`

, each of which is an `OffsetArray`

s (or `NamedTuple`

s of `OffsetArray`

s depending on the turbulence closure) of field data.

When `discrete_form=true`

and `parameters`

*is* specified, `func`

must be callable with the signature

`func(i, j, k, grid, clock, model_fields, parameters)`

**Examples**

```
using Oceananigans
# Parameterized forcing
parameterized_func(x, y, z, t, p) = p.μ * exp(z / p.λ) * cos(p.ω * t)
v_forcing = Forcing(parameterized_func, parameters = (μ=42, λ=0.1, ω=π))
# output
ContinuousForcing{NamedTuple{(:μ, :λ, :ω), Tuple{Int64, Float64, Irrational{:π}}}}
├── func: parameterized_func (generic function with 1 method)
├── parameters: (μ = 42, λ = 0.1, ω = π)
└── field dependencies: ()
```

Note that because forcing locations are regularized within the `NonhydrostaticModel`

constructor:

```
grid = RectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1))
model = NonhydrostaticModel(grid=grid, forcing=(v=v_forcing,))
model.forcing.v
# output
ContinuousForcing{NamedTuple{(:μ, :λ, :ω), Tuple{Int64, Float64, Irrational{:π}}}} at (Center, Face, Center)
├── func: parameterized_func (generic function with 1 method)
├── parameters: (μ = 42, λ = 0.1, ω = π)
└── field dependencies: ()
```

After passing through the constructor for `NonhydrostaticModel`

, the `v`

-forcing location information is available and set to `Center, Face, Center`

.

```
# Field-dependent forcing
growth_in_sunlight(x, y, z, t, P) = exp(z) * P
plankton_forcing = Forcing(growth_in_sunlight, field_dependencies=:P)
# output
ContinuousForcing{Nothing}
├── func: growth_in_sunlight (generic function with 1 method)
├── parameters: nothing
└── field dependencies: (:P,)
```

```
# Parameterized, field-dependent forcing
tracer_relaxation(x, y, z, t, c, p) = p.μ * exp((z + p.H) / p.λ) * (p.dCdz * z - c)
c_forcing = Forcing(tracer_relaxation,
field_dependencies = :c,
parameters = (μ=1/60, λ=10, H=1000, dCdz=1))
# output
ContinuousForcing{NamedTuple{(:μ, :λ, :H, :dCdz), Tuple{Float64, Int64, Int64, Int64}}}
├── func: tracer_relaxation (generic function with 1 method)
├── parameters: (μ = 0.016666666666666666, λ = 10, H = 1000, dCdz = 1)
└── field dependencies: (:c,)
```

```
# Unparameterized discrete-form forcing function
filtered_relaxation(i, j, k, grid, clock, model_fields) =
@inbounds - (model_fields.c[i-1, j, k] + model_fields.c[i, j, k] + model_fields.c[i+1, j, k]) / 3
filtered_forcing = Forcing(filtered_relaxation, discrete_form=true)
# output
DiscreteForcing{Nothing}
├── func: filtered_relaxation (generic function with 1 method)
└── parameters: nothing
```

```
# Discrete-form forcing function with parameters
masked_damping(i, j, k, grid, clock, model_fields, parameters) =
@inbounds - parameters.μ * exp(grid.zᵃᵃᶜ[k] / parameters.λ) * model_fields.u[i, j, k]
masked_damping_forcing = Forcing(masked_damping, parameters=(μ=42, λ=π), discrete_form=true)
# output
DiscreteForcing{NamedTuple{(:μ, :λ), Tuple{Int64, Irrational{:π}}}}
├── func: masked_damping (generic function with 1 method)
└── parameters: (μ = 42, λ = π)
```

## Grids

`Oceananigans.Grids.AbstractCurvilinearGrid`

— Type`AbstractCurvilinearGrid{FT, TX, TY, TZ}`

Abstract supertype for curvilinear grids with elements of type `FT`

and topology `{TX, TY, TZ}`

.

`Oceananigans.Grids.AbstractGrid`

— Type`AbstractGrid{FT, TX, TY, TZ}`

Abstract supertype for grids with elements of type `FT`

and topology `{TX, TY, TZ}`

.

`Oceananigans.Grids.AbstractHorizontallyCurvilinearGrid`

— Type`AbstractHorizontallyCurvilinearGrid{FT, TX, TY, TZ}`

Abstract supertype for horizontally-curvilinear grids with elements of type `FT`

and topology `{TX, TY, TZ}`

.

`Oceananigans.Grids.AbstractRectilinearGrid`

— Type`AbstractRectilinearGrid{FT, TX, TY, TZ}`

Abstract supertype for rectilinear grids with elements of type `FT`

and topology `{TX, TY, TZ}`

.

`Oceananigans.Grids.AbstractTopology`

— Type`AbstractTopology`

Abstract supertype for grid topologies.

`Oceananigans.Grids.AbstractUnderlyingGrid`

— Type`AbstractUnderlyingGrid{FT, TX, TY, TZ}`

Abstract supertype for "primary" grids (as opposed to grids with immersed boundaries) with elements of type `FT`

and topology `{TX, TY, TZ}`

.

`Oceananigans.Grids.Bounded`

— Type`Bounded`

Grid topology for bounded dimensions, e.g., wall-bounded dimensions.

`Oceananigans.Grids.Center`

— Type`Center`

A type describing the location at the center of a grid cell.

`Oceananigans.Grids.Face`

— Type`Face`

A type describing the location at the face of a grid cell.

`Oceananigans.Grids.Flat`

— Type`Flat`

Grid topology for flat dimensions, generally with one grid point, along which the solution is uniform and does not vary.

`Oceananigans.Grids.FullyConnected`

— Type`FullyConnected`

Grid topology for dimensions that are connected to other models or domains.

`Oceananigans.Grids.LatitudeLongitudeGrid`

— Type```
LatitudeLongitudeGrid([architecture = CPU(), FT = Float64];
size,
longitude,
latitude,
z = nothing,
radius = R_Earth,
topology = nothing,
precompute_metrics = true,
halo = nothing)
```

Creates a `LatitudeLongitudeGrid`

with coordinates `(λ, φ, z)`

denoting longitude, latitude, and vertical coordinate respectively.

**Positional arguments**

`architecture`

: Specifies whether arrays of coordinates and spacings are stored on the CPU or GPU. Default:`CPU()`

.`FT`

: Floating point data type. Default:`Float64`

.

**Keyword arguments**

`size`

(required): A 3-tuple prescribing the number of grid points each direction.`longitude`

(required),`latitude`

(required),`z`

(default:`nothing`

): Each is either a:- 2-tuple that specify the end points of the domain,
- one-dimensional array specifying the cell interface locations, or
- a single-argument function that takes an index and returns cell interface location.

**Note**: the latitude and longitude coordinates extents are expected in degrees.`radius`

: The radius of the sphere the grid lives on. By default is equal to the radius of Earth.`topology`

: Tuple of topologies (`Flat`

,`Bounded`

,`Periodic`

) for each direction. The vertical`topology[3]`

must be`Bounded`

, while the latitude-longitude topologies can be`Bounded`

,`Periodic`

, or`Flat`

.`precompute_metrics`

: Boolean specifying whether to precompute horizontal spacings and areas. Default:`true`

. When`false`

, horizontal spacings and areas are computed on-the-fly during a simulation.`halo`

: A 3-tuple of integers specifying the size of the halo region of cells surrounding the physical interior. The default is 3 halo cells in every direction.

**Examples**

- A default grid with
`Float64`

type:

```
julia> using Oceananigans
julia> grid = LatitudeLongitudeGrid(size=(36, 34, 25),
longitude = (-180, 180),
latitude = (-85, 85),
z = (-1000, 0))
36×34×25 LatitudeLongitudeGrid{Float64, Periodic, Bounded, Bounded} on CPU with 3×3×3 halo and with precomputed metrics
├── longitude: Periodic λ ∈ [-180.0, 180.0) regularly spaced with Δλ=10.0
├── latitude: Bounded φ ∈ [-85.0, 85.0] regularly spaced with Δφ=5.0
└── z: Bounded z ∈ [-1000.0, 0.0] regularly spaced with Δz=40.0
```

- A bounded spherical sector with cell interfaces stretched hyperbolically near the top:

```
julia> using Oceananigans
julia> σ = 1.1; # stretching factor
julia> Nz = 24; # vertical resolution
julia> Lz = 1000; # depth (m)
julia> hyperbolically_spaced_faces(k) = - Lz * (1 - tanh(σ * (k - 1) / Nz) / tanh(σ));
julia> grid = LatitudeLongitudeGrid(size=(36, 34, Nz),
longitude = (-180, 180),
latitude = (-20, 20),
z = hyperbolically_spaced_faces,
topology = (Bounded, Bounded, Bounded))
36×34×24 LatitudeLongitudeGrid{Float64, Bounded, Bounded, Bounded} on CPU with 3×3×3 halo and with precomputed metrics
├── longitude: Bounded λ ∈ [-180.0, 180.0] regularly spaced with Δλ=10.0
├── latitude: Bounded φ ∈ [-20.0, 20.0] regularly spaced with Δφ=1.17647
└── z: Bounded z ∈ [-1000.0, -0.0] variably spaced with min(Δz)=21.3342, max(Δz)=57.2159
```

`Oceananigans.Grids.LeftConnected`

— Type`LeftConnected`

Grid topology for dimensions that are connected to other models or domains only on the left (the other direction is bounded)

`Oceananigans.Grids.Periodic`

— Type`Periodic`

Grid topology for periodic dimensions.

`Oceananigans.Grids.RectilinearGrid`

— Type```
RectilinearGrid([architecture = CPU(), FT = Float64];
size,
x = nothing,
y = nothing,
z = nothing,
halo = nothing,
extent = nothing,
topology = (Periodic, Periodic, Bounded))
```

Creates a `RectilinearGrid`

with `size = (Nx, Ny, Nz)`

grid points.

**Positional arguments**

`architecture`

: Specifies whether arrays of coordinates and spacings are stored on the CPU or GPU. Default:`architecture = CPU()`

.`FT`

: Floating point data type. Default:`FT = Float64`

.

**Keyword arguments**

`size`

(required): A tuple prescribing the number of grid points in non-`Flat`

directions.`size`

is a 3-tuple for 3D models, a 2-tuple for 2D models, and either a scalar or 1-tuple for 1D models.`topology`

: A 3-tuple`(TX, TY, TZ)`

specifying the topology of the domain.`TX`

,`TY`

, and`TZ`

specify whether the`x`

-,`y`

-, and`z`

directions are`Periodic`

,`Bounded`

, or`Flat`

. The topology`Flat`

indicates that a model does not vary in those directions so that derivatives and interpolation are zero. The default is`topology = (Periodic, Periodic, Bounded)`

.`extent`

: A tuple prescribing the physical extent of the grid in non-`Flat`

directions. All directions are contructed with regular grid spacing and the domain (in the case that no direction is`Flat`

) is x ∈ (0, Lx), y ∈ (0, Ly), and z ∈ (-Lz, 0), which is most appropriate for oceanic applications with z = 0 usually being the ocean's surface.`x`

,`y`

, and`z`

: Each of`x, y, z`

are either (i) 2-tuples that specify the end points of the domain in their respect directions (in which case scalar values may be used in`Flat`

directions), or (ii) arrays or functions of the corresponding indices`i`

,`j`

, or`k`

that specify the locations of cell faces in the`x`

-,`y`

-, or`z`

-direction, respectively. For example, to prescribe the cell faces in`z`

we need to provide a function that takes`k`

as argument and retuns the location of the faces for indices`k = 1`

through`k = Nz + 1`

, where`Nz`

is the`size`

of the stretched`z`

dimension.

**Note**: *Either* `extent`

, or *all* of `x`

, `y`

, and `z`

must be specified.

`halo`

: A tuple of integers that specifies the size of the halo region of cells surrounding the physical interior for each non-`Flat`

direction. The default is 3 halo cells in every direction.

The physical extent of the domain can be specified via `x`

, `y`

, and `z`

keyword arguments indicating the left and right endpoints of each dimensions, e.g. `x = (-π, π)`

or via the `extent`

argument, e.g. `extent = (Lx, Ly, Lz)`

, which specifies the extent of each dimension in which case 0 ≤ x ≤ Lx, 0 ≤ y ≤ Ly, and -Lz ≤ z ≤ 0.

A grid topology may be specified via a tuple assigning one of `Periodic`

, `Bounded`

, and `Flat`

to each dimension. By default, a horizontally periodic grid topology `(Periodic, Periodic, Bounded)`

is assumed.

Constants are stored using floating point values of type `FT`

. By default this is `Float64`

. Make sure to specify the desired `FT`

if not using `Float64`

.

**Grid properties**

`(Nx, Ny, Nz) :: Int`

: Number of physical points in the $(x, y, z)$-direction.`(Hx, Hy, Hz) :: Int`

: Number of halo points in the $(x, y, z)$-direction.`(Lx, Ly, Lz) :: FT`

: Physical extent of the grid in the $(x, y, z)$-direction.`(Δxᶜᵃᵃ, Δyᵃᶜᵃ, Δzᵃᵃᶜ)`

: Grid spacing in the $(x, y, z)$-direction between cell centers. Defined at cell centers in $x$, $y$, and $z$.`(Δxᶠᵃᵃ, Δyᵃᶠᵃ, Δzᵃᵃᶠ)`

: Grid spacing in the $(x, y, z)$-direction between cell faces. Defined at cell faces in $x$, $y$, and $z$.`(xᶜᵃᵃ, yᵃᶜᵃ, zᵃᵃᶜ)`

: $(x, y, z)$ coordinates of cell centers.`(xᶠᵃᵃ, yᵃᶠᵃ, zᵃᵃᶠ)`

: $(x, y, z)$ coordinates of cell faces.

**Examples**

- A default grid with
`Float64`

type:

```
julia> using Oceananigans
julia> grid = RectilinearGrid(size=(32, 32, 32), extent=(1, 2, 3))
32×32×32 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── Periodic x ∈ [0.0, 1.0) regularly spaced with Δx=0.03125
├── Periodic y ∈ [0.0, 2.0) regularly spaced with Δy=0.0625
└── Bounded z ∈ [-3.0, 0.0] regularly spaced with Δz=0.09375
```

- A default grid with
`Float32`

type:

```
julia> using Oceananigans
julia> grid = RectilinearGrid(Float32; size=(32, 32, 16), x=(0, 8), y=(-10, 10), z=(-π, π))
32×32×16 RectilinearGrid{Float32, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── Periodic x ∈ [0.0, 8.0) regularly spaced with Δx=0.25
├── Periodic y ∈ [-10.0, 10.0) regularly spaced with Δy=0.625
└── Bounded z ∈ [-3.14159, 3.14159] regularly spaced with Δz=0.392699
```

- A two-dimenisional, horizontally-periodic grid:

```
julia> using Oceananigans
julia> grid = RectilinearGrid(size=(32, 32), extent=(2π, 4π), topology=(Periodic, Periodic, Flat))
32×32×1 RectilinearGrid{Float64, Periodic, Periodic, Flat} on CPU with 3×3×0 halo
├── Periodic x ∈ [3.60072e-17, 6.28319) regularly spaced with Δx=0.19635
├── Periodic y ∈ [7.20145e-17, 12.5664) regularly spaced with Δy=0.392699
└── Flat z
```

- A one-dimensional "column" grid:

```
julia> using Oceananigans
julia> grid = RectilinearGrid(size=256, z=(-128, 0), topology=(Flat, Flat, Bounded))
1×1×256 RectilinearGrid{Float64, Flat, Flat, Bounded} on CPU with 0×0×3 halo
├── Flat x
├── Flat y
└── Bounded z ∈ [-128.0, 0.0] regularly spaced with Δz=0.5
```

- A horizontally-periodic regular grid with cell interfaces stretched hyperbolically near the top:

```
julia> using Oceananigans
julia> σ = 1.1; # stretching factor
julia> Nz = 24; # vertical resolution
julia> Lz = 32; # depth (m)
julia> hyperbolically_spaced_faces(k) = - Lz * (1 - tanh(σ * (k - 1) / Nz) / tanh(σ));
julia> grid = RectilinearGrid(size = (32, 32, Nz), x = (0, 64),
y = (0, 64), z = hyperbolically_spaced_faces)
32×32×24 RectilinearGrid{Float64, Periodic, Periodic, Bounded} on CPU with 3×3×3 halo
├── Periodic x ∈ [0.0, 64.0) regularly spaced with Δx=2.0
├── Periodic y ∈ [0.0, 64.0) regularly spaced with Δy=2.0
└── Bounded z ∈ [-32.0, -0.0] variably spaced with min(Δz)=0.682695, max(Δz)=1.83091
```

- A three-dimensional grid with regular spacing in x, cell interfaces at Chebyshev nodes in y, and cell interfaces stretched in z hyperbolically near the top:

```
julia> using Oceananigans
julia> Nx, Ny, Nz = 32, 30, 24;
julia> Lx, Ly, Lz = 200, 100, 32; # (m)
julia> chebychev_nodes(j) = - Ly/2 * cos(π * (j - 1) / Ny);
julia> σ = 1.1; # stretching factor
julia> hyperbolically_spaced_faces(k) = - Lz * (1 - tanh(σ * (k - 1) / Nz) / tanh(σ));
julia> grid = RectilinearGrid(size = (Nx, Ny, Nz),
topology=(Periodic, Bounded, Bounded),
x = (0, Lx),
y = chebychev_nodes,
z = hyperbolically_spaced_faces)
32×30×24 RectilinearGrid{Float64, Periodic, Bounded, Bounded} on CPU with 3×3×3 halo
├── Periodic x ∈ [0.0, 200.0) regularly spaced with Δx=6.25
├── Bounded y ∈ [-50.0, 50.0] variably spaced with min(Δy)=0.273905, max(Δy)=5.22642
└── Bounded z ∈ [-32.0, -0.0] variably spaced with min(Δz)=0.682695, max(Δz)=1.83091
```

`Oceananigans.Grids.RightConnected`

— Type`RightConnected`

Grid topology for dimensions that are connected to other models or domains only on the right (the other direction is bounded)

`Oceananigans.Grids.halo_size`

— Method`halo_size(grid)`

Return a tuple with the size of the halo in each dimension.

`Oceananigans.Grids.new_data`

— Function`new_data(FT, grid, loc, indices)`

Returns an `OffsetArray`

of zeros of float type `FT`

on `arch`

itecture, with indices corresponding to a field on a `grid`

of `size(grid)`

and located at `loc`

.

`Oceananigans.Grids.nodes`

— Method`nodes(loc, grid; reshape=false)`

Return a 3-tuple of views over the interior nodes at the locations in `loc`

in `x, y, z`

.

If `reshape=true`

, the views are reshaped to 3D arrays with non-singleton dimensions 1, 2, 3 for `x, y, z`

, respectively. These reshaped arrays can then be used in broadcast operations with 3D fields or arrays.

`Oceananigans.Grids.offset_data`

— Function`offset_data(underlying_data, grid::AbstractGrid, loc)`

Returns an `OffsetArray`

that maps to `underlying_data`

in memory, with offset indices appropriate for the `data`

of a field on a `grid`

of `size(grid)`

and located at `loc`

.

`Oceananigans.Grids.topology`

— Method`topology(grid, dim)`

Return the topology of the `grid`

for the `dim`

-th dimension.

`Oceananigans.Grids.topology`

— Method`topology(grid)`

Return a tuple with the topology of the `grid`

for each dimension.

`Oceananigans.Grids.total_size`

— Method`total_size(loc, grid)`

Return the "total" size of a `grid`

at `loc`

. This is a 3-tuple of integers corresponding to the number of grid points along `x, y, z`

.

`Oceananigans.Grids.xnodes`

— Method`xnodes(loc, grid, reshape=false)`

Return a view over the interior `loc=Center`

or `loc=Face`

nodes on `grid`

in the $x$-direction. For `Bounded`

directions, `Face`

nodes include the boundary points.

**Keyword argument**

`reshape`

: With`reshape=false`

(default) the output is a 1D array while with`reshape=true`

the output is a 3D array with size`Nx×1×1`

.

See `znodes`

for examples.

`Oceananigans.Grids.ynodes`

— Method`ynodes(loc, grid, reshape=false)`

Return a view over the interior `loc=Center`

or `loc=Face`

nodes on `grid`

in the $y$-direction. For `Bounded`

directions, `Face`

nodes include the boundary points.

**Keyword argument**

`reshape`

: With`reshape=false`

(default) the output is a 1D array while with`reshape=true`

the output is a 3D array with size`1×Ny×1`

.

See `znodes`

for examples.

`Oceananigans.Grids.znodes`

— Method`znodes(loc, grid, reshape=false)`

Return a view over the interior `loc=Center`

or `loc=Face`

nodes on `grid`

in the $z$-direction. For `Bounded`

directions, `Face`

nodes include the boundary points.

**Keyword argument**

`reshape`

: With`reshape=false`

(default) the output is a 1D array while with`reshape=true`

the output is a 3D array with size`1×1×Nz`

.

**Examples**

```
julia> using Oceananigans
julia> horz_periodic_grid = RectilinearGrid(size=(3, 3, 3), extent=(2π, 2π, 1), halo=(1, 1, 1),
topology=(Periodic, Periodic, Bounded));
julia> zC = znodes(Center, horz_periodic_grid)
3-element view(OffsetArray(::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}, 0:4), 1:3) with eltype Float64:
-0.8333333333333334
-0.5
-0.16666666666666666
```

```
julia> zF = znodes(Face, horz_periodic_grid)
4-element view(OffsetArray(::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}, 0:5), 1:4) with eltype Float64:
-1.0
-0.6666666666666666
-0.3333333333333333
0.0
```

## Immersed boundaries

`Oceananigans.ImmersedBoundaries.GridFittedBottom`

— Type`GridFittedBottom(bottom_height, [immersed_condition=CenterImmersedCondition()])`

Return an immersed boundary with an irregular bottom fit to the underlying grid.

`Oceananigans.ImmersedBoundaries.ImmersedBoundaryCondition`

— Method`ImmersedBoundaryCondition(; interfaces...)`

Return an ImmersedBoundaryCondition with conditions on individual cell `interfaces ∈ (west, east, south, north, bottom, top)`

between the fluid and immersed boundary.

`Oceananigans.ImmersedBoundaries.ImmersedBoundaryGrid`

— Method`ImmersedBoundaryGrid(grid, ib::GridFittedBottom)`

Return a grid with `GridFittedBottom`

immersed boundary.

Computes ib.bottom_height and wraps in an array.

## Lagrangian particle tracking

`Oceananigans.LagrangianParticleTracking.LagrangianParticles`

— Method`LagrangianParticles(particles::StructArray; restitution=1.0, tracked_fields::NamedTuple=NamedTuple(), dynamics=no_dynamics)`

Construct some `LagrangianParticles`

that can be passed to a model. The `particles`

should be a `StructArray`

and can contain custom fields. The coefficient of restitution for particle-wall collisions is specified by `restitution`

.

A number of `tracked_fields`

may be passed in as a `NamedTuple`

of fields. Each particle will track the value of each field. Each tracked field must have a corresponding particle property. So if `T`

is a tracked field, then `T`

must also be a custom particle property.

`dynamics`

is a function of `(lagrangian_particles, model, Δt)`

that is called prior to advecting particles. `parameters`

can be accessed inside the `dynamics`

function.

`Oceananigans.LagrangianParticleTracking.LagrangianParticles`

— Method`LagrangianParticles(; x, y, z, restitution=1.0, dynamics=no_dynamics, parameters=nothing)`

Construct some `LagrangianParticles`

that can be passed to a model. The particles will have initial locations `x`

, `y`

, and `z`

. The coefficient of restitution for particle-wall collisions is specified by `restitution`

.

`dynamics`

is a function of `(lagrangian_particles, model, Δt)`

that is called prior to advecting particles. `parameters`

can be accessed inside the `dynamics`

function.

## Logger

`Oceananigans.Logger.OceananigansLogger`

— Type`OceananigansLogger(stream::IO=stdout, level=Logging.Info; show_info_source=false)`

Based on Logging.SimpleLogger, it tries to log all messages in the following format:

`[yyyy/mm/dd HH:MM:SS.sss] log_level message [-@-> source_file:line_number]`

where the source of the message between the square brackets is included only if `show_info_source=true`

or if the message is not an info level message.

## Models

### Non-hydrostatic models

`Oceananigans.Models.NonhydrostaticModels.NonhydrostaticModel`

— Method```
NonhydrostaticModel(; grid,
clock = Clock{eltype(grid)}(0, 0, 1),
advection = CenteredSecondOrder(),
buoyancy = nothing,
coriolis = nothing,
stokes_drift = nothing,
forcing::NamedTuple = NamedTuple(),
closure = nothing,
boundary_conditions::NamedTuple = NamedTuple(),
tracers = (),
timestepper = :QuasiAdamsBashforth2,
background_fields::NamedTuple = NamedTuple(),
particles::ParticlesOrNothing = nothing,
velocities = nothing,
pressures = nothing,
diffusivity_fields = nothing,
pressure_solver = nothing,
immersed_boundary = nothing,
auxiliary_fields = NamedTuple(),
)
```

Construct a model for a non-hydrostatic, incompressible fluid on `grid`

, using the Boussinesq approximation when `buoyancy != nothing`

. By default, all Bounded directions are rigid and impenetrable.

**Keyword arguments**

`grid`

: (required) The resolution and discrete geometry on which the`model`

is solved. The architecture (CPU/GPU) that the model is solve is inferred from the architecture of the`grid`

.`advection`

: The scheme that advects velocities and tracers. See`Oceananigans.Advection`

.`buoyancy`

: The buoyancy model. See`Oceananigans.BuoyancyModels`

.`coriolis`

: Parameters for the background rotation rate of the model.`stokes_drift`

: Parameters for Stokes drift fields associated with surface waves. Default:`nothing`

.`forcing`

:`NamedTuple`

of user-defined forcing functions that contribute to solution tendencies.`closure`

: The turbulence closure for`model`

. See`Oceananigans.TurbulenceClosures`

.`boundary_conditions`

:`NamedTuple`

containing field boundary conditions.`tracers`

: A tuple of symbols defining the names of the modeled tracers, or a`NamedTuple`

of preallocated`CenterField`

s.`timestepper`

: A symbol that specifies the time-stepping method. Either`:QuasiAdamsBashforth2`

or`:RungeKutta3`

.`background_fields`

:`NamedTuple`

with background fields (e.g., background flow). Default:`nothing`

.`particles`

: Lagrangian particles to be advected with the flow. Default:`nothing`

.`velocities`

: The model velocities. Default:`nothing`

.`pressures`

: Hydrostatic and non-hydrostatic pressure fields. Default:`nothing`

.`diffusivity_fields`

: Diffusivity fields. Default:`nothing`

.`pressure_solver`

: Pressure solver to be used in the model. If`nothing`

(default), the model constructor chooses the default based on the`grid`

provide.`immersed_boundary`

: The immersed boundary. Default:`nothing`

.`auxiliary_fields`

:`NamedTuple`

of auxiliary fields. Default:`nothing`

.

### Hydrostatic free-surface models

`Oceananigans.Models.HydrostaticFreeSurfaceModels.ExplicitFreeSurface`

— Type`struct ExplicitFreeSurface{E, T}`

The explicit free surface solver.

`η::Any`

free surface elevation

`gravitational_acceleration::Any`

gravitational accelerations

`Oceananigans.Models.HydrostaticFreeSurfaceModels.HydrostaticFreeSurfaceModel`

— Method```
HydrostaticFreeSurfaceModel(; grid,
clock = Clock{eltype(grid)}(0, 0, 1),
momentum_advection = CenteredSecondOrder(),
tracer_advection = CenteredSecondOrder(),
buoyancy = SeawaterBuoyancy(eltype(grid)),
coriolis = nothing,
free_surface = ImplicitFreeSurface(gravitational_acceleration=g_Earth),
forcing::NamedTuple = NamedTuple(),
closure = nothing,
boundary_conditions::NamedTuple = NamedTuple(),
tracers = (:T, :S),
particles::Union{Nothing, LagrangianParticles} = nothing,
velocities = nothing,
pressure = nothing,
diffusivity_fields = nothing,
auxiliary_fields = NamedTuple(),
)
```

Construct a hydrostatic model with a free surface on `grid`

.

**Keyword arguments**

`grid`

: (required) The resolution and discrete geometry on which`model`

is solved. The architecture (CPU/GPU) that the model is solve is inferred from the architecture of the grid.`momentum_advection`

: The scheme that advects velocities. See`Oceananigans.Advection`

.`tracer_advection`

: The scheme that advects tracers. See`Oceananigans.Advection`

.`buoyancy`

: The buoyancy model. See`Oceananigans.BuoyancyModels`

.`coriolis`

: Parameters for the background rotation rate of the model.`forcing`

:`NamedTuple`

of user-defined forcing functions that contribute to solution tendencies.`free_surface`

: The free surface model.`closure`

: The turbulence closure for`model`

. See`Oceananigans.TurbulenceClosures`

.`boundary_conditions`

:`NamedTuple`

containing field boundary conditions.`tracers`

: A tuple of symbols defining the names of the modeled tracers, or a`NamedTuple`

of preallocated`CenterField`

s.`particles`

: Lagrangian particles to be advected with the flow. Default:`nothing`

.`velocities`

: The model velocities. Default:`nothing`

.`pressure`

: Hydrostatic pressure field. Default:`nothing`

.`diffusivity_fields`

: Diffusivity fields. Default:`nothing`

.`auxiliary_fields`

:`NamedTuple`

of auxiliary fields. Default:`nothing`

.

`Oceananigans.Models.HydrostaticFreeSurfaceModels.ImplicitFreeSurface`

— Method`ImplicitFreeSurface(; solver_method=:Default, gravitational_acceleration=g_Earth, solver_settings...)`

Return an implicit free-surface solver. The implicit free-surface equation is

\[\left [ 𝛁_h ⋅ (H 𝛁_h) - \frac{1}{g Δt^2} \right ] η^{n+1} = \frac{𝛁_h ⋅ 𝐐_⋆}{g Δt} - \frac{η^{n}}{g Δt^2} ,\]

where $η^n$ is the free-surface elevation at the $n$-th time step, $H$ is depth, $g$ is the gravitational acceleration, $Δt$ is the time step, $𝛁_h$ is the horizontal gradient operator, and $𝐐_⋆$ is the barotropic volume flux associated with the predictor velocity field $𝐮_⋆$, i.e.,

\[𝐐_⋆ = \int_{-H}^0 𝐮_⋆ \, 𝖽 z ,\]

where

\[𝐮_⋆ = 𝐮^n + \int_{t_n}^{t_{n+1}} 𝐆ᵤ \, 𝖽t .\]

This equation can be solved, in general, using the `PreconditionedConjugateGradientSolver`

but other solvers can be invoked in special cases.

If $H$ is constant, we divide through out to obtain

\[\left ( ∇^2_h - \frac{1}{g H Δt^2} \right ) η^{n+1} = \frac{1}{g H Δt} \left ( 𝛁_h ⋅ 𝐐_⋆ - \frac{η^{n}}{Δt} \right ) .\]

Thus, for constant $H$ and on grids with regular spacing in $x$ and $y$ directions, the free surface can be obtained using the `FFTBasedPoissonSolver`

.

`solver_method`

can be either of:

`:FastFourierTransform`

for`FFTBasedPoissonSolver`

`:HeptadiagonalIterativeSolver`

for`HeptadiagonalIterativeSolver`

`:PreconditionedConjugateGradient`

for`PreconditionedConjugateGradientSolver`

`:Multigrid`

for`MultigridSolver`

By default, if the grid has regular spacing in the horizontal directions then the `:FastFourierTransform`

is chosen, otherwise the `:HeptadiagonalIterativeSolver`

.

`Oceananigans.Models.HydrostaticFreeSurfaceModels.PrescribedVelocityFields`

— Method`PrescribedVelocityFields(; u=zerofunc, v=zerofunc, w=zerofunc, parameters=nothing)`

Builds `PrescribedVelocityFields`

with prescribed functions `u`

, `v`

, and `w`

.

If `isnothing(parameters)`

, then `u, v, w`

are called with the signature

`u(x, y, z, t) = # something interesting`

If `!isnothing(parameters)`

, then `u, v, w`

are called with the signature

`u(x, y, z, t, parameters) = # something parameterized and interesting`

In the constructor for `HydrostaticFreeSurfaceModel`

, the functions `u, v, w`

are wrapped in `FunctionField`

and associated with the model's `grid`

and `clock`

.

`Oceananigans.Models.HydrostaticFreeSurfaceModels.SplitExplicitFreeSurface`

— Type`struct SplitExplicitFreeSurface{𝒩, 𝒮, ℱ, 𝒫 ,ℰ}`

The split-explicit free surface solver.

`η::Any`

The instantaneous free surface (

`ReducedField`

)`state::Any`

The entire state for the split-explicit (

`SplitExplicitState`

)`auxiliary::Any`

Parameters for timestepping split-explicit (

`NamedTuple`

)`gravitational_acceleration::Any`

Gravitational acceleration

`settings::Any`

Settings for the split-explicit scheme (

`NamedTuple`

)

### Shallow-water models

`Oceananigans.Models.ShallowWaterModels.ShallowWaterModel`

— Method```
ShallowWaterModel(; grid,
gravitational_acceleration,
clock = Clock{eltype(grid)}(0, 0, 1),
momentum_advection = UpwindBiasedFifthOrder(),
tracer_advection = WENO(),
mass_advection = WENO(),
coriolis = nothing,
forcing::NamedTuple = NamedTuple(),
closure = nothing,
bathymetry = nothing,
tracers = (),
diffusivity_fields = nothing,
boundary_conditions::NamedTuple = NamedTuple(),
timestepper::Symbol = :RungeKutta3,
formulation = ConservativeFormulation())
```

Construct a shallow water model on `grid`

with `gravitational_acceleration`

constant.

**Keyword arguments**

`grid`

: (required) The resolution and discrete geometry on which`model`

is solved. The architecture (CPU/GPU) that the model is solve is inferred from the architecture of the grid.`gravitational_acceleration`

: (required) The gravitational acceleration constant.`clock`

: The`clock`

for the model.`momentum_advection`

: The scheme that advects velocities. See`Oceananigans.Advection`

. Default:`UpwindBiasedFifthOrder()`

.`tracer_advection`

: The scheme that advects tracers. See`Oceananigans.Advection`

. Default:`WENO()`

.`mass_advection`

: The scheme that advects the mass equation. See`Oceananigans.Advection`

. Default:`WENO()`

.`coriolis`

: Parameters for the background rotation rate of the model.`forcing`

:`NamedTuple`

of user-defined forcing functions that contribute to solution tendencies.`closure`

: The turbulence closure for`model`

. See`Oceananigans.TurbulenceClosures`

.`bathymetry`

: The bottom bathymetry.`tracers`

: A tuple of symbols defining the names of the modeled tracers, or a`NamedTuple`

of preallocated`CenterField`

s.`diffusivity_fields`

: Stores diffusivity fields when the closures require a diffusivity to be calculated at each timestep.`boundary_conditions`

:`NamedTuple`

containing field boundary conditions.`timestepper`

: A symbol that specifies the time-stepping method. Either`:QuasiAdamsBashforth2`

or`:RungeKutta3`

(default).`formulation`

: Whether the dynamics are expressed in conservative form (`ConservativeFormulation()`

; default) or in non-conservative form with a vector-invariant formulation for the non-linear terms (`VectorInvariantFormulation()`

).

The `ConservativeFormulation()`

requires `RectilinearGrid`

. Use `VectorInvariantFormulation()`

with `LatitudeLongitudeGrid`

.

## MultiRegion

## Operators

`Oceananigans.Operators.div_xyᶜᶜᶜ`

— Method`div_xyᶜᶜᵃ(i, j, k, grid, u, v)`

Return the discrete `div_xy = ∂x u + ∂y v`

of velocity field `u, v`

defined as

`1 / Azᶜᶜᵃ * [δxᶜᵃᵃ(Δyᵃᶜᵃ * u) + δyᵃᶜᵃ(Δxᶜᵃᵃ * v)]`

at `i, j, k`

, where `Azᶜᶜᵃ`

is the area of the cell centered on (Center, Center, Any) –- a tracer cell, `Δy`

is the length of the cell centered on (Face, Center, Any) in `y`

(a `u`

cell), and `Δx`

is the length of the cell centered on (Center, Face, Any) in `x`

(a `v`

cell). `div_xyᶜᶜᵃ`

ends up at the location `cca`

.

`Oceananigans.Operators.divᶜᶜᶜ`

— Method`divᶜᶜᶜ(i, j, k, grid, u, v, w)`

Calculates the divergence $∇·𝐕$ of a vector field $𝐕 = (u, v, w)$,

`1/V * [δxᶜᵃᵃ(Ax * u) + δxᵃᶜᵃ(Ay * v) + δzᵃᵃᶜ(Az * w)]`

which ends up at the cell centers `ccc`

.

`Oceananigans.Operators.ζ₃ᶠᶠᶜ`

— MethodVertical vorticity associated with horizontal velocities u, v.

`Oceananigans.Operators.∇²ᶜᶜᶜ`

— Method`∇²ᶜᶜᶜ(i, j, k, grid, c)`

Calculate the Laplacian of $c$ via

`1/V * [δxᶜᵃᵃ(Ax * ∂xᶠᵃᵃ(c)) + δyᵃᶜᵃ(Ay * ∂yᵃᶠᵃ(c)) + δzᵃᵃᶜ(Az * ∂zᵃᵃᶠ(c))]`

which ends up at the location `ccc`

.

## Output readers

`Oceananigans.OutputReaders.FieldDataset`

— Method```
FieldDataset(filepath;
architecture=CPU(), grid=nothing, backend=InMemory(), metadata_paths=["metadata"])
```

Returns a `Dict`

containing a `FieldTimeSeries`

for each field in the JLD2 file located at `filepath`

. Note that model output **must** have been saved with halos.

**Keyword arguments**

`backend`

: Either`InMemory()`

(default) or`OnDisk()`

. The`InMemory`

backend will

load the data fully in memory as a 4D multi-dimensional array while the `OnDisk()`

backend will lazily load field time snapshots when the `FieldTimeSeries`

is indexed linearly.

`metadata_paths`

: A list of JLD2 paths to look for metadata. By default it looks in`file["metadata"]`

.`grid`

: May be specified to override the grid used in the JLD2 file.

`Oceananigans.OutputReaders.FieldTimeSeries`

— Method```
FieldTimeSeries(path, name;
backend = InMemory(),
grid = nothing,
iterations = nothing,
times = nothing)
```

Returns a `FieldTimeSeries`

for the field `name`

describing a field's time history from a JLD2 file located at `path`

.

**Keyword arguments**

`backend`

:`InMemory()`

to load data into a 4D array or`OnDisk()`

to lazily load data from disk when indexing into`FieldTimeSeries`

.`grid`

: A grid to associated with data, in the case that the native grid was not serialized properly.`iterations`

: Iterations to load. Defaults to all iterations found in the file.`times`

: Save times to load, as determined through an approximate floating point comparison to recorded save times. Defaults to times associated with`iterations`

. Takes precedence over`iterations`

if`times`

is specified.

`Oceananigans.OutputReaders.FieldTimeSeries`

— Method```
FieldTimeSeries{LX, LY, LZ}(grid, times, [FT=eltype(grid);]
indices = (:, :, :),
boundary_conditions = nothing)
```

Return a `FieldTimeSeries`

at location `(LX, LY, LZ)`

, on `grid`

, at `times`

.

## Output writers

`Oceananigans.OutputWriters.AveragedTimeInterval`

— Type`mutable struct AveragedTimeInterval <: AbstractSchedule`

Container for parameters that configure and handle time-averaged output.

`Oceananigans.OutputWriters.AveragedTimeInterval`

— Method`AveragedTimeInterval(interval; window=interval, stride=1)`

Returns a `schedule`

that specifies periodic time-averaging of output. The time `window`

specifies the extent of the time-average, which reoccurs every `interval`

.

`output`

is computed and accumulated into the average every `stride`

iterations during the averaging window. For example, `stride=1`

computs output every iteration, whereas `stride=2`

computes output every other iteration. Time-averages with longer `stride`

s are faster to compute, but less accurate.

The time-average of $a$ is a left Riemann sum corresponding to

\[⟨a⟩ = T⁻¹ \int_{tᵢ-T}^{tᵢ} a \mathrm{d} t \, ,\]

where $⟨a⟩$ is the time-average of $a$, $T$ is the time-window for averaging, and the $tᵢ$ are discrete times separated by the time `interval`

. The $tᵢ$ specify both the end of the averaging window and the time at which output is written.

**Example**

```
using Oceananigans.OutputWriters: AveragedTimeInterval
using Oceananigans.Utils: year, years
schedule = AveragedTimeInterval(4years, window=1year)
# output
AveragedTimeInterval(window=1 year, stride=1, interval=4 years)
```

An `AveragedTimeInterval`

schedule directs an output writer to time-average its outputs before writing them to disk:

```
using Oceananigans
using Oceananigans.OutputWriters: JLD2OutputWriter
using Oceananigans.Utils: minutes
model = NonhydrostaticModel(grid=RectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1)))
simulation = Simulation(model, Δt=10minutes, stop_time=30years)
simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocities,
filename= "averaged_velocity_data.jld2",
schedule = AveragedTimeInterval(4years, window=1year, stride=2))
# output
JLD2OutputWriter scheduled on TimeInterval(4 years):
├── filepath: ./averaged_velocity_data.jld2
├── 3 outputs: (u, v, w) averaged on AveragedTimeInterval(window=1 year, stride=2, interval=4 years)
├── array type: Array{Float32}
├── including: [:grid, :coriolis, :buoyancy, :closure]
└── max filesize: Inf YiB
```

`Oceananigans.OutputWriters.Checkpointer`

— Method```
Checkpointer(model; schedule,
dir = ".",
prefix = "checkpoint",
overwrite_existing = false,
cleanup = false,
additional_kwargs...)
```

Construct a `Checkpointer`

that checkpoints the model to a JLD2 file on `schedule.`

The `model.clock.iteration`

is included in the filename to distinguish between multiple checkpoint files.

To restart or "pickup" a model from a checkpoint, specify `pickup=true`

when calling `run!`

, ensuring that the checkpoint file is the current working directory. See

`help> run!`

for more details.

Note that extra model `properties`

can be safely specified, but removing crucial properties such as `:velocities`

will make restoring from the checkpoint impossible.

The checkpointer attempts to serialize as much of the model to disk as possible, but functions or objects containing functions cannot be serialized at this time.

**Keyword arguments**

`schedule`

(required): Schedule that determines when to checkpoint.`dir`

: Directory to save output to. Default: "." (current working directory).`prefix`

: Descriptive filename prefixed to all output files. Default: "checkpoint".`overwrite_existing`

: Remove existing files if their filenames conflict. Default:`false`

.`verbose`

: Log what the output writer is doing with statistics on compute/write times and file sizes. Default:`false`

.`cleanup`

: Previous checkpoint files will be deleted once a new checkpoint file is written. Default:`false`

.`properties`

: List of model properties to checkpoint. This list must contain`[:grid, :architecture, :timestepper, :particles]`

. Default: [:architecture, :grid, :clock, :coriolis, :buoyancy, :closure, :velocities, :tracers, :timestepper, :particles]

`Oceananigans.OutputWriters.JLD2OutputWriter`

— Method```
JLD2OutputWriter(model, outputs; filename, schedule,
dir = ".",
indices = (:, :, :),
with_halos = false,
array_type = Array{Float32},
max_filesize = Inf,
overwrite_existing = false,
init = noinit,
including = [:grid, :coriolis, :buoyancy, :closure],
verbose = false,
part = 1,
jld2_kw = Dict{Symbol, Any}())
```

Construct a `JLD2OutputWriter`

for an Oceananigans `model`

that writes `label, output`

pairs in `outputs`

to a JLD2 file.

The argument `outputs`

may be a `Dict`

or `NamedTuple`

. The keys of `outputs`

are symbols or strings that "name" output data. The values of `outputs`

are either `AbstractField`

s, objects that are called with the signature `output(model)`

, or `WindowedTimeAverage`

s of `AbstractFields`

s, functions, or callable objects.

**Keyword arguments**

**Filenaming**

`filename`

(required): Descriptive filename. ".jld2" is appended to`filename`

in the file path if`filename`

does not end in ".jld2".`dir`

: Directory to save output to. Default: "." (current working directory).

**Output frequency and time-averaging**

`schedule`

(required):`AbstractSchedule`

that determines when output is saved.

**Slicing and type conversion prior to output**

`indices`

: Specifies the indices to write to disk with a`Tuple`

of`Colon`

,`UnitRange`

, or`Int`

elements. Indices must be`Colon`

,`Int`

, or contiguous`UnitRange`

. Defaults to`(:, :, :)`

or "all indices". If`!with_halos`

, halo regions are removed from`indices`

. For example,`indices = (:, :, 1)`

will save xy-slices of the bottom-most index.`with_halos`

(Bool): Whether or not to slice halo regions from fields before writing output. Note, that to postprocess saved output (e.g., compute derivatives, etc) information about the boundary conditions is often crucial. In that case you might need to set`with_halos = true`

.`array_type`

: The array type to which output arrays are converted to prior to saving. Default:`Array{Float32}`

.

**File management**

`max_filesize`

: The writer will stop writing to the output file once the file size exceeds`max_filesize`

, and write to a new one with a consistent naming scheme ending in`part1`

,`part2`

, etc. Defaults to`Inf`

.`overwrite_existing`

: Remove existing files if their filenames conflict. Default:`false`

.

**Output file metadata management**

`init`

: A function of the form`init(file, model)`

that runs when a JLD2 output file is initialized. Default:`noinit(args...) = nothing`

.`including`

: List of model properties to save with every file. Default:`[:grid, :coriolis, :buoyancy, :closure]`

**Miscellaneous keywords**

`verbose`

: Log what the output writer is doing with statistics on compute/write times and file sizes. Default:`false`

.`part`

: The starting part number used if`max_filesize`

is finite. Default: 1.`jld2_kw`

: Dict of kwargs to be passed to`jldopen`

when data is written.

**Example**

Write out 3D fields for $u$, $v$, $w$, and a tracer $c$, along with a horizontal average:

```
using Oceananigans
using Oceananigans.Utils: hour, minute
model = NonhydrostaticModel(grid=RectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1)), tracers=(:c,))
simulation = Simulation(model, Δt=12, stop_time=1hour)
function init_save_some_metadata!(file, model)
file["author"] = "Chim Riggles"
file["parameters/coriolis_parameter"] = 1e-4
file["parameters/density"] = 1027
return nothing
end
c_avg = Field(Average(model.tracers.c, dims=(1, 2)))
# Note that model.velocities is NamedTuple
simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocities,
filename = "some_data.jld2",
schedule = TimeInterval(20minute),
init = init_save_some_metadata!)
# output
JLD2OutputWriter scheduled on TimeInterval(20 minutes):
├── filepath: ./some_data.jld2
├── 3 outputs: (u, v, w)
├── array type: Array{Float32}
├── including: [:grid, :coriolis, :buoyancy, :closure]
└── max filesize: Inf YiB
```

and a time- and horizontal-average of tracer $c$ every 20 minutes of simulation time to a file called `some_averaged_data.jld2`

```
simulation.output_writers[:avg_c] = JLD2OutputWriter(model, (; c=c_avg),
filename = "some_averaged_data.jld2",
schedule = AveragedTimeInterval(20minute, window=5minute))
# output
JLD2OutputWriter scheduled on TimeInterval(20 minutes):
├── filepath: ./some_averaged_data.jld2
├── 1 outputs: c averaged on AveragedTimeInterval(window=5 minutes, stride=1, interval=20 minutes)
├── array type: Array{Float32}
├── including: [:grid, :coriolis, :buoyancy, :closure]
└── max filesize: Inf YiB
```

`Oceananigans.OutputWriters.NetCDFOutputWriter`

— Method```
NetCDFOutputWriter(model, outputs; filename, schedule
dir = ".",
array_type = Array{Float32},
indices = nothing,
with_halos = false,
global_attributes = Dict(),
output_attributes = Dict(),
dimensions = Dict(),
overwrite_existing = false,
compression = 0,
verbose = false)
```

Construct a `NetCDFOutputWriter`

that writes `(label, output)`

pairs in `outputs`

(which should be a `Dict`

) to a NetCDF file, where `label`

is a string that labels the output and `output`

is either a `Field`

(e.g. `model.velocities.u`

) or a function `f(model)`

that returns something to be written to disk. Custom output requires the spatial `dimensions`

(a `Dict`

) to be manually specified (see examples).

**Keyword arguments**

`filename`

(required): Descriptive filename. ".nc" is appended to`filename`

if ".nc" is not detected.`schedule`

(required):`AbstractSchedule`

that determines when output is saved.`dir`

: Directory to save output to.`array_type`

: The array type to which output arrays are converted to prior to saving. Default:`Array{Float32}`

.`indices`

: Tuple of indices of the output variables to include. Default is`(:, :, :)`

, which includes the full fields.`with_halos`

: Boolean defining whether or not to include halos in the outputs. Default:`false`

. Note, that to postprocess saved output (e.g., compute derivatives, etc) information about the boundary conditions is often crucial. In that case you might need to set`with_halos = true`

.`global_attributes`

: Dict of model properties to save with every file. Default:`Dict()`

.`output_attributes`

: Dict of attributes to be saved with each field variable (reasonable defaults are provided for velocities, buoyancy, temperature, and salinity; otherwise`output_attributes`

*must*be user-provided).`dimensions`

: A`Dict`

of dimension tuples to apply to outputs (required for function outputs)`overwrite_existing`

: If false,`NetCDFOutputWriter`

will be set to append to`filepath`

. If true,`NetCDFOutputWriter`

will overwrite`filepath`

if it exists or create it if it does not. Default:`false`

. See NCDatasets.jl documentation for more information about its`mode`

option.`compression`

: Determines the compression level of data (0-9; default: 0)

**Examples**

Saving the $u$ velocity field and temperature fields, the full 3D fields and surface 2D slices to separate NetCDF files:

```
using Oceananigans
grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1))
model = NonhydrostaticModel(grid=grid, tracers=:c)
simulation = Simulation(model, Δt=12, stop_time=3600)
fields = Dict("u" => model.velocities.u, "c" => model.tracers.c)
simulation.output_writers[:field_writer] =
NetCDFOutputWriter(model, fields, filename="fields.nc", schedule=TimeInterval(60))
# output
NetCDFOutputWriter scheduled on TimeInterval(1 minute):
├── filepath: ./fields.nc
├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0)
├── 2 outputs: (c, u)
└── array type: Array{Float32}
```

```
simulation.output_writers[:surface_slice_writer] =
NetCDFOutputWriter(model, fields, filename="surface_xy_slice.nc",
schedule=TimeInterval(60), indices=(:, :, grid.Nz))
# output
NetCDFOutputWriter scheduled on TimeInterval(1 minute):
├── filepath: ./surface_xy_slice.nc
├── dimensions: zC(1), zF(1), xC(16), yF(16), xF(16), yC(16), time(0)
├── 2 outputs: (c, u)
└── array type: Array{Float32}
```

```
simulation.output_writers[:averaged_profile_writer] =
NetCDFOutputWriter(model, fields,
filename = "averaged_z_profile.nc",
schedule = AveragedTimeInterval(60, window=20),
indices = (1, 1, :))
# output
NetCDFOutputWriter scheduled on TimeInterval(1 minute):
├── filepath: ./averaged_z_profile.nc
├── dimensions: zC(16), zF(17), xC(1), yF(1), xF(1), yC(1), time(0)
├── 2 outputs: (c, u) averaged on AveragedTimeInterval(window=20 seconds, stride=1, interval=1 minute)
└── array type: Array{Float32}
```

`NetCDFOutputWriter`

also accepts output functions that write scalars and arrays to disk, provided that their `dimensions`

are provided:

```
using Oceananigans
grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 2, 3))
model = NonhydrostaticModel(grid=grid)
simulation = Simulation(model, Δt=1.25, stop_iteration=3)
f(model) = model.clock.time^2; # scalar output
g(model) = model.clock.time .* exp.(znodes(Center, grid)) # vector/profile output
h(model) = model.clock.time .* ( sin.(xnodes(Center, grid, reshape=true)[:, :, 1])
.* cos.(ynodes(Face, grid, reshape=true)[:, :, 1])) # xy slice output
outputs = Dict("scalar" => f, "profile" => g, "slice" => h)
dims = Dict("scalar" => (), "profile" => ("zC",), "slice" => ("xC", "yC"))
output_attributes = Dict(
"scalar" => Dict("longname" => "Some scalar", "units" => "bananas"),
"profile" => Dict("longname" => "Some vertical profile", "units" => "watermelons"),
"slice" => Dict("longname" => "Some slice", "units" => "mushrooms")
);
global_attributes = Dict("location" => "Bay of Fundy", "onions" => 7)
simulation.output_writers[:things] =
NetCDFOutputWriter(model, outputs,
schedule=IterationInterval(1), filename="things.nc", dimensions=dims, verbose=true,
global_attributes=global_attributes, output_attributes=output_attributes)
# output
NetCDFOutputWriter scheduled on IterationInterval(1):
├── filepath: ./things.nc
├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0)
├── 3 outputs: (profile, slice, scalar)
└── array type: Array{Float32}
```

`Oceananigans.OutputWriters.WindowedTimeAverage`

— Type`WindowedTimeAverage(operand, model=nothing; schedule)`

Returns an object for computing running averages of `operand`

over `schedule.window`

and recurring on `schedule.interval`

, where `schedule`

is an `AveragedTimeInterval`

. During the collection period, averages are computed every `schedule.stride`

iteration.

`operand`

may be a `Oceananigans.Field`

or a function that returns an array or scalar.

Calling `wta(model)`

for `wta::WindowedTimeAverage`

object returns `wta.result`

.

## Simulations

`Oceananigans.Simulations.Callback`

— Type`Callback(func, schedule=IterationInterval(1); parameters=nothing)`

Return `Callback`

that executes `func`

on `schedule`

with optional `parameters`

. `schedule = IterationInterval(1)`

by default.

If `isnothing(parameters)`

, `func(sim::Simulation)`

is called. Otherwise, `func`

is called via `func(sim::Simulation, parameters)`

.

`Oceananigans.Simulations.Simulation`

— Method```
Simulation(model; Δt,
stop_iteration = Inf,
stop_time = Inf,
wall_time_limit = Inf)
```

Construct a `Simulation`

for a `model`

with time step `Δt`

.

**Keyword arguments**

`Δt`

: Required keyword argument specifying the simulation time step. Can be a`Number`

for constant time steps or a`TimeStepWizard`

for adaptive time-stepping.`stop_iteration`

: Stop the simulation after this many iterations.`stop_time`

: Stop the simulation once this much model clock time has passed.`wall_time_limit`

: Stop the simulation if it's been running for longer than this many seconds of wall clock time.

`Oceananigans.Simulations.TimeStepWizard`

— Type`TimeStepWizard(cfl=0.2, diffusive_cfl=Inf, max_change=1.1, min_change=0.5, max_Δt=Inf, min_Δt=0.0)`

Callback for adapting simulation time-steps `Δt`

to maintain the advective Courant-Freidrichs-Lewy (`cfl`

) number, the `diffusive_cfl`

, while maintaining `max_Δt`

, `min_Δt`

, and satisfying `max_change`

and `min_change`

criteria so `Δt`

is not adapted "too quickly".

For more information on the `cfl`

number, see its wikipedia entry.

**Example**

To use `TimeStepWizard`

, adapt in a `Callback`

and add it to a `Simulation`

:

```
julia> simulation = Simulation(model, Δt=0.9, stop_iteration=100)
julia> wizard = TimeStepWizard(cfl=0.2)
julia> simulation.callbacks[:wizard] = Callback(wizard, IterationInterval(4))
```

Then when `run!(simulation)`

is invoked, the time-step `simulation.Δt`

will be updated every 4 iterations. Note that the name `:wizard`

is unimportant.

`Oceananigans.Simulations.erroring_NaNChecker!`

— Method`erroring_NaNChecker!(simulation)`

Toggles `simulation`

's `NaNChecker`

to throw an error when a `NaN`

is detected.

`Oceananigans.Simulations.iteration`

— Method`iteration(sim::Simulation)`

Return the current simulation iteration.

`Oceananigans.Simulations.run!`

— Method`run!(simulation; pickup=false)`

Run a `simulation`

until one of `simulation.stop_criteria`

evaluates `true`

. The simulation will then stop.

**Picking simulations up from a checkpoint**

Simulations are "picked up" from a checkpoint if `pickup`

is either `true`

, a `String`

, or an `Integer`

greater than 0.

Picking up a simulation sets field and tendency data to the specified checkpoint, leaving all other model properties unchanged.

Possible values for `pickup`

are:

`pickup=true`

picks a simulation up from the latest checkpoint associated with the`Checkpointer`

in`simulation.output_writers`

.`pickup=iteration::Int`

picks a simulation up from the checkpointed file associated with`iteration`

and the`Checkpointer`

in`simulation.output_writers`

.`pickup=filepath::String`

picks a simulation up from checkpointer data in`filepath`

.

Note that `pickup=true`

and `pickup=iteration`

fails if `simulation.output_writers`

contains more than one checkpointer.

## Solvers

`Oceananigans.Solvers.BatchedTridiagonalSolver`

— Type`BatchedTridiagonalSolver`

A batched solver for large numbers of triadiagonal systems.

`Oceananigans.Solvers.BatchedTridiagonalSolver`

— Method`BatchedTridiagonalSolver(grid; lower_diagonal, diagonal, upper_diagonal, parameters=nothing)`

Construct a solver for batched tridiagonal systems on `grid`

of the form

```
bⁱʲ¹ ϕⁱʲ¹ + cⁱʲ¹ ϕⁱʲ² = fⁱʲ¹, k = 1
aⁱʲᵏ⁻¹ ϕⁱʲᵏ⁻¹ + bⁱʲᵏ ϕⁱʲᵏ + cⁱʲᵏ ϕⁱʲᵏ⁺¹ = fⁱʲᵏ, k = 2, ..., N-1
aⁱʲᴺ⁻¹ ϕⁱʲᴺ⁻¹ + bⁱʲᴺ ϕⁱʲᴺ = fⁱʲᴺ, k = N
```

where `a`

is the `lower_diagonal`

, `b`

is the `diagonal`

, and `c`

is the `upper_diagonal`

. `ϕ`

is the solution and `f`

is the right hand side source term passed to `solve!(ϕ, tridiagonal_solver, f)`

`a`

, `b`

, `c`

, and `f`

can be specified in three ways:

A 1D array means that

`aⁱʲᵏ = a[k]`

.A 3D array means that

`aⁱʲᵏ = a[i, j, k]`

.Otherwise,

`a`

is assumed to be callable:- If
`isnothing(parameters)`

then`aⁱʲᵏ = a(i, j, k, grid, args...)`

. - If
`!isnothing(parameters)`

then`aⁱʲᵏ = a(i, j, k, grid, parameters, args...)`

.

where

`args...`

are`Varargs`

passed to`solve_batched_tridiagonal_system!(ϕ, solver, args...)`

.- If

`Oceananigans.Solvers.FFTBasedPoissonSolver`

— Type`FFTBasedPoissonSolver(grid, planner_flag=FFTW.PATIENT)`

Return an `FFTBasedPoissonSolver`

that solves the "generalized" Poisson equation,

\[(∇² + m) ϕ = b,\]

where $m$ is a number, using a eigenfunction expansion of the discrete Poisson operator on a staggered grid and for periodic or Neumann boundary conditions.

In-place transforms are applied to $b$, which means $b$ must have complex-valued elements (typically the same type as `solver.storage`

).

See `solve!`

for more information about the FFT-based Poisson solver algorithm.

`Oceananigans.Solvers.HeptadiagonalIterativeSolver`

— Method```
HeptadiagonalIterativeSolver(coeffs;
grid,
iterative_solver = cg!,
maximum_iterations = prod(size(grid)),
tolerance = 1e-13,
reduced_dim = (false, false, false),
placeholder_timestep = -1.0,
preconditioner_method = :Default,
preconditioner_settings = nothing,
template = arch_array(architecture(grid), zeros(prod(size(grid)))),
verbose = false)
```

Return a `HeptadiagonalIterativeSolver`

to solve the problem `A * x = b`

, provided that `A`

is a symmetric matrix.

The solver relies on a sparse version of the matrix `A`

that is stored in `matrix_constructors`

.

In particular, given coefficients `Ax`

, `Ay`

, `Az`

, `C`

, `D`

, the solved problem is

```
Axᵢ₊₁ ηᵢ₊₁ + Axᵢ ηᵢ₋₁ + Ayⱼ₊₁ ηⱼ₊₁ + Ayⱼ ηⱼ₋₁ + Azₖ₊₁ ηₖ₊₁ + Azₖ ηₖ₋₁
- 2 ( Axᵢ₊₁ + Axᵢ + Ayⱼ₊₁ + Ayⱼ + Azₖ₊₁ + Azₖ ) ηᵢⱼₖ
+ ( Cᵢⱼₖ + Dᵢⱼₖ/Δt^2 ) ηᵢⱼₖ = b
```

To have the equation solved at location `{Center, Center, Center}`

, the coefficients must be specified at:

`Ax`

->`{Face, Center, Center}`

`Ay`

->`{Center, Face, Center}`

`Az`

->`{Center, Center, Face}`

`C`

->`{Center, Center, Center}`

`D`

->`{Center, Center, Center}`

`solver.matrix`

is precomputed with a placeholder timestep value of `placeholder_timestep = -1.0`

.

The sparse matrix `A`

can be constructed with:

`SparseMatrixCSC(constructors...)`

for CPU`CuSparseMatrixCSC(constructors...)`

for GPU

The matrix constructors are calculated based on the pentadiagonal coeffients passed as an input to `matrix_from_coefficients`

function.

To allow for variable time step, the diagonal term `- Az / (g * Δt²)`

is only added later on and it is updated only when the previous time step changes (`previous_Δt != Δt`

).

Preconditioning is done through the various methods implemented in `Solvers/sparse_preconditioners.jl`

.

The `iterative_solver`

used can is to be chosen from the IterativeSolvers.jl package. The default solver is a Conjugate Gradient (`cg`

):

`solver = HeptadiagonalIterativeSolver((Ax, Ay, Az, C, D); grid)`

`Oceananigans.Solvers.MultigridSolver`

— Method```
MultigridSolver(linear_operation!::Function,
args...;
template_field::AbstractField,
maxiter = prod(size(template_field)),
reltol = sqrt(eps(eltype(template_field.grid))),
abstol = 0,
amg_algorithm = RugeStubenAMG()
)
```

Returns a MultigridSolver that solves the linear equation $A x = b$ using a multigrid method, where `A * x`

is determined by `linear_operation!`

`linear_operation!`

is a function with signature `linear_operation!(Ax, x, args...)`

that calculates `A * x`

for given `x`

and stores the result in `Ax`

.

The solver is used by calling

`solve!(x, solver::MultigridSolver, b; kwargs...)`

for `solver`

, right-hand side `b`

, solution `x`

, and optional keyword arguments `kwargs...`

.

**Arguments**

`template_field`

: Dummy field that is the same type and size as`x`

and`b`

, which is used to infer the`architecture`

,`grid`

, and to create work arrays that are used internally by the solver.`maxiter`

: Maximum number of iterations the solver may perform before exiting.`reltol, abstol`

: Relative and absolute tolerance for convergence of the algorithm. The iteration stops when`norm(A * x - b) < max(reltol * norm(b), abstol)`

.`amg_algorithm`

: Algebraic Multigrid algorithm defining mapping between different grid spacings. Options are`RugeStubenAMG()`

(default) or`SmoothedAggregationAMG()`

. Note: This keyword is relevant*only*on the CPU.

`Oceananigans.Solvers.PreconditionedConjugateGradientSolver`

— Method```
PreconditionedConjugateGradientSolver(linear_operation;
template_field,
maxiter = size(template_field.grid),
reltol = sqrt(eps(eltype(template_field.grid))),
abstol = 0,
preconditioner = nothing)
```

Returns a `PreconditionedConjugateGradientSolver`

that solves the linear equation $A x = b$ using a iterative conjugate gradient method with optional preconditioning.

The solver is used by calling

`solve!(x, solver::PreconditionedConjugateGradientOperator, b, args...)`

for `solver`

, right-hand side `b`

, solution `x`

, and optional arguments `args...`

.

**Arguments**

`linear_operation`

: Function with signature`linear_operation!(p, y, args...)`

that calculates`A * y`

and stores the result in`p`

for a "candidate solution"`y`

.`args...`

are optional positional arguments passed from`solve!(x, solver, b, args...)`

.`template_field`

: Dummy field that is the same type and size as`x`

and`b`

, which is used to infer the`architecture`

,`grid`

, and to create work arrays that are used internally by the solver.`maxiter`

: Maximum number of iterations the solver may perform before exiting.`reltol, abstol`

: Relative and absolute tolerance for convergence of the algorithm. The iteration stops when`norm(A * x - b) < tolerance`

.`preconditioner`

: Object for which`precondition!(z, preconditioner, r, args...)`

computes`z = P * r`

, where`r`

is the residual. Typically`P`

is approximately`A⁻¹`

.

See `solve!`

for more information about the preconditioned conjugate-gradient algorithm.

`Oceananigans.Solvers.solve!`

— Function`solve!(ϕ, solver::FFTBasedPoissonSolver, b, m=0)`

Solves the "generalized" Poisson equation,

\[(∇² + m) ϕ = b,\]

where $m$ is a number, using a eigenfunction expansion of the discrete Poisson operator on a staggered grid and for periodic or Neumann boundary conditions.

In-place transforms are applied to $b$, which means $b$ must have complex-valued elements (typically the same type as `solver.storage`

).

Equation $(∇² + m) ϕ = b$ is sometimes referred to as the "screened Poisson" equation when $m < 0$, or the Helmholtz equation when $m > 0$.

`Oceananigans.Solvers.solve!`

— Method`solve!(ϕ, solver::BatchedTridiagonalSolver, rhs, args...; dependencies = device_event(solver.architecture))`

Solve the batched tridiagonal system of linear equations with right hand side `rhs`

and lower diagonal, diagonal, and upper diagonal coefficients described by the `BatchedTridiagonalSolver`

`solver`

. `BatchedTridiagonalSolver`

uses a modified TriDiagonal Matrix Algorithm (TDMA).

The result is stored in `ϕ`

which must have size `(grid.Nx, grid.Ny, grid.Nz)`

.

Reference implementation per Numerical Recipes, Press et. al 1992 (§ 2.4).

`Oceananigans.Solvers.solve!`

— Method`solve!(x, solver::MultigridSolver, b; kwargs...)`

Solve `A * x = b`

using a multigrid method, where `A`

is `solver.matrix`

.

`Oceananigans.Solvers.solve!`

— Method`solve!(x, solver::PreconditionedConjugateGradientSolver, b, args...)`

Solve `A * x = b`

using an iterative conjugate-gradient method, where `A * x`

is determined by `solver.linear_operation`

See figure 2.5 in

The Preconditioned Conjugate Gradient Method in "Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods" Barrett et. al, 2nd Edition.

Given:

- Linear Preconditioner operator
`M!(solution, x, other_args...)`

that computes`M * x = solution`

- A matrix operator
`A`

as a function`A()`

; - A dot product function
`norm()`

; - A right-hand side
`b`

; - An initial guess
`x`

; and - Local vectors:
`z`

,`r`

,`p`

,`q`

This function executes the psuedocode algorithm

```
β = 0
r = b - A(x)
iteration = 0
Loop:
if iteration > maxiter
break
end
ρ = r ⋅ z
z = M(r)
β = ρⁱ⁻¹ / ρ
p = z + β * p
q = A(p)
α = ρ / (p ⋅ q)
x = x + α * p
r = r - α * q
if |r| < tolerance
break
end
iteration += 1
ρⁱ⁻¹ = ρ
```

## Stokes drift

`Oceananigans.StokesDrift.UniformStokesDrift`

— Type`UniformStokesDrift{UZ, VZ, UT, VT} <: AbstractStokesDrift`

Parameter struct for Stokes drift fields associated with surface waves.

`Oceananigans.StokesDrift.UniformStokesDrift`

— Method`UniformStokesDrift(; ∂z_uˢ=addzero, ∂z_vˢ=addzero, ∂t_uˢ=addzero, ∂t_vˢ=addzero)`

Construct a set of functions that describes the Stokes drift field beneath a uniform surface gravity wave field.

## Time steppers

`Oceananigans.TimeSteppers.Clock`

— Type`mutable struct Clock{T<:Number}`

Keeps track of the current `time`

, `iteration`

number, and time-stepping `stage`

. The `stage`

is updated only for multi-stage time-stepping methods. The `time::T`

is either a number or a `DateTime`

object.

`Oceananigans.TimeSteppers.Clock`

— Method`Clock(; time, iteration=0, stage=1)`

Returns a `Clock`

object. By default, `Clock`

is initialized to the zeroth `iteration`

and first time step `stage`

.

`Oceananigans.TimeSteppers.QuasiAdamsBashforth2TimeStepper`

— Method```
QuasiAdamsBashforth2TimeStepper(grid, tracers,
χ = 0.1;
implicit_solver = nothing,
Gⁿ = TendencyFields(grid, tracers),
G⁻ = TendencyFields(grid, tracers))
```

Return a 2nd-order quasi Adams-Bashforth (AB2) time stepper (`QuasiAdamsBashforth2TimeStepper`

) on `grid`

, with `tracers`

, and AB2 parameter `χ`

. The tendency fields `Gⁿ`

and `G⁻`

can be specified via optional `kwargs`

.

The 2nd-order quasi Adams-Bashforth timestepper steps forward the state `Uⁿ`

by `Δt`

via

`Uⁿ⁺¹ = Uⁿ + Δt * [(3/2 + χ) * Gⁿ - (1/2 + χ) * Gⁿ⁻¹]`

where `Uⁿ`

is the state at the $n$-th timestep, `Gⁿ`

is the tendency at the $n$-th timestep, and `Gⁿ⁻¹`

is the tendency at the previous timestep (`G⁻`

).

For the first timestep, since there are no saved tendencies from the previous timestep, the `QuasiAdamsBashforth2TimeStepper`

performs an Euler timestep:

`Uⁿ⁺¹ = Uⁿ + Δt * Gⁿ`

`Oceananigans.TimeSteppers.RungeKutta3TimeStepper`

— Type`RungeKutta3TimeStepper{FT, TG} <: AbstractTimeStepper`

Holds parameters and tendency fields for a low storage, third-order Runge-Kutta-Wray time-stepping scheme described by Le and Moin (1991).

`Oceananigans.TimeSteppers.RungeKutta3TimeStepper`

— Method```
RungeKutta3TimeStepper(grid, tracers;
implicit_solver = nothing,
Gⁿ = TendencyFields(grid, tracers),
G⁻ = TendencyFields(grid, tracers))
```

Return a 3rd-order Runge0Kutta timestepper (`RungeKutta3TimeStepper`

) on `grid`

and with `tracers`

. The tendency fields `Gⁿ`

and `G⁻`

can be specified via optional `kwargs`

.

The scheme described by Le and Moin (1991) (see H. Le, P. Moin (1991)). In a nutshel, the 3rd-order Runge Kutta timestepper steps forward the state `Uⁿ`

by `Δt`

via 3 substeps. A pressure correction step is applied after at each substep.

The state `U`

after each substep `m`

is

`Uᵐ⁺¹ = Uᵐ + Δt * (γᵐ * Gᵐ + ζᵐ * Gᵐ⁻¹)`

where `Uᵐ`

is the state at the $m$-th substep, `Gᵐ`

is the tendency at the $m$-th substep, `Gᵐ⁻¹`

is the tendency at the previous substep, and constants $γ¹ = 8/15$, $γ² = 5/12$, $γ³ = 3/4$, $ζ¹ = 0$, $ζ² = -17/60$, $ζ³ = -5/12$.

The state at the first substep is taken to be the one that corresponds to the $n$-th timestep, `U¹ = Uⁿ`

, and the state after the third substep is then the state at the `Uⁿ⁺¹ = U⁴`

.

`Oceananigans.TimeSteppers.time_step!`

— Method`time_step!(model::AbstractModel{<:QuasiAdamsBashforth2TimeStepper}, Δt; euler=false)`

Step forward `model`

one time step `Δt`

with a 2nd-order Adams-Bashforth method and pressure-correction substep. Setting `euler=true`

will take a forward Euler time step.

`Oceananigans.TimeSteppers.time_step!`

— Method`time_step!(model::AbstractModel{<:RungeKutta3TimeStepper}, Δt)`

Step forward `model`

one time step `Δt`

with a 3rd-order Runge-Kutta method. The 3rd-order Runge-Kutta method takes three intermediate substep stages to achieve a single timestep. A pressure correction step is applied at each intermediate stage.

## Turbulence closures

`Oceananigans.TurbulenceClosures.AnisotropicMinimumDissipation`

— Type`AnisotropicMinimumDissipation{FT} <: AbstractTurbulenceClosure`

Parameters for the "anisotropic minimum dissipation" turbulence closure for large eddy simulation proposed originally by Wybe Rozema, Hyun J. Bae, Parviz Moin, Roel Verstappen (2015) and Mahdi Abkar, Hyun J. Bae, Parviz Moin (2016), then modified by Roel Verstappen (2018), and finally described and validated for by Catherine A. Vreugdenhil, John R. Taylor (2018).

`Oceananigans.TurbulenceClosures.AnisotropicMinimumDissipation`

— Method```
AnisotropicMinimumDissipation([time_discretization = ExplicitTimeDiscretization, FT = Float64;]
C = 1/12, Cν = nothing, Cκ = nothing, Cb = nothing)
```

Return parameters of type `FT`

for the `AnisotropicMinimumDissipation`

turbulence closure.

**Keyword arguments**

`C`

: Poincaré constant for both eddy viscosity and eddy diffusivities.`C`

is overridden for eddy viscosity or eddy diffusivity if`Cν`

or`Cκ`

are set, respecitvely.`Cν`

: Poincaré constant for momentum eddy viscosity.`Cκ`

: Poincaré constant for tracer eddy diffusivities. If one number or function, the same number or function is applied to all tracers. If a`NamedTuple`

, it must possess a field specifying the Poncaré constant for every tracer.`Cb`

: Buoyancy modification multiplier (`Cb = nothing`

turns it off,`Cb = 1`

was used by Mahdi Abkar, Hyun J. Bae, Parviz Moin (2016)).*Note*: that we*do not*subtract the horizontally-average component before computing this buoyancy modification term. This implementation differs from Mahdi Abkar, Hyun J. Bae, Parviz Moin (2016)'s proposal and the impact of this approximation has not been tested or validated.`time_discretization`

: Either`ExplicitTimeDiscretization()`

or`VerticallyImplicitTimeDiscretization()`

, which integrates the terms involving only z-derivatives in the viscous and diffusive fluxes with an implicit time discretization.

By default: `C = Cν = Cκ`

= 1/12, which is appropriate for a finite-volume method employing a second-order advection scheme, `Cb = nothing`

, which terms off the buoyancy modification term.

`Cν`

or `Cκ`

may be constant numbers, or functions of `x, y, z`

.

**Examples**

```
julia> using Oceananigans
julia> pretty_diffusive_closure = AnisotropicMinimumDissipation(C=1/2)
AnisotropicMinimumDissipation{ExplicitTimeDiscretization} turbulence closure with:
Poincaré constant for momentum eddy viscosity Cν: 0.5
Poincaré constant for tracer(s) eddy diffusivit(ies) Cκ: 0.5
Buoyancy modification multiplier Cb: nothing
```

```
julia> using Oceananigans
julia> const Δz = 0.5; # grid resolution at surface
julia> surface_enhanced_tracer_C(x, y, z) = 1/12 * (1 + exp((z + Δz/2) / 8Δz));
julia> fancy_closure = AnisotropicMinimumDissipation(Cκ=surface_enhanced_tracer_C)
AnisotropicMinimumDissipation{ExplicitTimeDiscretization} turbulence closure with:
Poincaré constant for momentum eddy viscosity Cν: 0.08333333333333333
Poincaré constant for tracer(s) eddy diffusivit(ies) Cκ: surface_enhanced_tracer_C
Buoyancy modification multiplier Cb: nothing
```

```
julia> using Oceananigans
julia> tracer_specific_closure = AnisotropicMinimumDissipation(Cκ=(c₁=1/12, c₂=1/6))
AnisotropicMinimumDissipation{ExplicitTimeDiscretization} turbulence closure with:
Poincaré constant for momentum eddy viscosity Cν: 0.08333333333333333
Poincaré constant for tracer(s) eddy diffusivit(ies) Cκ: (c₁ = 0.08333333333333333, c₂ = 0.16666666666666666)
Buoyancy modification multiplier Cb: nothing
```

**References**

Vreugdenhil C., and Taylor J. (2018), "Large-eddy simulations of stratified plane Couette flow using the anisotropic minimum-dissipation model", Physics of Fluids 30, 085104.

Verstappen, R. (2018), "How much eddy dissipation is needed to counterbalance the nonlinear production of small, unresolved scales in a large-eddy simulation of turbulence?", Computers & Fluids 176, pp. 276-284.

`Oceananigans.TurbulenceClosures.ConvectiveAdjustmentVerticalDiffusivity`

— Type```
ConvectiveAdjustmentVerticalDiffusivity([time_discretization = VerticallyImplicitTimeDiscretization(), FT=Float64;]
convective_κz = 0,
convective_νz = 0,
background_κz = 0,
background_νz = 0)
```

Return a convective adjustment vertical diffusivity closure that applies different values of diffusivity and/or viscosity depending whether the region is statically stable (positive or zero buoyancy gradient) or statically unstable (negative buoyancy gradient).

**Arguments**

`time_discretization`

: Either`ExplicitTimeDiscretization()`

or`VerticallyImplicitTimeDiscretization()`

; default`VerticallyImplicitTimeDiscretization()`

.`FT`

: Float type; default`Float64`

.

**Keyword arguments**

`convective_κz`

: Vertical tracer diffusivity in regions with negative (unstable) buoyancy gradients. Either a single number, function, array, field, or tuple of diffusivities for each tracer.`background_κz`

: Vertical tracer diffusivity in regions with zero or positive (stable) buoyancy gradients.`convective_νz`

: Vertical viscosity in regions with negative (unstable) buoyancy gradients. Either a number, function, array, or field.`background_κz`

: Vertical viscosity in regions with zero or positive (stable) buoyancy gradients.

**Example**

```
julia> using Oceananigans
julia> cavd = ConvectiveAdjustmentVerticalDiffusivity(convective_κz = 1)
ConvectiveAdjustmentVerticalDiffusivity{VerticallyImplicitTimeDiscretization}(background_κz=0.0 convective_κz=1 background_νz=0.0 convective_νz=0.0)
```

`Oceananigans.TurbulenceClosures.ExplicitTimeDiscretization`

— Type`struct ExplicitTimeDiscretization <: AbstractTimeDiscretization`

A fully-explicit time-discretization of a `TurbulenceClosure`

.

`Oceananigans.TurbulenceClosures.HorizontalDivergenceScalarDiffusivity`

— Type```
HorizontalDivergenceScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
FT::DataType=Float64;]
kwargs...)
```

Shorthand for a `ScalarDiffusivity`

with `HorizontalDivergenceFormulation()`

. See `ScalarDiffusivity`

.

`Oceananigans.TurbulenceClosures.HorizontalScalarDiffusivity`

— Type```
HorizontalScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
FT::DataType=Float64;]
kwargs...)
```

Shorthand for a `ScalarDiffusivity`

with `HorizontalFormulation()`

. See `ScalarDiffusivity`

.

`Oceananigans.TurbulenceClosures.IsopycnalSkewSymmetricDiffusivity`

— Method```
IsopycnalSkewSymmetricDiffusivity([time_disc=VerticallyImplicitTimeDiscretization(), FT=Float64;]
κ_skew = 0,
κ_symmetric = 0,
isopycnal_tensor = SmallSlopeIsopycnalTensor(),
slope_limiter = FluxTapering(1e-2))
```

Return parameters for an isopycnal skew-symmetric tracer diffusivity with skew diffusivity `κ_skew`

and symmetric diffusivity `κ_symmetric`

that uses an `isopycnal_tensor`

model for for calculating the isopycnal slopes, and (optionally) applying a `slope_limiter`

to the calculated isopycnal slope values.

Both `κ_skew`

and `κ_symmetric`

may be constants, arrays, fields, or functions of `(x, y, z, t)`

.

`Oceananigans.TurbulenceClosures.RiBasedVerticalDiffusivity`

— Type```
RiBasedVerticalDiffusivity([time_discretization = VerticallyImplicitTimeDiscretization(),
FT = Float64;]
Ri_dependent_tapering = ExponentialRiDependentTapering(),
ν₀ = 0.30,
κ₀ = 0.42,
κᶜ = 4.0,
Cᵉ = 0.57,
Ri₀ = 0.27,
Riᵟ = 0.20,
warning = true)
```

Return a closure that estimates the vertical viscosity and diffusivit from "convective adjustment" coefficients `ν₀`

and `κ₀`

multiplied by a decreasing function of the Richardson number, $Ri$.

**Keyword Arguments**

`Ri_dependent_tapering`

: The $Ri$-dependent tapering. Options are:`PiecewiseLinearRiDependentTapering()`

,`HyperbolicTangentRiDependentTapering()`

(default), and`ExponentialRiDependentTapering()`

.`ν₀`

: Non-convective viscosity.`κ₀`

: Non-convective diffusivity for tracers.`κᶜ`

: Convective adjustment diffusivity for tracers.`Cᵉ`

: Entrainment coefficient for tracers.`Ri₀`

: $Ri$ threshold for decreasing viscosity and diffusivity.`Riᵟ`

: $Ri$-width over which viscosity and diffusivity decreases to 0.

`Oceananigans.TurbulenceClosures.ScalarBiharmonicDiffusivity`

— Type```
ScalarBiharmonicDiffusivity([formulation=ThreeDimensionalFormulation(), FT=Float64;]
ν=0, κ=0,
discrete_form = false)
```

Return a scalar biharmonic diffusivity turbulence closure with viscosity coefficient `ν`

and tracer diffusivities `κ`

for each tracer field in `tracers`

. If a single `κ`

is provided, it is applied to all tracers. Otherwise `κ`

must be a `NamedTuple`

with values for every tracer individually.

**Arguments**

`formulation`

:`HorizontalFormulation()`

for diffusivity applied in the horizontal direction(s)`VerticalFormulation()`

for diffusivity applied in the vertical direction,`ThreeDimensionalFormulation()`

(default) for diffusivity applied isotropically to all directions

`FT`

: the float datatype (default:`Float64`

)

**Keyword arguments**

`ν`

: Viscosity.`Number`

,`AbstractArray`

, or`Function(x, y, z, t)`

.`κ`

: Diffusivity.`Number`

,`AbstractArray`

, or`Function(x, y, z, t)`

, or`NamedTuple`

of diffusivities with entries for each tracer.`discrete_form`

:`Boolean`

.

`Oceananigans.TurbulenceClosures.ScalarBiharmonicDiffusivity`

— Type`struct ScalarBiharmonicDiffusivity{F, N, K} <: AbstractScalarBiharmonicDiffusivity{F}`

Holds viscosity and diffusivities for models with prescribed isotropic diffusivities.

`Oceananigans.TurbulenceClosures.ScalarDiffusivity`

— Type```
ScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
formulation=ThreeDimensionalFormulation(), FT=Float64];
ν=0, κ=0,
discrete_form = false)
```

Return `ScalarDiffusivity`

turbulence closure with viscosity `ν`

and tracer diffusivities `κ`

for each tracer field in `tracers`

. If a single `κ`

is provided, it is applied to all tracers. Otherwise `κ`

must be a `NamedTuple`

with values for every tracer individually.

**Arguments**

`time_discretization`

: either`ExplicitTimeDiscretization()`

(default) or`VerticallyImplicitTimeDiscretization()`

.`formulation`

:`HorizontalFormulation()`

for diffusivity applied in the horizontal direction(s)`VerticalFormulation()`

for diffusivity applied in the vertical direction,`ThreeDimensionalFormulation()`

(default) for diffusivity applied isotropically to all directions

`FT`

: the float datatype (default:`Float64`

)

**Keyword arguments**

`ν`

and the fields of `κ`

may be constants (converted to `FT`

), arrays, fields or

- functions of
`(x, y, z, t)`

if`discrete_form = false`

- functions of
`(i, j, k, grid, LX, LY, LZ)`

with`LX`

,`LY`

and`LZ`

are either`Face()`

or`Center()`

if`discrete_form = true`

.

`Oceananigans.TurbulenceClosures.SmagorinskyLilly`

— Method`SmagorinskyLilly(time_discretization = ExplicitTimeDiscretization, [FT=Float64;] C=0.16, Pr=1)`

Return a `SmagorinskyLilly`

type associated with the turbulence closure proposed by Lilly (1962) and Smagorinsky (1958, 1963), which has an eddy viscosity of the form

`νₑ = (C * Δᶠ)² * √(2Σ²) * √(1 - Cb * N² / Σ²)`

and an eddy diffusivity of the form

`κₑ = νₑ / Pr`

where `Δᶠ`

is the filter width, `Σ² = ΣᵢⱼΣᵢⱼ`

is the double dot product of the strain tensor `Σᵢⱼ`

, `Pr`

is the turbulent Prandtl number, and `N²`

is the total buoyancy gradient, and `Cb`

is a constant the multiplies the Richardson number modification to the eddy viscosity.

**Keyword arguments**

`C`

: Smagorinsky constant. Default value is 0.16 as obtained by Lilly (1966).`Cb`

: Buoyancy term multipler based on Lilly (1962) (`Cb = 0`

turns it off,`Cb ≠ 0`

turns it on. Typically, and according to the original work by Lilly (1962),`Cb=1/Pr`

.)`Pr`

: Turbulent Prandtl numbers for each tracer. Either a constant applied to every tracer, or a`NamedTuple`

with fields for each tracer individually.`time_discretization`

: Either`ExplicitTimeDiscretization()`

or`VerticallyImplicitTimeDiscretization()`

, which integrates the terms involving only $z$-derivatives in the viscous and diffusive fluxes with an implicit time discretization.

**References**

Smagorinsky, J. "On the numerical integration of the primitive equations of motion for baroclinic flow in a closed region." Monthly Weather Review (1958)

Lilly, D. K. "On the numerical simulation of buoyant convection." Tellus (1962)

Smagorinsky, J. "General circulation experiments with the primitive equations: I. The basic experiment." Monthly weather review (1963)

Lilly, D. K. "The representation of small-scale turbulence in numerical simulation experiments." NCAR Manuscript No. 281, 0, 1966.

`Oceananigans.TurbulenceClosures.TwoDimensionalLeith`

— Type```
TwoDimensionalLeith(FT=Float64;
C=0.3, C_Redi=1, C_GM=1,
isopycnal_model=SmallSlopeIsopycnalTensor())
```

Return a `TwoDimensionalLeith`

type associated with the turbulence closure proposed by Leith (1965) and Fox-Kemper & Menemenlis (2008) which has an eddy viscosity of the form

`νₑ = (C * Δᶠ)³ * √(|∇ₕ ζ|² + |∇ₕ ∂w/∂z|²)`

and an eddy diffusivity of the form...

where `Δᶠ`

is the filter width, `ζ = ∂v/∂x - ∂u/∂y`

is the vertical vorticity, and `C`

is a model constant.

**Keyword arguments**

`C`

: Model constant`C_Redi`

: Coefficient for down-gradient tracer diffusivity for each tracer. Either a constant applied to every tracer, or a`NamedTuple`

with fields for each tracer individually.`C_GM`

: Coefficient for down-gradient tracer diffusivity for each tracer. Either a constant applied to every tracer, or a`NamedTuple`

with fields for each tracer individually.

**References**

Leith, C. E. (1968). "Diffusion Approximation for Two‐Dimensional Turbulence", The Physics of Fluids 11, 671. doi: 10.1063/1.1691968

Fox‐Kemper, B., & D. Menemenlis (2008), "Can large eddy simulation techniques improve mesoscale rich ocean models?", in Ocean Modeling in an Eddying Regime, Geophys. Monogr. Ser., vol. 177, pp. 319–337. doi: 10.1029/177GM19

Pearson, B. et al. (2017) , "Evaluation of scale-aware subgrid mesoscale eddy models in a global eddy rich model", Ocean Modelling 115, 42-58. doi: 10.1016/j.ocemod.2017.05.007

`Oceananigans.TurbulenceClosures.VerticalScalarDiffusivity`

— Type```
VerticalScalarDiffusivity([time_discretization=ExplicitTimeDiscretization(),
FT::DataType=Float64;]
kwargs...)
```

Shorthand for a `ScalarDiffusivity`

with `VerticalFormulation()`

. See `ScalarDiffusivity`

.

`Oceananigans.TurbulenceClosures.VerticallyImplicitTimeDiscretization`

— Type`struct VerticallyImplicitTimeDiscretization <: AbstractTimeDiscretization`

A vertically-implicit time-discretization of a `TurbulenceClosure`

.

This implies that a flux divergence such as $𝛁 ⋅ q$ at the n-th timestep is time-discretized as

`[∇ ⋅ q]ⁿ = [explicit_flux_divergence]ⁿ + [∂z (κ ∂z c)]ⁿ⁺¹`

## Utilities

`Oceananigans.Utils.AndSchedule`

— Method`AndSchedule(schedules...)`

Return a schedule that actuates when all `child_schedule`

s actuate.

`Oceananigans.Utils.IterationInterval`

— Method`IterationInterval(interval; offset=0)`

Return a callable `IterationInterval`

that "actuates" (schedules output or callback execution) whenever the model iteration (modified by `offset`

) is a multiple of `interval`

.

For example,

`IterationInterval(100)`

actuates at iterations`[100, 200, 300, ...]`

.`IterationInterval(100, offset=-1)`

actuates at iterations`[99, 199, 299, ...]`

.

`Oceananigans.Utils.OrSchedule`

— Method`OrSchedule(schedules...)`

Return a schedule that actuates when any of the `child_schedule`

s actuates.

`Oceananigans.Utils.SpecifiedTimes`

— Method`SpecifiedTimes(times)`

Return a callable `TimeInterval`

that "actuates" (schedules output or callback execution) whenever the model's clock equals the specified values in `times`

. For example,

`SpecifiedTimes([1, 15.3])`

actuates when`model.clock.time`

is`1`

and`15.3`

.

The specified `times`

need not be ordered as the `SpecifiedTimes`

constructor will check and order them in ascending order if needed.

`Oceananigans.Utils.TimeInterval`

— Type`struct TimeInterval <: AbstractSchedule`

Callable `TimeInterval`

schedule for periodic output or diagnostic evaluation according to `model.clock.time`

.

`Oceananigans.Utils.TimeInterval`

— Method`TimeInterval(interval)`

Return a callable `TimeInterval`

that schedules periodic output or diagnostic evaluation on a `interval`

of simulation time, as kept by `model.clock`

.

`Oceananigans.Utils.WallTimeInterval`

— Method`WallTimeInterval(interval; start_time = time_ns() * 1e-9)`

Return a callable `WallTimeInterval`

that schedules periodic output or diagnostic evaluation on a `interval`

of "wall time" while a simulation runs, in units of seconds.

The "wall time" is the actual real world time in seconds, as kept by an actual or hypothetical clock hanging on your wall.

The keyword argument `start_time`

can be used to specify a starting wall time other than the moment `WallTimeInterval`

is constructed.

`Oceananigans.Utils.cell_advection_timescale`

— MethodReturns the time-scale for advection on a regular grid across a single grid cell.

`Oceananigans.Utils.launch!`

— Method`launch!(arch, grid, layout, kernel!, args...; dependencies=nothing, kwargs...)`

Launches `kernel!`

, with arguments `args`

and keyword arguments `kwargs`

, over the `dims`

of `grid`

on the architecture `arch`

.

Returns an `event`

token associated with the `kernel!`

launch.

The keyword argument `dependencies`

is an `Event`

or `MultiEvent`

specifying prior kernels that must complete before `kernel!`

is launched.

`Oceananigans.Utils.pretty_filesize`

— Function`pretty_filesize(s, suffix="B")`

Convert a floating point value `s`

representing a file size to a more human-friendly formatted string with one decimal places with a `suffix`

defaulting to "B". Depending on the value of `s`

the string will be formatted to show `s`

using an SI prefix from bytes, kiB (1024 bytes), MiB (1024² bytes), and so on up to YiB (1024⁸ bytes).

`Oceananigans.Utils.prettytime`

— Function`prettytime(t, longform=true)`

Convert a floating point value `t`

representing an amount of time in SI units of seconds to a human-friendly string with three decimal places. Depending on the value of `t`

the string will be formatted to show `t`

in nanoseconds (ns), microseconds (μs), milliseconds (ms), seconds, minutes, hours, days, or years.

With `longform=false`

, we use s, m, hrs, d, and yrs in place of seconds, minutes, hours, and years.

`Oceananigans.Utils.with_tracers`

— Method`with_tracers(tracer_names, initial_tuple, tracer_default)`

Create a tuple corresponding to the solution variables `u`

, `v`

, `w`

, and `tracer_names`

. `initial_tuple`

is a `NamedTuple`

that at least has fields `u`

, `v`

, and `w`

, and may have some fields corresponding to the names in `tracer_names`

. `tracer_default`

is a function that produces a default tuple value for each tracer if not included in `initial_tuple`

.

`Oceananigans.Utils.work_layout`

— Method`work_layout(grid, dims; include_right_boundaries=false, location=nothing)`

Returns the `workgroup`

and `worksize`

for launching a kernel over `dims`

on `grid`

. The `workgroup`

is a tuple specifying the threads per block in each dimension. The `worksize`

specifies the range of the loop in each dimension.

Specifying `include_right_boundaries=true`

will ensure the work layout includes the right face end points along bounded dimensions. This requires the field `location`

to be specified.

For more information, see: https://github.com/CliMA/Oceananigans.jl/pull/308

`Oceananigans.Utils.@apply_regionally`

— Macro`@apply_regionally expr`

Use `@apply_regionally`

to distribute locally the function calls. Call `compute_regionally`

in case of a returning value and `apply_regionally!`

in case of no return.

## Units

`Oceananigans.Units.GiB`

— Constant`GiB`

A `Float64`

constant equal to 1024`MiB`

. Useful for increasing the clarity of scripts, e.g. `max_filesize = 50GiB`

.

`Oceananigans.Units.KiB`

— Constant`KiB`

A `Float64`

constant equal to 1024.0. Useful for increasing the clarity of scripts, e.g. `max_filesize = 250KiB`

.

`Oceananigans.Units.MiB`

— Constant`MiB`

A `Float64`

constant equal to 1024`KiB`

. Useful for increasing the clarity of scripts, e.g. `max_filesize = 100MiB`

.

`Oceananigans.Units.TiB`

— Constant`TiB`

A `Float64`

constant equal to 1024`GiB`

. Useful for increasing the clarity of scripts, e.g. `max_filesize = 2TiB`

.

`Oceananigans.Units.day`

— Constant`day`

A `Float64`

constant equal to 24`hours`

. Useful for increasing the clarity of scripts, e.g. `stop_time = 1day`

.

`Oceananigans.Units.days`

— Constant`days`

A `Float64`

constant equal to 24`hours`

. Useful for increasing the clarity of scripts, e.g. `stop_time = 7days`

.

`Oceananigans.Units.hour`

— Constant`hour`

A `Float64`

constant equal to 60`minutes`

. Useful for increasing the clarity of scripts, e.g. `Δt = 1hour`

.

`Oceananigans.Units.hours`

— Constant`hours`

A `Float64`

constant equal to 60`minutes`

. Useful for increasing the clarity of scripts, e.g. `Δt = 3hours`

.

`Oceananigans.Units.kilometer`

— Constant`kilometer`

A `Float64`

constant equal to 1000`meters`

. Useful for increasing the clarity of scripts, e.g. `Lx = 1kilometer`

.

`Oceananigans.Units.kilometers`

— Constant`kilometers`

A `Float64`

constant equal to 1000`meters`

. Useful for increasing the clarity of scripts, e.g. `Lx = 5000kilometers`

.

`Oceananigans.Units.meter`

— Constant`meter`

A `Float64`

constant equal to 1.0. Useful for increasing the clarity of scripts, e.g. `Lx = 1meter`

.

`Oceananigans.Units.meters`

— Constant`meters`

A `Float64`

constant equal to 1.0. Useful for increasing the clarity of scripts, e.g. `Lx = 50meters`

.

`Oceananigans.Units.minute`

— Constant`minute`

A `Float64`

constant equal to 60`seconds`

. Useful for increasing the clarity of scripts, e.g. `Δt = 1minute`

.

`Oceananigans.Units.minutes`

— Constant`minutes`

A `Float64`

constant equal to 60`seconds`

. Useful for increasing the clarity of scripts, e.g. `Δt = 15minutes`

.

`Oceananigans.Units.second`

— Constant`second`

A `Float64`

constant equal to 1.0. Useful for increasing the clarity of scripts, e.g. `Δt = 1second`

.

`Oceananigans.Units.seconds`

— Constant`seconds`

A `Float64`

constant equal to 1.0. Useful for increasing the clarity of scripts, e.g. `Δt = 7seconds`

.

`Oceananigans.Units.year`

— Constant`year`

A `Float64`

constant equal to 365`days`

. Useful for increasing the clarity of scripts, e.g. `stop_time = 1year`

.

`Oceananigans.Units.years`

— Constant`years`

A `Float64`

constant equal to 365`days`

. Useful for increasing the clarity of scripts, e.g. `stop_time = 100years`

.