From cd6e84f42d2b89f95f5bfd27905ba2b8e76878d2 Mon Sep 17 00:00:00 2001
From: Fredrik Jansson <fjansson@abo.fi>
Date: Thu, 15 May 2025 11:18:19 +0200
Subject: [PATCH] update compiling instructions

---
 book/_toc.yml                  |   4 +-
 book/running/compilation.ipynb | 119 -------------------------
 book/running/compilation.md    | 157 +++++++++++++++++++++++++++++++++
 book/running/settingup.ipynb   | 144 ------------------------------
 book/running/settingup.md      |  43 +++++++++
 5 files changed, 202 insertions(+), 265 deletions(-)
 delete mode 100644 book/running/compilation.ipynb
 create mode 100644 book/running/compilation.md
 delete mode 100644 book/running/settingup.ipynb
 create mode 100644 book/running/settingup.md

diff --git a/book/_toc.yml b/book/_toc.yml
index 7676879..6e83772 100644
--- a/book/_toc.yml
+++ b/book/_toc.yml
@@ -5,8 +5,8 @@ parts:
   - caption: Getting started with DALES!
     chapters:
       - file: running/changes.md
-      - file: running/settingup.ipynb
-      - file: running/compilation.ipynb
+      - file: running/settingup.md
+      - file: running/compilation.md
   - caption: Running your first case in DALES
     chapters:
       - file: running/testcase.ipynb
