Improve surface fluxes

Manifest.toml

@@ -30,11 +30,17 @@ git-tree-sha1 = "e214a9b9bd1b4e1b4f15b22c0994862b66af7ff7"
 uuid = "68821587-b530-5797-8361-c406ea357684"
 version = "3.5.0+3"
 
+[[ArrayInterface]]
+deps = ["LinearAlgebra", "Requires", "SparseArrays"]
+git-tree-sha1 = "649c08a5a3a513f4662673d3777fe6ccb4df9f5d"
+uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
+version = "2.8.7"
+
 [[ArrayLayouts]]
 deps = ["FillArrays", "LinearAlgebra"]
-git-tree-sha1 = "cee952c726065d21a6b9a0abe04e201debdffc20"
+git-tree-sha1 = "0517f50df07250903194a94c2bc793c2bc239a76"
 uuid = "4c555306-a7a7-4459-81d9-ec55ddd5c99a"
-version = "0.3.0"
+version = "0.3.1"
 
 [[Base64]]
 uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
@@ -176,6 +182,12 @@ git-tree-sha1 = "eb0c34204c8410888844ada5359ac8b96292cfd1"
 uuid = "b552c78f-8df3-52c6-915a-8e097449b14b"
 version = "1.0.1"
 
+[[Distances]]
+deps = ["LinearAlgebra", "Statistics"]
+git-tree-sha1 = "23717536c81b63e250f682b0e0933769eecd1411"
+uuid = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
+version = "0.8.2"
+
 [[Distributed]]
 deps = ["Random", "Serialization", "Sockets"]
 uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
@@ -217,9 +229,15 @@ version = "1.3.0"
 
 [[FillArrays]]
 deps = ["LinearAlgebra", "Random", "SparseArrays"]
-git-tree-sha1 = "5322d34d7600d3429665b37bcf7628dc602a28cc"
+git-tree-sha1 = "6c89d5b673e59b8173c546c84127e5f623d865f6"
 uuid = "1a297f60-69ca-5386-bcde-b61e274b549b"
-version = "0.8.8"
+version = "0.8.9"
+
+[[FiniteDiff]]
+deps = ["ArrayInterface", "LinearAlgebra", "Requires", "SparseArrays", "StaticArrays"]
+git-tree-sha1 = "e65805de69d457029940acff64dd92e57b93c8a5"
+uuid = "6a86dc24-6348-571c-b903-95158fe2bd41"
+version = "2.3.1"
 
 [[ForwardDiff]]
 deps = ["CommonSubexpressions", "DiffResults", "DiffRules", "NaNMath", "Random", "SpecialFunctions", "StaticArrays"]
@@ -327,6 +345,12 @@ git-tree-sha1 = "be855e3c975b89746b09952407c156b5e4a33a1d"
 uuid = "9c8b4983-aa76-5018-a973-4c85ecc9e179"
 version = "0.8.1"
 
+[[LineSearches]]
+deps = ["LinearAlgebra", "NLSolversBase", "NaNMath", "Parameters", "Printf", "Test"]
+git-tree-sha1 = "54eb90e8dbe745d617c78dee1d6ae95c7f6f5779"
+uuid = "d3d80556-e9d4-5f37-9878-2ab0fcc64255"
+version = "7.0.1"
+
 [[LinearAlgebra]]
 deps = ["Libdl"]
 uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -395,6 +419,18 @@ git-tree-sha1 = "271e4670a6b30ec1e5daf6ba8b30240b7d85f535"
 uuid = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 version = "0.10.2"
 
