ratarmount workflow example

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

@@ -239,31 +239,56 @@ Furthermore, the analysis results of the archive will be stored in a sidecar fil
 archive or in your home directory if the archive is in a non-writable location.
 Subsequent mounts instantly load that sidecar file instead of reanalyzing the archive.
 
-[Ratarmount](https://github.com/mxmlnkn/ratarmount) is available on PyPI and can be installed via pip.
-It is recommended to install it inside a [Python virtual environment](python_virtual_environments.md).
+Ratarmount is still in development, so if there are problems or if it is unexpectedly slow,
+please [open an issue](https://github.com/mxmlnkn/ratarmount/issues) on GitHub.
+
+There also is a library interface called
+[ratarmountcore](https://github.com/mxmlnkn/ratarmount/tree/master/core#example) that works
+fully without FUSE, which might make access to files from Python even faster.
+
+#### Example Workflow for using Ratarmount
+
+Ratarmount is installed globally on the HPC system.
+The first step is to create a tar archive to bundle your small files into one.
+If your small files are already on the HPC filesystems, you can move them using the
+Datamover node.
+If they are still on your local machine, you should do this locally
+and just upload the tar archive, which will also speed up the upload step.
+Just replace `dtar` with `tar` in the following example.
+Please note that in most cases creating a compressed archive will degrade read performance
+e.g. for images, audio and video files.
 
 ```console
-marie@compute$ pip install ratarmount
+marie@login$ dttar cf <dataset.tar> <folder_containing_my_small_files> 
 ```
 
-After that, you can use ratarmount to mount a TAR file using the following approach:
+Once the tar archive has been created, you can mount it on the compute node using `ratarmount'.
+All files in the mount points can be accessed as normal files or directories
+in the filesystem without any special treatment.
+Note that the tar archive must be mounted on every compute node in your job.
 
 ```bash
-marie@compute$ ratarmount <compressed_file> <mountpoint>
-```
+#!/bin/bash
 
-Thus, you could invoke ratarmount as follows:
+#SBATCH --ntasks=3
+#SBATCH --nodes=2
+#SBATCH --time=00:05:00
 
-```console
-marie@compute$ ratarmount inputdata.tar.gz input-folder
 
-# Now access the data as if it was a directory, e.g.:
-marie@compute$ cat input-folder/input-file1
-```
+# mount the dataset on every node one time
+DATASET=/tmp/${SLURM_JOB_ID}
+srun --ntasks-per-node=1 mkdir ${DATASET}
+srun --ntasks-per-node=1 ratarmount <dataset.tar> ${DATASET}
 
-Ratarmount is still in development, so if there are problems or if it is unexpectedly slow,
-please [open an issue](https://github.com/mxmlnkn/ratarmount/issues) on GitHub.
+# now it can be accessed like a normal directory
+srun -ntasks=1 ls ${DATASET}
 
-There also is a library interface called
-[ratarmountcore](https://github.com/mxmlnkn/ratarmount/tree/master/core#example) that works
-fully without FUSE, which might make access to files from Python even faster.
+# start the application
+srun ./my_application --input-directory ${DATASET}
+
+# unmount it after all work is done
+srun --ntasks-per-node=1 ratarmount -u ${DATASET}
+```
+
+Hint: If you are starting many processes per node, Ratarmount could benefit from
+having individual mount points for each process, rather than just one per node.