From d1046ae6526732ae04e8c61811cb53461eb20ae7 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Fri, 18 Jul 2025 17:23:59 +0200 Subject: [PATCH 01/19] initialize docs --- .github/workflows/docs.yml | 57 ++++++++++++++++++++++ docs.yml | 56 +++++++++++++++++++++ docs/INDEX.md | 8 +++ docs/Makefile | 15 ++++++ docs/README.md | 17 +++++++ docs/_config.yml | 40 +++++++++++++++ docs/_toc.yml | 23 +++++++++ docs/building_TSMP2/BuildingTSMP2wCMake.md | 5 ++ docs/building_TSMP2/Quickstart.md | 5 ++ docs/building_TSMP2/README.md | 3 ++ docs/introduction_to_TSMP2/README.md | 5 ++ docs/introduction_to_TSMP2/introduction.md | 16 ++++++ docs/requirements.txt | 5 ++ 13 files changed, 255 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs.yml create mode 100644 docs/INDEX.md create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/_config.yml create mode 100644 docs/_toc.yml create mode 100644 docs/building_TSMP2/BuildingTSMP2wCMake.md create mode 100644 docs/building_TSMP2/Quickstart.md create mode 100644 docs/building_TSMP2/README.md create mode 100644 docs/introduction_to_TSMP2/README.md create mode 100644 docs/introduction_to_TSMP2/introduction.md create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..f9fdd07 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,57 @@ +name: Deploy Docs + +on: + push: + branches: + - master + - 'docs-**' + +env: + BASE_URL: /${{ github.event.repository.name }} + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy-docs: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + permissions: + pages: write + id-token: write + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.11 + uses: actions/setup-python@v5 + with: + python-version: 3.11 + cache: 'pip' + + - name: Install dependencies + run: pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt + + - name: Build eCLM doc homepage + working-directory: ./docs + run: | + make clean docs + + - name: Build eCLM Source Code browser + working-directory: ./docs + run: | + make src-browser + + - name: Upload documentation artifacts + uses: actions/upload-pages-artifact@v3 + with: + path: "docs/_build/html" + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + diff --git a/docs.yml b/docs.yml new file mode 100644 index 0000000..4637cf6 --- /dev/null +++ b/docs.yml @@ -0,0 +1,56 @@ +name: Deploy Docs + +on: + push: + branches: + - master + - 'docs-**' + +env: + BASE_URL: /${{ github.event.repository.name }} + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy-docs: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + permissions: + pages: write + id-token: write + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.11 + uses: actions/setup-python@v5 + with: + python-version: 3.11 + cache: 'pip' + + - name: Install dependencies + run: pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt + + - name: Build eCLM doc homepage + working-directory: ./docs + run: | + make clean docs + + - name: Build eCLM Source Code browser + working-directory: ./docs + run: | + make src-browser + + - name: Upload documentation artifacts + uses: actions/upload-pages-artifact@v3 + with: + path: "docs/_build/html" + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 0000000..82aad47 --- /dev/null +++ b/docs/INDEX.md @@ -0,0 +1,8 @@ +# TSMP2 Documentation + +```{important} +**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. +``` + +```{tableofcontents} +``` diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..7c40135 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,15 @@ +BUILD_DIR = ./_build +SRC_DIR = ../src + +all: docs src-browser + +docs: + jupyter-book build -W -n --keep-going . + +src-browser: + ford -d $(SRC_DIR) -o $(BUILD_DIR)/html/src FORD_options.md + +.PHONY: clean + +clean: + jupyter-book clean . \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1ced8d0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# Building TSMP2 Documentation + +If you'd like to develop and/or build the TSMP2 documentation, you should: + +1. Switch to this directory: `cd docs` +2. Run `pip install -r requirements.txt` +3. (*Optional*) Edit the books source files (`*.md`) in this folder. Check out the [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) for reference. +4. Build the docs: `make clean docs`. +5. Launch the doc homepage on your default browser: `open _build/html/index.html` + +## Contributors + +We welcome and recognize all contributions. You can see a list of current contributors in the [contributors tab](https://github.com/HPSCTerrSys/TSMP2/graphs/contributors). + +## Credits + +This project is created using the excellent open source [Jupyter Book project](https://jupyterbook.org/) and the [executablebooks/cookiecutter-jupyter-book template](https://github.com/executablebooks/cookiecutter-jupyter-book). diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..6c6790e --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,40 @@ +####################################################################################### +# A default configuration that will be loaded for all jupyter books +# See the documentation for help and more options: +# https://jupyterbook.org/customize/config.html + +####################################################################################### +# Book settings +title : TSMP2 Documentation # The title of the book. Will be placed in the left navbar. +author : HPSC TerrSys # The author of the book +copyright : "2025" # Copyright year to be placed in the footer +logo : "" # A path to the book logo + +# Force re-execution of notebooks on each build. +# See https://jupyterbook.org/content/execute.html +execute: + execute_notebooks: force + +# Define the name of the latex output file for PDF builds +latex: + latex_documents: + targetname: book.tex + +sphinx: + config: + language: en + +# Information about where the book exists on the web +repository: + url: https://github.com/HPSCTerrSys/TSMP2 # Online location of your book + path_to_book: docs # Optional path to your book, relative to the repository root + branch: master # Which branch of the repository should be used when creating links (optional) + +# Add GitHub buttons to your book +# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository +html: + use_issues_button: true + use_repository_button: true + +# Do not parse these files +exclude_patterns: [README.md] diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000..02d584d --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,23 @@ +# https://hpscterrsys.github.io/TSMP2 + +format: jb-book +root: INDEX +parts: + - caption: User's Guide + chapters: + + - file: users_guide/introduction_to_TSMP2/README + title: Introduction to TSMP2 + sections: + - file: users_guide/introduction_to_TSMP2/introduction + + - file: users_guide/building_TSMP2/README + title: Building TSMP2 + sections: + - file: users_guide/building_TSMP2/Quickstart + - file: users_guide/building_TSMP2/BuildingTSMP2wCMake + + - caption: Reference + chapters: + - url: https://terrsysmp.org/ + title: TSMP webpage diff --git a/docs/building_TSMP2/BuildingTSMP2wCMake.md b/docs/building_TSMP2/BuildingTSMP2wCMake.md new file mode 100644 index 0000000..78fcdd3 --- /dev/null +++ b/docs/building_TSMP2/BuildingTSMP2wCMake.md @@ -0,0 +1,5 @@ +# Building TSMP2 with CMake + +```{warning} +Page under construction +``` diff --git a/docs/building_TSMP2/Quickstart.md b/docs/building_TSMP2/Quickstart.md new file mode 100644 index 0000000..4b49fe3 --- /dev/null +++ b/docs/building_TSMP2/Quickstart.md @@ -0,0 +1,5 @@ +# Quickstart + +```{warning} +Page under construction +``` diff --git a/docs/building_TSMP2/README.md b/docs/building_TSMP2/README.md new file mode 100644 index 0000000..100865f --- /dev/null +++ b/docs/building_TSMP2/README.md @@ -0,0 +1,3 @@ +# Building TSMP2 + + diff --git a/docs/introduction_to_TSMP2/README.md b/docs/introduction_to_TSMP2/README.md new file mode 100644 index 0000000..951395e --- /dev/null +++ b/docs/introduction_to_TSMP2/README.md @@ -0,0 +1,5 @@ +# Introduction to TSMP2 + +The Terrestrial Systems Modeling Platform (TSMP, https://www.terrsysmp.org) is a scale-consistent, highly modular, physics-based, massively parallel, and fully integrated groundwater-vegetation-atmosphere modeling framework for regional climate system modeling. TSMP is composed of the atmospheric models [ICON](https://github.com/HPSCTerrSys/icon-model_coup-oas) or COSMO, the land surface model Community Land Model ([CLM](https://github.com/HPSCTerrSys/eCLM)), and the [ParFlow](https://github.com/parflow/parflow) subsurface-surface hydrological model, coupled using OASIS3-MCT. TSMP is applied across a wide range of spatio-temporal scales, ranging from field to continental scale in a variety of applied research topics, such as water resources, land-atmosphere coupling and climate change projections. + +The following section will give you a brief overview of TSMP2. diff --git a/docs/introduction_to_TSMP2/introduction.md b/docs/introduction_to_TSMP2/introduction.md new file mode 100644 index 0000000..bae1831 --- /dev/null +++ b/docs/introduction_to_TSMP2/introduction.md @@ -0,0 +1,16 @@ +# The Terrestrial Systems Modelling Platform v2 (TSMP2) + +The Community Land Model is the land model for the Community Earth System Model (CESM). It focuses on modeling the land as the critical interface through which humanity affects, adapts to, and mitigates global environmental change. It includes a comprehensive representation of land biogeophysics, hydrology, plant physiology, biogeochemistry, anthropogenic land use, and ecosystem dynamics across a variety of spatial and temporal scales. The central theme is that terrestrial ecosystems, through their cycling of energy, water, chemical elements, and trace gases, are important determinants of climate. +The model represents several aspects of the land surface including surface heterogeneity and consists of components or submodels related to land biogeophysics, the hydrologic cycle, biogeochemistry, human dimensions, and ecosystem dynamics. Specific processes that are represented include: + +- Vegetation composition, structure, and phenology +- Land management including crops and crop management and wood harvest +- Ecosystem Demography (FATES, optional) + +```{figure} ../images/CLM5_processes_Lawrence2019.png +:height: 400px +:name: fig1 + +Overview of land biogeophysical, biogeochemical and landscape processes simulated by CLM5 Lawrence et al. (2019). +``` + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b497855 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +jupyter-book +matplotlib +numpy +ghp-import +ford \ No newline at end of file From 76a79f9634631714dd14f91121ab5b337d8460c6 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 11:01:53 +0200 Subject: [PATCH 02/19] docs: update md-files pathes --- docs/introduction_to_TSMP2/introduction.md | 16 ---------------- .../building_TSMP2/BuildingTSMP2wCMake.md | 0 .../building_TSMP2/Quickstart.md | 0 docs/{ => users_guide}/building_TSMP2/README.md | 0 .../introduction_to_TSMP2/README.md | 0 .../introduction_to_TSMP2/introduction.md | 12 ++++++++++++ 6 files changed, 12 insertions(+), 16 deletions(-) delete mode 100644 docs/introduction_to_TSMP2/introduction.md rename docs/{ => users_guide}/building_TSMP2/BuildingTSMP2wCMake.md (100%) rename docs/{ => users_guide}/building_TSMP2/Quickstart.md (100%) rename docs/{ => users_guide}/building_TSMP2/README.md (100%) rename docs/{ => users_guide}/introduction_to_TSMP2/README.md (100%) create mode 100644 docs/users_guide/introduction_to_TSMP2/introduction.md diff --git a/docs/introduction_to_TSMP2/introduction.md b/docs/introduction_to_TSMP2/introduction.md deleted file mode 100644 index bae1831..0000000 --- a/docs/introduction_to_TSMP2/introduction.md +++ /dev/null @@ -1,16 +0,0 @@ -# The Terrestrial Systems Modelling Platform v2 (TSMP2) - -The Community Land Model is the land model for the Community Earth System Model (CESM). It focuses on modeling the land as the critical interface through which humanity affects, adapts to, and mitigates global environmental change. It includes a comprehensive representation of land biogeophysics, hydrology, plant physiology, biogeochemistry, anthropogenic land use, and ecosystem dynamics across a variety of spatial and temporal scales. The central theme is that terrestrial ecosystems, through their cycling of energy, water, chemical elements, and trace gases, are important determinants of climate. -The model represents several aspects of the land surface including surface heterogeneity and consists of components or submodels related to land biogeophysics, the hydrologic cycle, biogeochemistry, human dimensions, and ecosystem dynamics. Specific processes that are represented include: - -- Vegetation composition, structure, and phenology -- Land management including crops and crop management and wood harvest -- Ecosystem Demography (FATES, optional) - -```{figure} ../images/CLM5_processes_Lawrence2019.png -:height: 400px -:name: fig1 - -Overview of land biogeophysical, biogeochemical and landscape processes simulated by CLM5 Lawrence et al. (2019). -``` - diff --git a/docs/building_TSMP2/BuildingTSMP2wCMake.md b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md similarity index 100% rename from docs/building_TSMP2/BuildingTSMP2wCMake.md rename to docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md diff --git a/docs/building_TSMP2/Quickstart.md b/docs/users_guide/building_TSMP2/Quickstart.md similarity index 100% rename from docs/building_TSMP2/Quickstart.md rename to docs/users_guide/building_TSMP2/Quickstart.md diff --git a/docs/building_TSMP2/README.md b/docs/users_guide/building_TSMP2/README.md similarity index 100% rename from docs/building_TSMP2/README.md rename to docs/users_guide/building_TSMP2/README.md diff --git a/docs/introduction_to_TSMP2/README.md b/docs/users_guide/introduction_to_TSMP2/README.md similarity index 100% rename from docs/introduction_to_TSMP2/README.md rename to docs/users_guide/introduction_to_TSMP2/README.md diff --git a/docs/users_guide/introduction_to_TSMP2/introduction.md b/docs/users_guide/introduction_to_TSMP2/introduction.md new file mode 100644 index 0000000..46c23a5 --- /dev/null +++ b/docs/users_guide/introduction_to_TSMP2/introduction.md @@ -0,0 +1,12 @@ +# The Terrestrial Systems Modelling Platform v2 (TSMP2) + +The Terrestrial Systems Modeling Platform (TSMP, https://www.terrsysmp.org) is a scale-consistent, highly modular, physics-based, massively parallel, and fully integrated groundwater-vegetation-atmosphere modeling framework for regional climate system modeling. TSMP2 is composed of the atmospheric models ICON, the land surface model encore Community Land Model (eCLM), and the ParFlow subsurface-surface hydrological model, coupled using OASIS3-MCT. TSMP2 is applied across a wide range of spatio-temporal scales, ranging from field to continental scale in a variety of applied research topics, such as water resources, land-atmosphere coupling and climate change projections. + + From a86e4c9526d44e46fb0aad1e65efaaba94df97e0 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 11:04:44 +0200 Subject: [PATCH 03/19] docs: remove src_browser --- docs/Makefile | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 7c40135..f93a3b0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,15 +1,12 @@ BUILD_DIR = ./_build SRC_DIR = ../src -all: docs src-browser +all: docs docs: jupyter-book build -W -n --keep-going . -src-browser: - ford -d $(SRC_DIR) -o $(BUILD_DIR)/html/src FORD_options.md - .PHONY: clean clean: - jupyter-book clean . \ No newline at end of file + jupyter-book clean . From 2d9344e06e1e86c4d8b44d9cc1bd04631e3ae241 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 11:11:05 +0200 Subject: [PATCH 04/19] docs: remove src_browser from workflow --- .github/workflows/docs.yml | 5 ----- docs/requirements.txt | 1 - 2 files changed, 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f9fdd07..e257677 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,11 +41,6 @@ jobs: run: | make clean docs - - name: Build eCLM Source Code browser - working-directory: ./docs - run: | - make src-browser - - name: Upload documentation artifacts uses: actions/upload-pages-artifact@v3 with: diff --git a/docs/requirements.txt b/docs/requirements.txt index b497855..5235316 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,4 +2,3 @@ jupyter-book matplotlib numpy ghp-import -ford \ No newline at end of file From c2a4c5de522edc54fa0b046209168769ef94db6d Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 11:25:34 +0200 Subject: [PATCH 05/19] docs: seperate build and deploy --- .github/workflows/docs.yml | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e257677..b2f7182 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,6 +5,9 @@ on: branches: - master - 'docs-**' + pull_request: + branches: + - 'master' env: BASE_URL: /${{ github.event.repository.name }} @@ -16,7 +19,7 @@ concurrency: cancel-in-progress: false jobs: - deploy-docs: + build: runs-on: ubuntu-latest environment: name: github-pages @@ -27,10 +30,10 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Set up Python 3.11 + - name: Set up Python 3.12 uses: actions/setup-python@v5 with: - python-version: 3.11 + python-version: 3.12 cache: 'pip' - name: Install dependencies @@ -45,8 +48,24 @@ jobs: uses: actions/upload-pages-artifact@v3 with: path: "docs/_build/html" + name: tsmp2_docs - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 + deploy: + if: github.event_name != 'pull_request' + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + with: + artifact_name: tsmp2_docs From cbfd45677bca1e6b94bcc4a3bb54392b5707c824 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 11:29:48 +0200 Subject: [PATCH 06/19] docs: do not check out submodules --- .github/workflows/docs.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b2f7182..3d815df 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -29,6 +29,11 @@ jobs: id-token: write steps: - uses: actions/checkout@v4 + with: + submodules: false + sparse-checkout: | + .github + docs - name: Set up Python 3.12 uses: actions/setup-python@v5 From 0640aa10d5868d50ede3451cfbc55ac4627869d1 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 13:12:52 +0200 Subject: [PATCH 07/19] docs: change branch in config.yml --- docs.yml | 56 ------------------------------------------------ docs/_config.yml | 2 +- 2 files changed, 1 insertion(+), 57 deletions(-) delete mode 100644 docs.yml diff --git a/docs.yml b/docs.yml deleted file mode 100644 index 4637cf6..0000000 --- a/docs.yml +++ /dev/null @@ -1,56 +0,0 @@ -name: Deploy Docs - -on: - push: - branches: - - master - - 'docs-**' - -env: - BASE_URL: /${{ github.event.repository.name }} - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - deploy-docs: - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - permissions: - pages: write - id-token: write - steps: - - uses: actions/checkout@v4 - - - name: Set up Python 3.11 - uses: actions/setup-python@v5 - with: - python-version: 3.11 - cache: 'pip' - - - name: Install dependencies - run: pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt - - - name: Build eCLM doc homepage - working-directory: ./docs - run: | - make clean docs - - - name: Build eCLM Source Code browser - working-directory: ./docs - run: | - make src-browser - - - name: Upload documentation artifacts - uses: actions/upload-pages-artifact@v3 - with: - path: "docs/_build/html" - - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/docs/_config.yml b/docs/_config.yml index 6c6790e..7152296 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -28,7 +28,7 @@ sphinx: repository: url: https://github.com/HPSCTerrSys/TSMP2 # Online location of your book path_to_book: docs # Optional path to your book, relative to the repository root - branch: master # Which branch of the repository should be used when creating links (optional) + branch: docs-release # Which branch of the repository should be used when creating links (optional) # Add GitHub buttons to your book # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository From aeb9a22ce55c73a6274326c34889cd4605c0f7c9 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 13:25:12 +0200 Subject: [PATCH 08/19] docs: modify docs.yml --- .github/workflows/docs.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3d815df..2729820 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -21,12 +21,6 @@ concurrency: jobs: build: runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - permissions: - pages: write - id-token: write steps: - uses: actions/checkout@v4 with: @@ -44,7 +38,7 @@ jobs: - name: Install dependencies run: pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt - - name: Build eCLM doc homepage + - name: Build TSMP2 doc homepage working-directory: ./docs run: | make clean docs From d8c3e982050e2b04c224b52065eae325a81ec7f4 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 13:28:03 +0200 Subject: [PATCH 09/19] docs: change to ubuntu-24.04 --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2729820..f495c51 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,7 +20,7 @@ concurrency: jobs: build: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 with: From c379c26f913d4ad10ef30e02736d88d07e3ee764 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 13:46:11 +0200 Subject: [PATCH 10/19] Revert "docs: change to ubuntu-24.04" This reverts commit d8c3e982050e2b04c224b52065eae325a81ec7f4. --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f495c51..2729820 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,7 +20,7 @@ concurrency: jobs: build: - runs-on: ubuntu-24.04 + runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: From 154d3a52127ee2c0d6ef7909e546540c41880023 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 14:02:17 +0200 Subject: [PATCH 11/19] docs: transfer info from README into docs --- README.md | 296 +----------------- .../building_TSMP2/BuildingTSMP2wCMake.md | 251 ++++++++++++++- docs/users_guide/building_TSMP2/Quickstart.md | 43 ++- 3 files changed, 302 insertions(+), 288 deletions(-) diff --git a/README.md b/README.md index 6c4dcc6..ef85fb5 100644 --- a/README.md +++ b/README.md @@ -1,296 +1,24 @@ -## Quickstart - -> [!TIP] -> `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). - -1. Clone this repository. - -```bash -git clone https://github.com/HPSCTerrSys/TSMP2.git -export TSMP2_DIR=$(realpath TSMP2) -cd $TSMP2_DIR -``` - -2. Build model components with TSMP2 framework - -To build a model component one need to activate the component model `--`. The options are not case-sensitive and do not need to be in an specific order. - -> [!NOTE] -> The component models (git submodules) are cloned during the execution of `build_tsmp2.sh`. If the component model (`models/`) 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 `--`. - - -```bash -# to see options -./build_tsmp2.sh --help - -# ICON-eCLM-ParFlow -./build_tsmp2.sh --ICON --eCLM --PARFLOW - -# eCLM-ParFlow -./build_tsmp2.sh --eCLM --PARFLOW - -# ICON-eCLM -./build_tsmp2.sh --ICON --eCLM - -# eCLM-PDAF -./build_tsmp2.sh --eCLM --PDAF - -# ICON (with source code) -./build_tsmp2.sh --ICON --ICON_SRC ${ICON_SRC} - -# ParFlow on Marvin (Uni Bonn) -./build_tsmp2.sh --ParFlow --env env/uni-bonn.gnu.openmpi -``` - - -## Building TSMP2 with CMake - -> [!NOTE] -> For experienced users. -> 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. -> The [Quickstart](#Quickstart) is the tested and supported method. - -1. Clone this repository. - -```bash -git clone https://github.com/HPSCTerrSys/TSMP2.git -export TSMP2_DIR=$(realpath TSMP2) -cd $TSMP2_DIR -``` - -2. Load the environment variables required for the build. - -```bash -source env/jsc.2024_Intel.sh -``` - -3. Specify build and install directories. - -```bash -# Name of the coupled model (e.g. ICON-eCLM, CLM3.5-COSMO-ParFlow, CLM3.5-ParFlow, CLM3.5-ParFlow-PDAF) -MODEL_ID="ICON-eCLM-ParFlow" - -# Build artifacts will be generated in this folder. It can be deleted after build. -BUILD_DIR="./bld/${SYSTEMNAME^^}_${MODEL_ID}" - -# Model executables and libraries will be installed here -INSTALL_DIR="./bin/${SYSTEMNAME^^}_${MODEL_ID}" - -# Create build and install directories -mkdir -p ${BUILD_DIR} ${INSTALL_DIR} -``` - -4. Download the OASIS3-MCT coupling library and the component models -you wish to use. You can check out the supported submodule commits -using - -```bash -# eCLM -git submodule update --init -- models/eCLM - -# ICON -git submodule update --init -- models/icon - -# ParFlow -git submodule update --init -- models/parflow - -# ParFlow (PDAF-patched) -git submodule update --init -- models/parflow_pdaf - -# CLM3.5 -git submodule update --init -- models/CLM3.5 +# Terrestrial Systems Modelling Platform v2 (TSMP2) -# COSMO5.01 -git submodule update --init -- models/cosmo5.01_fresh +[![docs](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml) -# OASIS3-MCT (required for coupled models) -git submodule update --init -- models/oasis3-mct -# PDAF -git submodule update --init -- models/pdaf -``` +## Introduction -If you wish to use alternative (possibly unsupported) commits of -component models, clone them explicitly. Then save the full path to -each model source code to `_SRC`. Examples are given -below: +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://code.mpimet.mpg.de/projects/iconpublic)) 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. -```bash -## NOTE: Download only the component models that you need! ## +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. -# eCLM -git clone -b beta-0.2 https://github.com/HPSCTerrSys/eCLM.git models/eCLM -eCLM_SRC=`realpath models/eCLM` +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). -# ICON -git clone https://icg4geo.icg.kfa-juelich.de/spoll/icon2.6.4_oascoup.git models/icon -ICON_SRC=`realpath models/icon` - -# ParFlow -git clone https://github.com/parflow/parflow.git models/parflow -PARFLOW_SRC=`realpath models/parflow` - -# ParFlow (PDAF-patched) -git clone -b v3.13.0-pdaf https://github.com/HPSCTerrSys/parflow models/parflow_pdaf -PARFLOW_SRC=`realpath models/parflow_pdaf` - -# CLM3.5 -git clone -b tsmp-patches-v0.1 https://github.com/HPSCTerrSys/CLM3.5.git models/CLM3.5 -CLM35_SRC=`realpath models/CLM3.5` - -# COSMO5.01 -git clone -b tsmp-oasis https://icg4geo.icg.kfa-juelich.de/ModelSystems/tsmp_src/cosmo5.01_fresh.git models/cosmo5.01_fresh -COSMO_SRC=`realpath models/cosmo5.01_fresh` - -# OASIS3-MCT (required for coupled models) -git clone -b tsmp-patches-v0.1 https://icg4geo.icg.kfa-juelich.de/ExternalReposPublic/oasis3-mct models/oasis3-mct -OASIS_SRC=`realpath models/oasis3-mct` - -# PDAF -git clone -b PDAF_V2.2.1-tsmp https://github.com/HPSCTerrSys/pdaf.git models/pdaf -PDAF_SRC=`realpath models/pdaf` -``` - -5. Run CMake configure step for the model combination that you wish to build. The - examples below show different CMake configure commands for each model combination. - -```bash -# -# 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_SRC=${_SRC}. OASIS is taken by default when coupled models are chosen. -# - -# ICON-eCLM -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DeCLM=ON \ - -DICON=ON - -# eCLM-ParFlow -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DeCLM=ON \ - -DPARFLOW_SRC=ON - -# ICON-eCLM-ParFlow -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DeCLM=ON \ - -DICON=ON \ - -DPARFLOW=ON - -# CLM3.5-COSMO5.01-ParFlow -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DCLM35=ON \ - -DCOSMO=ON \ - -DPARFLOW=ON - -# CLM3.5-ParFlow -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DCLM35=ON \ - -DPARFLOW=ON - -# CLM3.5-COSMO5.01 -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DCLM35=ON \ - -DCOSMO=ON - -# -# For standalone models -# pass the component model name (i.e. -D=ON). -# - -# CLM3.5 standalone -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DCLM35=ON - -# eCLM standalone -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DeCLM=ON - -# ParFlow standalone -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DPARFLOW=ON - -# -# For TSMP-PDAF builds, add -PDAF=ON -# - -# CLM3.5-PDAF -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DCLM35=ON \ - -DPDAF=ON - -# CLM3.5-ParFlow-PDAF -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DCLM35=ON \ - -DPARFLOW=ON \ - -DPDAF=ON - -# eCLM-PDAF -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DeCLM=ON \ - -DPDAF=ON - -# eCLM-ParFlow-PDAF -cmake -S . -B ${BUILD_DIR} \ - -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ - -DeCLM=ON \ - -DPARFLOW=ON \ - -DPDAF=ON - -``` - -6. Build and install the models. - -```bash -cmake --build ${BUILD_DIR} -cmake --install ${BUILD_DIR} -``` - -### Resuming a failed build - -When the build gets interrupted or fails for some reason, it can be resumed by simply running Step 6: - -```bash -cmake --build ${BUILD_DIR} -cmake --install ${BUILD_DIR} -``` - -Note that this works only if the required environment variables are already set. If you are resuming -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 `_SRC` (Step 4) before you can run Step 6. - -### Rebuilding specific component models - -TSMP2 can rebuild a specific component model via the `cmake --build ${BUILD_DIR} --target ${MODEL}` command. -This may be useful when you need to recompile a component model that has been modified or updated. +## Quickstart -```bash -# Rebuilding examples +Please see [quickstart section](https://hpscterrsys.github.io/TSMP2/users_guide/building_TSMP2/Quickstart.html) for guided steps on how the model can be build. -cmake --build ${BUILD_DIR} --target eCLM && cmake --install ${BUILD_DIR} # Rebuilds eCLM -cmake --build ${BUILD_DIR} --target ICON && cmake --install ${BUILD_DIR} # Rebuilds ICON -cmake --build ${BUILD_DIR} --clean-first --target ParFlow && cmake --install ${BUILD_DIR} # Does a clean rebuild of ParFlow -``` +## Usage / Documentation -Only component models specified during CMake configure step (see Step 5) can be rebuilt. For instance, if you -configured TSMP2 to build `eCLM-ParFlow`, then rebuilding `ICON` would of course be not possible. +Please check the documentation at https://hpscterrsys.github.io/TSMP2 -The list below shows all component models supported by TSMP2. To rebuild a component model(s), -run one or more commands below, wait until the build succeeds, then finally run -`cmake --install ${BUILD_DIR}` so that the generated libraries and executables are copied to `${INSTALL_DIR}`. +## License +TSMP is open source software and is licensed under the [MIT-License](https://github.com/HPSCTerrSys/TSMP2/blob/master/LICENSE). -- `cmake --build ${BUILD_DIR} --target eCLM` -- `cmake --build ${BUILD_DIR} --target ParFlow` -- `cmake --build ${BUILD_DIR} --target ICON` -- `cmake --build ${BUILD_DIR} --target OASIS3_MCT` -- `cmake --build ${BUILD_DIR} --target CLM3_5` -- `cmake --build ${BUILD_DIR} --target COSMO5_1` diff --git a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md index 78fcdd3..605e302 100644 --- a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md +++ b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md @@ -1,5 +1,252 @@ # Building TSMP2 with CMake -```{warning} -Page under construction +> [!NOTE] +> For experienced users. +> 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. +> The [Quickstart](#Quickstart) is the tested and supported method. + +1. Clone this repository. + +```bash +git clone https://github.com/HPSCTerrSys/TSMP2.git +export TSMP2_DIR=$(realpath TSMP2) +cd $TSMP2_DIR +``` + +2. Load the environment variables required for the build. + +```bash +source env/jsc.2024_Intel.sh +``` + +3. Specify build and install directories. + +```bash +# Name of the coupled model (e.g. ICON-eCLM, CLM3.5-COSMO-ParFlow, CLM3.5-ParFlow, CLM3.5-ParFlow-PDAF) +MODEL_ID="ICON-eCLM-ParFlow" + +# Build artifacts will be generated in this folder. It can be deleted after build. +BUILD_DIR="./bld/${SYSTEMNAME^^}_${MODEL_ID}" + +# Model executables and libraries will be installed here +INSTALL_DIR="./bin/${SYSTEMNAME^^}_${MODEL_ID}" + +# Create build and install directories +mkdir -p ${BUILD_DIR} ${INSTALL_DIR} +``` + +4. Download the OASIS3-MCT coupling library and the component models +you wish to use. You can check out the supported submodule commits +using + +```bash +# eCLM +git submodule update --init -- models/eCLM + +# ICON +git submodule update --init -- models/icon + +# ParFlow +git submodule update --init -- models/parflow + +# ParFlow (PDAF-patched) +git submodule update --init -- models/parflow_pdaf + +# CLM3.5 +git submodule update --init -- models/CLM3.5 + +# COSMO5.01 +git submodule update --init -- models/cosmo5.01_fresh + +# OASIS3-MCT (required for coupled models) +git submodule update --init -- models/oasis3-mct + +# PDAF +git submodule update --init -- models/pdaf +``` + +If you wish to use alternative (possibly unsupported) commits of +component models, clone them explicitly. Then save the full path to +each model source code to `_SRC`. Examples are given +below: + +```bash +## NOTE: Download only the component models that you need! ## + +# eCLM +git clone -b beta-0.2 https://github.com/HPSCTerrSys/eCLM.git models/eCLM +eCLM_SRC=`realpath models/eCLM` + +# ICON +git clone https://icg4geo.icg.kfa-juelich.de/spoll/icon2.6.4_oascoup.git models/icon +ICON_SRC=`realpath models/icon` + +# ParFlow +git clone https://github.com/parflow/parflow.git models/parflow +PARFLOW_SRC=`realpath models/parflow` + +# ParFlow (PDAF-patched) +git clone -b v3.13.0-pdaf https://github.com/HPSCTerrSys/parflow models/parflow_pdaf +PARFLOW_SRC=`realpath models/parflow_pdaf` + +# CLM3.5 +git clone -b tsmp-patches-v0.1 https://github.com/HPSCTerrSys/CLM3.5.git models/CLM3.5 +CLM35_SRC=`realpath models/CLM3.5` + +# COSMO5.01 +git clone -b tsmp-oasis https://icg4geo.icg.kfa-juelich.de/ModelSystems/tsmp_src/cosmo5.01_fresh.git models/cosmo5.01_fresh +COSMO_SRC=`realpath models/cosmo5.01_fresh` + +# OASIS3-MCT (required for coupled models) +git clone -b tsmp-patches-v0.1 https://icg4geo.icg.kfa-juelich.de/ExternalReposPublic/oasis3-mct models/oasis3-mct +OASIS_SRC=`realpath models/oasis3-mct` + +# PDAF +git clone -b PDAF_V2.2.1-tsmp https://github.com/HPSCTerrSys/pdaf.git models/pdaf +PDAF_SRC=`realpath models/pdaf` +``` + +5. Run CMake configure step for the model combination that you wish to build. The + examples below show different CMake configure commands for each model combination. + +```bash +# +# 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_SRC=${_SRC}. OASIS is taken by default when coupled models are chosen. +# + +# ICON-eCLM +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DeCLM=ON \ + -DICON=ON + +# eCLM-ParFlow +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DeCLM=ON \ + -DPARFLOW_SRC=ON + +# ICON-eCLM-ParFlow +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DeCLM=ON \ + -DICON=ON \ + -DPARFLOW=ON + +# CLM3.5-COSMO5.01-ParFlow +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DCLM35=ON \ + -DCOSMO=ON \ + -DPARFLOW=ON + +# CLM3.5-ParFlow +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DCLM35=ON \ + -DPARFLOW=ON + +# CLM3.5-COSMO5.01 +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DCLM35=ON \ + -DCOSMO=ON + +# +# For standalone models +# pass the component model name (i.e. -D=ON). +# + +# CLM3.5 standalone +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DCLM35=ON + +# eCLM standalone +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DeCLM=ON + +# ParFlow standalone +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DPARFLOW=ON + +# +# For TSMP-PDAF builds, add -PDAF=ON +# + +# CLM3.5-PDAF +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DCLM35=ON \ + -DPDAF=ON + +# CLM3.5-ParFlow-PDAF +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DCLM35=ON \ + -DPARFLOW=ON \ + -DPDAF=ON + +# eCLM-PDAF +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DeCLM=ON \ + -DPDAF=ON + +# eCLM-ParFlow-PDAF +cmake -S . -B ${BUILD_DIR} \ + -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \ + -DeCLM=ON \ + -DPARFLOW=ON \ + -DPDAF=ON + ``` + +6. Build and install the models. + +```bash +cmake --build ${BUILD_DIR} +cmake --install ${BUILD_DIR} +``` + +## Resuming a failed build + +When the build gets interrupted or fails for some reason, it can be resumed by simply running Step 6: + +```bash +cmake --build ${BUILD_DIR} +cmake --install ${BUILD_DIR} +``` + +Note that this works only if the required environment variables are already set. If you are resuming +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 `_SRC` (Step 4) before you can run Step 6. + +## Rebuilding specific component models + +TSMP2 can rebuild a specific component model via the `cmake --build ${BUILD_DIR} --target ${MODEL}` command. +This may be useful when you need to recompile a component model that has been modified or updated. + +```bash +# Rebuilding examples + +cmake --build ${BUILD_DIR} --target eCLM && cmake --install ${BUILD_DIR} # Rebuilds eCLM +cmake --build ${BUILD_DIR} --target ICON && cmake --install ${BUILD_DIR} # Rebuilds ICON +cmake --build ${BUILD_DIR} --clean-first --target ParFlow && cmake --install ${BUILD_DIR} # Does a clean rebuild of ParFlow +``` + +Only component models specified during CMake configure step (see Step 5) can be rebuilt. For instance, if you +configured TSMP2 to build `eCLM-ParFlow`, then rebuilding `ICON` would of course be not possible. + +The list below shows all component models supported by TSMP2. To rebuild a component model(s), +run one or more commands below, wait until the build succeeds, then finally run +`cmake --install ${BUILD_DIR}` so that the generated libraries and executables are copied to `${INSTALL_DIR}`. + +- `cmake --build ${BUILD_DIR} --target eCLM` +- `cmake --build ${BUILD_DIR} --target ParFlow` +- `cmake --build ${BUILD_DIR} --target ICON` +- `cmake --build ${BUILD_DIR} --target OASIS3_MCT` +- `cmake --build ${BUILD_DIR} --target CLM3_5` +- `cmake --build ${BUILD_DIR} --target COSMO5_1` + diff --git a/docs/users_guide/building_TSMP2/Quickstart.md b/docs/users_guide/building_TSMP2/Quickstart.md index 4b49fe3..6306b11 100644 --- a/docs/users_guide/building_TSMP2/Quickstart.md +++ b/docs/users_guide/building_TSMP2/Quickstart.md @@ -1,5 +1,44 @@ # Quickstart -```{warning} -Page under construction +> [!TIP] +> `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). + +1. Clone this repository. + +```bash +git clone https://github.com/HPSCTerrSys/TSMP2.git +export TSMP2_DIR=$(realpath TSMP2) +cd $TSMP2_DIR ``` + +2. Build model components with TSMP2 framework + +To build a model component one need to activate the component model `--`. The options are not case-sensitive and do not need to be in an specific order. + +> [!NOTE] +> The component models (git submodules) are cloned during the execution of `build_tsmp2.sh`. If the component model (`models/`) 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 `--`. + + +```bash +# to see options +./build_tsmp2.sh --help + +# ICON-eCLM-ParFlow +./build_tsmp2.sh --ICON --eCLM --PARFLOW + +# eCLM-ParFlow +./build_tsmp2.sh --eCLM --PARFLOW + +# ICON-eCLM +./build_tsmp2.sh --ICON --eCLM + +# eCLM-PDAF +./build_tsmp2.sh --eCLM --PDAF + +# ICON (with source code) +./build_tsmp2.sh --ICON --ICON_SRC ${ICON_SRC} + +# ParFlow on Marvin (Uni Bonn) +./build_tsmp2.sh --ParFlow --env env/uni-bonn.gnu.openmpi +``` + From c036914a6287119ebb565af49daf2ea61202edd9 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 14:15:16 +0200 Subject: [PATCH 12/19] docs: fix reference --- README.md | 2 +- docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md | 2 +- docs/users_guide/building_TSMP2/Quickstart.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ef85fb5..dcaf53e 100644 --- a/README.md +++ b/README.md @@ -20,5 +20,5 @@ Please see [quickstart section](https://hpscterrsys.github.io/TSMP2/users_guide/ Please check the documentation at https://hpscterrsys.github.io/TSMP2 ## License -TSMP is open source software and is licensed under the [MIT-License](https://github.com/HPSCTerrSys/TSMP2/blob/master/LICENSE). +TSMP is open source software and is licensed under the [MIT-License](https://github.com/HPSCTerrSys/TSMP2/blob/master/LICENSE.txt). diff --git a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md index 605e302..0ca7cd5 100644 --- a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md +++ b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md @@ -3,7 +3,7 @@ > [!NOTE] > For experienced users. > 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. -> The [Quickstart](#Quickstart) is the tested and supported method. +[//]: > The [Quickstart](#Quickstart) is the tested and supported method. 1. Clone this repository. diff --git a/docs/users_guide/building_TSMP2/Quickstart.md b/docs/users_guide/building_TSMP2/Quickstart.md index 6306b11..bfdd5f1 100644 --- a/docs/users_guide/building_TSMP2/Quickstart.md +++ b/docs/users_guide/building_TSMP2/Quickstart.md @@ -1,7 +1,7 @@ # Quickstart > [!TIP] -> `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). +> `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/BuildingTSMP2wCMake) or {doc}`BuildingTSMP2wCMake`. 1. Clone this repository. From e4343c364592d1b03a5a45243500546b02c4996f Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 14:17:42 +0200 Subject: [PATCH 13/19] dos: fix cross-reference --- docs/users_guide/building_TSMP2/Quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/users_guide/building_TSMP2/Quickstart.md b/docs/users_guide/building_TSMP2/Quickstart.md index bfdd5f1..060c6d2 100644 --- a/docs/users_guide/building_TSMP2/Quickstart.md +++ b/docs/users_guide/building_TSMP2/Quickstart.md @@ -1,7 +1,7 @@ # Quickstart > [!TIP] -> `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/BuildingTSMP2wCMake) or {doc}`BuildingTSMP2wCMake`. +> `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 {doc}`BuildingTSMP2wCMake`. 1. Clone this repository. From 105ebe97b81bb619f75625c8dea68edce4d26aee Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 14:33:49 +0200 Subject: [PATCH 14/19] dos: revise tip/note --- .../users_guide/building_TSMP2/BuildingTSMP2wCMake.md | 9 +++++---- docs/users_guide/building_TSMP2/Quickstart.md | 11 ++++++----- docs/users_guide/building_TSMP2/README.md | 5 ++++- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md index 0ca7cd5..7ef8109 100644 --- a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md +++ b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md @@ -1,9 +1,10 @@ # Building TSMP2 with CMake -> [!NOTE] -> For experienced users. -> 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. -[//]: > The [Quickstart](#Quickstart) is the tested and supported method. +```{note} +For experienced users. +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. +The [Quickstart](#Quickstart) is the tested and supported method. +``` 1. Clone this repository. diff --git a/docs/users_guide/building_TSMP2/Quickstart.md b/docs/users_guide/building_TSMP2/Quickstart.md index 060c6d2..55dcb32 100644 --- a/docs/users_guide/building_TSMP2/Quickstart.md +++ b/docs/users_guide/building_TSMP2/Quickstart.md @@ -1,7 +1,8 @@ # Quickstart -> [!TIP] -> `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 {doc}`BuildingTSMP2wCMake`. +```{tip} +`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 {doc}`BuildingTSMP2wCMake`. +``` 1. Clone this repository. @@ -15,9 +16,9 @@ cd $TSMP2_DIR To build a model component one need to activate the component model `--`. The options are not case-sensitive and do not need to be in an specific order. -> [!NOTE] -> The component models (git submodules) are cloned during the execution of `build_tsmp2.sh`. If the component model (`models/`) 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 `--`. - +```{note} +The component models (git submodules) are cloned during the execution of `build_tsmp2.sh`. If the component model (`models/`) 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 `--`. +``` ```bash # to see options diff --git a/docs/users_guide/building_TSMP2/README.md b/docs/users_guide/building_TSMP2/README.md index 100865f..8947e0c 100644 --- a/docs/users_guide/building_TSMP2/README.md +++ b/docs/users_guide/building_TSMP2/README.md @@ -1,3 +1,6 @@ # Building TSMP2 - +```{contents} +:local: +:depth: 2 +``` From a74333fc017889b22ec4d6c4f7582bd6bcea8687 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 14:40:48 +0200 Subject: [PATCH 15/19] update README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dcaf53e..6015e1d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # Terrestrial Systems Modelling Platform v2 (TSMP2) [![docs](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml) - +[![build](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/CI.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/CI.yml) ## Introduction -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://code.mpimet.mpg.de/projects/iconpublic)) 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. +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. 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. From 5a78ef933b7112d8fab0b207f0d327a8595b9b78 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Tue, 22 Jul 2025 15:32:26 +0200 Subject: [PATCH 16/19] docs: trigger docs workflow only for master --- .github/workflows/docs.yml | 2 +- docs/Makefile | 1 - docs/_config.yml | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2729820..acdd518 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,7 +4,7 @@ on: push: branches: - master - - 'docs-**' +# - 'docs-**' pull_request: branches: - 'master' diff --git a/docs/Makefile b/docs/Makefile index f93a3b0..a50ffeb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,5 +1,4 @@ BUILD_DIR = ./_build -SRC_DIR = ../src all: docs diff --git a/docs/_config.yml b/docs/_config.yml index 7152296..6c6790e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -28,7 +28,7 @@ sphinx: repository: url: https://github.com/HPSCTerrSys/TSMP2 # Online location of your book path_to_book: docs # Optional path to your book, relative to the repository root - branch: docs-release # Which branch of the repository should be used when creating links (optional) + branch: master # Which branch of the repository should be used when creating links (optional) # Add GitHub buttons to your book # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository From b5a2e8f0e54c733511f3bbd1a940ed6a843886f9 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Wed, 23 Jul 2025 17:51:22 +0200 Subject: [PATCH 17/19] README update and tip-o in docs --- README.md | 5 +++-- docs/users_guide/introduction_to_TSMP2/README.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6015e1d..5deb809 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ -# Terrestrial Systems Modelling Platform v2 (TSMP2) +# Terrestrial Systems Modeling Platform v2 (TSMP2) [![docs](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/docs.yml) [![build](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/CI.yml/badge.svg)](https://github.com/HPSCTerrSys/TSMP2/actions/workflows/CI.yml) +[![doi](https://img.shields.io/badge/rsd-tsmp2-00a3e3)](https://helmholtz.software/software/tsmp2) ## Introduction @@ -13,7 +14,7 @@ TSMP development has been driven by groups within the [Center for High-Performan ## Quickstart -Please see [quickstart section](https://hpscterrsys.github.io/TSMP2/users_guide/building_TSMP2/Quickstart.html) for guided steps on how the model can be build. +Please see [quickstart section](../building_TSMP2/Quickstart.md) for guided steps on how the model can be build. ## Usage / Documentation diff --git a/docs/users_guide/introduction_to_TSMP2/README.md b/docs/users_guide/introduction_to_TSMP2/README.md index 951395e..df7e69a 100644 --- a/docs/users_guide/introduction_to_TSMP2/README.md +++ b/docs/users_guide/introduction_to_TSMP2/README.md @@ -1,5 +1,5 @@ # Introduction to TSMP2 -The Terrestrial Systems Modeling Platform (TSMP, https://www.terrsysmp.org) is a scale-consistent, highly modular, physics-based, massively parallel, and fully integrated groundwater-vegetation-atmosphere modeling framework for regional climate system modeling. TSMP is composed of the atmospheric models [ICON](https://github.com/HPSCTerrSys/icon-model_coup-oas) or COSMO, the land surface model Community Land Model ([CLM](https://github.com/HPSCTerrSys/eCLM)), and the [ParFlow](https://github.com/parflow/parflow) subsurface-surface hydrological model, coupled using OASIS3-MCT. TSMP is applied across a wide range of spatio-temporal scales, ranging from field to continental scale in a variety of applied research topics, such as water resources, land-atmosphere coupling and climate change projections. +The Terrestrial Systems Modeling Platform (TSMP, https://www.terrsysmp.org) is a scale-consistent, highly modular, physics-based, massively parallel, and fully integrated groundwater-vegetation-atmosphere modeling framework for regional climate system modeling. TSMP is composed of the atmospheric models [ICON](https://github.com/HPSCTerrSys/icon-model_coup-oas), the land surface model encore Community Land Model ([eCLM](https://github.com/HPSCTerrSys/eCLM)), and the [ParFlow](https://github.com/parflow/parflow) subsurface-surface hydrological model, coupled using OASIS3-MCT. TSMP is applied across a wide range of spatio-temporal scales, ranging from field to continental scale in a variety of applied research topics, such as water resources, land-atmosphere coupling and climate change projections. The following section will give you a brief overview of TSMP2. From 6d1b906e5b1a2bbdbfb1c736990ab37e4caa1786 Mon Sep 17 00:00:00 2001 From: Stefan Poll Date: Wed, 23 Jul 2025 17:58:22 +0200 Subject: [PATCH 18/19] fix cross reserence at README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5deb809..724394c 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ TSMP development has been driven by groups within the [Center for High-Performan ## Quickstart -Please see [quickstart section](../building_TSMP2/Quickstart.md) for guided steps on how the model can be build. +Please see [quickstart section](./docs/users_guide/building_TSMP2/Quickstart.md) for guided steps on how the model can be build. ## Usage / Documentation From eabc1777f08c4dfdce397bf699627e10cba169df Mon Sep 17 00:00:00 2001 From: Johannes Keller Date: Thu, 24 Jul 2025 10:32:55 +0200 Subject: [PATCH 19/19] doc: add PDAF references in README and documentation sidebar --- README.md | 6 ++++++ docs/_toc.yml | 2 ++ 2 files changed, 8 insertions(+) diff --git a/README.md b/README.md index 724394c..3b3b521 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,12 @@ The Terrestrial System Modeling Platform v2 (TSMP2, https://www.terrsysmp.org) i 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. +TSMP-PDAF describes the build commands of TSMP that can introduce data +assimilation for an ensemble of TSMP simulations using the Parallel + Data Assimilation Framework +([PDAF](https://pdaf.awi.de/trac/wiki)). For more information, see the +[documentation of TSMP-PDAF](https://hpscterrsys.github.io/pdaf). + 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). ## Quickstart diff --git a/docs/_toc.yml b/docs/_toc.yml index 02d584d..12ed7a2 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -21,3 +21,5 @@ parts: chapters: - url: https://terrsysmp.org/ title: TSMP webpage + - url: https://hpscterrsys.github.io/pdaf + title: TSMP-PDAF documentation