Merge pull request #1208 from CliMA/js/docs

update docs

Author: juliasloan25

docs/make.jl

@@ -39,7 +39,7 @@ mkpath(GENERATED_DIR)
 end
 tutorials_jl = flatten_to_array_of_strings(get_second(tutorials))
 println("Building literate tutorials...")
-tutorials_dir = joinpath(@__DIR__, "tutorials")
+tutorials_dir = joinpath(@__DIR__, "src", "tutorials")
 tutorials_jl = map(x -> joinpath(tutorials_dir, x), tutorials_jl)
 pmap(t -> generate_tutorial(tutorials_dir, t), tutorials_jl)
 
@@ -51,18 +51,28 @@ include("list_standalone_models.jl")
 include("list_diagnostics.jl")
 pages = Any[
     "Home" => "index.md",
-    "Getting Started" => "getting_started.md",
-    "Repository structure" => "folderstructure.md",
+    "Running your first simulation" => "getting_started.md",
+    "ClimaLand structure" => [
+        "Model structure" => "model_structure.md",
+        "Repository structure" => "repo_structure.md",
+    ],
     "Tutorials" => tutorials,
     "Standalone models" => standalone_models,
-    "Diagnostics" => diagnostics,
+    "Analyzing model output" => [
+        "Diagnostics" => diagnostics,
+        "Leaderboard" => "leaderboard/leaderboard.md",
+    ],
+    "Running on GPU or with MPI" => "architectures.md",
     "Calibration" => "calibration.md",
-    "Leaderboard" => "leaderboard/leaderboard.md",
-    "Restarts" => "restarts.md",
-    "Time type" => "timemanager.md",
-    "Misc. utilities" => "shared_utilities.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,
-    "Contribution guide" => "Contributing.md",
+    "Contributor guide" => "contributing.md",
 ]
 
 mathengine = MathJax(

docs/src/Contributing.md

@@ -0,0 +1,98 @@
+# Running on GPU or with MPI
+
+ClimaLand.jl is designed to run on either CPU or GPU, and to be compatible with MPI.
+This section will explain how to select the architecture you want to run your simulation on.
+
+The CliMA ecosystem uses [ClimaComms.jl](https://github.com/CliMA/ClimaComms.jl)
+to control which architecture to run on, and related internals are handled within that package.
+This isolation makes specifying the architecture to use relatively simple.
+
+ClimaComms.jl introduces two concepts that we utilize to define the architecture
+to run a simulation on: the `device` and the `context`.
+
+The `device` specifies whether we want to run on CPU or GPU.
+The `context` contains information about the device, and also defines whether we
+want to run on an individual processor or distributedly with MPI.
+Since the device is contained within the context's data structure, when we construct
+these objects in ClimaLand we simply refer to them as the context.
+
+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/).
+
+## Choosing the architecture within a script/REPL
+
+To select the architecture to use within a script or the REPL, we will
+explicitly set the device and context to use. The context is then
+automatically used for the rest of the session.
+
+### Running on CPU (without MPI)
+
+```
+context = ClimaComms.SingletonCommsContext(ClimaComms.CPUSingleThreaded())
+```
+
+### Running on GPU (without MPI)
+
+```
+context = ClimaComms.SingletonCommsContext(ClimaComms.CUDADevice())
+```
+
+### Running with MPI
+
+On CPU:
+```
+context = ClimaComms.MPICommsContext(ClimaComms.CPUSingleThreaded())
+```
+
+On GPU:
+```
+context = ClimaComms.MPICommsContext(ClimaComms.CUDADevice())
+```
+
+### Default context and device
+
+We can also set the context using the following default constructor. This is useful for runs where
+we want to run on CPU and don't have MPI available, perhaps for example in simple local runs.
+```
+context = ClimaComms.context()
+```
+
+This constructor will by default run on CPU without MPI, unless the relevant environment variables are set.
+See the section below for more details about controlling the architecture with environment variables.
+
+## Choosing the architecture via environment variables
+
+ClimaComms checks two environment variables to determine which device and context to use: `CLIMACOMMS_DEVICE` and
+`CLIMACOMMS_CONTEXT`. Setting these environment variables provides an alternative to defining the device and context
+explicitly, as was done above.
+
+### Running on CPU (without MPI)
+
+```
+ENV["CLIMACOMMS_DEVICE"] = "CPU"
+ENV["CLIMACOMMS_CONTEXT"] = "SINGLETON"
+```
+
+### Running on GPU (without MPI)
+
+```
+ENV["CLIMACOMMS_DEVICE"] = "CUDA"
+ENV["CLIMACOMMS_CONTEXT"] = "SINGLETON"
+```
+
+### Running with MPI
+
+On CPU:
+```
+ENV["CLIMACOMMS_DEVICE"] = "CPU"
+ENV["CLIMACOMMS_CONTEXT"] = "MPI"
+```
+
+On GPU:
+```
+ENV["CLIMACOMMS_DEVICE"] = "CUDA"
+ENV["CLIMACOMMS_CONTEXT"] = "MPI"
+```

docs/src/architectures.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for contributing to `ClimaLand`! We encourage Pull Requests (PRs).
+Please do not hesitate to ask questions, or to open issues if something seems amiss
+or you'd like a new feature.
+
+## Some useful tips
+- When developing code it's best to work on a branch off of the most recent main.
+This can be done by running the following commands, where "initials" corresponds to the first and last initial of the person starting the branch.
+```
+git checkout main
+git pull
+git checkout -b initials/branch_name
+```
+
+- Make sure you add tests for your code in `test/`, appropriate documentation in `docs/`,
+  and descriptive inline comments throughout the code.
+  All exported functions and structs must have docstrings.
+- When your PR is ready for review, clean up your commit history by squashing to 1 commit per PR
+  and make sure your code is current with `ClimaLand.jl` main by rebasing.
+
+## Continuous integration
+
+After rebasing your branch, you can ask for review. Fill out the template and
+provide a clear summary of what your PR does. When a PR is created or
+updated, a set of automated tests are run on the PR in our continuous
+integration (CI) system.
+
+ClimaLand.jl's continuous integration contains multiple automated tests,
+which are described below. All of these must pass for a PR to be eligible
+to merge into the main branch.
+
+### Unit testing
+
+Unit tests are defined in the `test/` folder, and are all listed in the file
+`test/runtests.jl`, which allows them to easily be called together.
+In our CI, these tests are run via Github Actions on a variety of operating
+systems and Julia versions. We also use downgrade tests to check the lower limits
+of our Julia package compat bounds, and downstream tests to verify compatibility
+with ClimaCoupler.jl.
+
+### Buildkite pipeline
+
+The buildkite pipeline contains a variety of ClimaLand simulations,
+which span the complexity of our models and domains.
+Some of these simulations have explicit checks, for example comparing
+to empirical solutions or output from external codebases, while others
+test that the simulation can run without error.
+
+This pipeline also runs our unit test suite on GPU and with MPI,
+to ensure all of our source code is compatible with those setups.
+
+### Formatting check
+
+The `JuliaFormatter` test checks if the PR is correctly formatted according
+to `.dev/climaformat.jl`. To ensure that this is the case, we recommend running
+`julia --project=.dev .dev/climaformat.jl` on each PR before requresting review.
+This command will apply the formatter and any changes it detects are necessary.
+
+### Documentation
+
+The `Documentation` test rebuilds the documentation for the PR and checks if the docs
+are consistent and generate valid output.

docs/src/contributing.md

@@ -4,15 +4,20 @@ When running a ClimaLand simulations, you have multiple options on how to write
 You may want all variables, or just a selected few.
 You may want instantaneous values, at the highest temporal and spatial resolution, or you may want to get averages at hourly or monthly time scale, and integrate in space
 (for example soil moisture from 0 to 1 meter depth).
-You may want to get more specific reductions, such as 10 days maximums, or compute a new variables that is a function of others.
-You may want to get your outputs in memory in a Julia Dict, or write them in a NetCDF file.
+You may want to get more specific reductions, such as 10 days maximums, or compute a new variables as a function of others.
+You may want to get your outputs in memory in a Julia dictionary, or write them in a NetCDF file.
 
 This is where ClimaLand Diagnostics comes in for users.
 
 In this documentation page, we first explain how to use default diagnostics and what are the defaults, and then explain how to define your own diagnostics for more advanced users.
 
 ## Default Diagnostics
 
+Diagnostics refer to output saved during the simulation, which may be prognostic or diagnostic variables.
+Note that this is different from checkpointing the simulation, which has specific requirements.
+For information about checkpointing and restarting simulations, please see the page titled
+[Restarting Simulations](@ref).
+
 Once you have defined your model and are ready to run a simulation, and after adding ClimaDiagnostics (using ClimaDiagnostics),
  you can add default diagnostics to it by doing the following steps:
 
@@ -161,4 +166,3 @@ viz.plot!(fig, var) # creates an axis inside fig, and plot your var in it.
 
 CairoMakie.save(fig) # saves the figure in current working directory
 ```
-

docs/src/diagnostics/users_diagnostics.md

@@ -1,17 +1,17 @@
 # Getting Started
 
-## For Users
+## Installation of Julia and ClimaLand
 
-### Installation
+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 install the ClimaLand package by doing:
+Then, you can launch a [Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/) and install the
+ClimaLand.jl package by running:
 
 ```julia
-julia> ] # Enter Package REPL mode
-Pkg> add ClimaLand # Install ClimaLand
-Pkg> # Go back to Julia REPL mode
-Julia> using ClimaLand
+julia> using Pkg
+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.
@@ -59,4 +59,3 @@ Where modules are shown in red, functions are shown in blue, and types are shown
 
 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).
-

docs/src/getting_started.md

@@ -14,41 +14,30 @@ Markdown.parse(String(take!(io)))
 
 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)).
+Details about the CliMA project can be found on the [project website](https://clima.caltech.edu/).
 
-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 can be run coupled ("online") with these other components via [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl),
+or it can be run as a standalone model, via prescribed meteorological data ("offline").
 
-ClimaLand library, described in this documentation, is written in the Julia
+The 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
+## This documentation includes information about:
+- How to run your first ClimaLand simulation
+- A series of tutorials explaining ClimaLand models and physics
+- The structure of ClimaLand models and code
+- How to analyze model output, calibrate models using CliMA's pipeline, and restart simulations
+- and more!
 
-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⁻¹        |
+## Important Links
 
+- [CliMA GitHub Organisation](https://github.com/CliMA)
+- [Julia Homepage](https://julialang.org)
+- [Julia Manual](https://docs.julialang.org/en/v1/manual/getting-started/)