Merge pull request #1267 from CliMA/js/eh-tut

Add simple standalone EnergyHydrology, Canopy tutorials

Author: juliasloan25

.buildkite/pipeline.yml

@@ -117,7 +117,7 @@ steps:
         agents:
           slurm_ntasks_per_node: 4
           slurm_nodes: 1
-          slurm_mem: 16G
+          slurm_mem: 24G
 
       - label: "Canopy Implicit Stepping CPU"
         command: "julia --color=yes --project=.buildkite experiments/standalone/Vegetation/timestep_test.jl"

README.md

@@ -24,11 +24,10 @@ component) or standalone (single component) modes.  </strong>
 # Introduction
 
 This is the repository of the CliMA land model code. Here are some notable features:
-- ClimaLand has a modular design, models can be run as standalone (e.g., soil moisture only) or integrated (e.g., soil moisture and energy AND canopy AND snow, etc.)
+- ClimaLand has a modular design, models can be run as standalone (e.g., soil moisture/energy only) or integrated (e.g., soil moisture/energy AND canopy AND snow, etc.)
 - ClimaLand can simulate single columns, regional boxes, and global runs
 - ClimaLand is CPU and GPU compatible
-- ClimaLand welcome contributions: please feel free to reach out to us with questions about how to get started, create a branch, and extend our code. For example, a modeler might want to test a new stomatal conductance model.
-- ClimaLand provides APIs and UIs at multiple levels.
+- ClimaLand welcomes contributions! Please feel free to reach out to us with questions about how to get started, create a branch, and extend our code.
 
 ## Installation
 
@@ -40,36 +39,31 @@ julia> using Pkg
 julia> Pkg.add(ClimaLand)
 ```
 
-Which is equivalent to doing
-
-```Julia
-julia> ] # typing the ] key with go into package REPL mode
-pkg> add ClimaLand
-```
-
-You are now ready to use `ClimaLand.jl`. To get started, we recommend reading the [documentation](https://clima.github.io/ClimaLand.jl/dev/).
+You are now ready to use `ClimaLand.jl`.
+To run a simple first simulation, please see our documentation page [Running your first simulation](https://clima.github.io/ClimaLand.jl/stable/getting_started/).
 
 ## Models
 
 In our code base, a "model" define a set of prognostic variables which must be timestepped. The equations which govern the time evolution likely contain parameters and are informed by parameterization and physical domain choices. Any ClimaLand model contains all of the information needed to evaluate these equations. Below are the current models we support:
 
 <strong> Component Models: </strong>
 
-- RichardsModel <: AbstractSoilModel <: AbstractModel (runnable only in standalone mode)
+- `RichardsModel`: Soil model option; runnable only in standalone mode
 
-- EnergyHydrologyModel <: AbstractSoilModel <: AbstractModel (runnable in standalone mode, or as part of a land model)
+- `EnergyHydrology`: Soil model option; runnable in standalone mode, or as part of an integrated model
 
-- CanopyModel <: AbstractVegetationModel <: AbstractModel  (runnable in standalone mode, or as part of a land model)
+- `CanopyModel`: runnable in standalone mode, or as part of an integrated model
 
-- SnowModel <: AbstractSnowModel <: AbstractModel (runnable in standalone mode, or as part of a land model)
+- `SnowModel`: runnable in standalone mode, or as part of an integrated model
 
 <strong> Combined Models: </strong>
 
-- SoilCanopyModel <: AbstractLandModel <: AbstractModel (an example of a land model, made of individual component models which are solved simultaneously but taking into account interactions between the components)
+- `SoilCanopyModel`: an integrated model made of individual component models `EnergyHydrology` + `CanopyModel`
+- `LandModel`: an integrated model made of individual component models `EnergyHydrology` + `CanopyModel` + `SnowModel` + `SoilCO2Model`
 
 ## Notes
 
-Recommended Julia Version: Stable release v1.11.1. CI tests Julia v1.10 and 1.11.
+Recommended Julia Version: Stable release v1.11.x. CI tests Julia v1.10 and 1.11.
 
 ClimaLand.jl is a different model from the original CliMA Land,
 which aims to utilize remote sensing data through more complex canopy RT

docs/list_tutorials.jl

@@ -16,6 +16,7 @@ tutorials = [
             "Changing soil parameterizations" => "standalone/Soil/changing_soil_parameterizations.jl",
         ],
         "Canopy" => [
+            "Default Canopy" => "standalone/Canopy/default_canopy.jl",
             "Standalone Canopy" => "standalone/Canopy/canopy_tutorial.jl",
             "Changing canopy parameterizations" => "standalone/Canopy/changing_canopy_parameterizations.jl",
         ],

docs/src/architectures.md

@@ -20,7 +20,7 @@ Below, we have descriptions for how to specify the context when trying to run a
 simulation in different setups. There are two ways to do this: internally within a
 script/REPL, or in the terminal via environment variables.
 
-For more detailed information, please see the ClimaComms.jl [documentation](https://clima.github.io/ClimaComms.jl/dev/).
+For more detailed information, please see the ClimaComms.jl [documentation](https://clima.github.io/ClimaComms.jl/stable/).
 
 ## Choosing the architecture within a script/REPL
 

docs/src/calibration.md

@@ -43,7 +43,7 @@ EKP.jl is possible, CliMA's preferred approach is using
 optimized for running on compute clusters. `ClimaCalibrate` handles efficient
 job orchestration and abstracts the details of the underlying system, providing
 a simpler user experience. Consult the
-[ClimaCalibrate documentation](https://clima.github.io/ClimaCalibrate.jl/dev/)
+[ClimaCalibrate documentation](https://clima.github.io/ClimaCalibrate.jl/stable/)
 for further information.
 
 ## Calibrate a land model
@@ -98,20 +98,20 @@ target plus or minus the noise at specific space and time, the goal is reached.
 - `TransformUnscented.Unscented` is a method in EKP, that requires `2p + 1`
   ensemble members for each iteration, where `p` is the number of parameters.
   For more information, read the
-  [EKP documentation for that method](https://clima.github.io/EnsembleKalmanProcesses.jl/dev/unscented_kalman_inversion/).
+  [EKP documentation for that method](https://clima.github.io/EnsembleKalmanProcesses.jl/stable/unscented_kalman_inversion/).
 
 - `verbose = true` is a setting that writes information about your calibration
   run to a log file.
 
 - `rng` is a set random seed.
 
 - `Scheduler` is a EKP setting for timestepping, please read
-  [EKP schedulers documentation](https://clima.github.io/EnsembleKalmanProcesses.jl/dev/learning_rate_scheduler/).
+  [EKP schedulers documentation](https://clima.github.io/EnsembleKalmanProcesses.jl/stable/learning_rate_scheduler/).
 
 - `ClimaCalibrate.WorkerBackend` defines how to interact with the underlying
   compute system. For other possible backends (for example, `JuliaBackend`,
   `ClimaGPUBackend`, or `DerechoBackend`), see the
-  [backend documentation in ClimaCalibrate](https://clima.github.io/ClimaCalibrate.jl/dev/backends/).
+  [backend documentation in ClimaCalibrate](https://clima.github.io/ClimaCalibrate.jl/stable/backends/).
 
 Each backend is optimized for specific use cases and computing resources. The
 backend system is implemented through Julia's multiple dispatch, so that code
@@ -126,7 +126,7 @@ prior_sc = EKP.constrained_gaussian("sc", 5e-6, 5e-4, 0, Inf);
 prior_pc = EKP.constrained_gaussian("pc", -2e6, 1e6, -Inf, Inf);
 prior = EKP.combine_distributions([prior_sc, prior_pc]);
 ```
