Merge pull request #1 from StevenvdLinden/main

20241023: added some initial (mostly empty) pages
dalesteam · Oct 23, 2024 · 8e11478 · 8e11478
2 parents e1d0e6d + 5185ed2
commit 8e11478
Show file tree

Hide file tree

Showing 16 changed files with 1,429 additions and 3 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/book/.DS_Store b/book/.DS_Store
diff --git a/book/_toc.yml b/book/_toc.yml
@@ -2,9 +2,30 @@ format: jb-book
 root: intro.md
 
 parts:
-  - caption: Running DALES
+  - caption: Getting started with DALES!
+    chapters:
+      - file: running/settingup.ipynb
+      - file: running/compilation.ipynb
+  - caption: Running your first case in DALES
+    chapters:
+      - file: running/testcase.ipynb
+      - file: running/output.ipynb
+  - caption: Setting up your own case
+    chapters:
+      - file: running/basic_namoptions.ipynb
+  - caption:  Advanced DALES options
     chapters:
       - file: running/tracers.ipynb
+      # - file: running/chemistry.ipynb
+      # - file: running/ibm.ipynb
+      # - file: running/openbcs.ipynb
+      # - file: running/gpu.ipynb
+  - caption:  Options outside main branch (for now)
+    chapters:
+      - file: running/ibm.ipynb
+  - caption:  Recent publications using DALES
+    chapters:
+      - file: running/papers.ipynb
   - caption: Contributing
     chapters:
       - file: developers/usermanual.md
diff --git a/book/intro.md b/book/intro.md
@@ -1,7 +1,15 @@
 # DALES documentation
 
