Merge branch 'preview' into merge-preview-in-main

.gitlab-ci.yml

-variables:
-    GIT_STRATEGY: none
-    DOCKER_IMAGE: webpage:$CI_PIPELINE_ID
-
-workflow:
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
-      when: never
-    - if: '$CI_COMMIT_BRANCH'
-
-stages:
-    - build
-    - test
-    - release
-    - cleanup
-
-
-Build Linter:
-    stage: build
-    variables:
-        GIT_STRATEGY: clone
-        GIT_DEPTH: 0
-    script: docker build -t "${DOCKER_IMAGE}" .
-
-Test mkdocs:
-    stage: test
-    script: docker run ${DOCKER_IMAGE}
-
-Check wording of changed md-files:
-    stage: test
-    script:
-        - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
-          doc.zih.tu-dresden.de/util/grep-forbidden-words.sh
-    only: [ merge_requests ]
-
-Lint changed md-files:
-    stage: test
-    script:
-        - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
-          doc.zih.tu-dresden.de/util/lint-changes.sh
-    only: [ merge_requests ]
-
-Check spelling for changed md-files:
-    stage: test
-    script:
-        - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
-          doc.zih.tu-dresden.de/util/check-spelling.sh
-    only: [ merge_requests ]
-
-Check links for changed md-files:
-    stage: test
-    script:
-        - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
-          doc.zih.tu-dresden.de/util/check-links.sh
-    only: [ merge_requests ]
-
-Lint md-files:
-    stage: test
-    script: docker run --rm "${DOCKER_IMAGE}" markdownlint docs
-    only: [ main, preview ]
-
-Check links for md-files:
-    stage: test
-    script:
-        - docker run --rm "${DOCKER_IMAGE}"
-          bash -c "find docs -type f -name '*.md' | xargs -L1 markdown-link-check --quiet"
-    only: [ main, preview ]
-
-Release preview branch:
-    stage: release
-    script:
-        - docker run --rm -v /var/www/html/preview:/mnt "${DOCKER_IMAGE}" mkdocs build --strict --site-dir /mnt
-    only: [ preview ]
-
-Release:
-    stage: release
-    script:
-        - docker run --rm -v /var/www/html/hpc-wiki:/mnt "${DOCKER_IMAGE}" mkdocs build --strict --site-dir /mnt
-    only: [ main ]
-
-Cleanup docker:
-    stage: cleanup
-    script:
-        - docker rmi -f "${DOCKER_IMAGE}"
-        - docker system prune --force
-    when: always

doc.zih.tu-dresden.de/docs/contrib/content_rules.md

@@ -327,7 +327,8 @@ highlighting. There is a complete list of supported
 
 Where possible, replace login, project name, and other private data with clearly recognizable
 placeholders. In particular, use the generic login `marie` and the project title `p_number_crunch`
