[WIP] Adds a pertubation advection open boundary matching scheme

Project.toml

@@ -1,7 +1,7 @@
 name = "Oceananigans"
 uuid = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 authors = ["Climate Modeling Alliance and contributors"]
-version = "0.95.2"
+version = "0.95.3"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

src/BoundaryConditions/BoundaryConditions.jl

@@ -40,4 +40,5 @@ include("update_boundary_conditions.jl")
 include("polar_boundary_condition.jl")
 
 include("flat_extrapolation_open_boundary_matching_scheme.jl")
+include("perturbation_advection_open_boundary_matching_scheme.jl")
 end # module

src/BoundaryConditions/fill_halo_regions.jl

@@ -20,12 +20,14 @@ conditions, possibly recursing into `fields` if it is a nested tuple-of-tuples.
 # Some fields have `nothing` boundary conditions, such as `FunctionField` and `ZeroField`.
 fill_halo_regions!(c::OffsetArray, ::Nothing, args...; kwargs...) = nothing
 
+retrieve_bc(bc) = bc
+
 # Returns the boundary conditions a specific side for `FieldBoundaryConditions` inputs and
 # a tuple of boundary conditions for `NTuple{N, <:FieldBoundaryConditions}` inputs
 for dir in (:west, :east, :south, :north, :bottom, :top)
     extract_side_bc = Symbol(:extract_, dir, :_bc)
     @eval begin
-        @inline $extract_side_bc(bc) = bc.$dir
+        @inline $extract_side_bc(bc) = retrieve_bc(bc.$dir)
         @inline $extract_side_bc(bc::Tuple) = map($extract_side_bc, bc)
     end
 end

src/BoundaryConditions/fill_halo_regions_open.jl

@@ -48,6 +48,8 @@ end
 @inline retrieve_open_bc(bc::OBC) = bc
 @inline retrieve_open_bc(bc) = nothing
 
+@inline retrieve_bc(bc::OBC) = nothing
+
 # for regular halo fills, return nothing if the BC is not an OBC
 @inline left_open_boundary_condition(boundary_condition, loc) = nothing
 @inline left_open_boundary_condition(boundary_conditions, ::Tuple{Face, Center, Center}) = retrieve_open_bc(boundary_conditions.west)
@@ -59,7 +61,7 @@ end
 @inline right_open_boundary_condition(boundary_conditions, ::Tuple{Center, Face, Center}) = retrieve_open_bc(boundary_conditions.north)
 @inline right_open_boundary_condition(boundary_conditions, ::Tuple{Center, Center, Face}) = retrieve_open_bc(boundary_conditions.top)
 
-# Opern boundary fill 
+# Open boundary fill 
 @inline   _fill_west_halo!(j, k, grid, c, bc::OBC, loc, args...) = @inbounds c[1, j, k]           = getbc(bc, j, k, grid, args...)
 @inline   _fill_east_halo!(j, k, grid, c, bc::OBC, loc, args...) = @inbounds c[grid.Nx + 1, j, k] = getbc(bc, j, k, grid, args...)
 @inline  _fill_south_halo!(i, k, grid, c, bc::OBC, loc, args...) = @inbounds c[i, 1, k]           = getbc(bc, i, k, grid, args...)

src/BoundaryConditions/flat_extrapolation_open_boundary_matching_scheme.jl

