(0.90.4) Implement three-dimensional StokesDrift 🌊 (#3384)

* Implement 3D StokesDrift

* Correction of three-dimensional Stokes drift implementation (#3392)

* Update StokesDrifts.jl

Adds horizontal Stokes drift gradient terms and a term due to the vertical gradient of the vertical Stokes drift component. These equations follow from the governing equation used by Oceananigans.

I think I got the interpolation right but it should be checked.

A test case/example is being developed

* Remove unnecessary gradients

* Create Spatially_varying_stokes_drift.jl

* Update Spatially_varying_stokes_drift.jl

Fix bug - was using old variable names

* Rewrite Stokes drift functions

* Improve docstring for StokesDrift

* Add stokes drift validation directory

* Update surface_wave_induced_flow.jl

Small clarifications (the order of operations in Lines 16 vs. 17 had me confused for a minute...I'm guessing different multiplication operators have different priority relative to division in Julia?)

* Fix typos in curl terms

* Move example to validation

* Update Spatially_varying_stokes_drift.jl

* Renames for Langmuir validation

* Create Langmuir_with_Stokes_y_jet.jl

Adds Langmuir case with y-oriented jet

* Add a unit test for StokesDrift

* Add time-stepping test for StokesDrift

* Add example with doctest for UniformStokesDrift

* Fix a bug for parameterized 3D StokesDrift

* Add Manifest and Project for StokesDrift validation

* Update src/StokesDrifts.jl

Co-authored-by: Navid C. Constantinou <[email protected]>

* Update src/StokesDrifts.jl

Co-authored-by: Navid C. Constantinou <[email protected]>

* Update src/StokesDrifts.jl

Co-authored-by: Navid C. Constantinou <[email protected]>

* fix UniformStokesDrift doctests

* fix minor inconsistency in example

* add units in docstring example

* Adds a show method for UniformStokesDrift, plus doctest

* Remove units

* addzero -> zerofunction

* uˢ₀ -> uˢ

* add show method for StokesDrift

* add method summary(::StokesDrift{Nothing})

* rename module StokesDrift -> StokesDrifts

* Bump to 0.90.4

* add StokesDrift example in docstring

* add StokesDrift example in docstring

* fix StokesDrift example

* more realistic wavelength in example

* better explanation for StokesDrift example

* bit better explanation for StokesDrift example

* fix algebra mistakes

---------

Co-authored-by: Brodie Pearson <[email protected]>
Co-authored-by: Navid C. Constantinou <[email protected]>

Project.toml

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

docs/src/appendix/library.md

@@ -181,7 +181,7 @@ Private = false
 ## Stokes drift
 
 ```@autodocs
-Modules = [Oceananigans.StokesDrift]
+Modules = [Oceananigans.StokesDrifts]
 Private = false
 ```
 

src/Models/HydrostaticFreeSurfaceModels/hydrostatic_free_surface_tendency_kernel_functions.jl

@@ -2,7 +2,6 @@ using Oceananigans.BuoyancyModels
 using Oceananigans.Coriolis
 using Oceananigans.Operators
 using Oceananigans.Operators: ∂xᶠᶜᶜ, ∂yᶜᶠᶜ
-using Oceananigans.StokesDrift
 using Oceananigans.TurbulenceClosures: ∂ⱼ_τ₁ⱼ, ∂ⱼ_τ₂ⱼ, ∇_dot_qᶜ
 using Oceananigans.Biogeochemistry: biogeochemical_transition, biogeochemical_drift_velocity
 using Oceananigans.TurbulenceClosures: immersed_∂ⱼ_τ₁ⱼ, immersed_∂ⱼ_τ₂ⱼ, immersed_∂ⱼ_τ₃ⱼ, immersed_∇_dot_qᶜ

src/Models/NonhydrostaticModels/nonhydrostatic_tendency_kernel_functions.jl

@@ -2,7 +2,7 @@ using Oceananigans.Advection
 using Oceananigans.BuoyancyModels
 using Oceananigans.Coriolis
 using Oceananigans.Operators
-using Oceananigans.StokesDrift
+using Oceananigans.StokesDrifts
 
 using Oceananigans.Biogeochemistry: biogeochemical_transition, biogeochemical_drift_velocity
 using Oceananigans.TurbulenceClosures: ∂ⱼ_τ₁ⱼ, ∂ⱼ_τ₂ⱼ, ∂ⱼ_τ₃ⱼ, ∇_dot_qᶜ

src/Oceananigans.jl

@@ -56,7 +56,7 @@ export
     BuoyancyField,
 
     # Surface wave Stokes drift via Craik-Leibovich equations
-    UniformStokesDrift,
+    UniformStokesDrift, StokesDrift,
 
     # Turbulence closures
     VerticalScalarDiffusivity,
@@ -216,7 +216,7 @@ include("DistributedComputations/DistributedComputations.jl")
 # Physics, time-stepping, and models
 include("Coriolis/Coriolis.jl")
 include("BuoyancyModels/BuoyancyModels.jl")
-include("StokesDrift.jl")
+include("StokesDrifts.jl")
 include("TurbulenceClosures/TurbulenceClosures.jl")
 include("Forcings/Forcings.jl")
 include("Biogeochemistry.jl")
@@ -249,7 +249,7 @@ using .BoundaryConditions
 using .Fields
 using .Coriolis
 using .BuoyancyModels
-using .StokesDrift
+using .StokesDrifts
 using .TurbulenceClosures
 using .Solvers
 using .OutputReaders