From f462e9f0bacfe11e2a6caf0b0ad619cba496dee2 Mon Sep 17 00:00:00 2001
From: "Navid C. Constantinou" <navidcy@users.noreply.github.com>
Date: Thu, 14 Mar 2024 18:59:55 +0200
Subject: [PATCH] Enhance immersed boundary grid docs (#3505)

* enhance immersed boundary grid docs

* revert to ib

* revert to ib

* clearer GridFittedBottom docstring

* elaborate bit more on immersed_condition
---
 src/ImmersedBoundaries/grid_fitted_bottom.jl  | 36 +++++++++++++------
 .../grid_fitted_boundary.jl                   |  1 -
 .../immersed_boundary_condition.jl            |  6 ++--
 3 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/src/ImmersedBoundaries/grid_fitted_bottom.jl b/src/ImmersedBoundaries/grid_fitted_bottom.jl
index a3461ac16d..6e9db6bf7e 100644
--- a/src/ImmersedBoundaries/grid_fitted_bottom.jl
+++ b/src/ImmersedBoundaries/grid_fitted_bottom.jl
@@ -24,11 +24,6 @@ struct InterfaceImmersedCondition end
 Base.summary(::CenterImmersedCondition) = "CenterImmersedCondition"
 Base.summary(::InterfaceImmersedCondition) = "InterfaceImmersedCondition"
 
-"""
-    GridFittedBottom(bottom_height, [immersed_condition=CenterImmersedCondition()])
-
-Return an immersed boundary with an irregular bottom fit to the underlying grid.
-"""
 struct GridFittedBottom{H, I} <: AbstractGridFittedBottom{H}
     bottom_height :: H
     immersed_condition :: I
@@ -36,6 +31,27 @@ end
 
 const GFBIBG = ImmersedBoundaryGrid{<:Any, <:Any, <:Any, <:Any, <:Any, <:GridFittedBottom}
 
+"""
+    GridFittedBottom(bottom_height, [immersed_condition=CenterImmersedCondition()])
+
+Return a bottom immersed boundary.
+
+Keyword Arguments
+=================
+
+* `bottom_height`: an array or function that gives the height of the
+                   bottom in absolute ``z`` coordinates.
+
+* `immersed_condition`: Determine whether the part of the domain that is 
+                        immersed are all the cell centers that lie below
+                        `bottom_height` (`CenterImmersedCondition()`; default)
+                        or all the cell faces that lie below `bottom_height`
+                        (`InterfaceImmersedCondition()`). The only purpose of
+                        `immersed_condition` to allow `GridFittedBottom` and
+                        `PartialCellBottom` to have the same behavior when the
+                        minimum fractional cell height for partial cells is set
+                        to 0.
+"""
 GridFittedBottom(bottom_height) = GridFittedBottom(bottom_height, CenterImmersedCondition())
 
 function Base.summary(ib::GridFittedBottom)
@@ -65,9 +81,9 @@ end
 """
     ImmersedBoundaryGrid(grid, ib::GridFittedBottom)
 
-Return a grid with `GridFittedBottom` immersed boundary.
+Return a grid with `GridFittedBottom` immersed boundary (`ib`).
 
-Computes ib.bottom_height and wraps in an array.
+Computes `ib.bottom_height` and wraps it in a Field.
 """
 function ImmersedBoundaryGrid(grid, ib::GridFittedBottom)
     bottom_field = Field{Center, Center, Nothing}(grid)
@@ -81,16 +97,17 @@ end
 @inline function _immersed_cell(i, j, k, underlying_grid, ib::GridFittedBottom{<:Any, <:InterfaceImmersedCondition})
     z = znode(i, j, k+1, underlying_grid, c, c, f)
     h = @inbounds ib.bottom_height[i, j, 1]
-    return z <= h
+    return z ≤ h
 end
 
 @inline function _immersed_cell(i, j, k, underlying_grid, ib::GridFittedBottom{<:Any, <:CenterImmersedCondition})
     z = znode(i, j, k, underlying_grid, c, c, c)
     h = @inbounds ib.bottom_height[i, j, 1]
-    return z <= h
+    return z ≤ h
 end
 
 @inline z_bottom(i, j, ibg::GFBIBG) = @inbounds ibg.immersed_boundary.bottom_height[i, j, 1]
+
 on_architecture(arch, ib::GridFittedBottom) = GridFittedBottom(ib.bottom_height, ib.immersed_condition)
 
 function on_architecture(arch, ib::GridFittedBottom{<:Field})
@@ -104,4 +121,3 @@ end
 
 Adapt.adapt_structure(to, ib::GridFittedBottom) = GridFittedBottom(adapt(to, ib.bottom_height),
                                                                              ib.immersed_condition)
-
diff --git a/src/ImmersedBoundaries/grid_fitted_boundary.jl b/src/ImmersedBoundaries/grid_fitted_boundary.jl
index c66c8fcafc..2805a78e30 100644
--- a/src/ImmersedBoundaries/grid_fitted_boundary.jl
+++ b/src/ImmersedBoundaries/grid_fitted_boundary.jl
@@ -36,4 +36,3 @@ on_architecture(arch, ib::GridFittedBoundary{<:Field}) = GridFittedBoundary(comp
 on_architecture(arch, ib::GridFittedBoundary) = ib # need a workaround...
 
 Adapt.adapt_structure(to, ib::AbstractGridFittedBoundary) = GridFittedBoundary(adapt(to, ib.mask))
-
diff --git a/src/ImmersedBoundaries/immersed_boundary_condition.jl b/src/ImmersedBoundaries/immersed_boundary_condition.jl
index eb9327cc12..34a7981c3c 100644
--- a/src/ImmersedBoundaries/immersed_boundary_condition.jl
+++ b/src/ImmersedBoundaries/immersed_boundary_condition.jl
@@ -45,9 +45,9 @@ Base.show(io::IO, ibc::IBC) =
 """
     ImmersedBoundaryCondition(; interfaces...)
 
-Return an ImmersedBoundaryCondition with conditions on individual
-cell `interfaces ∈ (west, east, south, north, bottom, top)`
-between the fluid and immersed boundary.
+Return an `ImmersedBoundaryCondition` with conditions on individual cell
+`interfaces ∈ (west, east, south, north, bottom, top)` between the fluid
+and the immersed boundary.
 """
 function ImmersedBoundaryCondition(; west = nothing,
                                      east = nothing,