@@ -1,4 +1,4 @@
-using Oceananigans.Operators: Δx, Δy, Δz
+using Oceananigans.Operators: Δxᶜᶜᶜ, Δyᶜᶜᶜ, Δzᶜᶜᶜ
 
 """
     FlatExtrapolation
@@ -59,12 +59,10 @@ end
     return ϕ + Δϕ
 end
 
-const c = Center()
-
-@inline function _fill_west_open_halo!(j, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
-    Δx₁ = Δx(1, j, k, grid, c, c, c)
-    Δx₂ = Δx(2, j, k, grid, c, c, c)
-    Δx₃ = Δx(3, j, k, grid, c, c, c)
+@inline function _fill_west_halo!(j, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
+    Δx₁ = Δxᶜᶜᶜ(1, j, k, grid)
+    Δx₂ = Δxᶜᶜᶜ(2, j, k, grid)
+    Δx₃ = Δxᶜᶜᶜ(3, j, k, grid)
 
     spacing_factor = Δx₁ / (Δx₂ + Δx₃)
 
@@ -75,12 +73,12 @@ const c = Center()
     return nothing
 end
 
-@inline function _fill_east_open_halo!(j, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
+@inline function _fill_east_halo!(j, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
     i = grid.Nx + 1
 
-    Δx₁ = Δx(i-1, j, k, grid, c, c, c)
-    Δx₂ = Δx(i-2, j, k, grid, c, c, c)
-    Δx₃ = Δx(i-3, j, k, grid, c, c, c)
+    Δx₁ = Δxᶜᶜᶜ(i-1, j, k, grid)
+    Δx₂ = Δxᶜᶜᶜ(i-2, j, k, grid)
+    Δx₃ = Δxᶜᶜᶜ(i-3, j, k, grid)
 
     spacing_factor = Δx₁ / (Δx₂ + Δx₃)
 
@@ -91,10 +89,10 @@ end
     return nothing
 end
 
-@inline function _fill_south_open_halo!(i, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
-    Δy₁ = Δy(i, 1, k, grid, c, c, c)
-    Δy₂ = Δy(i, 2, k, grid, c, c, c)
-    Δy₃ = Δy(i, 3, k, grid, c, c, c)
+@inline function _fill_south_halo!(i, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
+    Δy₁ = Δyᶜᶜᶜ(i, 1, k, grid)
+    Δy₂ = Δyᶜᶜᶜ(i, 2, k, grid)
+    Δy₃ = Δyᶜᶜᶜ(i, 3, k, grid)
 
     spacing_factor = Δy₁ / (Δy₂ + Δy₃)
 
@@ -105,12 +103,12 @@ end
     return nothing
 end
 
-@inline function _fill_north_open_halo!(i, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
+@inline function _fill_north_halo!(i, k, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
     j = grid.Ny + 1
 
-    Δy₁ = Δy(i, j-1, k, grid, c, c, c)
-    Δy₂ = Δy(i, j-2, k, grid, c, c, c)
-    Δy₃ = Δy(i, j-3, k, grid, c, c, c)
+    Δy₁ = Δyᶜᶜᶜ(i, j-1, k, grid)
+    Δy₂ = Δyᶜᶜᶜ(i, j-2, k, grid)
+    Δy₃ = Δyᶜᶜᶜ(i, j-3, k, grid)
 
     spacing_factor = Δy₁ / (Δy₂ + Δy₃)
 
@@ -121,10 +119,10 @@ end
     return nothing
 end
 
-@inline function _fill_bottom_open_halo!(i, j, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
-    Δz₁ = Δz(i, j, 1, grid, c, c, c)
-    Δz₂ = Δz(i, j, 2, grid, c, c, c)
-    Δz₃ = Δz(i, j, 3, grid, c, c, c)
+@inline function _fill_bottom_halo!(i, j, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
+    Δz₁ = Δzᶜᶜᶜ(i, j, 1, grid)
+    Δz₂ = Δzᶜᶜᶜ(i, j, 2, grid)
+    Δz₃ = Δzᶜᶜᶜ(i, j, 3, grid)
 
     spacing_factor = Δz₁ / (Δz₂ + Δz₃)
 
@@ -135,12 +133,12 @@ end
     return nothing
 end
 
-@inline function _fill_top_open_halo!(i, j, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
+@inline function _fill_top_halo!(i, j, grid, ϕ, bc::FEOBC, loc, clock, model_fields)
     k = grid.Nz + 1
 
-    Δz₁ = Δz(i, j, k-1, grid, c, c, c)
-    Δz₂ = Δz(i, j, k-2, grid, c, c, c)
-    Δz₃ = Δz(i, j, k-3, grid, c, c, c)
+    Δz₁ = Δzᶜᶜᶜ(i, j, k-1, grid)
+    Δz₂ = Δzᶜᶜᶜ(i, j, k-2, grid)
+    Δz₃ = Δzᶜᶜᶜ(i, j, k-3, grid)
 
     spacing_factor = Δz₁ / (Δz₂ + Δz₃)
 

src/BoundaryConditions/perturbation_advection_open_boundary_matching_scheme.jl

@@ -0,0 +1,172 @@
+using Oceananigans.Operators: Δxᶠᶜᶜ, Δyᶜᶠᶜ, Δzᶜᶜᶠ, Ax_qᶠᶜᶜ, Ay_qᶜᶠᶜ, Az_qᶜᶜᶠ
+
+"""
+    PerturbationAdvection
+
+For cases where we assume that the internal flow is a small perturbation from 
+an external prescribed or coarser flow, we can split the velocity into background
+and perturbation components:
+...
+see latex document for now
+
+TODO: check what the coriolis is doing, and check what happens if U is the mean velocity
+"""
+struct PerturbationAdvection{VT, FT}
+       backward_step :: VT
+    inflow_timescale :: FT
+   outflow_timescale :: FT
+end
+
+Adapt.adapt_structure(to, pe::PerturbationAdvection) = 
+    PerturbationAdvection(adapt(to, pe.backward_step),
+                          adapt(to, pe.outflow_timescale),
+                          adapt(to, pe.inflow_timescale))
+
+function PerturbationAdvectionOpenBoundaryCondition(val, FT = Float64; 
+                                                    backward_step = true,
+                                                    outflow_timescale = Inf, 
+                                                    inflow_timescale = 300.0, kwargs...)
+
+    classification = Open(PerturbationAdvection(Val(backward_step), inflow_timescale, outflow_timescale))
+
+    @warn "`PerturbationAdvection` open boundaries matching scheme is experimental and un-tested/validated"
+
+    return BoundaryCondition(classification, val; kwargs...)
+end
+
+const PAOBC = BoundaryCondition{<:Open{<:PerturbationAdvection}}
+
+const BPAOBC = BoundaryCondition{<:Open{<:PerturbationAdvection{Val{true}}}}
+const FPAOBC = BoundaryCondition{<:Open{<:PerturbationAdvection{Val{false}}}}
+
+@inline function step_right_boundary!(bc::BPAOBC, l, m, boundary_indices, boundary_adjacent_indices, 
+                                      grid, u, clock, model_fields, ΔX)
+    Δt = clock.last_stage_Δt
+
+    Δt = ifelse(isinf(Δt), 0, Δt)
+
+    ūⁿ⁺¹ = getbc(bc, l, m, grid, clock, model_fields)
+
+    uᵢⁿ     = @inbounds getindex(u, boundary_indices...)
+    uᵢ₋₁ⁿ⁺¹ = @inbounds getindex(u, boundary_adjacent_indices...)
+
+    U = max(0, min(1, Δt / ΔX * ūⁿ⁺¹))
+
+    pa = bc.classification.matching_scheme
+
+    τ = ifelse(ūⁿ⁺¹ >= 0, pa.outflow_timescale, pa.inflow_timescale)
+
+    τ̃ = Δt / τ
+
+    uᵢⁿ⁺¹ = uᵢⁿ + U * (uᵢ₋₁ⁿ⁺¹ - ūⁿ⁺¹)
+
+    @inbounds setindex!(u, uᵢⁿ⁺¹, boundary_indices...)
+
+    return nothing
+end
+
+@inline function step_left_boundary!(bc::BPAOBC, l, m, boundary_indices, boundary_adjacent_indices, boundary_secret_storage_indices, 
+                                     grid, u, clock, model_fields, ΔX)
+    Δt = clock.last_stage_Δt
+
+    Δt = ifelse(isinf(Δt), 0, Δt)
+
+    ūⁿ⁺¹ = getbc(bc, l, m, grid, clock, model_fields)
+
+    uᵢⁿ     = @inbounds getindex(u, boundary_secret_storage_indices...)
+    uᵢ₋₁ⁿ⁺¹ = @inbounds getindex(u, boundary_adjacent_indices...)
+
+    U = min(0, max(-1, Δt / ΔX * ūⁿ⁺¹))
+
+    pa = bc.classification.matching_scheme
+
+    τ = ifelse(ūⁿ⁺¹ <= 0, pa.outflow_timescale, pa.inflow_timescale)
+
+    τ̃ = Δt / τ
+
+    u₁ⁿ⁺¹ = uᵢⁿ - U * (uᵢ₋₁ⁿ⁺¹ - ūⁿ⁺¹)
+
+    @inbounds setindex!(u, u₁ⁿ⁺¹, boundary_indices...)
+    @inbounds setindex!(u, u₁ⁿ⁺¹, boundary_secret_storage_indices...)
+
+    return nothing
+end
+
+
+@inline function step_right_boundary!(bc::FPAOBC, l, m, boundary_indices, boundary_adjacent_indices, 
+                                      grid, u, clock, model_fields, ΔX)
+    Δt = clock.last_stage_Δt
+
+    Δt = ifelse(isinf(Δt), 0, Δt)
+
+    ūⁿ⁺¹ = getbc(bc, l, m, grid, clock, model_fields)
+
+    uᵢⁿ     = @inbounds getindex(u, boundary_indices...)
+    uᵢ₋₁ⁿ⁺¹ = @inbounds getindex(u, boundary_adjacent_indices...)
+
+    U = max(0, min(1, Δt / ΔX * ūⁿ⁺¹))
+
+    pa = bc.classification.matching_scheme
+
+    τ = ifelse(ūⁿ⁺¹ >= 0, pa.outflow_timescale, pa.inflow_timescale)
+
+    τ̃ = Δt / τ
+
+    uᵢⁿ⁺¹ = uᵢⁿ + U * (uᵢ₋₁ⁿ⁺¹ - ūⁿ⁺¹) + (ūⁿ⁺¹ - uᵢⁿ) * τ̃
+
+    @inbounds setindex!(u, uᵢⁿ⁺¹, boundary_indices...)
+
+    return nothing
+end
+
+@inline function step_left_boundary!(bc::FPAOBC, l, m, boundary_indices, boundary_adjacent_indices, boundary_secret_storage_indices, 
+                                     grid, u, clock, model_fields, ΔX)
+    Δt = clock.last_stage_Δt
+
+    Δt = ifelse(isinf(Δt), 0, Δt)
+
+    ūⁿ⁺¹ = getbc(bc, l, m, grid, clock, model_fields)
+
+    uᵢⁿ     = @inbounds getindex(u, boundary_secret_storage_indices...)
+    uᵢ₋₁ⁿ⁺¹ = @inbounds getindex(u, boundary_adjacent_indices...)
+
+    U = min(0, max(-1, Δt / ΔX * ūⁿ⁺¹))
+
+    pa = bc.classification.matching_scheme
+
+    τ = ifelse(ūⁿ⁺¹ <= 0, pa.outflow_timescale, pa.inflow_timescale)
+
+    τ̃ = Δt / τ
+
+    u₁ⁿ⁺¹ = uᵢⁿ - U * (uᵢ₋₁ⁿ⁺¹ - ūⁿ⁺¹) + (ūⁿ⁺¹ - uᵢⁿ) * τ̃
+
+    @inbounds setindex!(u, u₁ⁿ⁺¹, boundary_indices...)
+    @inbounds setindex!(u, u₁ⁿ⁺¹, boundary_secret_storage_indices...)
+
+    return nothing
+end
+
+@inline function _fill_east_halo!(j, k, grid, u, bc::PAOBC, ::Tuple{Face, Any, Any}, clock, model_fields)
+    i = grid.Nx + 1
+
+    boundary_indices = (i, j, k)
+    boundary_adjacent_indices = (i-1, j, k)
+
+    Δx = Δxᶠᶜᶜ(i, j, k, grid)
+
+    step_right_boundary!(bc, j, k, boundary_indices, boundary_adjacent_indices, grid, u, clock, model_fields, Δx)
+
+    return nothing
+end
+
+@inline function _fill_west_halo!(j, k, grid, u, bc::PAOBC, ::Tuple{Face, Any, Any}, clock, model_fields)
+    boundary_indices = (1, j, k)
+    boundary_adjacent_indices = (2, j, k)
+    boundary_secret_storage_indices = (0, j, k)
+
+    Δx = Δxᶠᶜᶜ(1, j, k, grid)
+
+    step_left_boundary!(bc, j, k, boundary_indices, boundary_adjacent_indices, boundary_secret_storage_indices, grid, u, clock, model_fields, Δx)
+
+    return nothing
+end