diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..acdd518 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,70 @@ +name: Deploy Docs + +on: + push: + branches: + - master +# - 'docs-**' + pull_request: + branches: + - 'master' + +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: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: false + sparse-checkout: | + .github + docs + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: 3.12 + cache: 'pip' + + - name: Install dependencies + run: pip install -r ${GITHUB_WORKSPACE}/docs/requirements.txt + + - name: Build TSMP2 doc homepage + working-directory: ./docs + run: | + make clean docs + + - name: Upload documentation artifacts + uses: actions/upload-pages-artifact@v3 + with: + path: "docs/_build/html" + name: tsmp2_docs + + 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 diff --git a/README.md b/README.md index 6c4dcc6..3b3b521 100644 --- a/README.md +++ b/README.md @@ -1,296 +1,31 @@ -## 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 Modeling 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) +[![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) -# OASIS3-MCT (required for coupled models) -git submodule update --init -- models/oasis3-mct +## Introduction -# PDAF -git submodule update --init -- models/pdaf -``` +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. -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: +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. -```bash -## NOTE: Download only the component models that you need! ## +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). -# 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](./docs/users_guide/building_TSMP2/Quickstart.md) 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.txt). -- `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/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..a50ffeb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,11 @@ +BUILD_DIR = ./_build + +all: docs + +docs: + jupyter-book build -W -n --keep-going . + +.PHONY: clean + +clean: + jupyter-book clean . 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..12ed7a2 --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,25 @@ +# 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 + - url: https://hpscterrsys.github.io/pdaf + title: TSMP-PDAF documentation diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..5235316 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +jupyter-book +matplotlib +numpy +ghp-import diff --git a/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md new file mode 100644 index 0000000..7ef8109 --- /dev/null +++ b/docs/users_guide/building_TSMP2/BuildingTSMP2wCMake.md @@ -0,0 +1,253 @@ +# 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 + +# 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 new file mode 100644 index 0000000..55dcb32 --- /dev/null +++ b/docs/users_guide/building_TSMP2/Quickstart.md @@ -0,0 +1,45 @@ +# 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`. +``` + +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 +``` + diff --git a/docs/users_guide/building_TSMP2/README.md b/docs/users_guide/building_TSMP2/README.md new file mode 100644 index 0000000..8947e0c --- /dev/null +++ b/docs/users_guide/building_TSMP2/README.md @@ -0,0 +1,6 @@ +# Building TSMP2 + +```{contents} +:local: +:depth: 2 +``` diff --git a/docs/users_guide/introduction_to_TSMP2/README.md b/docs/users_guide/introduction_to_TSMP2/README.md new file mode 100644 index 0000000..df7e69a --- /dev/null +++ b/docs/users_guide/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), 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. 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. + +