GPU: document the contents of a standalone dataset and how to produce one

Author: ktf

GPU/documentation/build-standalone.md

@@ -81,18 +81,42 @@ The standalone benchmark supports running on Run2 data exported from AliRoot, or
 In o2, `o2-tpc-reco-workflow` and the `o2-gpu-reco-workflow` can dump event data with the `configKeyValue` `GPU_global.dump=1;`.
 This will dump the event data to the local folder, all dumped files have a `.dump` file extension. If there are multiple TFs/events processed, there will be multiple `event.i.dump` files. In order to create a standalone dataset out of these, just copy all the `.dump` files to a subfolder in `~/standalone/events/[FOLDERNAME]`.
 
+## What a dataset consists of
+
+A dataset folder is read by `GPUReconstruction::ReadSettings` and `GPUChainTracking::ReadSettings`, and holds:
+
+- `settings.dump` - the GRP settings (solenoid field, continuous max time bin). Without it the benchmark aborts with `Error reading event config file`.
+- `event.<i>.dump` - one file per time frame / event.
+- the calibration objects, each written only if it was present when dumping: `tpctransform.dump`, `tpcpadgaincalib.dump`, `tpczslinkmapping.dump`, `dEdxCalibContainer.dump`, `matlut.dump`, `trdgeometry.dump`, `trdrecoparam.dump`.
+
+`tpctransform.dump` is needed for everything except already-transformed clusters; without it the run stops at `Need cluster native data for on-the-fly TPC transform`. `dEdxCalibContainer.dump` is needed unless dE/dx is switched off with `--rundEdx 0`.
+
+The folder is looked up under `./events/` relative to the working directory, so `-e mydata` reads `./events/mydata/`. Use `--absoluteEventsDir` to pass a path outside of `./events/`.
+
+## From simulated data
+
 Data can be dumped from raw data, or from MC data, e.g. generated by the Full System Test. In case of MC data, also MC labels are dumped, such that they are used in the `./ca --qa` mode.
 
-To get a dump from simulated data, please run e.g. the FST simulation as described in [full-system-test-setup.md](https://github.com/AliceO2Group/AliceO2/blob/dev/prodtests/full-system-test/documentation/full-system-test-setup.md).
-A simple run as
+First simulate, digitize and convert to raw, as described in [full-system-test-setup.md](https://github.com/AliceO2Group/AliceO2/blob/dev/prodtests/full-system-test/documentation/full-system-test-setup.md). Run it in a scratch folder, since it writes a lot of intermediate files:
 ```
-DISABLE_PROCESSING=1 NEvents=5 NEventsQED=100 SHMSIZE=16000000000 $O2_ROOT/prodtests/full_system_test.sh
+mkdir -p test && cd test
+ulimit -n 1024
+NEvents=5 NEventsQED=100 $O2_ROOT/prodtests/full_system_test.sh
 ```
-should be enough.
+`ulimit -n 1024` avoids the workflow running out of file descriptors. `NEventsQED` controls the QED background, which dominates the TPC occupancy, so lower it for a smaller dataset.
 
-Afterwards run the following command to dump the data:
+This leaves the raw time frames in `raw/` and already runs the reconstruction once. To get the dumps, re-run only the reconstruction over that raw data with the dump enabled:
 ```
-SYNCMODE=1 CONFIG_EXTRA_PROCESS_o2_gpu_reco_workflow="GPU_global.dump=1;" WORKFLOW_DETECTORS=TPC SHMSIZE=16000000000 $O2_ROOT/prodtests/full-system-test/dpl-workflow.sh
+ARGS_ALL_EXTRA="--completion-policy=wait --exit-transition-timeout 20" \
+  CONFIG_EXTRA_PROCESS_o2_gpu_reco_workflow="GPU_global.dump=1;"      \
+  WORKFLOW_DETECTORS=TPC SYNCMODE=1 SHMSIZE=$((16<<30)) EXTINPUT=1    \
+  $O2_ROOT/prodtests/full-system-test/dpl-workflow.sh
+```
+`CONFIG_EXTRA_PROCESS_o2_gpu_reco_workflow="GPU_global.dump=1;"` is what writes the `.dump` files; everything else just shapes the workflow. `--completion-policy=wait` and `--exit-transition-timeout 20` let the workflow drain and shut down by itself once the input ends, instead of having to be killed. `EXTINPUT=1` takes the raw data from the `readout-proxy` FMQ channel, which means a feeder has to run in a second shell (`datadistribution.sh` from the same folder, which needs the `DataDistribution` package). Leave `EXTINPUT` unset to have `dpl-workflow.sh` read the raw files directly instead, which needs no second process. See [env-variables.md](https://github.com/AliceO2Group/AliceO2/blob/dev/prodtests/full-system-test/documentation/env-variables.md) for the other variables.
+
+Finally collect the result into a dataset:
+```
+mkdir -p ~/standalone/events/fst-tpc && cp *.dump ~/standalone/events/fst-tpc/
 ```
 
 To dump standalone data from CTF raw data in `myctf.root`, you can use the same script, e.g.:
@@ -101,3 +125,16 @@ CTFINPUT=1 INPUT_FILE_LIST=myctf.root CONFIG_EXTRA_PROCESS_o2_gpu_reco_workflow=
 ```
 
 On the EPNs, you can find some reference data sets at `/home/drohr/standalone/events`.
+
+## Using the built-in event generator
+
+With `--eventGenerator` the benchmark generates simple synthetic events itself, without any simulation or raw data. The parent `events/` folder has to exist, since the generator only creates the dataset folder itself:
+```
+mkdir -p events
+./ca --eventGenerator -e gen --setMaxTimeBin 0 --rundEdx 0
+```
+`--setMaxTimeBin` has to be given, because the GRP settings are not read from a dataset in this mode and their default is the invalid sentinel `-2`.
+
+This writes `settings.dump` and the `event.<i>.dump` files, but no calibration objects. The events hold the legacy cluster format, not native clusters, so they can be inspected and used for the generator's own QA, but tracking on them stops at `Need cluster native data for on-the-fly TPC transform`, also with calibration objects present.
+
+`--recreateTrivialCalibObjects` writes default calibration objects (`tpctransform.dump`, `dEdxCalibContainer.dump`, ...) to the current folder without CCDB access; it needs `O2_ROOT` set for the TPC mapping files.