Skip to content

Update README.md #1311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+10 −17
Open

Update README.md #1311

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
27 changes: 10 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,10 @@ component) or standalone (single component) modes. </strong>
# Introduction

This is the repository of the CliMA land model code. Here are some notable features:
- ClimaLand has a modular design, models can be run as standalone (e.g., soil moisture only) or integrated (e.g., soil moisture and energy AND canopy AND snow, etc.)
- ClimaLand has a modular design, models can be run as standalone (e.g., soil moisture/energy only) or integrated (e.g., soil moisture/energy AND canopy AND snow, etc.)
- ClimaLand can simulate single columns, regional boxes, and global runs
- ClimaLand is CPU and GPU compatible
- ClimaLand welcome contributions: please feel free to reach out to us with questions about how to get started, create a branch, and extend our code. For example, a modeler might want to test a new stomatal conductance model.
- ClimaLand provides APIs and UIs at multiple levels.
- ClimaLand welcomes contributions! Please feel free to reach out to us with questions about how to get started, create a branch, and extend our code.

## Installation

Expand All @@ -40,36 +39,30 @@ julia> using Pkg
julia> Pkg.add(ClimaLand)
```

Which is equivalent to doing

```Julia
julia> ] # typing the ] key with go into package REPL mode
pkg> add ClimaLand
```

You are now ready to use `ClimaLand.jl`. To get started, we recommend reading the [documentation](https://clima.github.io/ClimaLand.jl/dev/).
You are now ready to use `ClimaLand.jl`. To get started, we recommend reading the [documentation](https://clima.github.io/ClimaLand.jl/stable/).

## Models
Copy link
Member

Choose a reason for hiding this comment

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

I believe @AlexisRenchon wants to add a few lines of code here showing how easy it is to setup and run a simulation! If so, that would be nice to include - either with him taking over this PR or in a followup PR.

(the changes you made look good, so I approved them)

Copy link
Member

Choose a reason for hiding this comment

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

I will make a follow up PR!

Copy link
Member Author

Choose a reason for hiding this comment

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

I have a PR open to set up and run a simple soil simulation in getting_started.md - maybe we can just point to that? #1267

Copy link
Member

Choose a reason for hiding this comment

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

I think it's good for now to point to it.

For a readme, it seems a bit long, there's 100+ lines?

I like how oceananigans readme has a simulation setup in a few lines

using Oceananigans
grid = RectilinearGrid(CPU(), size=(128, 128), x=(0, 2π), y=(0, 2π), topology=(Periodic, Periodic, Flat))
model = NonhydrostaticModel(; grid, advection=WENO())
ϵ(x, y) = 2rand() - 1
set!(model, u=ϵ, v=ϵ)
simulation = Simulation(model; Δt=0.01, stop_time=4)
run!(simulation)

I think to have something equivalent we would need a even higher level API (with more defaults setup) and possibly less dependency via a module?

But that's just a thought. I am not suggesting to do anything for now. Pointing to the simple example in the docs is good! We can discuss further if it would be useful or not to have a even higher level API. Maybe MC3 workshop will tell if users want that.


In our code base, a "model" define a set of prognostic variables which must be timestepped. The equations which govern the time evolution likely contain parameters and are informed by parameterization and physical domain choices. Any ClimaLand model contains all of the information needed to evaluate these equations. Below are the current models we support:

<strong> Component Models: </strong>

- RichardsModel <: AbstractSoilModel <: AbstractModel (runnable only in standalone mode)
- `RichardsModel`: Soil model option; runnable only in standalone mode

- EnergyHydrologyModel <: AbstractSoilModel <: AbstractModel (runnable in standalone mode, or as part of a land model)
- `EnergyHydrology`: Soil model option; runnable in standalone mode, or as part of an integrated model

- CanopyModel <: AbstractVegetationModel <: AbstractModel (runnable in standalone mode, or as part of a land model)
- `CanopyModel`: runnable in standalone mode, or as part of an integrated model

- SnowModel <: AbstractSnowModel <: AbstractModel (runnable in standalone mode, or as part of a land model)
- `SnowModel`: runnable in standalone mode, or as part of an integrated model

<strong> Combined Models: </strong>

- SoilCanopyModel <: AbstractLandModel <: AbstractModel (an example of a land model, made of individual component models which are solved simultaneously but taking into account interactions between the components)
- `SoilCanopyModel`: an integrated model made of individual component models `EnergyHydrology` + `CanopyModel`
- `LandModel`: an integrated model made of individual component models `EnergyHydrology` + `CanopyModel` + `SnowModel` + `SoilCO2Model`

## Notes

Recommended Julia Version: Stable release v1.11.1. CI tests Julia v1.10 and 1.11.
Recommended Julia Version: Stable release v1.11.x. CI tests Julia v1.10 and 1.11.

ClimaLand.jl is a different model from the original CliMA Land,
which aims to utilize remote sensing data through more complex canopy RT
Expand Down
Loading