Boundary conditions

A boundary condition is applied to each field, dimension, and endpoint. There are left and right boundary conditions for each of the x, y, and z dimensions so each field is associated with 6 boundary conditions. Each of these boundary conditions may be specified individually. Each boundary condition can be specified via a constant value, an array, or a function.

The left and right boundary conditions associated with the x-dimension are called west and east, respectively. For the y-dimension, left and right are called south and north. For the z-dimension, left and right are called bottom and top.

See Numerical implementation of boundary conditions for more details.

Types of boundary conditions

Notice that open boundary conditions and radiation boundary conditions can be imposed via flux or value boundary conditions defined by a function or array. Or alternatively, through a forcing function which is more flexible.

Default boundary conditions

By default, periodic boundary conditions are applied on all fields along periodic dimensions. Otherwise tracers get no-flux boundary conditions and velocities get free-slip and no-penetration boundary conditions.

Boundary condition structures

Oceananigans uses a hierarchical structure to expressing boundary conditions.

A BoundaryCondition is associated with every field, dimension, and endpoint.
Boundary conditions specifying the condition at the left and right endpoints are grouped into CoordinateBoundaryConditions.
A set of three CoordinateBoundaryConditions specifying the boundary conditions along the x, y, and z dimensions for a single field are grouped into a FieldBoundaryConditions named tuple.
A set of FieldBoundaryConditions, one for each field, are grouped together into a named tuple and passed to the Model constructor.

Boundary conditions are defined at model construction time by passing a named tuple of FieldBoundaryConditions specifying boundary conditions on every field: velocities ($u$, $v$, $w$) and all tracers.

See the sections below for more details. The examples and verification experiments also provide examples for setting up many different kinds of boundary conditions.

Creating individual boundary conditions

Some examples of creating individual boundary conditions:

A constant Value (Dirchlet) boundary condition, perhaps representing a constant temperature at some boundary.

constant_T_bc = ValueBoundaryCondition(20)

BoundaryCondition: type=Value, condition=20

A constant flux boundary condition, perhaps representing a constant wind stress at some boundary such as the ocean surface.

ρ₀ = 1027  # Reference density [kg/m³]
τₓ = 0.08  # Wind stress [N/m²]
wind_stress_bc = FluxBoundaryCondition(τₓ/ρ₀)

BoundaryCondition: type=Flux, condition=7.789678675754625e-5

A spatially varying (white noise) cooling flux to be imposed at some boundary. Note that the boundary condition is given by the array Q here. When running on the GPU, Q must be converted to a CuArray.

Nx = Ny = 16  # Number of grid points.

ρ₀ = 1027  # Reference density [kg/m³]
cₚ = 4000  # Heat capacity of water at constant pressure [J/kg/K]

Q  = randn(Nx, Ny) ./ (ρ₀ * cₚ)

white_noise_T_bc = FluxBoundaryCondition(Q)

