documentation improvements

docs/_dependencies.md

@@ -1,7 +1,7 @@
 ### Required dependencies
 
 - [CMake] 3.14 or higher
-- [Geant4] 11.2.2 or higher
+- [Geant4] 11.2.2 or higher, recommended 11.3
 - Python3 interpreter
 
 ### Optional dependencies

docs/conf.py.in

@@ -191,6 +191,8 @@ class Geant4MacroLexer(RegexLexer):
             (r"#.*$", Comment),
             # command name at start of line
             (r"^(/\S+)", Name.Function),
+            # geant4 alias
+            (r"\{\w+\}", Name.Variable),
             # any other text
             (r".", Text),
         ],

docs/index.md

@@ -34,6 +34,8 @@ commands, as well as the [remage macro interface](./rmg-commands).
   useful examples of complex experimental setup implementations.
 - [reboost](https://github.com/legend-exp/reboost): post-processing and analysis
   of remage output.
+- [revertex](https://github.com/legend-exp/revertex): generator for input vertex
+  files for remage.
 
 ## Next steps
 

docs/manual/analysis.md

@@ -5,6 +5,7 @@
 :::{todo}
 
 - pointers to useful tools (reboost or pygama), once they are in place
+- this needs considerable rework
 
 :::
 

docs/manual/confinement.md

@@ -5,7 +5,6 @@
 :::{todo}
 
 - examples
-- tricks for vertex visualization
 
 :::
 
@@ -167,13 +166,35 @@ All sampling modes described above are available, with few notes/limitations:
   to sample the candidate surface vertices from must be set with
   <project:../rmg-commands.md#rmggeneratorconfinementfirstsamplingvolume>. This
   is not optional.
+- The value of
+  <project:../rmg-commands.md#rmggeneratorconfinementsurfacesamplemaxintersections>
+  should be set to the maximum number of times a line can intersect with the
+  surface of the volume. For example this is 2 for a sphere or cube. The
+  supplied value can be an overestimate. For slight overestimates this is comes
+  with a small but usually acceptable performance cost, however very large
+  values can significantly slow down the simulation.
 
 ## Vertices from external files
 
 For more complicated vertex confinement _remage_ supports the possibility to
 read in directly event primary positions from input files, as described in
 {ref}`manual-input-vertex`.
 
+## Visualization
+
+You can use `legend-pygeom-vis` from the
+[_legend-pygeom-tools_](https://github.com/legend-exp/legend-pygeom-tools)
+package to visualize the simulated vertices your generated output files:
+
+```console
+$ remage -o {RMG_OUTPUT_FILE} -g {GDML_FILE} -- ...
+$ legend-pygeom-vis --add_points {RMG_OUTPUT_FILE} {GDML_FILE}
+```
+
+If you want to only show the vertices without the run-time overhead of actually
+simulating any physics, you could consider switching to generating only
+geantinos instead of your usual physics.
+
 [^1]:
     J. A. Detwiler, R. Henning, R. A. Johnson and M. G. Marino, in IEEE
     Transactions on Nuclear Science, vol. 55, no. 4, pp. 2329-2333, Aug. 2008,

docs/manual/generators.md

@@ -79,6 +79,8 @@ too (`/RMG/Generator/Select G4Gun`), a more basic alternative to the GPS.
 
 :::
 
+(manual-generators-decays)=
+
 ## Generating nuclear decays
 
 A special case of the GPS can be used to generate radioactive decays. This is

docs/manual/input.md

@@ -7,6 +7,11 @@
 The python package [_revertex_](https://revertex.readthedocs.io/en/latest/)
 contains functionality for generating input files in the correct format.
 
+If you generate the input files on your own without _revertex_, you have to
+ensure that all data types and units are as defined here. The input reader does
+not support dynamic type conversions, as you would expect for example for python
+(i.e. float32 to float64)!
+
 :::
 
 (manual-input-vertex)=
@@ -23,15 +28,24 @@ between the particles produced in the event.
 The input file can be selected with the macro command
 <project:../rmg-commands.md#rmggeneratorconfinementfromfilefilename>:
 
-```remage
+```geant4
 /RMG/Generator/Confine FromFile
 /RMG/Generator/Confinement/FromFile/FileName {FILE}
 ```
 
 The vertex input file should be an LH5 table with the following columns:
 
-- `xloc`, `yloc`, `zloc` (with units): the global position of the particle
-  emission
+```
+/
+└── vtx
+    └── vtx · table{xloc,yloc,zloc}
+        ├── xloc · array<1>{real} ── {'units': 'm'}
+        ├── yloc · array<1>{real} ── {'units': 'm'}
+        └── zloc · array<1>{real} ── {'units': 'm'}
+```
+
+- `xloc`, `yloc`, `zloc` (double, with units): the global position of the
+  particle emission
 
 (manual-input-kinetics)=
 
@@ -46,7 +60,7 @@ format.
 ```
 /
 └── vtx
-    └── kin · table{px,py,pz,ekin,g4_pid}
+    └── kin · table{ekin,g4_pid,n_part,px,py,pz}
         ├── ekin · array<1>{real} ── {'units': 'keV'}
         ├── g4_pid · array<1>{real}
         ├── px · array<1>{real}
@@ -69,6 +83,23 @@ Each event starts with a row with `n_part` > 0. This specifies the count of rows
 that will be read in for this event. The following rows for this event are then
 required to set `n_part` to zero.
 
+Once this input file is created it can be read into _remage_ as an event
+generator using the macro command
+<project:../rmg-commands.md#rmggeneratorfromfilefilename>:
+
+```geant4
+/RMG/Generator/Select FromFile
+/RMG/Generator/FromFile/FileName {FILE_PATH}
+```
+
+Where `{FILE_PATH}` is the path to the input LH5 file.
+
+## Combining vertex and kinematics input
+
+Combining vertex and kinetics input is possible, even from the same file.
+However, by design, each event can only have a single vertex, that will be
+shared between all particles for an event from the kinetics file.
+
 :::{warning}
 
 In a multithreaded run, the consistent iteration between vertex and kinetic
@@ -78,13 +109,17 @@ statistically dependent on their location.
 
 :::
 
-Once this input file is created it can be read into _remage_ as an event
-generator using the macro command
-<project:../rmg-commands.md#rmggeneratorfromfilefilename>:
+:::{tip}
+
+When you want to simulate kinetics from a file at a specific point instead of
+confined to volume, you cannot use `/gps/position` to set the position. You can
+however use
 
 ```geant4
-/RMG/Generator/Select FromFile
-/RMG/Generator/FromFile/FileName {FILE_PATH}
+/RMG/Vertex/Select FromPoint
+/RMG/Vertex/FromPoint/Position {x} {y} {z}
 ```
 
-Where `{FILE_PATH}` is the path to the input LH5 file.
+to set a constant position for all events.
+
+:::

docs/manual/install.md

@@ -2,8 +2,29 @@
 
 # Installation
 
-The recommended and fastest way of running _remage_ is through pre-built
-software containers. Alternatively, the project can be built from source.
+The recommended and fastest way of running _remage_ is through the pre-built
+packages on conda-forge; alternatively through our pre-built software container
+images. Alternatively, the project can be built from source.
+
+## Pre-built packages on conda-forge
+
+Stable releases are made available
+[on conda-forge](https://anaconda.org/conda-forge/remage) for Linux and macOS
+systems. To install the latest version of remage into your environment, use pixi
+or conda:
+
+```console
+$ pixi add remage
+# or
+$ conda install conda-forge::remage
+```
+
+:::{note}
+
+The conda-forge provided binaries do not support the ROOT output format, but
+fully supports LH5/HDF5.
+
+:::
 
 ## Pre-built container images
 
@@ -27,23 +48,6 @@ More information is available in {ref}`manual-containers`. If containers do not
 work for you, see the next section to learn how to build and install from source
 or from conda-forge.
 
-## Pre-built packages on conda-forge
-
-Stable releases are made available
-[on conda-forge](https://anaconda.org/conda-forge/remage) for Linux and macOS
-systems. To install the latest version use:
-
-```console
-$ conda install conda-forge::remage
-```
-
-:::{note}
-
-The conda-forge provided binaries does not support the ROOT output format, but
-fully supports LH5/HDF5.
-
-:::
-
 ## Building from source
 
 In preparation for the actual build, users are required to obtain some

docs/manual/output.md

@@ -2,12 +2,6 @@
 
 # Output
 
-:::{todo}
-
-- isotope filtering
-
-:::
-
 _remage_ mainly supports the
 [LH5](https://legend-exp.github.io/legend-data-format-specs/dev/hdf5) output
 format. This is the only format we can provide the convenient output reshaping
@@ -172,7 +166,7 @@ occur. The macro commands
 <project:../rmg-commands.md#rmgoutputgermaniumedepcutlow> and
 <project:../rmg-commands.md#rmgoutputgermaniumedepcuthigh>:
 
-```remage
+```geant4
 /RMG/Output/Germanium/AddDetectorForEdepThreshold {UID}
 /RMG/Output/Germanium/EdepCutLow {ELOW}
 /RMG/Output/Germanium/EdepCutHigh {EHIGH}
@@ -338,6 +332,8 @@ UID through the symbolic stored in the `/stp/__by_uid__` group.
 
 ## Data reduction methods
 
+### Step (pre-)clustering
+
 Often Geant4 takes steps much shorter than those that are meaningful in a HPGe
 or a scintillation detector. For example the typical dimension of charge clouds
 produced by interactions in germanium are 1-2 mm, so we are not sensitive to
@@ -478,6 +474,55 @@ step length.
 
 :::
 
+### Output filtering
+
+Another strategy for output file size reduction is to filter out unwanted events
+before even writing them to disk. In _remage_, these filters can be registered
+as optional "output" schemes (do not get confused by the name, they will not
+produce any additional output).
+
+#### Isotope filter
+
+The isotope filter is rather simple and can be enabled and used like this:
+
+```geant4
+/RMG/Output/ActivateOutputScheme IsotopeFilter
+/RMG/Output/IsotopeFilter/AddIsotope {A} {Z}
+```
+
+Adds an isotope to the list. Only events that have a track with this isotope at
+any point in time will be persisted.
+
+#### Particle filter
+
+The particle filter does not only affect the output files, but actually works on
+the track level. Tracks matching the defined criteria will not be simulated.
+With this, it not only reduces output file size, but also reduces the necessary
+simulation run time.
+
+```geant4
+/RMG/Output/ActivateOutputScheme ParticleFilter
+/RMG/Output/ParticleFilter/AddParticle {PDG_CODE}
+```
+
+Only particles with the PDG encoding `{PDG_CODE}` will be considered to be
+filtered out (the command can be used multiple times). This can be chained with
+additional constraints by physical volume in which the particle was created or
+by creator process:
+
+- <project:../rmg-commands.md#rmgoutputparticlefilteraddkeepvolume> disables the
+  filtering in the specified volume; whereas
+  <project:../rmg-commands.md#rmgoutputparticlefilteraddkillvolume> only
+  performs the filtering in this volume (the two commands cannot be combined).
+- <project:../rmg-commands.md#rmgoutputparticlefilteraddkeepprocess> will only
+  keep the specified particles when they were created by the specified
+  process(es).
+  <project:../rmg-commands.md#rmgoutputparticlefilteraddkillprocess> will not
+  simulate the particles when they were created by the specified process (the
+  two commands cannot be combined).
+
+Filtering by process and process can be combined.
+
 ## LH5 output
 
 [LH5 (LEGEND-HDF5)](https://legend-exp.github.io/legend-data-format-specs/dev/hdf5/)