Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 175 additions & 38 deletions docs/Manifest-v1.11.toml

Large diffs are not rendered by default.

213 changes: 175 additions & 38 deletions docs/Manifest.toml

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
Expand All @@ -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"
Expand Down
6 changes: 3 additions & 3 deletions docs/list_of_apis.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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"],
]
46 changes: 26 additions & 20 deletions docs/list_tutorials.jl
Original file line number Diff line number Diff line change
@@ -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",
Expand All @@ -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",
Expand Down
32 changes: 16 additions & 16 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APIs currently has two nested ClimaLand
image

we should remove the ClimaLand fold (there's only one fold)

"Contributor guide" => "contributing.md",
]
Expand Down
7 changes: 5 additions & 2 deletions docs/src/APIs/ClimaLand.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/src/getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
140 changes: 140 additions & 0 deletions docs/src/tutorials/global/bucket.jl
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading