(v0.85.0) Switching cells where fluxes are applied in `ImmersedBounda…

…ryCondition` to match `FieldBoundaryConditions`' kwargs (#3142) * test it out * Elaborate on ImmersedBoundaryCondition in the docs * Update docs/src/model_setup/boundary_conditions.md Co-authored-by: Tomas Chor <[email protected]> * added warning when using ImmersedBonudaryCOndition * Bump minor version (since this release is breaking for anyone using IBC) * add warnings to doctest * change warning --------- Co-authored-by: Gregory Wagner <[email protected]> Co-authored-by: Tomas Chor <[email protected]>
CliMA · Jul 11, 2023 · a1f4f4e · a1f4f4e · navidcy · Jul 11, 2023
1 parent 8634ef1
commit a1f4f4e
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 9 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Oceananigans"
 uuid = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 authors = ["Climate Modeling Alliance and contributors"]
-version = "0.84.1"
+version = "0.85.0"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

diff --git a/docs/src/model_setup/boundary_conditions.md b/docs/src/model_setup/boundary_conditions.md
@@ -434,7 +434,7 @@ top and bottom of both `model.velocities.u` and `model.tracers.c`.
 Immersed boundary conditions are supported experimentally. A no-slip boundary condition is specified
 with
 
-```jldoctest
+```jldoctest; filter = r".*@ Oceananigans.ImmersedBoundaries.*"
 julia> underlying_grid = RectilinearGrid(size=(32, 32, 16), x=(-3, 3), y=(-3, 3), z=(0, 1), topology=(Periodic, Periodic, Bounded));
 
 julia> hill(x, y) = 0.1 + 0.1 * exp(-x^2 - y^2)
@@ -451,6 +451,12 @@ julia> grid = ImmersedBoundaryGrid(underlying_grid, GridFittedBottom(hill))
 julia> velocity_bcs = FieldBoundaryConditions(immersed=ValueBoundaryCondition(0.0));
 
 julia> model = NonhydrostaticModel(; grid, boundary_conditions=(u=velocity_bcs, v=velocity_bcs, w=velocity_bcs));
+┌ Warning: `ImmersedBoundaryCondition` is experimental.
+└ @ Oceananigans.ImmersedBoundaries ~/repos/Oceananigans.jl3/src/ImmersedBoundaries/immersed_boundary_condition.jl:54
+┌ Warning: `ImmersedBoundaryCondition` is experimental.
+└ @ Oceananigans.ImmersedBoundaries ~/repos/Oceananigans.jl3/src/ImmersedBoundaries/immersed_boundary_condition.jl:54
+┌ Warning: `ImmersedBoundaryCondition` is experimental.
+└ @ Oceananigans.ImmersedBoundaries ~/repos/Oceananigans.jl3/src/ImmersedBoundaries/immersed_boundary_condition.jl:54
 
 julia> model.velocities.w.boundary_conditions.immersed
 ImmersedBoundaryCondition:
@@ -466,8 +472,10 @@ An `ImmersedBoundaryCondition` encapsulates boundary conditions on each potentia
 of a boundary-adjacent cell. Boundary conditions on specific faces of immersed-boundary-adjacent
 cells may also be specified by manually building an `ImmersedBoundaryCondition`:
 
-```jldoctest
+```jldoctest; filter = r".*@ Oceananigans.ImmersedBoundaries.*"
 julia> bottom_drag_bc = ImmersedBoundaryCondition(bottom=ValueBoundaryCondition(0.0))
+┌ Warning: `ImmersedBoundaryCondition` is experimental.
+└ @ Oceananigans.ImmersedBoundaries ~/repos/Oceananigans.jl3/src/ImmersedBoundaries/immersed_boundary_condition.jl:54
 ImmersedBoundaryCondition:
 ├── west: Nothing
 ├── east: Nothing
