Add computation of neutral bulk coefficients to docs (#526)

* Experiment with computing the neutral coefficients

* clean up stability_profile implementation

* edson -> atmosphere_ocean

* fixes

* open docs and tweak

* atmosphere surface name

* updates and clean up

* export CoefficientBasedFluxes

* test increasing charnock parameter

* update docs

* rm ClimaOcean from docs Project

* add examples back

* few tweaks

* huge fonts

* different legent setup

* updates

* better introduction

* more updates

* fix wrong statement about water vapor heaviness

* Update src/OceanSeaIceModels/InterfaceComputations/roughness_lengths.jl

* continuing

* API streamlining

* fix

* plot stability function + bugfix

* fix

* put examples back

* add docstring to struct

@glwagner if we wanna document the structs I think this is the way to do so

* import DocStringExtensions

* only convert if it's a number

* fix few typos and stray spaces

* fix bug?

* bit of typos/rephrasing/better rendering

* fix bug?

* bugfix for roughness length interface

* Update docs/src/interface_fluxes.md

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

* fix roughness length interface again

* fix surface_specific_humidity function

* fix grachev bug

* fix

* small fixes

* add colorbars and labels

* add units

* balance colormap

* fix typo

* add legend w ΔTs

* better notation for stabiltiy fucntions

* fix some tests

* add back the mysterious log and atan

@glwagner, confirm that it was not removed intentionally

* add few refs

* fix latex rendering

* add vanilla docstring

* add ETOPO2022() in available datasets

* add modules

* fix docs ref

* add back chatgpt error

* beautifications + remove duplicate code

* add citations

---------

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

Author: glwagner

Project.toml

@@ -12,6 +12,7 @@ ClimaSeaIce = "6ba0ff68-24e6-4315-936c-2e99227c95a4"
 CubicSplines = "9c784101-8907-5a6d-9be6-98f00873c89b"
 DataDeps = "124859b0-ceae-595e-8997-d05f6a7a8dfe"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 ImageMorphology = "787d08f9-d448-5407-9aad-5290dd7ab264"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
@@ -47,6 +48,7 @@ ClimaSeaIce = "0.2.6"
 CondaPkg = "0.2.28"
 CubicSplines = "0.2"
 DataDeps = "0.7"
+DocStringExtensions = "0.9"
 Downloads = "1.6"
 ImageMorphology = "0.4"
 JLD2 = "0.4, 0.5"

docs/climaocean.bib

@@ -8,3 +8,24 @@ @article{edson2013exchange
   year={2013},
   doi={10.1175/JPO-D-12-0173.1}
 }
+
+@article{large2009global,
+  title={The global climatology of an interannually varying air--sea flux data set},
+  author={Large, W G and Yeager, S G},
+  journal={Climate Dynamics},
+  volume={33},
+  pages={341--364},
+  year={2009},
+  doi={10.1007/s00382-008-0441-3}
+}
+
+@article{nishizawa2018surface,
+  author = {Nishizawa, S. and Kitamura, Y.},
+  title = {A Surface Flux Scheme Based on the {Monin-Obukhov} Similarity for Finite Volume Models},
+  journal = {Journal of Advances in Modeling Earth Systems},
+  volume = {10},
+  number = {12},
+  pages = {3159-3175},
+  doi = {10.1029/2018MS001534},
+  year = {2018}
+}

docs/make.jl

@@ -17,12 +17,8 @@ const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
 const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")
 
 to_be_literated = [
-    # "ecco_inspect_temperature_salinity.jl",
-    # "generate_bathymetry.jl",
-    # "generate_surface_fluxes.jl",
     "single_column_os_papa_simulation.jl",
     "one_degree_simulation.jl",
-    # "mediterranean_simulation_with_ecco_restoring.jl",
     "near_global_ocean_simulation.jl"
 ]
 
@@ -46,15 +42,13 @@ pages = [
     "Home" => "index.md",
 
     "Examples" => [
-        # "Inspect ECCO2 data" => "literated/ecco_inspect_temperature_salinity.md",
-        # "Generate bathymetry" => "literated/generate_bathymetry.md",
-        # "Surface fluxes" => "literated/generate_surface_fluxes.md",
         "Single-column ocean simulation" => "literated/single_column_os_papa_simulation.md",
-        # "Mediterranean simulation with ECCO restoring" => "literated/mediterranean_simulation_with_ecco_restoring.md",
         "One-degree ocean simulation" => "literated/one_degree_simulation.md",
         "Near-global ocean simulation" => "literated/near_global_ocean_simulation.md",
         ],
 
+    "Interface fluxes" => "interface_fluxes.md",
+
     "Library" => [
         "Contents"       => "library/outline.md",
         "Public"         => "library/public.md",

docs/src/index.md

@@ -2,9 +2,13 @@
 
 🌎 Realistic ocean-only and coupled ocean + sea-ice simulations driven by prescribed atmospheres and based on [Oceananigans](https://github.com/CliMA/Oceananigans.jl) and [ClimaSeaIce](https://github.com/CliMA/ClimaSeaIce.jl).
 
-ClimaOcean implements a framework for driving coupled ocean and sea ice simulations with prescribed atmospheres, using bulk formula to compute atmosphere-ocean, atmosphere-ice, and ocean-ice fluxes of heat, momentum, and freshwater. ClimaOcean builds off the Oceananigans framework, which provides tools for gridded finite volume computations on CPUs and GPUs and building ocean-flavored fluid dynamics simulations. ClimaSeaIce, which provides software for both stand-alone and coupled sea ice simulations, is also built with Oceananigans.
+ClimaOcean implements a framework for coupling prescribed or prognostic representations of the ocean, sea ice, and atmosphere state.
+Fluxes of heat, momentum, and freshwater are computed across the interfaces of its component models according to either Monin-Obukhov similarity theory,
+or coefficient-based "bulk formula".
+ClimaOcean builds off Oceananigans, which provides tools for gridded finite volume computations on CPUs and GPUs and building ocean-flavored fluid dynamics simulations. ClimaSeaIce, which provides software for both stand-alone and coupled sea ice simulations, is also built with Oceananigans.
 
-ClimaOcean's core abstractions are `OceanSeaIceModel` which encapsulates the ocean simulation, sea ice simulation, prescribed atmospheric state, atmospheric thermodynamic parameters, and parameterizations that define how the three communicate. ClimaOcean also implements `ocean_simulation`, a utility for building realistic, hydrostatic ocean simulations with Oceananigans ensuring compatibility with `OceanSeaIceModel`.
+ClimaOcean's core abstraction is [`OceanSeaIceModel`](@ref), which encapsulates the ocean, sea ice, and atmosphere state, and interfacial flux parameterizations.
+ClimaOcean also implements [`ocean_simulation`](@ref), a utility for building realistic, hydrostatic ocean simulations with Oceananigans ensuring compatibility with `OceanSeaIceModel`.
 
 ClimaOcean is written in Julia by the [Climate Modeling Alliance](https://clima.caltech.edu)
 and heroic external collaborators.