fix up docs

Author: kmdeck

docs/make.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/src/tutorials/global/bucket.jl

@@ -35,20 +35,20 @@ diagnostics_outdir = joinpath(root_path, "global_diagnostics")
 outdir =
     ClimaUtilities.OutputPathGenerator.generate_output_path(diagnostics_outdir);
 
-# Set timestep, start_date, stop_date
+# Set timestep, start_date, stop_date:
 Δt = 900.0
 start_date = DateTime(2008)
 stop_date = DateTime(2009);
 
 # Create the domain - intentionally low resolution since
-# we are running on CPU
-nelements = (30, 7)
+# we are running 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
+# Parameters:
 earth_param_set = LP.LandParameters(FT)
 α_snow = FT(0.8)
 albedo = PrescribedBaregroundAlbedo{FT}(α_snow, domain.space.surface)
@@ -63,7 +63,9 @@ bucket_parameters = BucketModelParameters(
     ρc_soil = FT(2e6),
     τc = FT(float(Δt)),
 );
-# Forcing data
+
+# 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,
@@ -78,15 +80,17 @@ atmos, radiation = ClimaLand.prescribed_forcing_era5(
     time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
     regridder_type = :InterpolationsRegridder,
 );
-# Make the model
+# Make the model:
 bucket = BucketModel(
     parameters = bucket_parameters,
     domain = domain,
     atmosphere = atmos,
     radiation = radiation,
 );
 
-# IC function
+# 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)
     temp_anomaly_amip(coord) = 40 * cosd(coord.lat)^4
     T_sfc_0 = 271.0
@@ -101,7 +105,7 @@ end
 timestepper = CTS.RK4()
 timestepper = CTS.ExplicitAlgorithm(timestepper);
 