@@ -487,8 +495,18 @@ Oceananigans.FieldBoundaryConditions, with boundary conditions
 └── immersed: ImmersedBoundaryCondition with west=Nothing, east=Nothing, south=Nothing, north=Nothing, bottom=Value, top=Nothing
 ```
 
-A boundary condition that depends on the fields may be prescribed using the `immersed` keyword argument in [`FieldBoundaryConditions`](@ref).
-We illustrate field-dependent boundary conditions with an example that imposes linear bottom drag on `u` on both immersed facets _and_ the bottom boundary of the underlying grid.
+!!! warning "`ImmersedBoundaryCondition`"
+    `ImmersedBoundaryCondition` is experimental.
+    Therefore, one should use it only when a finer level of control over the boundary conditions
+    at the immersed boundary is required, and the user is familiar with the implementation of boundary 
+    conditions on staggered grids. For all other cases , using the `immersed` argument of
+    `FieldBoundaryConditions` is preferred.
+
+A boundary condition that depends on the fields may be prescribed using the `immersed`
+keyword argument in [`FieldBoundaryConditions`](@ref).
+We illustrate field-dependent boundary conditions with an example that imposes linear bottom drag
+on `u` on both the bottom facets of cells adjacent to an immersed boundary, _and_ the bottom boundary
+of the underlying grid.
 
 First we create the boundary condition for the grid's bottom:
 
@@ -500,16 +518,19 @@ julia> drag_u = FluxBoundaryCondition(linear_drag, field_dependencies=:u)
 FluxBoundaryCondition: ContinuousBoundaryFunction linear_drag at (Nothing, Nothing, Nothing)
 ```
 
-Next, we create the immersed boundary condition by adding the argument `z` to `linear_drag` and imposing drag only on "bottom" facets of the immersed boundary:
+Next, we create the immersed boundary condition by adding the argument `z` to `linear_drag`
+and imposing drag only on "bottom" facets of cells that neighbor immersed cells:
 
-```jldoctest immersed_bc
+```jldoctest immersed_bc; filter = r".*@ Oceananigans.ImmersedBoundaries.*"
 julia> @inline immersed_linear_drag(x, y, z, t, u) = - 0.2 * u
 immersed_linear_drag (generic function with 1 method)
 
 julia> immersed_drag_u = FluxBoundaryCondition(immersed_linear_drag, field_dependencies=:u)
 FluxBoundaryCondition: ContinuousBoundaryFunction immersed_linear_drag at (Nothing, Nothing, Nothing)
 
 julia> u_immersed_bc = ImmersedBoundaryCondition(bottom = immersed_drag_u)
+┌ Warning: `ImmersedBoundaryCondition` is experimental.
+└ @ Oceananigans.ImmersedBoundaries ~/repos/Oceananigans.jl3/src/ImmersedBoundaries/immersed_boundary_condition.jl:54
 ImmersedBoundaryCondition:
 ├── west: Nothing
 ├── east: Nothing

diff --git a/src/ImmersedBoundaries/immersed_boundary_condition.jl b/src/ImmersedBoundaries/immersed_boundary_condition.jl
@@ -51,6 +51,7 @@ function ImmersedBoundaryCondition(; west = nothing,
                                      bottom = nothing,
                                      top = nothing)
 
+    @warn "`ImmersedBoundaryCondition` is experimental."
     return ImmersedBoundaryCondition(west, east, south, north, bottom, top)
 end
 
@@ -197,8 +198,8 @@ end
     q̃ᴮ = bottom_ib_flux(i, j, k, ibg, bc.bottom, loc, c, closure, K, id, clock, fields)
     q̃ᵀ =    top_ib_flux(i, j, k, ibg, bc.top,    loc, c, closure, K, id, clock, fields)
 
-    iᵂ, jˢ, kᴮ = map(index_right, (i, j, k), loc) # Broadcast instead of map causes inference failure
-    iᴱ, jᴺ, kᵀ = map(index_left, (i, j, k), loc)
+    iᵂ, jˢ, kᴮ = map(index_left,  (i, j, k), loc) # Broadcast instead of map causes inference failure
+    iᴱ, jᴺ, kᵀ = map(index_right, (i, j, k), loc)
     LX, LY, LZ = loc
 
     # Impose i) immersed fluxes if we're on an immersed boundary or ii) zero otherwise.