+[[NLSolversBase]]
+deps = ["DiffResults", "Distributed", "FiniteDiff", "ForwardDiff"]
+git-tree-sha1 = "7c4e66c47848562003250f28b579c584e55becc0"
+uuid = "d41bc354-129a-5804-8e4c-c37616107c6c"
+version = "7.6.1"
+
+[[NLsolve]]
+deps = ["Distances", "LineSearches", "LinearAlgebra", "NLSolversBase", "Printf", "Reexport"]
+git-tree-sha1 = "cce0463af83a0f36c7bfa5820e373ac090cc46ad"
+uuid = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
+version = "4.3.0"
+
 [[NNlib]]
 deps = ["BinaryProvider", "Libdl", "LinearAlgebra", "Requires", "Statistics"]
 git-tree-sha1 = "d9f196d911f55aeaff11b11f681b135980783824"
@@ -429,6 +465,12 @@ git-tree-sha1 = "2fc6f50ddd959e462f0a2dbc802ddf2a539c6e35"
 uuid = "90014a1f-27ba-587c-ab20-58faa44d9150"
 version = "0.9.12"
 
+[[Parameters]]
+deps = ["OrderedCollections", "UnPack"]
+git-tree-sha1 = "38b2e970043613c187bd56a995fe2e551821eb4a"
+uuid = "d96e819e-fc66-5662-9728-84c9c7592b0a"
+version = "0.12.1"
+
 [[Parsers]]
 deps = ["Dates", "Test"]
 git-tree-sha1 = "72c3451932513427caffbd8bab15643ad693804b"
@@ -474,6 +516,12 @@ git-tree-sha1 = "54f8ceb165a0f6d083f0d12cb4996f5367c6edbc"
 uuid = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 version = "1.0.1"
 
+[[Reexport]]
+deps = ["Pkg"]
+git-tree-sha1 = "7b1d07f411bc8ddb7977ec7f377b97b158514fe0"
+uuid = "189a3867-3050-52da-a836-e630ba90ab69"
+version = "0.2.0"
+
 [[Requires]]
 deps = ["UUIDs"]
 git-tree-sha1 = "d37400976e98018ee840e0ca4f9d20baa231dc6b"
@@ -586,6 +634,11 @@ version = "0.4.1"
 deps = ["Random", "SHA"]
 uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
+[[UnPack]]
+git-tree-sha1 = "bc9ef72a4a826740895bf2772b48c21f9a1c13a7"
+uuid = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
+version = "1.0.0"
+
 [[Unicode]]
 uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 

Project.toml

@@ -29,6 +29,7 @@ Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 MPI = "da04e1cc-30fd-572f-bb4f-1f8673147195"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
+NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"

docs/Project.toml

@@ -18,6 +18,7 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 MPI = "da04e1cc-30fd-572f-bb4f-1f8673147195"
+NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"

docs/src/HowToGuides/Common/SurfaceFluxes.md

@@ -1,94 +1,36 @@
 # Surface Fluxes
 