-Welcome to the DALES documentation!
+Welcome to the documentation of the Dutch Atmospheric Large-Eddy Simulation (in short: DALES)!
 
 ```{note}
 This documentation is a work-in-progress and for a future release of DALES.
-```
+```
+
+The aim of this manual is to provide an up-to-date starting point for new users, explaining how to compile, setup and run the Dutch Atmospheric Large-Eddy Simulation. The manual will cover, among other things, general settings, and options (for example, statistics output), and instructions how to make more advanced cases (for example, simulations with tracers). The principles of the DALES model are described in [Heus et al., 2010](https://doi.org/10.5194/gmd-3-415-2010).
+
+```{note}
+This manual is written for the main-branch (v. X.Y) in mind. Other branches may contain new features that are not necessarily described in this manual.
+```
+
+At a later stage, this manual may be extended with in-depth information on code structure, variable naming schemes, and implementation details, better enabling people to become _new contributors_ to DALES.
diff --git a/book/running/basic_namoptions.ipynb b/book/running/basic_namoptions.ipynb
@@ -0,0 +1,33 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Basic Namoptions\n",
+    "\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/chemistry.ipynb b/book/running/chemistry.ipynb
@@ -0,0 +1,239 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Setting up your system\n",
+    "\n",
+    "DALES can handle an arbitrary number of tracers. Examples of tracers are aerosols, hydrometeors, chemical species, et cetera. We distinguish two types of tracers:\n",
+    "\n",
+    "- Internal tracers. These are tracers defined internally, by the model itself. For example, the the bulkmicrophysics schemes define various tracers that represent quantities like rain and cloud droplets. The user does not have to provide any input for these tracers.\n",
+    "- User-defined tracers. These tracers need to be provided by the user in a NetCDF file. \n",
+    "\n",
+    "## Preparing the NetCDF file"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First, we have to define a new tracer NetCDF file. This file has to be called `tracers.<iexpnr>.nc`, where `<iexpnr>` corresponds to what you have set as `iexpnr` in the `&RUN` section of your namelist."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import netCDF4 as nc\n",
+    "\n",
+    "tracers_nc = nc.Dataset(\"tracers.001.nc\", \"w\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, we'll create a dimension corresponding to the vertical levels. Tracers are defined at the full levels (cell centers), so the dimension we have to provide is `zt`. We don't have to provide the actual values of the levels, since those have already been read from `init.001.nc`. This example is based on the benchmark RICO case, which uses 126 vertical levels."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<class 'netCDF4._netCDF4.Dataset'>\n",
+      "root group (NETCDF4 data model, file format HDF5):\n",
+      "    dimensions(sizes): zt(126)\n",
+      "    variables(dimensions): \n",
+      "    groups: \n"
+     ]
+    }
+   ],
+   "source": [
+    "height_dim = tracers_nc.createDimension(\"zt\", size=126)\n",
+    "print(tracers_nc)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Adding a tracer\n",
+    "Now we can define our tracer. For this example, we make a tracer that represents carbon dioxide (CO2): "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<class 'netCDF4._netCDF4.Dataset'>\n",
+      "root group (NETCDF4 data model, file format HDF5):\n",
+      "    dimensions(sizes): zt(126)\n",
+      "    variables(dimensions): float64 co2(zt)\n",
+      "    groups: \n"
+     ]
+    }
+   ],
+   "source": [
+    "co2 = tracers_nc.createVariable(\"co2\", \"f8\", (\"zt\",))\n",
+    "print(tracers_nc)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And we provide some (fake) initial profile:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "co2[:] = np.ones(126) * 1e-6"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Tracer attributes\n",
+    "We can provide a number of attributes for our new tracer. These attributes either provide extra information for output, or enable extra schemes for the tracer.\n",
+    "\n",
+    "| Attribute    | Type    | Description |\n",
+    "| ------------ | ------- | ----------- |\n",
+    "| `long_name`  | String  | Full name of the tracer |\n",
+    "| `unit`       | String  | Unit of the tracer |\n",
+    "| `molar_mass` | Float   | Molar mass of the tracer |\n",
+    "| `lemis`      | Integer | Tracer is emitted (1=True, 0=False)|\n",
+    "| `lreact`     | Integer | Tracer is involved in chemistry |\n",
+    "| `ldep`       | Integer | Tracer is deposited |\n",
+    "| `lags`       | Integer | Tracer is involved in photosynthesis |\n",
+    "\n",
+    "Attributes can be set like this:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "ename": "RuntimeError",
+     "evalue": "NetCDF: Not a valid ID",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mRuntimeError\u001b[0m                              Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[13], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43mco2\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mlong_name\u001b[49m \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mcarbon dioxide\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m      2\u001b[0m co2\u001b[38;5;241m.\u001b[39munit \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mkg/kg\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m      3\u001b[0m co2\u001b[38;5;241m.\u001b[39mmolar_mass \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m44.009\u001b[39m\u001b[38;5;124m\"\u001b[39m\n",
+      "File \u001b[0;32msrc/netCDF4/_netCDF4.pyx:4907\u001b[0m, in \u001b[0;36mnetCDF4._netCDF4.Variable.__setattr__\u001b[0;34m()\u001b[0m\n",
+      "File \u001b[0;32msrc/netCDF4/_netCDF4.pyx:4613\u001b[0m, in \u001b[0;36mnetCDF4._netCDF4.Variable.setncattr\u001b[0;34m()\u001b[0m\n",
+      "File \u001b[0;32msrc/netCDF4/_netCDF4.pyx:1775\u001b[0m, in \u001b[0;36mnetCDF4._netCDF4._set_att\u001b[0;34m()\u001b[0m\n",
+      "File \u001b[0;32msrc/netCDF4/_netCDF4.pyx:1700\u001b[0m, in \u001b[0;36mnetCDF4._netCDF4._get_format\u001b[0;34m()\u001b[0m\n",
+      "File \u001b[0;32msrc/netCDF4/_netCDF4.pyx:2113\u001b[0m, in \u001b[0;36mnetCDF4._netCDF4._ensure_nc_success\u001b[0;34m()\u001b[0m\n",
+      "\u001b[0;31mRuntimeError\u001b[0m: NetCDF: Not a valid ID"
+     ]
+    }
+   ],
+   "source": [
+    "co2.long_name = \"carbon dioxide\"\n",
+    "co2.unit = \"kg/kg\"\n",
+    "co2.molar_mass = \"44.009\"\n",
+    "co2.lemis = 1\n",
+    "co2.lags = 1\n",
+    "\n",
+    "print(co2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Don't forget to close the NetCDF file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tracers_nc.close()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can check the end result with `ncdump`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "netcdf tracers.001 {\n",
+      "dimensions:\n",
+      "\tzt = 126 ;\n",
+      "variables:\n",
+      "\tdouble co2(zt) ;\n",
+      "data:\n",
+      "\n",
+      " co2 = _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, \n",
+      "    _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, \n",
+      "    _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, \n",
+      "    _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, \n",
+      "    _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, _, \n",
+      "    _, _, _, _, _, _, _ ;\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "!ncdump tracers.001.nc"
+   ]
+  }
+ ],
+ "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
+}