-as placeholders.
+as placeholders at first. If you need a second login and a second project stick to `martin` and
+`p_long_computations`.
 
 ```console
 marie@login$ ls -l
@@ -344,6 +345,8 @@ drwxr-xr-x   3 marie p_number_crunch      4096 Feb 12  2020 data
     and [Marianne](https://en.wikipedia.org/wiki/Marianne), symbol of France standing for liberty,
     equality and fraternity.
 
+    The very same holds for the generic login *martin*.
+
 #### Placeholders
 
 Placeholders represent arguments or code parts that can be adapted to the user's needs. Use them to

doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md

@@ -4,15 +4,89 @@
 
     Ink is better than the best memory.
 
-This documentation is written in markdown and translated into static html pages using
-[mkdocs](https://www.mkdocs.org/). A single configuration file holds the pages structure
-as well as specification of the theme and extensions. This file is `mkdocs.yaml`.
+In this section you will find information on the technical setup of this documentation, the applied
+content rules, Git workflow and certain ways to contribute.
+
+Your contributions are highly welcome. This can range from fixing typos, improving the phrasing and
+wording to adopting examples, command lines and adding new content. Our goal is to provide a
+general, consistent and up to date documentation. Thus, it is by no means a static documentation.
+Moreover, is is constantly reviewed and updated.
 
-We manage all essential files (markdown pages, graphics, configuration, theme, etc.) within a Git
-repository, which makes it quite easy to contribute to this documentation. In principle, there are
-three possible ways how to contribute to this documentation. These ways are outlined below.
+## Technical Setup
 
-## Content Guide Lines
+This documentation is written in markdown and translated into static html pages using
+[mkdocs](https://www.mkdocs.org/). The single configuration file `mkdocs.yml` holds the pages
+structure as well as specification of the theme and extensions.
+
+We manage all essential files (markdown pages, graphics, configuration, theme, etc.) within a
+[public Git repository](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium),
+allowing for collaborative working and revision control. GitLab features offer different
+possibilities of contribution and ensure up-to-date and consistent content by including a review
+process. In principle, there are three possible ways how you can contribute to this documentation.
+These are outlined below.
+
+!!! tip "Before you start"
+
+    Before you start your very first commit, please make sure that you are familiar with our
+    [Git workflow](#git-workflow) and that you have at least skimmed the
+    [Content Rules](content_rules.md).
+
+## Git Workflow
+
+We employ a so-called Git feature workflow with development branch. In our case, the working branch
+is called `preview` and is kept in parallel to the `main` branch.
+
+All contributions, e.g., new content, improved wording, fixed typos, etc, are added to separate
+feature branches which base on `preview`. If the contribution is ready, you will have to create a
+merge request back to the `preview` branch. A member of ZIH team will review the changes (four-eyes
+principle) and finally merge your changes to `preview`. All contributions need to pass the CI
+pipeline consisting of several checks to ensure compliance with the content rules. Please, don't
+worry too much about the checks. ZIH staff will help you with that. You will find more information
+on the [CI/CD pipeline](cicd-pipeline) in the eponymous subsection.
+
+In order to publish the updates and make them visible in the compendium,
+the changes on `preview` branch are either automatically merged into the `main` branch on every
+Monday via a pipeline schedule, or manually by admin staff. Moreover, the `main` branch is deployed
+to [https://compendium.hpc.tu-dresden.de](https://compendium.hpc.tu-dresden.de) and always reflects
+a production-ready state. Manual interventions are only necessary in case of merge conflicts. The
+admin staff will take care on this process.
+
+???+ note "Graphic on Git workflow"
+
+    The applied Git workflow is depicted in the following graphic. Here, two feature branches `foo`
+    and `bar` are created basing on `preview`. Three individual commits are added to branch `foo`
+    before it is ready and merged back to `preview`. The contributions on `bar` consist only one
+    commit. In the end, all contribution are merged to the `main` branch.
+
+    ```mermaid
+    %% Issues:
+    %% - showCommitLabel: false does not work; workaround is to use `commit id: " "`%%
+    %% - Changing the theme does not effect the rendered output. %%
+    %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': false} }%%
+    gitGraph
+        commit
+        branch preview
+        checkout preview
+        commit
+        branch foo
+        checkout foo
+        commit
+        commit
+        checkout preview
+        branch bar
+        checkout bar
+        commit
+        checkout preview
+        merge bar
+        checkout foo
+        commit
+        checkout preview
+        merge foo
+        checkout main
+        merge preview
+    ```
+
+## Content Rules
 
 To ensure a high-quality and consistent documentation and to make it easier for readers to
 understand all content, we set some [Content rules](content_rules.md). Please follow
@@ -46,8 +120,8 @@ documentation.
 
 If you have a web browser (most probably you are using it to read this page) and want to contribute
 to the documentation, you are good to go. GitLab offers a rich and versatile web interface to work
-with repositories. To start fixing typos and edit source files, please find more information on
-[Contributing via web browser](contribute_browser.md).
+with repositories. To start fixing typos and edit source files, please find more information on the
+page [Contributing via web browser](contribute_browser.md).
 
 ## Contribute via Local Clone
 
@@ -56,3 +130,11 @@ used in the back-end. Using them should ensure that merge requests will not be b
 due to automatic checking.
 The page on [Contributing via local clone](contribute_container.md) provides you with the details
 about how to setup and use your local clone of the repository.
+
+## CI/CD Pipeline
+
+All contributions need to pass the CI pipeline which consists of various checks to ensure, that the
+[content rules](content_rules.md) are met.
+
+The stages of the CI/CD pipeline are defined in a `.gitlab.yaml` file. For security reasons, this
+file is managed in a second, private repository.

doc.zih.tu-dresden.de/docs/jobs_and_resources/binding_and_distribution_of_tasks.md

@@ -270,3 +270,9 @@ node and the second node while filling the sockets linearly.
     export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK
     srun --ntasks 8 --cpus-per-task $OMP_NUM_THREADS --cpu_bind=cores --distribution=cyclic:block ./application
     ```