BoundaryCondition: type=Flux, condition=[-3.935716202152894e-7 5.617693984184132e-8 1.9986258802118155e-7 -1.4452425113754395e-7 -6.309524126134682e-7 1.1451501128473791e-7 -1.04704285268474e-7 -1.9045965407675425e-7 9.17007466262568e-8 -3.398461339334809e-7 -1.891638939081068e-7 5.200412024463195e-8 1.1891539906864153e-7 4.148764422027395e-9 -1.1853662279444855e-7 -1.2909931967921814e-8; -2.98087791982917e-7 1.6367533415625151e-7 6.18537282531456e-9 -1.6243324427300583e-7 4.3401256681315274e-8 -2.102913824430969e-7 -2.9434600569467957e-8 -1.0686137743772435e-7 -2.273968127298443e-7 3.1489974684821914e-7 5.430811734886545e-7 -5.388685910810687e-7 -1.3630985616447431e-8 3.5921038210626806e-8 -4.00144552526296e-7 1.696406060613124e-7; 2.6356610137785284e-7 3.334860714900999e-7 2.0499126375445358e-7 -1.7493618961636028e-7 -6.736651919444873e-7 2.891319519355817e-7 1.0864981550535224e-7 -3.0419825282223024e-8 -1.298911073566572e-7 -1.6643898597488397e-7 7.561993210996562e-9 -4.753696310760619e-7 2.619633158419149e-7 3.2579514199573114e-7 -1.492444537331859e-9 -2.170654826764918e-7; 1.7751575822202786e-7 3.531793388829692e-7 -2.8783177570172113e-8 5.758212763766426e-8 2.388389387125149e-7 1.0134661780606028e-7 8.938651999837589e-8 -2.6342964767803386e-8 -1.981007593884524e-7 3.661786243951172e-7 -3.0197694071415786e-7 -2.3806628474536465e-7 1.6988507622909756e-7 2.3241919153627092e-7 -1.7998597353146517e-7 -1.0179987231196232e-7; 4.156684084667774e-9 -2.5592379923682024e-7 9.617555305278308e-8 8.963951551298989e-8 1.3754270717017093e-7 1.1701031781603699e-7 2.8581688047627584e-7 5.6301186461414874e-8 2.2989366177156798e-8 7.2553434346786395e-9 1.835653094087581e-8 -3.249862361093218e-7 2.588659948360146e-7 2.0081182722859857e-7 4.267730948740215e-8 -4.913106937584911e-7; -1.1470939634417509e-7 -2.984006402756354e-7 -2.114698053561401e-7 2.3856064371172286e-7 1.2904386962108045e-7 1.1224724861303086e-7 -5.2925997910538325e-8 4.060110267673039e-7 1.4812062545394878e-7 -5.095821390113698e-9 -3.494079878531566e-7 1.2361633233440675e-7 3.097443916962668e-8 -9.364089917414067e-9 4.288143400819122e-7 2.4879311848295376e-7; 1.708252032021404e-8 9.33644559918717e-9 -5.137738992939137e-7 5.084739110984746e-8 -1.70215118566552e-7 1.0657917789904007e-7 1.3583760486324618e-7 1.9613171284466233e-7 -3.754425951651586e-7 4.436272516481516e-7 -3.07251919741758e-7 8.229467016861012e-9 -1.7698270968303495e-7 -1.7555084069207926e-7 3.358952669383402e-8 1.4261093298385913e-7; -4.790164478333945e-8 2.3630057053921797e-7 4.534088007586709e-8 -1.4311322350085718e-7 -2.9343153097425634e-7 -2.940014650976793e-7 -1.1432832501577569e-7 -4.3260848974799545e-7 -1.9856264887209964e-7 2.099600501697684e-7 -1.1127589407519799e-7 -1.752797746014302e-7 1.4063417090643523e-7 -8.566037275579809e-8 -3.4625467228064015e-7 -2.545260955262818e-9; -2.6349732968528867e-8 -2.8448134581889295e-7 -4.5664766074496135e-8 -5.172874473776508e-7 -2.4806374666303753e-7 1.0733042101978144e-7 -3.617318086710949e-7 5.08363631134131e-7 -3.207488559199222e-7 8.879293835816398e-8 8.851341846762442e-8 5.2957470476036824e-8 2.4491605495915076e-7 4.667586384881376e-7 1.518479766382727e-9 2.0960581709136447e-7; -3.6488053439162267e-8 3.897852488001601e-7 -4.654405196796356e-8 -2.377578701457133e-8 1.6231480925819357e-7 -1.7794901554163043e-7 -1.5717265279004058e-7 4.5658193299954906e-7 -1.774213304017902e-7 -1.2434954374457032e-7 -1.744407468265951e-7 -1.5355265939230369e-7 3.1623052751201837e-7 1.4240583072866507e-7 2.0006502103005504e-7 3.020563204536203e-7; -9.061552328105436e-8 -1.0736008520276944e-7 -5.0458438922566755e-9 -8.051233938238175e-8 -5.650219698724112e-7 6.032469209508256e-8 1.0151619505815497e-7 2.3427433894175366e-7 2.829533498647762e-7 3.218630300424262e-7 1.648553799343411e-7 -1.1038011413594915e-7 1.7727814268854535e-7 -8.64008410459844e-8 -1.5782961360623464e-7 3.6572952166072137e-7; 2.805373272707013e-7 -9.98049883299526e-8 1.1079973697729302e-7 6.461239933784546e-8 1.1766086819763781e-7 1.3424799254996112e-7 2.6057572536235876e-7 2.211004577006648e-7 5.171723633119678e-7 -4.424144042816267e-7 6.683660352882233e-9 -2.204500865144239e-8 6.371456850599351e-8 1.3632430303872345e-7 -4.367603942940315e-8 -4.3615929532939295e-7; -4.3779140559786584e-7 1.5330092339775719e-7 -2.258702133268696e-7 1.8315394818461935e-7 -4.334118000098924e-8 -3.0724725847959737e-7 -2.964324924554959e-7 -2.126454570880971e-8 6.550281455915661e-8 -2.1388505785132913e-7 2.884443213943248e-9 1.831803100741167e-7 -2.469529678378213e-7 3.125350873071097e-7 -1.1889238553628346e-7 1.1844627885960422e-7; -1.7794643935426663e-7 -3.9751389916496726e-7 -7.996651497654167e-8 -2.899308184441005e-7 1.7577932747931109e-7 -5.883584908236237e-7 -3.4876754128446025e-8 -1.494470598639163e-7 -3.2039484945260356e-8 3.395410930427737e-7 2.987851670147363e-7 -1.2871957698347955e-7 -2.3710844731352786e-7 1.63865198265449e-7 1.0103924605778617e-8 -6.002906124456325e-8; -2.832648233590749e-7 -3.0559277223135547e-9 1.3778324631586097e-7 -1.1142154215716741e-7 -3.55206875123066e-7 -2.185949547163066e-7 -1.7808390182339716e-7 -9.154173006169128e-8 2.999490514298972e-8 -1.3603542712169146e-9 -9.929380877985463e-8 2.2656065536722336e-7 4.0827135689979585e-8 -3.860283120600278e-7 -3.6432938770595176e-7 -7.487249210357706e-8; 1.6793532551205904e-7 7.672061501247928e-8 -2.411716728542439e-7 4.009539666923278e-8 1.2568891561728089e-8 1.89143734761578e-7 9.484187431010537e-8 1.0081641316878406e-7 -3.116961463603353e-7 3.2493855667111347e-7 1.9804647320025994e-7 -3.6548865628367294e-8 1.1864840318682112e-7 2.237873539876927e-7 -3.372846350238488e-7 -1.1170522924685669e-7]

