Skip to content

Commit 0252d09

Browse files
s-polljjokella
s-poll
and
jjokella
authored
Docs release (#85)
* initialize docs * docs: update md-files pathes * docs: remove src_browser * docs: remove src_browser from workflow * docs: seperate build and deploy * docs: do not check out submodules * docs: change branch in config.yml * docs: modify docs.yml * docs: change to ubuntu-24.04 * Revert "docs: change to ubuntu-24.04" This reverts commit d8c3e98. * docs: transfer info from README into docs * docs: fix reference * dos: fix cross-reference * dos: revise tip/note * update README * docs: trigger docs workflow only for master * README update and tip-o in docs * fix cross reserence at README * doc: add PDAF references in README and documentation sidebar --------- Co-authored-by: Johannes Keller <jo.keller@fz-juelich.de>
1 parent 81352da commit 0252d09

File tree

13 files changed

+515
-284
lines changed

13 files changed

+515
-284
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
# - 'docs-**'
8+
pull_request:
9+
branches:
10+
- 'master'
11+
12+
env:
13+
BASE_URL: /${{ github.event.repository.name }}
14+
15+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
16+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
with:
27+
submodules: false
28+
sparse-checkout: |
29+
.github
30+
docs
31+
32+
- name: Set up Python 3.12
33+
uses: actions/setup-python@v5
34+
with:
35+
python-version: 3.12
36+
cache: 'pip'
37+
38+
- name: Install dependencies
39+
run: pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt
40+
41+
- name: Build TSMP2 doc homepage
42+
working-directory: ./docs
43+
run: |
44+
make clean docs
45+
46+
- name: Upload documentation artifacts
47+
uses: actions/upload-pages-artifact@v3
48+
with:
49+
path: "docs/_build/html"
50+
name: tsmp2_docs
51+
52+
deploy:
53+
if: github.event_name != 'pull_request'
54+
needs: build
55+
runs-on: ubuntu-latest
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.deployment.outputs.page_url }}
59+
60+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
61+
permissions:
62+
pages: write # to deploy to Pages
63+
id-token: write # to verify the deployment originates from an appropriate source
64+
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4
69+
with:
70+
artifact_name: tsmp2_docs

‎README.md‎