diff --git a/book/running/compilation.ipynb b/book/running/compilation.ipynb
deleted file mode 100644
index 056d951..0000000
--- a/book/running/compilation.ipynb
+++ /dev/null
@@ -1,119 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "(sec:compilation)=\n",
-    "# Compilation of DALES\n",
-    "\n",
-    "## Generic compilation\n",
-    "The next step after obtaining the code and installing required dependencies, is to build the code. As a starting point, we assume you are still in the main `dales` directory after checking out the main branch via git. It is advised the build the code in a different folder to better maintain overview. We therefore first move one directory up, make a new directory and move into that directory.\n",
-    "```{code} shell\n",
-    "cd ../\n",
-    "mkdir build\n",
-    "cd build\n",
-    "```\n",
-    "\n",
-    "We then invoke `cmake` on the directory where the code is placed. This will configure the build of the code.\n",
-    "```{code} shell\n",
-    "cmake ../dales \n",
-    "```\n",
-    "Finally, the code can be build with the following command:\n",
-    "```{code} shell\n",
-    "make \n",
-    "```\n",
-    "After successfull compilation, the executable `dales` is located in the subdirectory `bin/`. Compilation of the code may be sped up using the `-j <nprocs>` specifier, with `nprocs` being the amount of parallel processes.\n",
-    "\n",
-    "## Compilation options\n",
-    "It is possible to specify optional features at the compilation stage of the model. These optional features can be activated by adding them as specifyers to the cmake command. CMake options are specified as `-D<option>=<value>`. For example:\n",
-    "```{code} shell\n",
-    "cmake ../dales -DCMAKE_BUILD_TYPE=Debug\n",
-    "```\n",
-    "will produce a debug build. The debug build is much slower than the release build but contains more error checks. A list of commonly used options is given below.\n",
-    "\n",
-    "| Option | Description | Allowed values | Default |\n",
-    "| ------ | ----------- | -------------- | ------- |\n",
-    "| `-DENABLE_FFTW` | Build with FFTW | True/False | True |\n",
-    "| `-DENABLE_HYPRE` | Build with HYPRE | True/False | False |\n",
-    "| `-DENABLE_FP32_FIELDS` | Use single precision floating-point numbers for prognostic fields (momentum, temperature, etc.) | True/False | False |\n",
-    "| `-DENABLE_FP32_POIS` | Use single precision floating-point numbers for the Poisson solver | True/False | False |\n",
-    "| `-DENABLE_ACC` | Build with GPU support through OpenACC | True/False | False |\n",
-    "\n",
-    "```{caution}\n",
-    "To use HYPRE or FFTW, the library needs to both be enabled at compilation and selected at runtime by setting the &SOLVER section of the namoptions input file. `FIX LINK: See Alternative Poisson solvers`.\n",
-    "```\n",
-    "```{hint}\n",
-    "`-DPOIS_PRECISION=32` and `-DUSE_HYPRE=True` can be used together, but HYPRE is 64-bit only, so only use this, if it is really what you want.\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Compilation on specific clusters\n",
-    "\n",
-    "### Delftblue (TUDelft HPC)\n",
-    "**Tested 20-11-2023**\n",
-    "```{code} shell\n",
-    "module load 2023r1-gcc11\n",
-    "module load openmpi/4.1.4\n",
-    "module load cmake/3.24.3\n",
-    "module load netcdf-fortran/4.6.0\n",
-    "module load fftw/3.3.10\n",
-    "\n",
-    "git clone https://github.com/dalesteam/dales\n",
-    "cd dales\n",
-    "mkdir build\n",
-    "cd build\n",
-    "\n",
-    "export SYST=gnu-fast\n",
-    "cmake ..  -DUSE_FFTW=True\n",
-    "\n",
-    "make -j 8\n",
-    "```\n",
-    "\n",
-    "### Snellius (Dutch National system)\n",
-    "**Tested with module set 2022**\n",
-    "```{code} shell\n",
-    "module load 2022\n",
-    "module load foss/2022a\n",
-    "module load netCDF-Fortran/4.6.0-gompi-2022a\n",
-    "module load CMake/3.23.1-GCCcore-11.3.0\n",
-    "# module load Hypre/2.25.0-foss-2022a # optional\n",
-    "\n",
-    "mkdir build\n",
-    "cd build\n",
-    "export SYST=gnu-fast\n",
-    "cmake .. -DUSE_FFTW=True\n",
-    "# or, for single precision:\n",
-    "# cmake .. -DUSE_FFTW=True -DFIELD_PRECISION=32 -DPOIS_PRECISION=32\n",
-    "\n",
-    "make -j 8\n",
-    "```"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "dalesdocs",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.13.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
diff --git a/book/running/compilation.md b/book/running/compilation.md
new file mode 100644
index 0000000..decd122
--- /dev/null
+++ b/book/running/compilation.md
@@ -0,0 +1,157 @@
+# Downloading the code
+
+The next step after installed these libraries and packages is to get the DALES code. The example below uses the `Git` software for this purpose. After going to the destination path on your system, download the code by using the command below
+``` shell
+<username> <currentpath> % git clone https://github.com/dalesteam/dales.git
+```
+
+Here, a new directory called `dales` should have appeared. By default, the latest main branch is checked out inside this directory (denoted by the `*`). This can be confirmed by doing the following
+``` shell
+cd dales
+git branch
+```
+which should give as output
+``` shell
+ * main
+```
+
+Other available branches of the main repository can be viewed with the `-a` option
+``` shell
+<username> dales % git branch -a
+* main
+remotes/origin/3.1
+remotes/origin/3.2
+remotes/origin/4.1
+remotes/origin/4.1_TROFFEEhack
+remotes/origin/4.1_aero_m7
+...
+```
+
+Checking out a specific branch (e.g., the `ruisdael` branch) is done via
+``` shell
+git checkout -b <newname> remotes/origin/ruisdael
+```
+
+### Initialize submodules
+This step is required to fetch some external libraries, e.g. RRTMG and RRTMGP.
+
+```shell
+git submodule init
+git submodule update
+```
+
+
+
+### Planning on coding yourself in DALES?
+If you plan to change parts of the code and want to keep track of your changes, it may be worthwhile to use your personal Github account and first fork the main repository. The steps to get the code on your system are then slightly different.
+
+``` shell
+git remote add origin https://github.com/<your_account>/dales.git
+git remote add upstream https://github.com/dalesteam/dales.git
+
+git config --global user.name "YOUR NAME"
+git config checkout.defaultRemote origin
+
+git fetch --all
+
+git checkout -b main origin/main
+```
+```{note}
+This option will checkout the code in your current directory, _without_ first making a separate `dales` destination directory.
+```
+
+
+
+
+(sec:compilation)=
+# Compilation of DALES
+
+## Generic compilation
+The next step after obtaining the code and installing required dependencies, is to build the code. As a starting point, we assume you are still in the main `dales` directory after checking out the main branch via git. It is advised the build the code in a different folder to better maintain overview. We therefore first move one directory up, make a new directory and move into that directory.
+``` shell
+cd ../
+mkdir build
+cd build
+```
+
+We then invoke `cmake` on the directory where the code is placed. This will configure the build of the code.
+``` shell
+cmake ../dales
+```
+Finally, the code can be build with the following command:
+``` shell
+make
+```
+After successfull compilation, the executable `dales` is located in the subdirectory `bin/`. Compilation of the code may be sped up using the `-j <nprocs>` specifier, with `nprocs` being the amount of parallel processes.
+
+## Compilation options
+It is possible to specify optional features at the compilation stage of the model. These optional features can be activated by adding them as specifyers to the cmake command. CMake options are specified as `-D<option>=<value>`. For example:
+``` shell
+cmake ../dales -DCMAKE_BUILD_TYPE=Debug
+```
+will produce a debug build. The debug build is much slower than the release build but contains more error checks. A list of commonly used options is given below.
+
+| Option | Description | Allowed values | Default |
+| ------ | ----------- | -------------- | ------- |
+| `-DENABLE_FFTW` | Build with FFTW | True/False | True |
+| `-DENABLE_HYPRE` | Build with HYPRE | True/False | False |
+| `-DENABLE_FP32_FIELDS` | Use single precision floating-point numbers for prognostic fields (momentum, temperature, etc.) | True/False | False |
+| `-DENABLE_FP32_POIS` | Use single precision floating-point numbers for the Poisson solver | True/False | False |
+| `-DENABLE_ACC` | Build with GPU support through OpenACC | True/False | False |
+
+```{caution}
+To use HYPRE or FFTW, the library needs to both be enabled at compilation and selected at runtime by setting the &SOLVER section of the namoptions input file. See [Alternative Poisson solvers (Wiki)](https://github.com/dalesteam/dales/wiki/Alternative-Poisson-solvers). By default, FFTW is used if the library was found at compilation.
+
+```
+```{hint}
+`-DPOIS_PRECISION=32` and `-DUSE_HYPRE=True` can be used together, but HYPRE is 64-bit only, so only use this, if it is really what you want.
+```
+
+## Compilation on specific clusters
+
+### Delftblue (TUDelft HPC)
+**Tested 20-11-2023**
+``` shell
+module load 2023r1-gcc11
+module load openmpi/4.1.4
+module load cmake/3.24.3
+module load netcdf-fortran/4.6.0
+module load fftw/3.3.10
+
+git clone https://github.com/dalesteam/dales
+
+# for dev branch:
+git checkout dev
+git submodule init
+git submodule update
+
+
+cd dales
+mkdir build
+cd build
+
+export SYST=gnu-fast
+cmake ..  -DUSE_FFTW=True
+
+make -j 8
+```
+
+### Snellius (Dutch National system)
+**Tested with module set 2023**
+``` shell
+module load 2023
+module load foss/2023a
+module load netCDF-Fortran/4.6.1-gompi-2023a
+module load CMake/3.26.3-GCCcore-12.3.0
+# module load Hypre/2.29.0-foss-2023a
+
+mkdir build
+cd build
+export SYST=gnu-fast
+cmake ..
+
+# or, for single precision (options for version >= 5.0 or dev):
+# cmake ../dales -DENABLE_FP32_FIELDS=ON -DENABLE_FP32_POIS=ON
+
+make -j 8
+```
diff --git a/book/running/settingup.ipynb b/book/running/settingup.ipynb
deleted file mode 100644
index c65e505..0000000
--- a/book/running/settingup.ipynb
+++ /dev/null
@@ -1,144 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Setting up your system\n",
-    "\n",
-    "This section aids you in preparing and setting up your system to run DALES. We assume you are using a UNIX-based system and are familiar with basic terminal commands. First, we will cover the basic requirements to use DALES, which are minimally required. Second, a list of optional librariers/packages is given that will enable optimal use of DALES. Finally, we will tell how you to obtain the latest, tested version of the code (i.e., the \"main branch\")."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Requirements\n",
-    "DALES has a few general requirements for installation and usage:\n",
-    "- Fortran compiler (e.g., gfortran)\n",
-    "- MPI implementation (for multi-cpu runs)\n",
-    "- NetCDF4 libraries (for output/input)\n",
-    "- CMake libraries\n",
-    "- Make (to build the code)\n",
-    "\n",
-    "These requirements can be easily installed on most UNIX-based systems via a package manager. For example, on `ubuntu` via the standard package manager\n",
-    "```{code} shell\n",
-    "sudo apt install cmake\n",
-    "```\n",
-    "On MacOS, a standard way to install packages is via `homebrew`\n",
-    "```{code} shell\n",
-    "brew install cmake\n",
-    "```\n",
-    "\n",
-    "When using high-performance conputing (HPC) infrastructures, these requirements may already be pre-installed. Many HPC infrastructures employ sets of software modules in which case the requirements often have to be loaded in. A list of available modules on the system is then given by the following command:\n",
-    "```{code} shell\n",
-    "module avail\n",
-    "```\n",
-    "Available modules can subsequently be loaded via the `load` command, for example, loading `cmake` via:\n",
-    "```{code} shell\n",
-    "module load cmake\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Optional libraries/packages\n",
-    "The folling list of libraries/packages can (probably: will) make your use of DALES easier:\n",
-    "- FFTW3 library (better performance Fourier transforms)\n",
-    "- HYPRE library (for the iterative Poisson solver)\n",
-    "- Python + numpy + matplotlib (to generate input files and/or analyse output)\n",
-    "- Python-netcdf4 library (to read in netcdf4 output)\n",
-    "- CDO (easily merge and operate on multiple netcdf4 files)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Downloading the code\n",
-    "The next step after installed these libraries and packages is to get the DALES code. The example below uses the `Git` software for this purpose. After going to the destination path on your system, download the code by using the command below\n",
-    "```{code} shell\n",
-    "<username> <currentpath> % git clone https://github.com/dalesteam/dales.git\n",
-    "```\n",
-    "\n",
-    "Here, a new directory called `dales` should have appeared. By default, the latest main branch is checked out inside this directory (denoted by the `*`). This can be confirmed by doing the following\n",
-    "```{code} shell\n",
-    "cd dales\n",
-    "git branch\n",
-    "```\n",
-    "which should give as output\n",
-    "```{code} shell\n",
-    "<username> dales % * main\n",
-    "```\n",
-    "\n",
-    "Other available branches of the main repository can be viewed with the `-a` option\n",
-    "```{code} shell\n",
-    "<username> dales % git branch -a\n",
-    "* main\n",
-    "remotes/origin/3.1\n",
-    "remotes/origin/3.2\n",
-    "remotes/origin/4.1\n",
-    "remotes/origin/4.1_TROFFEEhack\n",
-    "remotes/origin/4.1_aero_m7\n",
-    "...\n",
-    "```\n",
-    "\n",
-    "Checking out a specific branch (e.g., the `ruisdael` branch) is done via\n",
-    "```{code} shell\n",
-    "git checkout -b <newname> remotes/origin/ruisdael\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Planning on coding yourself in DALES?\n",
-    "If you plan to change parts of the code and want to keep track of your changes, it may be worthwhile to use your personal Github account and first fork the main repository. The steps to get the code on your system are then slightly different.\n",
-    "\n",
-    "```{code} shell\n",
-    "git remote add origin https://github.com/<your_account>/dales.git\n",
-    "git remote add upstream https://github.com/dalesteam/dales.git\n",
-    "\n",
-    "git config --global user.name \"YOUR NAME\"\n",
-    "git config checkout.defaultRemote origin\n",
-    "\n",
-    "git fetch --all\n",
-    "\n",
-    "git checkout -b main origin/main\n",
-    "```\n",
-    "```{note}\n",
-    "This option will checkout the code in your current directory, _without_ first making a separate `dales` destination directory.\n",
-    "```"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "dalesdocs",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.13.0"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}
diff --git a/book/running/settingup.md b/book/running/settingup.md
new file mode 100644
index 0000000..c5a672b
--- /dev/null
+++ b/book/running/settingup.md
@@ -0,0 +1,43 @@
+# Setting up your system
+
+This section aids you in preparing and setting up your system to run DALES. We assume you are using a UNIX-based system and are familiar with basic terminal commands. First, we will cover the basic requirements to use DALES, which are minimally required. Second, a list of optional librariers/packages is given that will enable optimal use of DALES. Finally, we will tell how you to obtain the latest, tested version of the code (i.e., the "main branch").
+
+## Requirements
+DALES has a few general requirements for installation and usage:
+- Fortran compiler (e.g., gfortran)
+- MPI implementation (for multi-cpu runs, OpemnMPI and MPICH have been tested)
+- NetCDF4 libraries (for output/input)
+- CMake
+- Make (to build the code)
+- FFTW library (for the Poisson solver. Optional but highly recommended.)
+- HYPRE library (alternative Poisson solver. Optional.)
+
+These requirements can be easily installed on most UNIX-based systems via a package manager. For example, on `ubuntu` via the standard package manager
+```shell
+sudo apt install cmake
+```
+On MacOS, a standard way to install packages is via `homebrew`
+```shell
+brew install cmake
+```
+
+When using high-performance conputing (HPC) infrastructures, these requirements may already be pre-installed. Many HPC infrastructures employ sets of software modules in which case the requiments often have to be loaded in. A list of available modules on the system is then given by the following command:
+``` shell
+module avail
+```
+Available modules can subsequently be loaded via the `load` command, for example, loading `cmake` via:
+``` shell
+module load cmake
+```
+
+## Optional libraries/packages
+The folling list of libraries/packages can (probably: will) make your use of DALES easier:
+- Python + numpy + matplotlib (to generate input files and/or analyse output)
+- Python-netcdf4 library (to read in netcdf4 output)
+- CDO (easily merge and operate on multiple netcdf4 files. Version >= 2.0.6.)
+- ncview (interactive netCDF viewer)
+
+To use ncview on windows you might need to download VcXsrv, and on OSX you need XQuartz.
+
+
+