-# Create the simulation
+# Create the simulation and solve it:
 simulation = LandSimulation(
     FT,
     start_date,
@@ -115,13 +119,22 @@ simulation = LandSimulation(
 
 solve!(simulation);
 
+# Make some plots:
 short_names = ["tsfc", "lhf", "shf", "wsoil"]
-LandSimVis.make_annual_timeseries(simulation; savedir = root_path, short_names)
-# ![](bucket_longrun_cpu/annual_timeseries.png)
+
+LandSimVis.make_annual_timeseries(
+    simulation;
+    savedir = ".",
+    short_names,
+    plot_name = "bucket_annual_timeseries.pdf",
+)
+# ![](bucket_annual_timeseries.pdf)
+
 LandSimVis.make_heatmaps(
     simulation;
-    savedir = root_path,
+    savedir = ".",
     short_names,
     date = stop_date,
+    plot_name = "bucket_figures.pdf",
 )
-# ![](bucket_longrun_cpu/figure.pdf)
+# ![](bucket_figures.pdf)

docs/src/tutorials/global/snowy_land.jl

@@ -2,8 +2,7 @@
 
 # The code sets up the ClimaLand land model  on a spherical domain,
 # forcing with ERA5 data, but does not actually run the simulation.
-# To run the simulation, we strongly recommend using a GPU: ClimaLand
-# global runs have not been optimized for CPU and may be very slow.
+# To run the simulation, we strongly recommend using a GPU.
 
 # First we import a lot of packages:
 import ClimaComms
@@ -34,7 +33,7 @@ outdir =
     ClimaUtilities.OutputPathGenerator.generate_output_path(diagnostics_outdir);
 earth_param_set = LP.LandParameters(FT);
 
-# Set timestep, start_date, stop_date
+# Set timestep, start_date, stop_date:
 Δt = 450.0
 start_date = DateTime(2008)
 stop_date = DateTime(2009);
@@ -47,7 +46,8 @@ domain = ClimaLand.Domains.global_domain(
     nelements,
 );
 
-# Forcing data
+# 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,
@@ -62,6 +62,8 @@ forcing = ClimaLand.prescribed_forcing_era5(
     time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
     regridder_type = :InterpolationsRegridder,
 );
+
+# MODIS LAI is prescribed for the canopy model:
 modis_lai_ncdata_path = ClimaLand.Artifacts.modis_lai_multiyear_paths(;
     context,
     start_date,
@@ -73,7 +75,7 @@ LAI = ClimaLand.prescribed_lai_modis(
     start_date;
     time_interpolation_method = LinearInterpolation(),
 );
-# Make the model
+# Make the model:
 model = ClimaLand.LandModel{FT}(forcing, LAI, earth_param_set, domain, Δt);
 simulation = ClimaLand.Simulations.LandSimulation(
     FT,
@@ -83,6 +85,7 @@ simulation = ClimaLand.Simulations.LandSimulation(
     model;
     outdir,
 );
+# Run the simulation and make plots:
 #
 # ``` julia
 # ClimaLand.Simulations.solve!(simulation)

docs/src/tutorials/integrated/fluxnet_data.jl

@@ -137,17 +137,42 @@ maxLAI =
 # data (e.g. soil moisture and temperature and depth). ClimaLand
 # provides a function to get the comparison data for a select number of
 # variables:
-# | Variable  | Unit       | ClimaLand short_name | Fluxnet Column name
-# |---------| --------| ------------| -----------|
-# |Gross primary prod. | mol/m^2/s |"gpp"|"GPP_DT_VUT_REF"|
-# |Latent heat flux | W/m^2/s |"lhf"|"LE_CORR"|
-# |Sensible heat flux | W/m^2/s |"shf"|"H_CORR"|
-# |Upwelling SW | W/m^2/s |"swu"|"SW_OUT"|
-# |Upwelling LW | W/m^2/s |"lwu"|"LW_OUT"|
-# |Soil water content |  |"swc"|"SWC_F_MDS_1"|
-# |Soil temperature |  K|"tsoil"|"TS_F_MDS_1"|
-# |Total precipitation | m/s|"precip"|"P_F"|
+
+# | Variable  | Unit       | ClimaLand short name | Fluxnet Column name
+# |:---------| :--------:| :------------:| -----------:|
+# |Gross primary prod. | mol/m^2/s |"gpp"|"GPP\_DT\_VUT\_REF"|
+# |Latent heat flux | W/m^2/s |"lhf"|"LE\_CORR"|
+# |Sensible heat flux | W/m^2/s |"shf"|"H\_CORR"|
+# |Upwelling SW | W/m^2/s |"swu"|"SW\_OUT"|
+# |Upwelling LW | W/m^2/s |"lwu"|"LW\_OUT"|
+# |Soil water content |  |"swc"|"SWC\_F\_MDS\_1"|
+# |Soil temperature |  K|"tsoil"|"TS\_F\_MDS\_1"|
+# |Total precipitation | m/s|"precip"|"P\_F"|
+
 comparison_data = FluxnetSimulations.get_comparison_data(site_ID, time_offset);
 @show propertynames(comparison_data)
 # If a column is missing, the column is not returned. Missing values
 # are replaced with the mean of the not missing values.
+
+# The data we use to force the simulations and to compare the results against
+# were obtained from Ameriflux:
+
+# US-Moz: https://doi.org/10.17190/AMF/1854370
+# Citation: Jeffrey Wood, Lianhong Gu (2025), AmeriFlux FLUXNET-1F US-MOz Missouri Ozark
+# Site, Ver. 5-7, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1854370
+
+# US-NR1: https://doi.org/10.17190/AMF/1871141
+# Citation: Peter D. Blanken, Russel K. Monson, Sean P. Burns,
+# David R. Bowling, Andrew A. Turnipseed (2022),
+# AmeriFlux FLUXNET-1F US-NR1 Niwot Ridge Forest (LTER NWT1),
+# Ver. 3-5, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1871141
+
+# US-Var: https://doi.org/10.17190/AMF/1993904
+# Citation: Siyan Ma, Liukang Xu, Joseph Verfaillie, Dennis Baldocchi (2023),
+# AmeriFlux FLUXNET-1F US-Var Vaira Ranch- Ione, Ver. 3-5, AmeriFlux AMP, (Dataset).
+# https://doi.org/10.17190/AMF/1993904
+
+# US-Ha1: https://doi.org/10.17190/AMF/1871137
+# Citation: J. William Munger (2022), AmeriFlux FLUXNET-1F US-Ha1
+# Harvard Forest EMS Tower (HFR1), Ver. 3-5, AmeriFlux AMP, (Dataset).
+# https://doi.org/10.17190/AMF/1871137

docs/src/tutorials/integrated/snowy_land_fluxnet_tutorial.jl

@@ -5,6 +5,12 @@
 # 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.
+# The forcing data was obtained from
+# AmeriFlux FLUXNET: https://doi.org/10.17190/AMF/1871141
+# Citation: Peter D. Blanken, Russel K. Monson, Sean P. Burns,
+# David R. Bowling, Andrew A. Turnipseed (2022),
+# AmeriFlux FLUXNET-1F US-NR1 Niwot Ridge Forest (LTER NWT1),
+# Ver. 3-5, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1871141
 
 # The focus of this tutorial is to learn the steps towards setting up and
 # running an integrated simulation, and less on the parameterization
@@ -117,11 +123,13 @@ LandSimVis.make_diurnal_timeseries(
     simulation;
     short_names = ["shf", "lhf", "swu", "lwu"],
     spinup_date = start_date + Day(20),
+    plot_name = "US_NR1_diurnal_timeseries.pdf",
 );
-# ![](diurnal_timeseries.png)
+# ![](US_NR1_diurnal_timeseries.pdf)
 LandSimVis.make_timeseries(
     simulation;
     short_names = ["swc", "si", "swe"],
     spinup_date = start_date + Day(20),
+    plot_name = "US_NR1_variable_timeseries.pdf",
 );
-# ![](variable_timeseries.png)
+# ![](US_NR1_variable_timeseries.pdf)

docs/src/tutorials/integrated/soil_canopy_fluxnet_tutorial.jl

@@ -12,6 +12,10 @@
 # We use initial conditions, atmospheric and radiative flux conditions,
 # and leaf area index observed at the US-MOz flux tower, a flux tower
 # located within an oak-hickory forest in Ozark, Missouri, USA.
+# The forcing data was obtained from
+# AmeriFlux FLUXNET: https://doi.org/10.17190/AMF/1854370
+# Citation: Jeffrey Wood, Lianhong Gu (2025), AmeriFlux FLUXNET-1F US-MOz Missouri Ozark
+# Site, Ver. 5-7, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1854370
 
 # The focus of this tutorial is to learn the steps towards setting up and
 # running an integrated simulation, and less on the parameterization
@@ -123,5 +127,6 @@ LandSimVis.make_diurnal_timeseries(
     simulation;
     short_names = ["gpp", "shf", "lhf", "swu", "lwu"],
     spinup_date = start_date + Day(20),
+    plot_name = "US_MOz_diurnal_timeseries.pdf",
 );
-# ![](diurnal_timeseries.png)
+# ![](US_MOz_diurnal_timeseries.pdf)