The following documentation in this section was written during February-March 2025 when the version of ClimaLand.jl was 0.15.8-9. There may be differences in the linked Example code, and that used to produce the output plots, since the versions may have evolved, and the code is taken from the Git repository for ClimaLand.jl.
There is extensive structured and readable documentation, combined with tutorial exercises for the reader to experiment on-line here.
The examples in the Tutorial section are taken from the ClimaLand.jl github file system in the docs/tutorials/standalone folder. Those in the Vegitation section are from experiments/standalone/Vegitation folder
The land bucket model implemented in ClimaLand is based on the models of Manabe (1969), Milly and Shmakin (2002), and the SLIM model of Bonan et al. (2019).
This tutorial explains in brief the core equations and the necessary parameters of the bucket model, and shows how to set up a simulation in standalone mode. More detail for coupled runs can be found in the ClimaCoupler.jl documentation(https://clima.github.io/ClimaCoupler.jl/dev/) and in the coupled simulation tutorial(https://clima.github.io/ClimaLand.jl/dev/generated/coupled_bucket/).
At each coordinate point on the surface, ordinary differential equations are solved for the subsurface water storage of land (`W`, m), the snow water equivalent multiplied by the snow cover fraction (`σS`, m), and the surface water content of land (`Ws`, m). Additionally a partial differential equation is solved for the land temperature as a function of depth (`T`, K). The snow cover fraction in the current code is given by a Heaviside function.
In the tutorial, surface fluxes over soil generally indicate fluxes over non-snow-covered regions. The exception is the albedo of vegetated and non-vegetated surfaces.
Example code: bucket_tutorial.jl
The five Output plots:
w.png: The land water storage in m per day.
swe.png: The area weighted (SWE) per day.
water_f.png: The surface water fluxes in m per day.
t.png: The surface termperature in degrees K per day.
energy_f.png: The turbulent flux and turbulent energy flux in W/m^2 per day.
For more information about the bucket model, please see the bucket model tutorial (https://clima.github.io/ClimaLand.jl/dev/generated/bucket_tutorial/).
To drive a single component system in standalone mode the user must provide prescribed functions of time for the water volume flux in precipitation, for the net downward shortwave and longwave radiative energy fluxes, for the atmospheric temperature T_a, wind speed u_a (m/s), specific humidity q_a, and air density ρ_a (kg/m^3) at a reference height h_a (m).
Turbulent surface fluxes are computed by the bucket model at each step of the simulation, using land surface properties as well as the prescribed atmospheric properties, according to Monin-Obukhov theory. These fluxes, as well as the net radiation, are stored in an auxiliary state of the bucket model: p.bucket.turbulent_fluxes.lhf, p.bucket.turbulent_fluxes.shf, p.bucket.turbulent_fluxes.vapor_flux, p.bucket.R_n, where they are accessible when boundary conditions are required in the ODE functions (right hand side) of the prognostic equations. Similarily, the precipitation rates are provided from prescribed conditions and stored in p.drivers.P_liq, p.drivers.P_snow.
In a coupled simulation, this changes. The coupler computes turbulent surface fluxes based on information (prognostic state, parameters) passed to it by both the atmosphere and land models. Net radiation is computed within the atmosphere model, using the prognostic land surface temperature and the land surface albedo, and passed back to the land model via the coupler. These details are important, but from the point of view of the land model, we only need to know that the coupler accesses land model variables to compute fluxes, and that the coupler passes these fluxes back to the land model.
In the current setup, "passed back to the land model via the coupler" means that the coupler accesses the auxiliary state of the land model and modifies it, at each step in the simulation, so that it holds the current net radiation, precipitation, and turbulent surface fluxes (p.bucket.turbulent_fluxes, p.bucket.R_n, p.drivers.P_liq, p.drivers.P_snow). These quantities are then still available in the ODE functions of the prognostic equations for the bucket model, as in the standalone case. In order for the land model to be able to run in both a standalone mode and in a coupled mode, use is made of multiple dispatch.
Example code has only comments and there is no output plot:
coupled_bucket.jl
Example code: sublimation.jl
Output plots:
water_fluxes.png: The evaporation and sublimation rates for water fluxes per day.
profiles.png: The temperature, ice depth, and liquid water depth per day over a period of 5 successive days.
Example code: phase_change_analytic.jl
Output plot:
phase_change_analytic.png: The plot gives both the frozen and unfrozen analytic profiles as a function of depth.
Example code: freezing_front.jl
Output plot:
The data for this comparison was obtained by us from the figures of Hansson et al. (2004), but was originally obtained
by Mizoguchi (1990). No error bars were reported, and we haven't quantified the error in our
estimation of the data from images. The depths taken for the fronts are at 12h, 24h and 50h.
mizoguchi_data_comparison.png
For further details on how to setup a simulation, please
see the other Soil tutorials. This one is very terse
and does not provide complete explanations
The same experiment is carried out 3 times:
1. No evaporation (zero flux boundary conditions),
2. With evaporation but no drainage,
3. With evaporation and drainage.
Example code: evaporation_gilat_loess.jl
Output plots:
evaporation_gardner_fig1.png: evaporation + drainage and volumetric water content vs days.
evaporation_lehmann2024_figS6.png: evaporation rate mm/d and cumulative evaporation mm vs days.
Evaporation is modelled using Monin-Obukhov surface theory. In this soil model, it is not possible to set the initial condition corresponding to most fluxes, but not include radiative fluxes. This is because for land surface models it does not make sense to include atmospheric forcing but not radiative forcing.
Because of this, we need to supply down-welling short and long wave radiation. We chose SW = 0 and LW = σT^4, in order to approximately balance out the blackbody emission of the soil which is accounted for by our model. Our assumption is that in the lab experiment there was no radiative heating or cooling of the soil.
Example code: evaporation.jl
Output plots:
evaporation_lehmann2008_fig8b.png: the data and model are plotted vs days and mass loss vs mass.
Example code: richards_equation.jl
Output plot:
equilibrium_test_nu_1.png: moisture content vs depth in the soil for an equilibrium solution.
Example code: soil_energy_hydrology.jl
Output plots:
eq_moisture_plot.png: depth vs the equlibrium moisture content at 0d, 1.5d and 3d.
eq_temperature_plot.png: depth vs the equlibrium temperature at 0d, 1.5d and 3d.
Example code:
base_tutorial.jl
data_tutorial.jl
There are two output plots: to show the model's output on some of the training data in physically meaningful units, first the timescale is reset and then the output scaling constants. From there, the dataframe for a given SNOTEL site and the trained model are passed to the make_timeseries function, and the result compared with the actual data.
The first plot is from Siagamount Lakes, Montana, and the second from Anchorage Hillside, Alaska.
Output plots:
base_tutorial_plot1.png
base_tutorial_plot2.png
The canopy biophysics model in ClimaLand combines a photosynthesis model with a canopy radiative transfer scheme, plant hydraulics model, and stomatal conductance model, placing them under either prescribed or simulated (as in a full Earth System Model) atmospheric and radiative flux conditions.
ClimaLand supports either Beer-Lambert law or a Two-Stream model for radiative transfer. For this tutorial, the Beer-Lambert law is used in which the intensity of light absorbed is a negative exponential function of depth in the canopy and with an exinction coefficient determined by optical depth.
The model of photosynthesis in ClimaLand is the Farquar Model in which gross photosynthesis production (GPP) is calculated based on C3 and C4 photosynthesis, which determines potential leaf-level photosynthesis.
The plant hydraulics model in ClimaLand solves for the water content within bulk root-stem-canopy system using Richards equation discretized into an arbitrary number of layers. The water content is related to the water potential using a retention curve relationship, and the water potential is used to simulate the effect moisture stress has on transpiration and GPP.
Example code: canopy_tutorial.jl
Output plots:
ozark_standalone_canopy_test.png
The output plot has 1 file with two components: the gross canopy photosynthesis \mu mol/mol per day(GPP), and the vapour flux mm per day.
In the previous tutorial(https://clima.github.io/ClimaLand.jl/dev/generated/soil_plant_hydrology_tutorial/), the canopy model is run in standalone mode using prescribed values for the inputs of soil hydraulics into the canopy hydraulics model. However, ClimaLand has the built-in capacity to couple the canopy model with a soil physics model and timestep the two simulations together to model a canopy-soil system. This tutorial demonstrates how to setup and run a coupled simulation, again using initial conditions, atmospheric and radiative flux conditions, and canopy properties observed at the US-MOz flux tower, a flux tower located within an oak-hickory forest in Ozark, Missouri, USA. See Wang et al. (2021) (https://doi.org/10.5194/gmd-14-6741-2021) for details on the site and parameters.
In ClimaLand, the coupling of the canopy and soil models is done by pairing the inputs and outputs which between the two models so that they match. For example, the root extraction of the canopy hydraulics model, which acts as a boundary flux for the plant system, is paired with a source term for root extraction in the soil model, so that the flux of water from the soil into the roots is equal and factored into both models. This pairing is done automatically in the constructor for a SoilCanopyModel (https://clima.github.io/ClimaLand.jl/dev/APIs/ClimaLand/LSM-Model-Types-and-methods) so that a user needs only specify the necessary arguments for each of the component models, and the two models will automatically be paired into a coupled simulation.
Example code: soil_canopy_tutorial.jl
There are three output plots:
ozark_canopy_flux_test.png: two plots, the first of GPP and the second of the vapour flux, both vs days.
ozark_soil_test.png: the augmented liquid water fraction at soil depths 10cm, 20cm and 30cm over the course of the simulation.
ozark_soil_plant_flux_test.png: the coupling of the water fluxes of the soil up into the plant hydraulic system.
Example code:
no_vegetation.jl
There are two output plots:
no_veg_state.png: the three sub-plots are of Temperature, Volumetric Water and LAI for the Canopy.
no_veg_fluxes.png: the the three sub-plots are of the Energy Fluxes, Water Fluxes and Carbon Fluxes.
The simulation is run multiple times: first, with a small reference timestep, then with increasing timestep sizes. The goal here is to see which timesteps are small enough to produce a stable simulation, and which timesteps are too large to produce accurate results.
The runs with larger timesteps are compared with the reference timestep run
using multiple metrics, including:
- mean, 99%th, and 95th% error over the course of the simulation
- T at the end of the simulation (used to test convergence with each dt)
- T throughout the entire simulation
Note that the simulation is run for 20 days + 80 seconds. This somewhat unusual length is necessary to test the convergence behavior of the solver. Convergence behavior must be assessed when T is actively changing, rather than when it is in equilibrium. T changes in the time period after a driver update, which occurs every 3 hours (so exactly at 20 days). Running for 20 days + 80 seconds allows us to look at results over a longer simulation, as well as convergence behavior. See also the discussion in https://github.com/CliMA/ClimaLand.jl/pull/675.
Example code:
timestep_test.jl
There are three output plots:
errors.png: a plot of the mean 95th percent and 99th percent errors for the temperature for timesteps over a range between 6 and 3600 minutes.
convergence.png: a measure of the convergence rate being the log of the difference of the end temperature and a final reference temperature.
states.png: a plot of the variation in temperature over a 20 day period with dt in a range with values between 0.2s and 60s.
Example code:
varying_lai.jl
There are two output plots:
varying_lai_state.png: three plots, the temperature, volumetric water and LAI over a period of about one year.
varying_lai_fluxes.png: three plots, the energy fluxes, the water fluxes and the carbon fluxes over a period of about one year.
Example code:
varying_lai_with_stem.jl
There are two output plots:
varying_lai_with_stem_state.png: three plots, the temperature, volumetric water and the LAI over a period of about 60 days.
varying_lai_with_stem_fluxes.png: three plots, the energy flux, the water flux and the carbon flux, over about 60 days.
5 March 2025
