documentation for fluxnet sites and global runs (#1288)

Author: kmdeck

docs/Manifest-v1.11.toml

@@ -3,7 +3,10 @@ AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 BSON = "fbb218c0-5317-5bc6-957e-2ee96dd4b1f0"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+ClimaAnalysis = "29b5916a-a76c-4e73-9657-3c8fd22e65e6"
+ClimaComms = "3a4d1b5c-c61d-41fd-a00a-5873ba7a1b0d"
 ClimaCore = "d414da3d-4745-48bb-8d80-42e94e092884"
+ClimaDiagnostics = "1ecacbb8-0713-4841-9a07-eb5aa8a2d53f"
 ClimaLand = "08f4d4ce-cf43-44bb-ad95-9d2d5f413532"
 ClimaLandSimulations = "348a0bd3-1299-4261-8002-d2cd97df6055"
 ClimaParams = "5c42b081-d73a-476f-9059-fd94b934656c"
@@ -17,6 +20,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 EnsembleKalmanProcesses = "aa8a2aa5-91d8-4396-bcef-d4f2ec43552d"
 Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 Format = "1fa38f19-a742-5d3f-a2b9-30dd87b9d5f8"
+GeoMakie = "db073c08-6b98-4ee5-b6a4-5efafb3259c6"
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 Insolation = "e98cc03f-d57e-4e3c-b70c-8d51efe9e0d8"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
@@ -25,6 +29,7 @@ JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 MethodAnalysis = "85b6ec6f-f7df-4429-9514-a64bcd9ee824"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Poppler_jll = "9c32591e-4766-534b-9725-b71a8799265b"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"

docs/Manifest.toml

@@ -4,9 +4,6 @@
 
 apis = [
     "ClimaLand" => [
-        "ClimaLand" => "APIs/ClimaLand.md",
-        "Shared Utilities" =>
-            ["APIs/Simulations.md", "APIs/shared_utilities.md"],
         "Soil" => [
             "Soil Energy and Hydrology" => "APIs/Soil.md",
             "Soil Biogeochemistry" => "APIs/SoilBiogeochemistry.md",
@@ -25,4 +22,7 @@ apis = [
         "Bucket Model" => "APIs/Bucket.md",
         "Snow Model" => "APIs/Snow.md",
     ],
+    "Integrated Models" => "APIs/ClimaLand.md",
+    "Shared Utilities" =>
+        ["APIs/Simulations.md", "APIs/shared_utilities.md"],
 ]

docs/Project.toml

@@ -1,19 +1,7 @@
 tutorials = [
-    "Running land simulations" => [
-        "Bucket LSM" => [
-            "standalone/Bucket/bucket_tutorial.jl",
-            "standalone/Bucket/coupled_bucket.jl",
-        ],
-        "Integrated soil+canopy modeling" => [
-            "Coupled Canopy and Soil" => "integrated/soil_canopy_tutorial.jl",
-        ],
-        "Handling interactions between model components" => [
-            "Adjusting boundary conditions for the soil" => "integrated/handling_soil_fluxes.jl",
-            "Adjusting boundary conditions for the snow" => "integrated/handling_snow_fluxes.jl",
-        ],
-    ],
     "Running standalone component simulations" => [
-        "Soil modeling" => [
+        "Bucket" => "standalone/Bucket/bucket_tutorial.jl",
+        "Soil" => [
             "Boundary conditions" => "standalone/Soil/boundary_conditions.jl",
             "Richards Equation" => "standalone/Soil/richards_equation.jl",
             "Energy and Hydrology" => "standalone/Soil/soil_energy_hydrology.jl",
@@ -25,22 +13,40 @@ tutorials = [
             "Coarse Sand Evaporation" => "standalone/Soil/evaporation.jl",
             "Gilat Loess Evaporation" => "standalone/Soil/evaporation_gilat_loess.jl",
             "Bare soil site" => "standalone/Soil/sublimation.jl",
+            "Changing soil parameterizations" => "standalone/Soil/changing_soil_parameterizations.jl",
         ],
-        "Canopy modeling" => [
+        "Canopy" => [
             "Standalone Canopy" => "standalone/Canopy/canopy_tutorial.jl",
+            "Changing canopy parameterizations" => "standalone/Canopy/changing_canopy_parameterizations.jl",
         ],
-        "Snow Modeling" => [
-            "standalone/Snow/base_tutorial.jl",
-            "standalone/Snow/data_tutorial.jl",
+        "Snow" => [
+            "Base tutorial" => "standalone/Snow/base_tutorial.jl",
+            "Data tutorial" => "standalone/Snow/data_tutorial.jl",
         ],
     ],
-    "Calibrating your ClimaLand model" => [
+    "Running Fluxnet simulations" => [
+        "Canopy and soil" => "integrated/soil_canopy_fluxnet_tutorial.jl",
+        "Canopy, soil, and snow" => "integrated/snowy_land_fluxnet_tutorial.jl",
+        "Data processing" => "integrated/fluxnet_data.jl",
+        "Visualization" => "integrated/fluxnet_vis.jl",
+    ],
+    "Running global simulations" => [
+        "Bucket" => "global/bucket.jl",
+        "Snow, soil, canopy" => "global/snowy_land.jl",
+    ],
+    "Calibrating a ClimaLand model" => [
         "Single site perfect model" => "calibration/minimal_working_example.jl",
         "Single site observations" => "calibration/minimal_working_example_obs.jl",
     ],
+    "Running coupled simulations" =>
+        ["Coupled bucket model" => "standalone/Bucket/coupled_bucket.jl"],
     "For model developers" => [
         "Intro to standalone models" => "standalone/Usage/model_tutorial.jl",
-        "Intro to multi-component models" => "standalone/Usage/LSM_single_column_tutorial.jl",
+        "Intro to multi-component models" => [
+            "Single column tutorial" => "standalone/Usage/LSM_single_column_tutorial.jl",
+            "Adjusting boundary conditions for the soil" => "integrated/handling_soil_fluxes.jl",
+            "Adjusting boundary conditions for the snow" => "integrated/handling_snow_fluxes.jl",
+        ],
         "Intro to ClimaLand Domains" => "standalone/Usage/domain_tutorial.jl",
         "Intro to forced site-level runs" => "shared_utilities/driver_tutorial.jl",
         "Intro to implicit/explicit timestepping" => "shared_utilities/timestepping.jl",

docs/list_of_apis.jl

@@ -52,25 +52,25 @@ include("list_diagnostics.jl")
 pages = Any[
     "Home" => "index.md",
     "Running your first simulation" => "getting_started.md",
-    "ClimaLand structure" => [
+    "Tutorials" => tutorials,
+    "Additional resources" => [
         "Model structure" => "model_structure.md",
         "Repository structure" => "repo_structure.md",
+        "Analyzing model output" => [
+            "Diagnostics" => diagnostics,
+            "Leaderboard" => "leaderboard/leaderboard.md",
+        ],
+        "Running on GPU or with MPI" => "architectures.md",
+        "Calibration" => "calibration.md",
+        "Restarting a simulation" => "restarts.md",
+        "Software utilities" => [
+            "ITime type" => "itime.md",
+            "Shared utilities" => "shared_utilities.md",
+        ],
+        "Physical units" => "physical_units.md",
+        "Model Equations" => standalone_models,
+        "Julia background" => "julia.md",
     ],
-    "Tutorials" => tutorials,
-    "Standalone models" => standalone_models,
-    "Analyzing model output" => [
-        "Diagnostics" => diagnostics,
-        "Leaderboard" => "leaderboard/leaderboard.md",
-    ],
-    "Running on GPU or with MPI" => "architectures.md",
-    "Calibration" => "calibration.md",
-    "Restarting a simulation" => "restarts.md",
-    "Software utilities" => [
-        "ITime type" => "itime.md",
-        "Shared utilities" => "shared_utilities.md",
-    ],
-    "Physical units" => "physical_units.md",
-    "Julia background" => "julia.md",
     "APIs" => apis,
     "Contributor guide" => "contributing.md",
 ]

docs/list_tutorials.jl

@@ -3,11 +3,14 @@
 ```@meta
 CurrentModule = ClimaLand
 ```
-## LSM Model Types and methods
+## Integrated Land Model Types and methods
 
 ```@docs
-ClimaLand.LandSoilBiogeochemistry
+ClimaLand.LandModel
+ClimaLand.SoilCanopyModel
 ClimaLand.LandHydrology
+ClimaLand.LandSoilBiogeochemistry
+ClimaLand.SoilSnowModel
 ClimaLand.land_components
 ClimaLand.lsm_aux_vars
 ClimaLand.lsm_aux_types

docs/make.jl

@@ -14,7 +14,7 @@ julia> Pkg.add(ClimaLand)
 julia> using ClimaLand
 ```
 
-A typical land simulation employs several different parameterizations to model the various land-surface processes. Let's start our journet into ClimaLand by looking at one of those.
+A typical land simulation employs several different parameterizations to model the various land-surface processes. Let's start our journey into ClimaLand by looking at one of those.
 
 ### Parameterization
 

docs/src/APIs/ClimaLand.md

@@ -0,0 +1,140 @@
+# # Global bucket run
+
+# The code sets up and runs the bucket model  on a spherical domain,
+# using ERA5 data.
+
+# First we import a lot of packages:
+import ClimaComms
+using ClimaCore
+using ClimaUtilities
+import Interpolations
+import ClimaUtilities.TimeVaryingInputs:
+    TimeVaryingInput, LinearInterpolation, PeriodicCalendar
+ClimaComms.@import_required_backends
+import ClimaTimeSteppers as CTS
+import ClimaParams as CP
+using ClimaLand.Bucket:
+    BucketModel, BucketModelParameters, PrescribedBaregroundAlbedo
+import ClimaLand
+import ClimaLand.Parameters as LP
+import ClimaLand.Simulations: LandSimulation, solve!
+using Dates
+using CairoMakie, ClimaAnalysis, GeoMakie, Poppler_jll, Printf, StatsBase
+import ClimaLand.LandSimVis as LandSimVis;
+
+# Set the simulation float type, determine the
+# context (MPI or on a single node), and device type. Create
+# a default output directory for diagnostics.
+const FT = Float64;
+context = ClimaComms.context()
+ClimaComms.init(context)
+device = ClimaComms.device()
+device_suffix = device isa ClimaComms.CPUSingleThreaded ? "cpu" : "gpu"
+root_path = "bucket_longrun_$(device_suffix)"
+diagnostics_outdir = joinpath(root_path, "global_diagnostics")
+outdir =
+    ClimaUtilities.OutputPathGenerator.generate_output_path(diagnostics_outdir);
+
+# Set timestep, start_date, stop_date:
+Δt = 900.0
+start_date = DateTime(2008)
+stop_date = DateTime(2009);
+
+# Create the domain - this is intentionally low resolution,
+# about 4.5 degrees x 4.5 degrees, to run quickly
+# when making the documentation on CPU.
+nelements = (20, 7)
+depth = FT(3.5)
+dz_tuple = FT.((1.0, 0.05))
+domain =
+    ClimaLand.Domains.global_domain(FT; context, nelements, depth, dz_tuple);
+
+# Parameters:
+earth_param_set = LP.LandParameters(FT)
+α_snow = FT(0.8)
+albedo = PrescribedBaregroundAlbedo{FT}(α_snow, domain.space.surface)
+bucket_parameters = BucketModelParameters(
+    FT;
+    albedo,
+    σS_c = FT(0.2),
+    W_f = FT(0.2),
+    z_0m = FT(1e-3),
+    z_0b = FT(1e-3),
+    κ_soil = FT(1.5),
+    ρc_soil = FT(2e6),
+    τc = FT(float(Δt)),
+);
+
+# Low-resolution forcing data from ERA5 is used here,
+# but high-resolution should be used for production runs.
+era5_ncdata_path = ClimaLand.Artifacts.era5_land_forcing_data2008_path(;
+    context,
+    lowres = true,
+)
+atmos, radiation = ClimaLand.prescribed_forcing_era5(
+    era5_ncdata_path,
+    domain.space.surface,
+    start_date,
+    earth_param_set,
+    FT;
+    max_wind_speed = 25.0,
+    time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
+    regridder_type = :InterpolationsRegridder,
+);
+
+# Make the model:
+bucket = BucketModel(
+    parameters = bucket_parameters,
+    domain = domain,
+    atmosphere = atmos,
+    radiation = radiation,
+);
+
+# Create a function which sets the initial conditions.
+# This should have the argument structure (Y,p,t, model)
+# in order to be used by the `LandSimulation` struct, below:
+function set_ic!(Y, p, t, bucket)
+    coords = ClimaCore.Fields.coordinate_field(Y.bucket.T)
+    T_sfc_0 = 271.0
+    @. Y.bucket.T = T_sfc_0 + 40 * cosd(coords.lat)^4
+    Y.bucket.W .= 0.15
+    Y.bucket.Ws .= 0.0
+    Y.bucket.σS .= 0.0
+end
+
+# Define timestepper and ODE algorithm
+timestepper = CTS.RK4()
+timestepper = CTS.ExplicitAlgorithm(timestepper);
+
+# Create the simulation and solve it:
+simulation = LandSimulation(
+    start_date,
+    stop_date,
+    Δt,
+    bucket;
+    set_ic!,
+    timestepper,
+    outdir,
+);
+
+solve!(simulation);
+
+# Make some plots:
+short_names = ["tsfc", "lhf", "shf", "wsoil"]
+
+LandSimVis.make_annual_timeseries(
+    simulation;
+    savedir = ".",
+    short_names,
+    plot_name = "bucket_annual_timeseries.pdf",
+)
+# ![](bucket_annual_timeseries.pdf)
+
+LandSimVis.make_heatmaps(
+    simulation;
+    savedir = ".",
+    short_names,
+    date = stop_date,
+    plot_name = "bucket_figures.pdf",
+)
+# ![](bucket_figures.pdf)