Specifying boundary conditions with functions

You can also specify the boundary condition via a function. For z boundary conditions the function will be called with the signature

f(i, j, grid, time, iteration, U, C, params)

where i, j is the grid index, grid is model.grid, time is the model.clock.time, iteration is the model.clock.iteration, U is the named tuple model.velocities, C is the named tuple C.tracers, and params is the user-defined model.parameters. The signature is similar for x and y boundary conditions expect that i, j is replaced with j, k and i, k respectively.

We can add a fourth example now:

A spatially varying and time-dependent heating representing perhaps a localized source of heating modulated by a diurnal cycle.

@inline Q(i, j, grid, t, I, U, C, params) = @inbounds exp(-(grid.xC[i]^2 + grid.yC[j]^2)) * sin(2π*t)
localized_heating_bc = FluxBoundaryCondition(Q)

BoundaryCondition: type=Flux, condition=Q

Performance of functions in boundary conditions

For performance reasons, you should define all functions used in boundary conditions as inline functions via the @inline macro. If any arrays are accessed within the function, disabling bounds-checking with @inbounds will also speed things up.

Specifying boundary conditions on a field

To, for example, create a set of horizontally periodic field boundary conditions

using Oceananigans # hide
topology = (Periodic, Periodic, Bounded)
grid = RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1), topology=topology)
T_bcs = TracerBoundaryConditions(grid,    top = ValueBoundaryCondition(20),
                                       bottom = GradientBoundaryCondition(0.01))

which will create a FieldBoundaryConditions object for temperature T appropriate for horizontally periodic model configurations where the x and y boundary conditions are all periodic.

Specifying model boundary conditions

A named tuple of FieldBoundaryConditions objects must be passed to the Model constructor specifying boundary conditions on all fields. To, for example, impose non-default boundary conditions on the u-velocity and temperature

using Oceananigans # hide
topology = (Periodic, Periodic, Bounded)
grid = RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1), topology=topology)

u_bcs = UVelocityBoundaryConditions(grid,   top = ValueBoundaryCondition(+0.1),
                                         bottom = ValueBoundaryCondition(-0.1))
T_bcs = TracerBoundaryConditions(grid,   top = ValueBoundaryCondition(20),
                                      bottom = GradientBoundaryCondition(0.01))

model_bcs = SolutionBoundaryConditions(u=u_bcs, T=T_bcs)

model = Model(grid=grid, boundary_conditions=model_bcs)
nothing # hide