Lines changed: 19 additions & 284 deletions
Original file line numberDiff line numberDiff line change
@@ -1,296 +1,31 @@
1-
## Quickstart
2-
3-
> [!TIP]
4-
> `build_tsmp2.sh` is a lightweight shell-script calling the CMake-based build-system. During execution of `build_tsmp2.sh`, the executed CMake-command is printed out. For advanced build use-cases, users can modify the outputted CMake command or directly head over to [Building TSMP2 with CMake](#Building-TSMP2-with-CMake).
5-
6-
1. Clone this repository.
7-
8-
```bash
9-
git clone https://github.com/HPSCTerrSys/TSMP2.git
10-
export TSMP2_DIR=$(realpath TSMP2)
11-
cd $TSMP2_DIR
12-
```
13-
14-
2. Build model components with TSMP2 framework
15-
16-
To build a model component one need to activate the component model `--<COMP>`. The options are not case-sensitive and do not need to be in an specific order.
17-
18-
> [!NOTE]
19-
> The component models (git submodules) are cloned during the execution of `build_tsmp2.sh`. If the component model (`models/<COMP>`) are already exists, the user is asked if the folder should be overwritten or not. If you do want to use the default model component source codes, one can use the option `--<COMP_SRC>`.
20-
21-
22-
```bash
23-
# to see options
24-
./build_tsmp2.sh --help
25-
26-
# ICON-eCLM-ParFlow
27-
./build_tsmp2.sh --ICON --eCLM --PARFLOW
28-
29-
# eCLM-ParFlow
30-
./build_tsmp2.sh --eCLM --PARFLOW
31-
32-
# ICON-eCLM
33-
./build_tsmp2.sh --ICON --eCLM
34-
35-
# eCLM-PDAF
36-
./build_tsmp2.sh --eCLM --PDAF
37-
38-
# ICON (with source code)
39-
./build_tsmp2.sh --ICON --ICON_SRC ${ICON_SRC}
40-
41-
# ParFlow on Marvin (Uni Bonn)
42-
./build_tsmp2.sh --ParFlow --env env/uni-bonn.gnu.openmpi
43-
```
44-
45-
46-
## Building TSMP2 with CMake
47-
48-
> [!NOTE]
49-
> For experienced users.
50-
> The result of the following commands may be different from the Quickstart above, most notably because the branches/commits in the `git clone` commands are not kept in sync with those in the `build_tsmp2.sh` script.
51-
> The [Quickstart](#Quickstart) is the tested and supported method.
52-
53-
1. Clone this repository.
54-
55-
```bash
56-
git clone https://github.com/HPSCTerrSys/TSMP2.git
57-
export TSMP2_DIR=$(realpath TSMP2)
58-
cd $TSMP2_DIR
59-
```
60-
61-
2. Load the environment variables required for the build.
62-
63-
```bash
64-
source env/jsc.2024_Intel.sh
65-
```
66-
67-
3. Specify build and install directories.
68-
69-
```bash
70-
# Name of the coupled model (e.g. ICON-eCLM, CLM3.5-COSMO-ParFlow, CLM3.5-ParFlow, CLM3.5-ParFlow-PDAF)
71-
MODEL_ID="ICON-eCLM-ParFlow"
72-
73-
# Build artifacts will be generated in this folder. It can be deleted after build.
74-
BUILD_DIR="./bld/${SYSTEMNAME^^}_${MODEL_ID}"
75-
76-
# Model executables and libraries will be installed here
77-
INSTALL_DIR="./bin/${SYSTEMNAME^^}_${MODEL_ID}"
78-
79-
# Create build and install directories
80-
mkdir -p ${BUILD_DIR} ${INSTALL_DIR}
81-
```
82-
83-
4. Download the OASIS3-MCT coupling library and the component models
84-
you wish to use. You can check out the supported submodule commits
85-
using
86-
87-
```bash
88-
# eCLM
89-
git submodule update --init -- models/eCLM
90-
91-
# ICON
92-
git submodule update --init -- models/icon
93-
94-
# ParFlow
95-
git submodule update --init -- models/parflow
96-
97-
# ParFlow (PDAF-patched)
98-
git submodule update --init -- models/parflow_pdaf
99-
100-
# CLM3.5
101-
git submodule update --init -- models/CLM3.5
1+
# Terrestrial Systems Modeling Platform v2 (TSMP2)
1022

103-
# COSMO5.01
104-
git submodule update --init -- models/cosmo5.01_fresh
3+
[![docs](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml)
4+
[![build](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/CI.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/CI.yml)
5+
[![doi](https://img.shields.io/badge/rsd-tsmp2-00a3e3)](https://helmholtz.software/software/tsmp2)
1056

106-
# OASIS3-MCT (required for coupled models)
107-
git submodule update --init -- models/oasis3-mct
7+
## Introduction
1088

109-
# PDAF
110-
git submodule update --init -- models/pdaf
111-
```
9+
The Terrestrial System Modeling Platform v2 (TSMP2, https://www.terrsysmp.org) is an open source scale-consistent, highly modular, massively parallel regional Earth system model. TSMP essentially consists of an interface which couples dedicated versions of the ICOsahedral Nonhydrostatic ([ICON](https://www.icon-model.org/)) atmospheric model in NWP or climate mode, the encore Community Land Model ([eCLM](https://hpscterrsys.github.io/eCLM)), and the hydrologic model [ParFlow](https://www.parflow.org) through the [OASIS3](https://oasis.cerfacs.fr/en/)-[MCT](https://www.mcs.anl.gov/research/projects/mct/) coupler.
11210

113-
If you wish to use alternative (possibly unsupported) commits of
114-
component models, clone them explicitly. Then save the full path to
115-
each model source code to `<model-name>_SRC`. Examples are given
116-
below:
11+
TSMP allows for a physically-based representation of transport processes of mass, energy and momentum and interactions between the different compartments of the geo-ecosystem across scales, explicitly reproducing feedbacks in the hydrological cycle from the groundwater into the atmosphere.
11712

118-
```bash
119-
## NOTE: Download only the component models that you need! ##
13+
TSMP-PDAF describes the build commands of TSMP that can introduce data
14+
assimilation for an ensemble of TSMP simulations using the Parallel
15+
Data Assimilation Framework
16+
([PDAF](https://pdaf.awi.de/trac/wiki)). For more information, see the
17+
[documentation of TSMP-PDAF](https://hpscterrsys.github.io/pdaf).
12018

121-
# eCLM
122-
git clone -b beta-0.2 https://github.com/HPSCTerrSys/eCLM.git models/eCLM
123-
eCLM_SRC=`realpath models/eCLM`
19+
TSMP development has been driven by groups within the [Center for High-Performance Scientific Computing in Terrestrial Systems](http://www.hpsc-terrsys.de) (HPSC-TerrSys).
12420

125-
# ICON
126-
git clone https://icg4geo.icg.kfa-juelich.de/spoll/icon2.6.4_oascoup.git models/icon
127-
ICON_SRC=`realpath models/icon`
128-
129-
# ParFlow
130-
git clone https://github.com/parflow/parflow.git models/parflow
131-
PARFLOW_SRC=`realpath models/parflow`
132-
133-
# ParFlow (PDAF-patched)
134-
git clone -b v3.13.0-pdaf https://github.com/HPSCTerrSys/parflow models/parflow_pdaf
135-
PARFLOW_SRC=`realpath models/parflow_pdaf`
136-
137-
# CLM3.5
138-
git clone -b tsmp-patches-v0.1 https://github.com/HPSCTerrSys/CLM3.5.git models/CLM3.5
139-
CLM35_SRC=`realpath models/CLM3.5`
140-
141-
# COSMO5.01
142-
git clone -b tsmp-oasis https://icg4geo.icg.kfa-juelich.de/ModelSystems/tsmp_src/cosmo5.01_fresh.git models/cosmo5.01_fresh
143-
COSMO_SRC=`realpath models/cosmo5.01_fresh`
144-
145-
# OASIS3-MCT (required for coupled models)
146-
git clone -b tsmp-patches-v0.1 https://icg4geo.icg.kfa-juelich.de/ExternalReposPublic/oasis3-mct models/oasis3-mct
147-
OASIS_SRC=`realpath models/oasis3-mct`
148-
149-
# PDAF
150-
git clone -b PDAF_V2.2.1-tsmp https://github.com/HPSCTerrSys/pdaf.git models/pdaf
151-
PDAF_SRC=`realpath models/pdaf`
152-
```
153-
154-
5. Run CMake configure step for the model combination that you wish to build. The
155-
examples below show different CMake configure commands for each model combination.
156-
157-
```bash
158-
#
159-
# The component source is searched in models/component by default but there is also the possibility to choose the path to the source code of components with -D<COMP>_SRC=${<COMP>_SRC}. OASIS is taken by default when coupled models are chosen.
160-
#
161-
162-
# ICON-eCLM
163-
cmake -S . -B ${BUILD_DIR} \
164-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
165-
-DeCLM=ON \
166-
-DICON=ON
167-
168-
# eCLM-ParFlow
169-
cmake -S . -B ${BUILD_DIR} \
170-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
171-
-DeCLM=ON \
172-
-DPARFLOW_SRC=ON
173-
174-
# ICON-eCLM-ParFlow
175-
cmake -S . -B ${BUILD_DIR} \
176-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
177-
-DeCLM=ON \
178-
-DICON=ON \
179-
-DPARFLOW=ON
180-
181-
# CLM3.5-COSMO5.01-ParFlow
182-
cmake -S . -B ${BUILD_DIR} \
183-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
184-
-DCLM35=ON \
185-
-DCOSMO=ON \
186-
-DPARFLOW=ON
187-
188-
# CLM3.5-ParFlow
189-
cmake -S . -B ${BUILD_DIR} \
190-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
191-
-DCLM35=ON \
192-
-DPARFLOW=ON
193-
194-
# CLM3.5-COSMO5.01
195-
cmake -S . -B ${BUILD_DIR} \
196-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
197-
-DCLM35=ON \
198-
-DCOSMO=ON
199-
200-
#
201-
# For standalone models
202-
# pass the component model name (i.e. -D<model-name>=ON).
203-
#
204-
205-
# CLM3.5 standalone
206-
cmake -S . -B ${BUILD_DIR} \
207-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
208-
-DCLM35=ON
209-
210-
# eCLM standalone
211-
cmake -S . -B ${BUILD_DIR} \
212-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
213-
-DeCLM=ON
214-
215-
# ParFlow standalone
216-
cmake -S . -B ${BUILD_DIR} \
217-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
218-
-DPARFLOW=ON
219-
220-
#
221-
# For TSMP-PDAF builds, add -PDAF=ON
222-
#
223-
224-
# CLM3.5-PDAF
225-
cmake -S . -B ${BUILD_DIR} \
226-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
227-
-DCLM35=ON \
228-
-DPDAF=ON
229-
230-
# CLM3.5-ParFlow-PDAF
231-
cmake -S . -B ${BUILD_DIR} \
232-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
233-
-DCLM35=ON \
234-
-DPARFLOW=ON \
235-
-DPDAF=ON
236-
237-
# eCLM-PDAF
238-
cmake -S . -B ${BUILD_DIR} \
239-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
240-
-DeCLM=ON \
241-
-DPDAF=ON
242-
243-
# eCLM-ParFlow-PDAF
244-
cmake -S . -B ${BUILD_DIR} \
245-
-DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
246-
-DeCLM=ON \
247-
-DPARFLOW=ON \
248-
-DPDAF=ON
249-
250-
```
251-
252-
6. Build and install the models.
253-
254-
```bash
255-
cmake --build ${BUILD_DIR}
256-
cmake --install ${BUILD_DIR}
257-
```
258-
259-
### Resuming a failed build
260-
261-
When the build gets interrupted or fails for some reason, it can be resumed by simply running Step 6:
262-
263-
```bash
264-
cmake --build ${BUILD_DIR}
265-
cmake --install ${BUILD_DIR}
266-
```
267-
268-
Note that this works only if the required environment variables are already set. If you are resuming
269-
the build from a fresh terminal session, first you need to run `source env/jsc.2023_Intel.sh` (Step 2), specify `BUILD_DIR` (Step 3) and set `<model-name>_SRC` (Step 4) before you can run Step 6.
270-
271-
### Rebuilding specific component models
272-
273-
TSMP2 can rebuild a specific component model via the `cmake --build ${BUILD_DIR} --target ${MODEL}` command.
274-
This may be useful when you need to recompile a component model that has been modified or updated.
21+
## Quickstart
27522

276-
```bash
277-
# Rebuilding examples
23+
Please see [quickstart section](./docs/users_guide/building_TSMP2/Quickstart.md) for guided steps on how the model can be build.
27824

279-
cmake --build ${BUILD_DIR} --target eCLM && cmake --install ${BUILD_DIR} # Rebuilds eCLM
280-
cmake --build ${BUILD_DIR} --target ICON && cmake --install ${BUILD_DIR} # Rebuilds ICON
281-
cmake --build ${BUILD_DIR} --clean-first --target ParFlow && cmake --install ${BUILD_DIR} # Does a clean rebuild of ParFlow
282-
```
25+
## Usage / Documentation
28326

284-
Only component models specified during CMake configure step (see Step 5) can be rebuilt. For instance, if you
285-
configured TSMP2 to build `eCLM-ParFlow`, then rebuilding `ICON` would of course be not possible.
27+
Please check the documentation at https://hpscterrsys.github.io/TSMP2
28628

287-
The list below shows all component models supported by TSMP2. To rebuild a component model(s),
288-
run one or more commands below, wait until the build succeeds, then finally run
289-
`cmake --install ${BUILD_DIR}` so that the generated libraries and executables are copied to `${INSTALL_DIR}`.
29+
## License
30+
TSMP is open source software and is licensed under the [MIT-License](https://github.com/HPSCTerrSys/TSMP2/blob/master/LICENSE.txt).
29031

291-
- `cmake --build ${BUILD_DIR} --target eCLM`
292-
- `cmake --build ${BUILD_DIR} --target ParFlow`
293-
- `cmake --build ${BUILD_DIR} --target ICON`
294-
- `cmake --build ${BUILD_DIR} --target OASIS3_MCT`
295-
- `cmake --build ${BUILD_DIR} --target CLM3_5`
296-
- `cmake --build ${BUILD_DIR} --target COSMO5_1`

‎docs/INDEX.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# TSMP2 Documentation
2+
3+
```{important}
4+
**Welcome!** You are viewing the first version of the documentation for TSMP2. This is a living document, which means it will be continuously updated and improved. Please check back regularly for the latest information and updates.
5+
```
6+
7+
```{tableofcontents}
8+
```

0 commit comments

Comments
 (0)