review comments

Author: kmdeck

docs/list_of_apis.jl

@@ -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/src/APIs/ClimaLand.md

@@ -10,7 +10,7 @@ ClimaLand.LandModel
 ClimaLand.SoilCanopyModel
 ClimaLand.LandHydrology
 ClimaLand.LandSoilBiogeochemistry
-ClimaLand.LandHydrology
+ClimaLand.SoilSnowModel
 ClimaLand.land_components
 ClimaLand.lsm_aux_vars
 ClimaLand.lsm_aux_types

docs/src/getting_started.md

@@ -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/tutorials/global/bucket.jl

@@ -40,8 +40,9 @@ outdir =
 start_date = DateTime(2008)
 stop_date = DateTime(2009);
 
-# Create the domain - intentionally low resolution since
-# we are running on CPU:
+# 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))
@@ -80,6 +81,7 @@ atmos, radiation = ClimaLand.prescribed_forcing_era5(
     time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
     regridder_type = :InterpolationsRegridder,
 );
+
 # Make the model:
 bucket = BucketModel(
     parameters = bucket_parameters,
@@ -92,10 +94,9 @@ bucket = BucketModel(
 # 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)
-    temp_anomaly_amip(coord) = 40 * cosd(coord.lat)^4
+    coords = ClimaCore.Fields.coordinate_field(Y.bucket.T)
     T_sfc_0 = 271.0
-    cds = ClimaCore.Fields.coordinate_field(Y.bucket.T)
-    @. Y.bucket.T = T_sfc_0 + temp_anomaly_amip(cds)
+    @. 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

docs/src/tutorials/global/snowy_land.jl

@@ -1,4 +1,4 @@
-# # Global snow+soil+canopy run
+# # Global full land (snow+soil+canopy) run
 
 # The code sets up the ClimaLand land model  on a spherical domain,
 # forcing with ERA5 data, but does not actually run the simulation.
@@ -20,8 +20,8 @@ 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.
+# context (MPI or on a single node), and device type (CPU or GPU).
+# Create a default output directory for diagnostics.
 const FT = Float64;
 context = ClimaComms.context()
 ClimaComms.init(context)
@@ -40,11 +40,7 @@ stop_date = DateTime(2009);
 
 # Create the domain:
 nelements = (101, 15)
-domain = ClimaLand.Domains.global_domain(
-    FT;
-    context = ClimaComms.context(),
-    nelements,
-);
+domain = ClimaLand.Domains.global_domain(FT; context, nelements);
 
 # Low-resolution forcing data from ERA5 is used here,
 # but high-resolution should be used for production runs.

docs/src/tutorials/integrated/fluxnet_data.jl

@@ -1,5 +1,9 @@
 # # Fluxnet forcing data: LAI, radiation, and atmospheric variables
 
+# In this tutorial, we will demonstrate how we read in forcing data at a Fluxnet site
+# using our ClimaLand infrastructure. To see an example running a simulation at a
+# Fluxnet site, please see the corresponding tutorials for the [SoilCanopyModel](docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.md) 
+# or [LandModel](docs/src/tutorials/integrated/snowy_land_fluxnet_tutorial.md)
 # To access the forcing data (LAI from MODIS, SW_d, LW_d, T_air, q_air,
 # P_air, and precipitation from fluxtower data), you first need the
 # the fluxtower site ID.
@@ -105,9 +109,10 @@ CairoMakie.save("air_temp.png", fig);
 # ![](air_temp.png)
 
 # We do something very similar with LAI, but now the data is coming
-# from MODIS. In this case, we linearly interpolate from the gridded
-# MODIS data to the latitude and longitude of the site. To do spatial
-# interpolation, we need to create a ClimaLand domain.
+# from MODIS. In this case, we use nearest-neighbor interpolatation
+# to move from the gridded
+# MODIS data to the LAI at the latitude and longitude of the site.
+# To do spatial interpolation, we need to create a ClimaLand domain.
 domain =
     Column(; zlim = (FT(-3.0), FT(0.0)), nelements = 10, longlat = (long, lat))
 surface_space = domain.space.surface;

docs/src/tutorials/integrated/fluxnet_vis.jl

@@ -5,7 +5,8 @@
 # are also implementing a method to write the simulation data to
 # file so that you can use your plotting methods of choice.
 
-# First, take a look at the fluxnet simulation tutorials, [canopy and soil](docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.md) or [canopy, soil, and snow](docs/src/tutorials/integrated/snowy_land_fluxnet_tutorial.md). To use the default plotting tools (`LandSimVis`),
+# First, take a look at the fluxnet simulation tutorials for [SoilCanopyModel](docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.md) or [LandModel](docs/src/tutorials/integrated/snowy_land_fluxnet_tutorial.md).
+# To use the default plotting tools (`LandSimVis`),
 # you need to start by importing the packages required:
 
 # ``` julia

docs/src/tutorials/integrated/snowy_land_fluxnet_tutorial.jl

@@ -1,7 +1,7 @@
 # # Fluxnet simulations with the full land model: snow, soil, canopy
 
 # In the
-# [canopy and soil tutorial](docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.md),
+# [SoilCanopyModel tutorial](docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.md),
 # we demonstrated how to run the an integrated model with a soil and
 # canopy component at the US-MOz fluxnet site.
 # Here we add in a snow component, and run the site at the Niwot Ridge site instead.
@@ -110,6 +110,7 @@ diagnostics = ClimaLand.default_diagnostics(
 data_dt = Second(FluxnetSimulations.get_data_dt(site_ID));
 updateat = Array(start_date:data_dt:stop_date);
 
+# Now we can construct the simulation object and solve it.
 simulation = Simulations.LandSimulation(
     start_date,
     stop_date,
@@ -120,7 +121,7 @@ simulation = Simulations.LandSimulation(
     user_callbacks = (),
     diagnostics,
 );
-@time solve!(simulation);
+solve!(simulation);
 
 # # Plotting results
 LandSimVis.make_diurnal_timeseries(

docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.jl

@@ -5,7 +5,7 @@
 # we demonstrated how to run the canopy model in
 # standalone mode using a prescribed soil moisture
 # and ground temperature. ClimaLand can also
-# integrate the canopy model with a prongostic soil model
+# integrate the canopy model with a prognostic soil model
 # and timestep the two components together to simulate an
 # interacting canopy-soil system. This tutorial
 # demonstrates how to set that up.

docs/src/tutorials/shared_utilities/driver_tutorial.jl

@@ -67,7 +67,8 @@ seconds = 0:data_dt:((length(local_datetime) - 1) * data_dt);
 T = @. 298.15 + 5.0 * sin(2π * (seconds - 3600 * 6) / (3600 * 24));
 LW_d = 5.67 * 10^(-8) .* T .^ 4;
 SW_d = @. max(1400 * sin(2π * (seconds - 3600 * 6) / (3600 * 24)), 0.0);
-diffuse_fraction = 0.5 .+ zeros(length(seconds))
+diffuse_fraction = 0.5 .+ zeros(length(seconds));
+
 # Next, fit interpolators to the data. These interpolators are what are stored in
 # the driver function. Then we can evaluate the radiative forcing
 # at any simulation time (and not just at times coinciding with measurements).