From f6c4b93577b6c15e363b382c4ed3fa7db4734d22 Mon Sep 17 00:00:00 2001
From: Fredrik Jansson <fjansson@abo.fi>
Date: Tue, 13 May 2025 16:03:39 +0200
Subject: [PATCH] add output documentation

---
 book/_toc.yml             |  2 +-
 book/running/output.ipynb | 32 ------------------
 book/running/output.md    | 68 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+), 33 deletions(-)
 delete mode 100644 book/running/output.ipynb
 create mode 100644 book/running/output.md

diff --git a/book/_toc.yml b/book/_toc.yml
index 04bb4b5..7676879 100644
--- a/book/_toc.yml
+++ b/book/_toc.yml
@@ -10,7 +10,7 @@ parts:
   - caption: Running your first case in DALES
     chapters:
       - file: running/testcase.ipynb
-      - file: running/output.ipynb
+      - file: running/output.md
   - caption: Setting up your own case
     chapters:
       - file: running/basic_namoptions.ipynb
diff --git a/book/running/output.ipynb b/book/running/output.ipynb
deleted file mode 100644
index 071241c..0000000
--- a/book/running/output.ipynb
+++ /dev/null
@@ -1,32 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Output"
-   ]
-  }
- ],
- "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/output.md b/book/running/output.md
new file mode 100644
index 0000000..3ddf036
--- /dev/null
+++ b/book/running/output.md
@@ -0,0 +1,68 @@
+# DALES Output
+
+## Enabling output
+
+To save cross sections or 3D fields the following settings are needed in the namelist file for Dales. Output is saved in netCDF format by default.
+
+```
+&NAMCROSSSECTION
+lcross      = .true.
+crossheight = 20,40,80
+dtav        = 60
+/
+```
+crossheights is a list of z-levels for which to save horizontal cross sections.
+
+```
+&NAMFIELDDUMP
+lfielddump  = .true.
+dtav        = 60
+/
+```
+
+
+## Output with one directory per MPI row
+When running with many cores the amount of output files in the run directory becomes annoying (and some supercomputer file systems don't like more than a few thousand files per directory).
+With the option `loutdirs` set to true, the output from each row of MPI processes is placed in its own directory: 000, 001, 002, ... .
+```
+&RUN
+loutdirs = .true.
+/
+```
+
+## Merging netCDF tiles
+
+For 2D and 3D output, each DALES process saves it's own  
+The command `cdo` can be used to merge netCDF tiles.
+Use cdo version >= 2.0.6.
+
+```
+cdo -O collgrid crossxy.0001.*.nc  crossxy.0001.nc
+```
+
+`-O` is for overwriting the target file if it exists.
+
+### Selecting variables
+
+```
+cdo -O collgrid,vxy crossxy.0001.*.nc  crossxy.0001.nc
+```
+To include only selected variables in the output, add a comma-separated list after collgrid (no spaces).
+
+### Compression
+Optionally add flags to enable compressed netCDF4 output:
+```
+cdo -f nc4 -z zip_6 -O collgrid crossxy.0001.*.nc  crossxy.0001.nc
+```
+
+### NetCDF time units
+
+If both `xyear` and `xday` are present in the DOMAIN namelist,
+DALES outputs proper time units in the netCDF: `seconds since 2020-01-02T00:00:00.` Otherwise the unit is just `s`, meaning seconds since the start of the simulation.
+
+### Handling large cases
+
+If cdo runs out of memory, it may help to do the merging in two steps:
+first merge each row of tiles into a stripe, then merge the stripes.
+To save time, do not enable compression for the intermediate files.
+