Merge pull request #76 from TUM-PIK-ESM/bg/update-readme

bgroenks96 · web-flow · commit 35571d0e1716 · 2026-02-11T09:16:00.000+01:00
Add quickstart section to README
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
     <img alt="code style: runic" src="https://img.shields.io/badge/code_style-%E1%9A%B1%E1%9A%A2%E1%9A%BE%E1%9B%81%E1%9A%B2-black.svg?style=flat-square">
 </a>
 
-[Terrarium.jl](https://tum-pik-esm.github.io/Terrarium.jl/dev) is a new and upcoming framework that aims to faciliate hybrid physics- and data-driven land modeling across multiple spatial and temporal scales. We envision Terrarium to be part of a new generation of Earth system component models that combine modularity, interactivity, GPU-compability and auto-differentiability (AD) for seamless integration of process-based and data-driven model components in both global and regional scale simulations.
+[Terrarium.jl](https://tum-pik-esm.github.io/Terrarium.jl/dev) is a new and upcoming framework for hybrid physics- and data-driven land modeling across spatial and temporal scales. We envision Terrarium to be part of a new generation of Earth system component models that combine modularity, interactivity, GPU-compability and auto-differentiability (AD) for seamless integration of process-based and data-driven model components in both global and regional scale simulations.
 
 Terrarium is being developed alongside [SpeedyWeather.jl](https://github.com/SpeedyWeather/SpeedyWeather.jl) and [Oceananigans.jl](https://github.com/CliMA/Oceananigans.jl) as the land component of a new, user-friendly, and fully GPU/AD-compatible Earth System Model in the Julia programming language.
 
@@ -37,14 +37,6 @@ It is important to emphasize, however, what Terrarium is not:
 - Terrarium is **not “just another model”**. We do not intend for users to simply download our model products and cite our papers. We want users to directly interact with our model, ideally running their own simulations and writing their own code.
 - Terrarium is **not a monolithic model**. Modularity and extensibility are core to our vision. Terrarium provides a library of models, process implementations, and numerical tools which users can use to build their own simulations. We will provide guidance and a set of well-tested and stable model configurations, but we encourage users to experiment and push the limits of what those models can do.
 
-## Why Oceananigans?
-It might initially seem strange that a land model would be built on top of a framework for ocean modeling. There are, however, some key advantages in doing so:
-
-
-1. Firstly, like ocean models, land models are commonly implemented using finite difference and/or finite volume method (FDM/FVM) to approximate spatial gradients in mass and energy conservation laws. Oceananigans provides state-of-the-art tools for FVM simulation in Julia, with a focus on geophysical applications, which aligns well with our goals. Like most land models, Terrarium will initially focus on 1D column modeling; however, using Oceananigans affords us the possibility of very feasibly expanding to 2D and 3D simulations in the future!
-2. Secondly, the numerical operators provided by Oceananigans are built to be both auto-differentiable and GPU-compatible out-of-the-box, which means that Terrarium can inherit these capabilities almost “for free”.
-3. Finally, and perhaps most importantly, we believe in the vision pioneered by the [Climate Modeling Alliance](https://clima.caltech.edu/) and the Oceananigans team for the development of a new generation of Earth System Models that are open, accessible, interactive, and capable of learning from data in ways that go beyond traditional data assimilation.
-
 ## Installation
 
 Terrarium is still in an early prototype stage and is not yet registered as a package in the Julia General registry.
@@ -59,7 +51,52 @@ or clone the repository and start hacking directly!
 
 ## Quick start
 
-Coming soon!
+A natural first step with `Terrarium` is to set up and run your very first `SoilModel`. This represents a standalone model of transient heat, water, and carbon transport over a particular choice of `grid`. We start by chosing a `ColumnGrid` which represents one or more laterally independent vertical columns:
+
+```julia
+using Terrarium
+
+# Set up a SoilModel on a ColumnGrid with 10 vertical soil layers that will run on the CPU with 32-bit precision
+num_columns = 1
+arch = CPU()
+grid = ColumnGrid(arch, Float32, ExponentialSpacing(N=10), num_columns)
+model = SoilModel(grid)
+# Prescribe a constant surface temperature of 1°C
+bcs = PrescribedSurfaceTemperature(:T_ub, 1.0)
+integrator = initialize(model, ForwardEuler(eltype(grid)), boundary_conditions = bcs)
+# Run the simulation forward for 10 model days
+@time run!(integrator, period = Day(10))
+```
+
+That's it! You already succesfully ran a (very simple) simulation with Terrarium!
+
+Note that setting `num_columns = 1` here corresponds to a point simulation for a single vertical column. However, we can easily scale this up by set `num_columns` to any positive integer (up to the memory limit of your system, of course).
+
+We can also easily adapt this code to run a *global* simulation over a suitable spatial grid. For this, we'll need to have [`RingGrids`](https://github.com/SpeedyWeather/RingGrids.jl) installed (or import it directly from Terrarium with `using Terrarium.RingGrids`). Optionally, if a GPU is available and [CUDA.jl](https://github.com/JuliaGPU/CUDA.jl) is installed in the current project or global Julia environment, we can accelerate the global simulation by simply changing `CPU` to `GPU`:
+
+```julia
+using RingGrids: FullGaussianGrid
+using CUDA # needs to be seaprately installed
+
+rings = FullGaussianGrid(8) # Gaussian grid with 16 lattitudinal rings (512 points, ~9.5˚)
+arch = GPU() # run on the GPU!
+grid = ColumnRingGrid(arch, Float32, ExponentialSpacing(N=10), rings)
+model = SoilModel(grid)
+# Prescribe a constant surface temperature of 1°C
+bcs = PrescribedSurfaceTemperature(:T_ub, 1.0)
+integrator = initialize(model, ForwardEuler(eltype(grid)), boundary_conditions = bcs)
+# Run the simulation forward for 10 model days
+@time run!(integrator, period = Day(10))
+```
+and voila! We have just run a GPU-accelerated, global-scale simulation of soil thermal dynamics with minimal additional effort. While more realistic simulations are of course more involved, this simple example demonstrates the core of what we aim to accomplish with Terrarium; a fast, user-friendly, and highly adaptable land model that can easily be configured to run on local, regional, and global scales.
+
+## Why Oceananigans?
+It might initially seem strange that a land model would be built on top of a framework for ocean modeling. There are, however, some key advantages in doing so:
+
+
+1. Firstly, like ocean models, land models are commonly implemented using finite difference and/or finite volume method (FDM/FVM) to approximate spatial gradients in mass and energy conservation laws. Oceananigans provides state-of-the-art tools for FVM simulation in Julia, with a focus on geophysical applications, which aligns well with our goals. Like most land models, Terrarium will initially focus on 1D column modeling; however, using Oceananigans affords us the possibility of very feasibly expanding to 2D and 3D simulations in the future!
+2. Secondly, the numerical operators provided by Oceananigans are built to be both auto-differentiable and GPU-compatible out-of-the-box, which means that Terrarium can inherit these capabilities almost “for free”.
+3. Finally, and perhaps most importantly, we believe in the vision pioneered by the [Climate Modeling Alliance](https://clima.caltech.edu/) and the [NumericalEarth](https://github.com/NumericalEarth/) projects for the development of a new generation of Earth System Models that are open, accessible, interactive, and capable of learning from data in a multitude of ways that go beyond traditional data assimilation.
 
 ## Contributing
 
