fix: Fix particle generation docs commands and add them to CI (#732)

PR #685 accidentally invalidated the Fatras tutorial's particle generation CLI examples. This fixes that, and uses the offending command line in our CI of the corresponding examples, which benefits both the docs (they won't accidentally get out of date anymore) and the examples CI (it tests evgen in a slightly more elaborate/realistic configuration).

EDIT: While I was at it, I also fixed the --output-xyz options of the material mapping tutorial in the same manner.

CI/run_examples.sh

@@ -78,9 +78,23 @@ run_example ActsExamplePropagationGeneric
 run_example ActsExamplePropagationPayload
 # TODO: Add TGeo propagation example (needs an input file + knowhow)
 
-# Run event generation examples
-run_example ActsExampleParticleGun
-run_example ActsExamplePythia8
+# Run event generation examples as suggested by the Fatras tutorial
+run_example ActsExampleParticleGun \
+                --output-dir=data/gen/four_muons \
+                --output-csv \
+                --gen-phi-degree=0:90 \
+                --gen-eta=-2:2 \
+                --gen-p-gev=1:5 \
+                --gen-pdg=13 \
+                --gen-randomize-charge \
+                --gen-nparticles=4
+run_example ActsExamplePythia8 \
+                --output-dir=data/gen/ttbar_mu140 \
+                --output-csv \
+                --rnd-seed=42 \
+                --gen-cms-energy-gev=14000 \
+                --gen-hard-process=Top:qqbar2ttbar=on \
+                --gen-npileup=140
 
 # Run Geantino recording example, as in the material mapping tutorial (but with
 # 10x less events to keep CI running times reasonable)

docs/howto/run_fatras.rst

@@ -37,7 +37,7 @@ directory.
    $ <build>/bin/ActsExampleParticleGun \
        --events=100 \
        --output-dir=data/gen/four_muons \
-       --output-csv=1 \
+       --output-csv \
        --gen-phi-degree=0:90 \
        --gen-eta=-2:2 \
        --gen-p-gev=1:5 \
@@ -70,7 +70,7 @@ the default soft QCD process. The output is written as CSV files in the
    $ <build>/bin/ActsExamplePythia8 \
        --events=100 \
        --output-dir=data/gen/ttbar_mu140 \
-       --output-csv=1 \
+       --output-csv \
        --rnd-seed=42 \
        --gen-cms-energy-gev=14000 \
        --gen-hard-process=Top:qqbar2ttbar=on \
@@ -104,7 +104,7 @@ muons in a reasonable kinematic range are generated.
 
    $ <build>/bin/ActsExampleFatrasGeneric \
        --output-dir=data/sim_generic/single_muon \
-       --output-csv=1 \
+       --output-csv \
        --events=100 \
        --bf-value=0 0 2 \
        --digi-geometric-3d
@@ -134,7 +134,7 @@ particles.
    $ <build>/bin/ActsExampleFatrasGeneric \
        --input-dir=data/gen/ttbar_mu140 \
        --output-dir=data/sim_generic/ttbar_mu140 \
-       --output-csv=1 \
+       --output-csv \
        --select-eta=-3:3 \
        --select-pt=0.5: \
        --remove-neutral \

docs/howto/run_material_mapping.rst

@@ -15,7 +15,7 @@ First we will need to extract the list of all the surfaces and volumes in our de
 
 .. code-block:: console
 
-  ./../build/bin/ActsExampleGeometryDD4hep -n1 -j1 --mat-output-file geometry-map  --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml --output-json true --mat-output-allmaterial true --mat-output-sensitives false
+  ./../build/bin/ActsExampleGeometryDD4hep -n1 -j1 --mat-output-file geometry-map  --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml --output-json --mat-output-allmaterial true --mat-output-sensitives false
 
 This algorithm is useful to obtain a visualisation of your detector using the different types of output available (``output-obj`` gives ``.obj`` with a 3D representation of the different subdetectors, for example). Here, we use ``output-json`` to obtain a map of all the surfaces and volumes in the detector with a ``ProtoSurfaceMaterial`` (or a ``ProtoVolumeMaterial``), ``mat-output-allmaterial`` ensure that a ``ProtoSurfaceMaterial`` (or a ``ProtoVolumeMaterial``) is associated to all the surfaces (or volumes), enforcing all of them to be written.
 Four types of surfaces exist:
@@ -58,7 +58,7 @@ The next step is to do a geantino scan of our detector. For this we will use the
 
 .. code-block:: console
 
-  ./../build/bin/ActsExampleGeantinoRecordingDD4hep -j1 --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml --output-root true -n10000
+  ./../build/bin/ActsExampleGeantinoRecordingDD4hep -j1 --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml --output-root -n10000
 
 
 The result of the geantino scan will be a root file containing material tracks. Those contain the direction and production vertex of the geantino, the total material accumulated and all the interaction points in the detector.
@@ -70,7 +70,7 @@ With the surfaces map and the material track we can finally do the material mapp
 
 .. code-block:: console
 
-  ./../build/bin/ActsExampleMaterialMappingDD4hep -j1 --input-root true --input-files geant-material-tracks.root --mat-input-type file --mat-input-file geometry-map.json --output-root true --output-json true --mat-mapping-collection material-tracks --mat-output-file material-maps --mat-mapping-surfaces true --mat-mapping-volumes true --mat-mapping-volume-stepsize 1 --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml
+  ./../build/bin/ActsExampleMaterialMappingDD4hep -j1 --input-root true --input-files geant-material-tracks.root --mat-input-type file --mat-input-file geometry-map.json --output-root --output-json --mat-mapping-collection material-tracks --mat-output-file material-maps --mat-mapping-surfaces true --mat-mapping-volumes true --mat-mapping-volume-stepsize 1 --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml
 
 
 As an output you will obtain the material map as a root and JSON file and a new material track collection in a root file. This new collection adds to each material interaction the associated surface during the mapping. This can be used for the control plots.
@@ -90,7 +90,7 @@ Now that the map has been written, you will want to validate it. First you can u
 
 .. code-block:: console
 
-  ./../build/bin/ActsExampleMaterialValidationDD4hep -n 1000 --mat-input-type file --mat-input-file material-maps.json --output-root true --mat-output-file val-mat-map --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml
+  ./../build/bin/ActsExampleMaterialValidationDD4hep -n 1000 --mat-input-type file --mat-input-file material-maps.json --output-root --mat-output-file val-mat-map --dd4hep-input ../Examples/Detectors/DD4hepDetector/compact/OpenDataDetector/OpenDataDetector.xml
 
 To do the validation, five root macros are available in ``scripts/MaterialMaping``: