From db089515281d1433a046b4e537e6195959484e23 Mon Sep 17 00:00:00 2001 From: AlexisRenchon Date: Fri, 30 Aug 2024 11:22:09 -0700 Subject: [PATCH] WIP --- docs/src/getting-started.md | 85 +++---------------------------------- 1 file changed, 7 insertions(+), 78 deletions(-) diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index 41fe16e3a4..a549ea7231 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -4,9 +4,8 @@ ### Installation -Installing ClimaLand in Julia is very easy. First, download and install Julia -by following the instructions at [https://julialang.org/downloads/](https://julialang.org/downloads/). -Then, you can add the ClimaLand package by simply doing: +First, download and install Julia by following the instructions at [https://julialang.org/downloads/](https://julialang.org/downloads/). +Then, you can install the ClimaLand package by doing: ```julia julia> ] # Enter Package REPL mode @@ -17,7 +16,7 @@ Julia> using ClimaLand ### Parameterisation -Let's start with an very basic example: compute canopy gross photosynthesis (GPP). +Let's start with an basic example: compute canopy gross photosynthesis (GPP). ```@repl using ClimaLand @@ -35,6 +34,7 @@ canopy.compute_GPP(FT(5.0), FT(0.5), FT(3.0), FT(0.7)) ``` Et voilà! + Note that our package [ParamViz](https://github.com/CliMA/ParamViz.jl) allow interactive visualisation of our parameterisations. See examples in the standalone models pages. @@ -118,7 +118,7 @@ root = build_tree(modules) print_sorted_tree(stdout, root) # hide ``` -To explore what function and structure is exported in a particular module, you can use About.jl: +To explore what modules, functions and types are exported in a particular module, you can use About.jl: ```@repl using ClimaLand @@ -126,79 +126,8 @@ using About about(ClimaLand.Soil.Biogeochemistry) ``` -Where names in red are Module, names in blue are functions, and name in yellow are Types. +Where names in red are module, names in blue are functions, and name in yellow are Types. -To see the documentation about a particular Module, function or type, you can use ? to go in help mode +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 [Parameterisation above](#Parameterisation). -#### Artifacts - -Artifacts contains... see ClimaArtifacts - -#### Diagnostics - -Diagnostics contains... see Diagnostics doc page - -#### Domains - -Domains contains... see xxxx pages (ClimaCore, other pages) - -#### Parameters - -Parameters contains... see ClimaParams - -#### Models - -See page X --> this should be its own page... - -A ClimaLand standalone model, such as our soil hydrology model, usually advance some state -(i.e., prognostic) variable(s) (e.g., soil moisture), in time and space, and computes cache -(i.e., diagnostic) variable(s) (e.g., ). - -State variables are solved via ordinary differential equations (ODEs), and require initial conditions -and a physical domain with discretized layers and boundary conditions, as well as a timestepper to -advance the state in time. - -ClimaLand domains are X, and timestepper are Y. - -## For Developers - -Note: This should be a separate page... to do, WIP - -### Multiple Dispatch and ClimaLand modularity - -explain FT -explain AbstractModel and why, etc. - -Existing Earth System Models and Land Surface Models are monolythique and the scientific community -has asked for modularity in those models for a long time, as currently making modifications in -existing models is a task requiring a lot of time and money. - -ClimaLand takes advantage of Julia multiple dispatch to build a modular model. - -You can find detailed explanation on Julia multiple dispatch here, but I will give a brief overview -and explain how we use it to build a modular land model in ClimaLand. - -The core idea is that functions can have multiple methods depending on their arguments number or type. - -For example, leaf transpiration is a function of stomatal conductance. Many models exists for stomatal conductance, -such as the Medlyn optimality model or the Ball-Berry model. - -We are going to create a new type, that we call "Abstract" type because it is not a fundamental type -(Number, Real, Float, Integer...), but a subtype. For example: - -```jl -abstract type AbstractStomatalConductanceModel{FT} <: AbstractModel{FT} end -abstract type MedlynConductanceModel <: AbstractStomatalConductanceModel{FT} end -abstract type BallBerryConductanceModel <: AbstractStomatalConductanceModel{FT} end -``` - -now, when we call the function `function leaf_transpiration(conductance::AbstractStomatalConductanceModel)`, -conductance can be either Medlyn of BallBerry. - -ClimaLand does this at multiple level, for example, our AbstractCanopyModel is made of photosynthesis, conductance, hydraulics, etc. -Similarly to AbstractConductanceModel, the AbstractCanopyModel can have multiple configurations that the rest of the model can dispatch -on, without changing anything. - -This approach allow us to build ClimaLand as a puzzle, where we assemble pieces of many sizes, and can swap them easily. -