diff --git a/docs/Manifest.toml b/docs/Manifest.toml index 46f6f4f509..efc85897e3 100644 --- a/docs/Manifest.toml +++ b/docs/Manifest.toml @@ -2,7 +2,7 @@ julia_version = "1.10.5" manifest_format = "2.0" -project_hash = "6c3f79ccae513840cc13b9ac947575c2305b507f" +project_hash = "6b19e20727d983c28286d493d461a6afa5ff8e8c" [[deps.ADTypes]] git-tree-sha1 = "99a6f5d0ce1c7c6afdb759daa30226f71c54f6b0" @@ -19,6 +19,16 @@ git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c" uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9" version = "0.0.1" +[[deps.About]] +deps = ["InteractiveUtils", "JuliaSyntaxHighlighting", "PrecompileTools", "StyledStrings"] +git-tree-sha1 = "3a94c01a1d7678f1c29b7d97216f5046f1ed1768" +uuid = "69d22d85-9f48-4c46-bbbe-7ad8341ff72a" +version = "1.0.0" +weakdeps = ["Pkg"] + + [deps.About.extensions] + PkgExt = "Pkg" + [[deps.AbstractFFTs]] deps = ["LinearAlgebra"] git-tree-sha1 = "d92ad398961a3ed262d8bf04a1a2b8340f915fef" @@ -1421,6 +1431,17 @@ git-tree-sha1 = "af433a10f3942e882d3c671aacb203e006a5808f" uuid = "9c1d0b0a-7046-5b2e-a33f-ea22f176ac7e" version = "0.2.1+0" +[[deps.JuliaSyntax]] +git-tree-sha1 = "956ac689b31cd871a48fbb70978b798c5e95018a" +uuid = "70703baa-626e-46a2-a12c-08ffd08c73b4" +version = "0.4.9" + +[[deps.JuliaSyntaxHighlighting]] +deps = ["JuliaSyntax", "StyledStrings"] +git-tree-sha1 = "19ecee1ea81c60156486a92b062e443b6bba60b7" +uuid = "ac6e5ff7-fb65-4e79-a425-ec3bc9c03011" +version = "0.1.0" + [[deps.JuliaVariables]] deps = ["MLStyle", "NameResolution"] git-tree-sha1 = "49fb3cb53362ddadb4415e9b73926d6b40709e70" @@ -1871,6 +1892,12 @@ git-tree-sha1 = "c13304c81eec1ed3af7fc20e75fb6b26092a1102" uuid = "442fdcdd-2543-5da2-b0f3-8c86c306513e" version = "0.3.2" +[[deps.MethodAnalysis]] +deps = ["AbstractTrees"] +git-tree-sha1 = "c2ee9b8f036c951f9ed0a47503a7f7dc0905b256" +uuid = "85b6ec6f-f7df-4429-9514-a64bcd9ee824" +version = "0.4.13" + [[deps.MicroCollections]] deps = ["BangBang", "InitialValues", "Setfield"] git-tree-sha1 = "629afd7d10dbc6935ec59b32daeb33bc4460a42e" @@ -2797,6 +2824,12 @@ weakdeps = ["Adapt", "GPUArraysCore", "SparseArrays", "StaticArrays"] StructArraysSparseArraysExt = "SparseArrays" StructArraysStaticArraysExt = "StaticArrays" +[[deps.StyledStrings]] +deps = ["PrecompileTools", "TOML"] +git-tree-sha1 = "711c9650010c95814911c2005ea04e70e70e65ed" +uuid = "f489334b-da3d-4c2e-b8f0-e476e12c162b" +version = "1.0.3" + [[deps.SuiteSparse]] deps = ["Libdl", "LinearAlgebra", "Serialization", "SparseArrays"] uuid = "4607b0f0-06f3-5cda-b6b1-a6196a1729e9" diff --git a/docs/Project.toml b/docs/Project.toml index e7f6f974ed..6de9a3d015 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,4 +1,6 @@ [deps] +About = "69d22d85-9f48-4c46-bbbe-7ad8341ff72a" +AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c" CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b" CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0" ClimaCore = "d414da3d-4745-48bb-8d80-42e94e092884" @@ -19,6 +21,7 @@ InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240" Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59" JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" +MethodAnalysis = "85b6ec6f-f7df-4429-9514-a64bcd9ee824" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d" SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462" diff --git a/docs/list_tutorials.jl b/docs/list_tutorials.jl new file mode 100644 index 0000000000..69df793d52 --- /dev/null +++ b/docs/list_tutorials.jl @@ -0,0 +1,34 @@ +tutorials = [ + "Running simulations" => [ + "Bucket LSM" => [ + "standalone/Bucket/bucket_tutorial.jl", + "standalone/Bucket/coupled_bucket.jl", + ], + "Soil modeling" => [ + "Boundary conditions" => "standalone/Soil/boundary_conditions.jl", + "Richards Equation" => "standalone/Soil/richards_equation.jl", + "Energy and Hydrology" => "standalone/Soil/soil_energy_hydrology.jl", + "Phase Changes" => "standalone/Soil/freezing_front.jl", + "Layered Soil" => "standalone/Soil/layered_soil.jl", + "Coarse Sand Evaporation" => "standalone/Soil/evaporation.jl", + "Gilat Loess Evaporation" => "standalone/Soil/evaporation_gilat_loess.jl", + "Bare soil site" => "standalone/Soil/sublimation.jl", + ], + "Canopy modeling" => [ + "Standalone Canopy" => "standalone/Canopy/canopy_tutorial.jl", + ], + "Integrated soil+canopy modeling" => [ + "Coupled Canopy and Soil" => "integrated/soil_canopy_tutorial.jl", + ], + "Snow Modeling" => [ + "standalone/Snow/base_tutorial.jl", + "standalone/Snow/data_tutorial.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 ClimaLand Domains" => "standalone/Usage/domain_tutorial.jl", + "Intro to forced site-level runs" => "shared_utilities/driver_tutorial.jl", + ], +] diff --git a/docs/make.jl b/docs/make.jl index 2a2e787778..3a451bcd63 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,40 +6,8 @@ using Distributed @everywhere using Literate using ClimaLand include("pages_helper.jl") -tutorials = [ - "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 ClimaLand Domains" => "standalone/Usage/domain_tutorial.jl", - "Intro to forced site-level runs" => "shared_utilities/driver_tutorial.jl", - ], - "Running simulations" => [ - "Bucket LSM" => [ - "standalone/Bucket/bucket_tutorial.jl", - "standalone/Bucket/coupled_bucket.jl", - ], - "Soil modeling" => [ - "Boundary conditions" => "standalone/Soil/boundary_conditions.jl", - "Richards Equation" => "standalone/Soil/richards_equation.jl", - "Energy and Hydrology" => "standalone/Soil/soil_energy_hydrology.jl", - "Phase Changes" => "standalone/Soil/freezing_front.jl", - "Layered Soil" => "standalone/Soil/layered_soil.jl", - "Coarse Sand Evaporation" => "standalone/Soil/evaporation.jl", - "Gilat Loess Evaporation" => "standalone/Soil/evaporation_gilat_loess.jl", - "Bare soil site" => "standalone/Soil/sublimation.jl", - ], - "Canopy modeling" => [ - "Standalone Canopy" => "standalone/Canopy/canopy_tutorial.jl", - ], - "Integrated soil+canopy modeling" => [ - "Coupled Canopy and Soil" => "integrated/soil_canopy_tutorial.jl", - ], - "Snow Modeling" => [ - "standalone/Snow/base_tutorial.jl", - "standalone/Snow/data_tutorial.jl", - ], - ], -] +include("list_tutorials.jl") + @everywhere const clima_dir = dirname(dirname(pathof(ClimaLand))); @everywhere source_dir = joinpath(@__DIR__, "src") @everywhere GENERATED_DIR = joinpath(source_dir, "generated") # generated files directory @@ -83,16 +51,15 @@ include("list_standalone_models.jl") include("list_diagnostics.jl") pages = Any[ "Home" => "index.md", - "APIs" => apis, - "Contribution guide" => "Contributing.md", + "Getting Started" => "getting_started.md", "Tutorials" => tutorials, - "Repository structure" => "folderstructure.md", "Standalone models" => standalone_models, "Diagnostics" => diagnostics, + "Contribution guide" => "Contributing.md", + "Repository structure" => "folderstructure.md", + "APIs" => apis, ] - - mathengine = MathJax( Dict( :TeX => Dict( @@ -102,7 +69,6 @@ mathengine = MathJax( ), ) - format = Documenter.HTML( prettyurls = !isempty(get(ENV, "CI", "")), collapselevel = 1, diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md new file mode 100644 index 0000000000..c4bcd9e8f6 --- /dev/null +++ b/docs/src/getting_started.md @@ -0,0 +1,60 @@ +# Getting Started + +## For Users + +### Installation + +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 +Pkg> add ClimaLand # Install ClimaLand +Pkg> # Go back to Julia REPL mode +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. + +### Parameterization + +Let's start with a basic example: compute canopy gross photosynthesis (GPP). + +```@repl +using ClimaLand +@doc ClimaLand.Canopy.compute_GPP +``` + +As you can see, our parameterization for GPP is located in the [`Canopy`](@ref ClimaLand.Canopy) 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) +``` + +Et voilà! + +Note that our package [ParamViz](https://github.com/CliMA/ParamViz.jl) allows interactive visualisation of +our parameterizations. See examples in the standalone models pages. + +### ClimaLand structure + +ClimaLand contains multiple modules. They are listed below: + +```@repl +using MethodAnalysis, ClimaLand +child_modules(ClimaLand) +``` + +To explore what modules, functions and types are exported in a particular module, you can use [About.jl](https://github.com/tecosaur/About.jl): + +```@repl +using ClimaLand +using About +about(ClimaLand.Soil.Biogeochemistry) +``` + +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). + diff --git a/docs/src/index.md b/docs/src/index.md index 33ef855cb4..4e064583c5 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,4 +1,54 @@ -# ClimaLand.jl +```@eval +using Pkg +io = IOBuffer() +v = Pkg.installed()["ClimaLand"] +print(io, """ + # ClimaLand.jl Documentation (v$(v)) + + """) +import Markdown +Markdown.parse(String(take!(io))) +``` + +## Introduction + +ClimaLand is the Land model of the Climate Modeling Alliance (CliMA) Earth System Model, which +also contains other components ([atmosphere](https://github.com/CliMA/ClimaAtmos.jl), [ocean](https://github.com/CliMA/ClimaOcean.jl), [sea-ice](https://github.com/CliMA/ClimaSeaIce.jl)). + +ClimaLand can be run coupled (or "online") with these other components via [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl), +or it can be run as a standalone, via prescribed meteorological data ("offline"). + +ClimaLand library, described in this documentation, is written in the Julia +programming language. It aims to be fast and have a clear syntax. ClimaLand +can run on CPU or GPU, it has a modular design, and is flexible in many ways. This documentation will expand on each of these elements. + +## Important Links + +- [CliMA Homepage](https://clima.caltech.edu/) +- [CliMA GitHub Organisation](https://github.com/CliMA) +- [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl) +- [ClimaAnalysis](https://github.com/CliMA/ClimaAnalysis.jl) +- [Julia Homepage](https://julialang.org) + +## Documentation for Users and Developers + +ClimaLand has documentation for both users and developers. The documentation for users is aimed at scientists who wants +to run simulations using ClimaLand, whereas the documentation for developers is aimed at contributors of the ClimaLand +code library. As such, users can skip reading the docs for developers, and vice-versa. + +## Physical units + +Note that CliMA, in all its repositories, uses Standard Units, reminded below + +| Quantity | Unit Name | SI Symbol | SI Unit Equivalent | +|:----------------------|:----------|:----------|:--------------------| +| Length | Meter | m | 1 m | +| Mass | Kilogram | kg | 1 kg | +| Time | Second | s | 1 s | +| Temperature | Kelvin | K | 1 K | +| Amount of Substance | Mole | mol | 1 mol | +| Energy | Joule | J | 1 J = 1 N·m | +| Power | Watt | W | 1 W = 1 J/s | +| Pressure | Pascal | Pa | 1 Pa = 1 N/m² | +| Frequency | Hertz | Hz | 1 Hz = 1 s⁻¹ | -`ClimaLand.jl` is a [Julia](https://julialang.org/) toolkit for land surface -modeling.