-Surface flux functions, e.g. for buoyancy flux, friction velocity, and exchange coefficients.
-
-## `Byun1990`
-
-Compute surface fluxes using the approach in Byun (1990).
-
-### Plots
-
-```@example byun1990
-using ClimateMachine.SurfaceFluxes.Byun1990
-using Plots, LaTeXStrings
-using CLIMAParameters
-struct EarthParameterSet <: AbstractEarthParameterSet end
-param_set = EarthParameterSet()
-
-FT = Float64
-Ri_range = range(FT(-1.2), stop=FT(0.24), length=100)
-scales = FT[50,200,600,1000,10_000]
-
-z_0 = FT(1.0)
-γ_m, γ_h = FT(15.0), FT(9.0)
-β_m, β_h = FT(4.8), FT(7.8)
-Pr_0 = FT(0.74)
-
-plot(Ri_range,
-    [Byun1990.compute_exchange_coefficients(param_set, Ri,scale*z_0,z_0,γ_m,γ_h,β_m,β_h,Pr_0)[1]
-        for Ri in Ri_range, scale in scales],
-    xlabel="Bulk Richardson number (Ri_b)", ylabel="Drag coefficient", title="Momentum exchange coefficient",
-    labels=scales, legendtitle=L"z/z_0")
-
-savefig("exchange_byun1990_fig4a.svg") # hide
-nothing # hide
-```
-![](exchange_byun1990_fig4a.svg)
-
-Recreation of Figure 4(a) from Byun (1990)
-
-```@example byun1990
-plot(Ri_range,
-    [Byun1990.compute_exchange_coefficients(param_set, Ri,scale*z_0,z_0,γ_m,γ_h,β_m,β_h,Pr_0)[2]
-        for Ri in Ri_range, scale in scales],
-    xlabel="Bulk Richardson number (Ri_b)", ylabel="Exchange coefficient", title="Heat exchange coefficient",
-    labels=scales, legendtitle=L"z/z_0")
-
-savefig("exchange_byun1990_fig4b.svg") # hide
-nothing # hide
+```@meta
+CurrentModule = CLIMA.SurfaceFluxes
 ```
-![](exchange_byun1990_fig4b.svg)
 
-Recreation of Figure 4(b) from Byun (1990)
+This module provides a means to compute surface fluxes given several variables, described in [`surface_conditions`](@ref).
 
-## `Nishizawa2018`
+## Interface
+  - [`surface_conditions`](@ref) computes
+    - Monin-Obukhov length
+    - Potential temperature flux (if not given) using Monin-Obukhov theory
+    - transport fluxes using Monin-Obukhov theory
+    - friction velocity/temperature scale/tracer scales
+    - exchange coefficients
 
-### Plots
-```@example
-using ClimateMachine.SurfaceFluxes.Nishizawa2018
-using Plots, LaTeXStrings
-using CLIMAParameters
-struct EarthParameterSet <: AbstractEarthParameterSet end
-param_set = EarthParameterSet()
-FT = Float64
+## API
 
-a = FT(4.7)
-θ = FT(350)
-z_0 = FT(10)
-u_ave = FT(10)
-flux = FT(1)
-Δz = range(FT(10.0), stop=FT(100.0), length=100)
-Ψ_m_tol, tol_abs, iter_max = FT(1e-3), FT(1e-3), 10
-u_star = Nishizawa2018.compute_friction_velocity.(
-  Ref(param_set),
-  u_ave, θ, flux, Δz, z_0, a, Ψ_m_tol, tol_abs, iter_max)
-plot(u_star, Δz, title = "Friction velocity vs dz", xlabel = "Friction velocity", ylabel = "dz")
-savefig("friction_velocity.svg") # hide
-nothing # hide
+```@docs
+surface_conditions
 ```
-![](friction_velocity.svg)
 
 ## References
 
-- Businger, Joost A., et al. "Flux-profile relationships in the atmospheric surface
-  layer." Journal of the atmospheric Sciences 28.2 (1971): 181-189.
-  doi: [10.1175/1520-0469(1971)028<0181:FPRITA>2.0.CO;2](https://doi.org/10.1175/1520-0469(1971)028<0181:FPRITA>2.0.CO;2)
-
 - Nishizawa, S., and Y. Kitamura. "A Surface Flux Scheme Based on the Monin-Obukhov
   Similarity for Finite Volume Models." Journal of Advances in Modeling Earth Systems
   10.12 (2018): 3159-3175.
   doi: [10.1029/2018MS001534](https://doi.org/10.1029/2018MS001534)
 
+- Businger, Joost A., et al. "Flux-profile relationships in the atmospheric surface
+  layer." Journal of the atmospheric Sciences 28.2 (1971): 181-189.
+  doi: [10.1175/1520-0469(1971)028<0181:FPRITA>2.0.CO;2](https://doi.org/10.1175/1520-0469(1971)028<0181:FPRITA>2.0.CO;2)
+
 - Byun, Daewon W. "On the analytical solutions of flux-profile relationships for the
   atmospheric surface layer." Journal of Applied Meteorology 29.7 (1990): 652-657.
   doi: [10.1175/1520-0450(1990)029<0652:OTASOF>2.0.CO;2](https://doi.org/10.1175/1520-0450(1990)029<0652:OTASOF>2.0.CO;2)