+
+## GPU
+
+Currently with the Slurm version (20.11.9) used ZIH systems
+it **is not possible** to bind tasks to GPUs. Is will be possible as soon as Slurm is updated at
+least to version 21.08.0 (see [GRES/MIG documentation in Slurm 21.08.0](https://slurm.schedmd.com/archive/slurm-21.08.0/gres.html#MIG_Management)).

doc.zih.tu-dresden.de/docs/software/singularity_recipe_hints.md

@@ -58,6 +58,70 @@ EOF
     ./hello
 ```
 
+### Distributed memory
+
+#### MPICH
+
+Ubuntu+MPICH definition file:
+
+```bash
+Bootstrap: docker
+From: ubuntu:20.04
+
+%files
+    mpitest.c /opt
+
+%environment
+    export MPICH_DIR=/opt/mpich
+    export SINGULARITY_MPICH_DIR=$MPICH_DIR
+    export SINGULARITYENV_APPEND_PATH=$MPICH_DIR/bin
+    export SINGULAIRTYENV_APPEND_LD_LIBRARY_PATH=$MPICH_DIR/lib
+
+%post
+    echo "Installing required packages..."
+    apt-get update && apt-get install -y wget git bash gcc gfortran g++ make file
+
+    # required for F90 bindings
+    apt-get install -y python3
+
+    echo "Installing MPICH"
+    export MPICH_DIR=/opt/mpich
+    export MPICH_VERSION=4.1
+    export MPICH_URL="https://www.mpich.org/static/downloads/$MPICH_VERSION/mpich-$MPICH_VERSION.tar.gz"
+    mkdir -p /tmp/mpich
+    mkdir -p /opt
+    # Download
+    cd /tmp/mpich && wget -O mpich-$MPICH_VERSION.tar.gz $MPICH_URL && tar -xf mpich-$MPICH_VERSION.tar.gz
+    
+    # Configure and compile/install
+    cd /tmp/mpich/mpich-$MPICH_VERSION
+    ./configure --prefix=$MPICH_DIR && make install
+    
+    
+    # Set env variables so we can compile our application
+    export PATH=$MPICH_DIR/bin:$PATH
+    export LD_LIBRARY_PATH=$MPICH_DIR/lib:$LD_LIBRARY_PATH
+    export MANPATH=$MPICH_DIR/share/man:$MANPATH
+    
+    
+    echo "Compiling the MPI application..."
+    cd /opt && mpicc -o mpitest mpitest.c
+```
+
+At your local machine:
+
+```console
+marie@local$ sudo singularity build ubuntu_mpich.sif ubuntu_mpich.def
+```
+
+This will create the `ubuntu_mpich.sif` file that you have to copy to HPC system.
+
+At the HPC system run as following:
+
+```console
+marie@login$ srun -n 4 --ntasks-per-node 2 --time=00:10:00 singularity exec ubuntu_mpich.sif /opt/mpitest
+```
+
 ### CUDA + CuDNN + OpenMPI
 
 * Chosen CUDA version depends on installed driver of host

doc.zih.tu-dresden.de/util/grep-forbidden-patterns.sh

@@ -38,7 +38,7 @@ Do not use \"up-to-date\", because this should be an inherent property of this g
 
 i	\(\<up-to-date\>\|up to date\)
 Replace \"todo\" with real content.
-doc.zih.tu-dresden.de/docs/archive/system_triton.md
+doc.zih.tu-dresden.de/docs/archive/system_triton.md	doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
 i	\<todo\>	<!--.*todo.*-->
 Replace variations of \"Coming soon\" with real content.