-For more documentation about prior distribution, see [this EKP documentation page](https://clima.github.io/EnsembleKalmanProcesses.jl/dev/parameter_distributions/).
+For more documentation about prior distribution, see [this EKP documentation page](https://clima.github.io/EnsembleKalmanProcesses.jl/stable/parameter_distributions/).
 
 - `n_iterations` is the number of times your priors distribution will be
   updated, at each iteration your model is run for  the number of
@@ -323,7 +323,7 @@ For the land calibration, the default optimization method is
 scheduler, you need to go to the `experiments/calibration/run_calibration.jl`
 file and modify it there. For more information about the different optimization
 methods, see
-[EnsembleKalmanProcesses.jl](https://clima.github.io/EnsembleKalmanProcesses.jl/dev/)
+[EnsembleKalmanProcesses.jl](https://clima.github.io/EnsembleKalmanProcesses.jl/stable/)
 for more information.
 
 ### Observation settings
@@ -359,14 +359,14 @@ over a particular year or over multiple years for example.
 
 To change the covariance matrix, you need to go to `generate_observations.jl`
 and modify the covariance matrix that is passed in. See
-[ClimaCalibrate.jl documentation](https://clima.github.io/ClimaCalibrate.jl/dev/api/#Observation-Recipe-Interface)
+[ClimaCalibrate.jl documentation](https://clima.github.io/ClimaCalibrate.jl/stable/api/#Observation-Recipe-Interface)
 for a list of different covariance matrices that can be used.
 
 #### Data pipelines
 
 !!! note "Data preprocessing"
     The data preprocessing uses ClimaAnalysis.jl. See the
-    [ClimaAnalysis.jl documentation](https://clima.github.io/ClimaAnalysis.jl/dev/api/)
+    [ClimaAnalysis.jl documentation](https://clima.github.io/ClimaAnalysis.jl/stable/api/)
     for functions you can use for preprocessing.
 
 To add additional variables or change how a variable is preprocessed, you must

docs/src/getting_started.md

@@ -1,61 +1,119 @@
-# Getting Started
-
 ## Installation of Julia and ClimaLand
 
 ClimaLand is provided as a Julia package, so it requires having Julia installed. Information about Julia packages is available on the [Julia website](https://julialang.org/packages/).
 
 First, download and install Julia by following the instructions at [https://julialang.org/downloads/](https://julialang.org/downloads/).
-Then, you can launch a [Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/) and install the
-ClimaLand.jl package by running:
+Then, you can launch a [Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/) by running `julia --project` and install the
+ClimaLand.jl package by running the following within the REPL:
 
 ```julia
-julia> using Pkg
-julia> Pkg.add(ClimaLand)
-julia> using ClimaLand
+using Pkg
+Pkg.add(ClimaLand)
 ```
 
-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
+## Running a simple soil model
 
-Let's start with a basic example: compute canopy gross photosynthesis (GPP).
+Now that we have Julia installed, let's set up and run a simple ClimaLand simulation!
+You can follow along by copying the following code segments into your REPL.
 
-```@repl
+First we import the necessary Julia packages:
+```julia
+import ClimaParams as CP
 using ClimaLand
-@doc ClimaLand.Canopy.compute_GPP
+using ClimaLand.Domains
+using ClimaLand.Soil
+import ClimaLand.Simulations: LandSimulation, solve!
+import ClimaLand.Parameters as LP
+using Dates
 ```
 
-As you can see, our parameterization for GPP is located in the [`Canopy`](@ref Photosynthesis) Module, and requires four arguments.
-For example, with An = 5 µmol m⁻² s⁻¹, K = 0.5, LAI = 3 m² m⁻², Ω = 0.7, you can compute GPP like below:
-
-```@repl
-import ClimaLand.Canopy as canopy
-canopy.compute_GPP(5.0, 0.5, 3.0, 0.7)
+Choose a floating point precision, and get the parameter set, which holds constants used across CliMA models.
+Note: we use SI units unless otherwise specified.
+See our [Physical Units](https://clima.github.io/ClimaLand.jl/stable/physical_units/) documentation for more information.
+```julia
+FT = Float32
+earth_param_set = LP.LandParameters(FT);
 ```
 
-Et voilà!
+We will run this simulation on a column domain with 1 meter depth, at a lat/lon location
+near Pasadena, California.
 
-Note that our package [ParamViz](https://github.com/CliMA/ParamViz.jl) allows interactive visualisation of
-our parameterizations. See examples in the standalone models pages.
+```julia
+zmax = FT(0)
+zmin = FT(-1.0)
+longlat = FT.((34.1, -118.1))
+domain = Domains.Column(; zlim = (zmin, zmax), nelements = 10, longlat);
+surface_space = domain.space.surface;
+```
 
-### ClimaLand structure
+We choose the initial and final simulation times as `DateTime`s, and a timestep in seconds.
+```julia
+start_date = DateTime(2008);
+end_date = start_date + Second(60 * 60 * 72);
+dt = 1000.0;
+```
 
-ClimaLand contains multiple modules. They are listed below:
+The soil model takes in 2 forcing objects, atmosphere and radiation,
+which we read in from ERA5 data.
+```julia
+era5_ncdata_path =
+    ClimaLand.Artifacts.era5_land_forcing_data2008_path(; lowres = true);
+atmos, radiation = ClimaLand.prescribed_forcing_era5(
+    era5_ncdata_path,
+    surface_space,
+    start_date,
+    earth_param_set,
+    FT,
+);
+```
 
-```@repl
-using MethodAnalysis, ClimaLand
-child_modules(ClimaLand)
+Now, we can create the [`EnergyHydrology`](@ref ClimaLand.Soil.EnergyHydrology) model.
+This constructor uses default parameters and parameterizations, but these can also be
+overwritten, which we'll demonstrate in later tutorials.
+```julia
+model = Soil.EnergyHydrology{FT}(
+    domain,
+    (; atmos, radiation),
+    earth_param_set,
+);
 ```
 
-To explore what modules, functions and types are exported in a particular module, you can use [About.jl](https://github.com/tecosaur/About.jl):
+Define a function to set initial conditions for the prognostic variables.
+```julia
+function set_ic!(Y, p, t0, model)
+    Y.soil.ϑ_l .= FT(0.24);
+    Y.soil.θ_i .= FT(0.0);
+    T = FT(290.15);
+    ρc_s = Soil.volumetric_heat_capacity.(
+        Y.soil.ϑ_l,
+        Y.soil.θ_i,
+        model.parameters.ρc_ds,
+        model.parameters.earth_param_set,
+    );
+    Y.soil.ρe_int .=
+        Soil.volumetric_internal_energy.(
+            Y.soil.θ_i,
+            ρc_s,
+            T,
+            model.parameters.earth_param_set,
+        );
+end
+```
 
-```@repl
-using ClimaLand
-using About
-about(ClimaLand.Soil.Biogeochemistry)
+Now construct the `LandSimulation` object, which contains the model
+and additional timestepping information.
+```julia
+simulation = LandSimulation(start_date, end_date, dt, model; set_ic!, user_callbacks = ());
+```
+
+Now we can run the simulation!
+```julia
+solve!(simulation);
 ```
 
-Where modules are shown in red, functions are shown in blue, and types are shown in yellow.
+That's it! For more complex examples and pretty plots,
+please see the tutorial section of our docs.
 
-To see the documentation about a particular module, function or type, you can use ? to go in help mode
-in the REPL, or `@doc` as in [Parameterization above](#Parameterization).
+Atmospheric forcing data citation:
+Hersbach, Hans, et al. "The ERA5 global reanalysis."
+Quarterly journal of the royal meteorological society 146.730 (2020): 1999-2049.

docs/src/itime.md

@@ -2,9 +2,9 @@
 
 `ITime`, or _integer time_, is a time type used by CliMA simulations to keep
 track of simulation time. For more information, refer to the
-[TimeManager section](https://clima.github.io/ClimaUtilities.jl/dev/timemanager/)
+[TimeManager section](https://clima.github.io/ClimaUtilities.jl/stable/timemanager/)
 in ClimaUtilities and the
-[ITime section](https://clima.github.io/ClimaAtmos.jl/dev/itime/) in ClimaAtmos.
+[ITime section](https://clima.github.io/ClimaAtmos.jl/stable/itime/) in ClimaAtmos.
 
 ### How do I use ITime?
 
@@ -70,7 +70,7 @@ chosen for the `ITime`.
     If no period is provided, then the constructor for `ITime` will assume the
     provided value is in seconds and choose a reasonable value for the period.
     See
-    [TimeManager section](https://clima.github.io/ClimaUtilities.jl/dev/timemanager/)
+    [TimeManager section](https://clima.github.io/ClimaUtilities.jl/stable/timemanager/)
     in ClimaUtilities for more information.
 
 Next, the different types of `dt1`, `dt2`, and `dt3` can lead to problems as

docs/src/leaderboard/leaderboard.md

@@ -23,7 +23,7 @@ modified to add a new variable to the leaderboard. The dictionaries are `sim_var
 
 To add a variable for the leaderboard, add a key-value pair to the dictionary `sim_var_dict`
 whose key is the short name of the variable and the value is a function that returns a
-[`OutputVar`](https://clima.github.io/ClimaAnalysis.jl/dev/var/). Any preprocessing is done
+[`OutputVar`](https://clima.github.io/ClimaAnalysis.jl/stable/var/). Any preprocessing is done
 in the function which includes unit conversion and shifting the dates.
 
 ```julia

docs/src/tutorials/calibration/minimal_working_example.jl

@@ -76,7 +76,7 @@ ensemble_kalman_process = EKP.EnsembleKalmanProcess(
 # We are now ready to carry out the inversion. At each iteration, we get the ensemble from the last iteration, apply
 # Ozark_LatentHeatFlux(params) to each ensemble member, and apply the Kalman update to the ensemble.
 
-# Can be multithreaded, see https://clima.github.io/EnsembleKalmanProcesses.jl/dev/parallel_hpc/
+# Can be multithreaded, see https://clima.github.io/EnsembleKalmanProcesses.jl/stable/parallel_hpc/
 ClimaLand_out = []
 for i in 1:N_iterations # This will run the model N_ensemble * N_iterations times
     params_i = EKP.get_ϕ_final(prior, ensemble_kalman_process)

docs/src/tutorials/integrated/snowy_land_fluxnet_tutorial.jl

@@ -86,7 +86,7 @@ LAI = ClimaLand.prescribed_lai_modis(
 # # Setup the integrated model
 
 # We want to simulate the canopy-soil-snow system together, so the model type
-# [`LandModel`](https://clima.github.io/ClimaLand.jl/dev/APIs/ClimaLand/#Integrated-Land-Model-Types-and-methods)
+# [`LandModel`](https://clima.github.io/ClimaLand.jl/stable/APIs/ClimaLand/#Integrated-Land-Model-Types-and-methods)
 # is chosen. Here we use the highest level model constructor, which uses default parameters,
 # and parameterizations, for the soil, snow, and canopy models.