Update documentation

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
   rev: v5.0.0
   hooks:
   - id: check-added-large-files
+    args: ['--maxkb=600']
   - id: check-case-conflict
   - id: check-executables-have-shebangs
   - id: check-merge-conflict

README.md

@@ -23,10 +23,6 @@ setup (supported specification languages are C++, GDML and more). The user can
 then benefit from a predefined set of tools to perform common actions (physics
 generators, standard output classes, etc).
 
-> [!WARNING]
-> *remage* is still under heavy development. Users are advised to use a tagged
-> release for any workloads unrelated to remage development, if possible.
-
 ### Main features
 
 * Support for modern [Geant4](https://geant4.web.cern.ch), including

docs/CMakeLists.txt

@@ -34,9 +34,26 @@ set(SPHINX_SOURCE ${CMAKE_CURRENT_BINARY_DIR})
 set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/_build)
 set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 
-set(SPHINX_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/index.rst)
+# FIXME: the logic here to handle sources is not really clean, needs some more
+# serious thought! one important requirement is CMake being able to copy the
+# sources again if they change
+file(
+  GLOB SPHINX_SOURCES
+  RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+  *.rst *.md)
+
 foreach(_file ${SPHINX_SOURCES})
-  configure_file(${_file} ${SPHINX_SOURCE} COPYONLY)
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/${_file} ${SPHINX_SOURCE} COPYONLY)
+endforeach()
+
+file(
+  GLOB SPHINX_IMAGES
+  RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+  img/*)
+
+file(MAKE_DIRECTORY ${SPHINX_SOURCE}/img)
+foreach(_file ${SPHINX_IMAGES})
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/${_file} ${SPHINX_SOURCE}/img COPYONLY)
 endforeach()
 
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${SPHINX_SOURCE}/conf.py @ONLY)
@@ -46,7 +63,7 @@ add_custom_command(
   COMMAND ${SPHINX_EXECUTABLE} -b html -Dbreathe_projects.remage=${DOXYGEN_OUTPUT_DIR}/xml
           ${SPHINX_SOURCE} ${SPHINX_BUILD}
   WORKING_DIRECTORY ${SPHINX_SOURCE}
-  DEPENDS ${SPHINX_SOURCES} ${DOXYGEN_INDEX_FILE}
+  DEPENDS ${SPHINX_SOURCES} ${SPHINX_IMAGES} ${DOXYGEN_INDEX_FILE}
   MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
   ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
   COMMENT "Generating Sphinx docs")

docs/conf.py.in

@@ -38,6 +38,8 @@ exhale_args = {
 
 breathe_projects = {}
 
+myst_enable_extensions = ["colon_fence"]
+
 if on_rtd:
     # assume build has been prepared in .readthedocs.yml
     breathe_projects["remage"] = "_doxygen/xml"

docs/developer.rst

@@ -96,6 +96,18 @@ following:
   other) must be provided as separate pages in ``docs/`` and linked in the
   table of contents.
 
+To generate documentation locally, run
+
+.. code-block:: console
+
+  $ cd remage/build/
+  $ cmake .. -DRMG_BUILD_DOCS=ON
+  $ make sphinx
+
+You'll need a Doxygen installation and Python software dependencies specified
+in ``docs/environment.yml``. The generated documentation can be viewed by
+pointing your browser to ``docs/_build/index.html``.
+
 Writing documentation
 ^^^^^^^^^^^^^^^^^^^^^
 

docs/index.rst

@@ -3,52 +3,11 @@ remage
 
 |remage| is a modern C++ simulation framework for germanium experiments.
 
-Pre-built binaries
-------------------
-
-The recommended and fastest way of running |remage| is through pre-built
-software containers. Stable releases are regularly made available `on Docker
-Hub <https://hub.docker.com/repository/docker/gipert/remage>`_. To obtain and
-run the latest just do:
-
-.. code-block:: console
-
-   $ docker run gipert/remage --help # just prints a help message
-
-If you prefer `Apptainer <https://apptainer.org/>`_, you can easily generate an image locally:
-
-.. code-block:: console
-
-  $ apptainer build remage_latest.sif docker://gipert/remage:latest
-  $ apptainer run remage_latest.sif --help
-
-If containers do not work for you, see the next section to learn how to build
-and install from source.
-
-Building from source
---------------------
-
-In preparation for the actual build, users are required to obtain some
-dependencies.
-
-.. include:: _dependencies.rst
-
-Building
-^^^^^^^^
-
-The build system is based on CMake:
-
-.. code-block:: console
-
-   $ git clone https://github.com/legend-exp/remage
-   $ cd remage
-   $ mkdir build && cd build
-   $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
-   $ make install
-
 Quick start
 -----------
 
+The installation process is documented in :doc:`install`.
+
 .. warning::
    A proper user guide is not available yet. In the meanwhile, users can have a
    look at the `examples
@@ -98,6 +57,8 @@ Next steps
 .. toctree::
     :maxdepth: 2
 
+    install
+    tutorial
     Geant4 command interface <rmg-commands>
     Output structure & LH5 output <output>
 

docs/install.rst

@@ -0,0 +1,47 @@
+Installation
+============
+
+Pre-built binaries
+------------------
+
+The recommended and fastest way of running |remage| is through pre-built
+software containers. Stable releases are regularly made available `on Docker
+Hub <https://hub.docker.com/repository/docker/legendexp/remage>`_. To obtain and
+run the latest just do:
+
+.. code-block:: console
+
+   $ docker run legendexp/remage:latest --help # just prints a help message
+
+If you prefer `Apptainer <https://apptainer.org/>`_, you can easily generate an image locally:
+
+.. code-block:: console
+
+  $ apptainer build remage_latest.sif docker://legendexp/remage:latest
+  $ apptainer run remage_latest.sif --help
+
+If containers do not work for you, see the next section to learn how to build
+and install from source.
+
+Building from source
+--------------------
+
+In preparation for the actual build, users are required to obtain some
+dependencies.
+
+.. include:: _dependencies.rst
+
+Building
+^^^^^^^^
+
+The build system is based on CMake:
+
+.. code-block:: console
+
+   $ git clone https://github.com/legend-exp/remage
+   $ cd remage
+   $ mkdir build && cd build
+   $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
+   $ make install
+
+.. |remage| replace:: *remage*

docs/tutorial.md

@@ -0,0 +1,202 @@
+# Basic Tutorial
+
+In this tutorial we are going to demonstrate the basic functionality of
+*remage* by simulating a series of particle physics processes in a simple setup.
+
+We need to develop a geometry, and we will be using the
+[pyg4ometry](https://pyg4ometry.readthedocs.io) library for this purpose. This
+library is well-suited for creating geometries that are compatible with the
+Geant4 framework, as it closely mirrors the Geant4 interface, making it easy
+for those familiar with Geant4 to use. Importantly, pyg4ometry is independent
+of Geant4 itself, meaning it doesn't require Geant4 as a dependency.
+Additionally, it offers the flexibility to export the developed geometry in
+GDML format, which is widely compatible for simulations and analyses in
+high-energy physics applications.
+
+The geometry consist in two high-purity germanium detectors (HPGes) immersed in
+a liquid argon balloon. The
+[legend-pygeom-hpges](https://legend-pygeom-hpges.readthedocs.io) package will
+help us creating the HPGe volumes. Let's start by importing the Python
+packages, declaring a geometry registry and specifying the dimensions and types
+of the two detectors as dictionaries:
+
+```python
+import legendhpges as hpges
+import pyg4ometry as pg4
+from numpy import pi
+
+
+reg = pg4.geant4.Registry()
+
+bege_meta = {
+    "name": "B00000B",
+    "type": "bege",
+    "production": {
+        "enrichment": {"val": 0.874, "unc": 0.003},
+        "mass_in_g": 697.0,
+    },
+    "geometry": {
+        "height_in_mm": 29.46,
+        "radius_in_mm": 36.98,
+        "groove": {"depth_in_mm": 2.0, "radius_in_mm": {"outer": 10.5, "inner": 7.5}},
+        "pp_contact": {"radius_in_mm": 7.5, "depth_in_mm": 0},
+        "taper": {
+            "top": {"angle_in_deg": 0.0, "height_in_mm": 0.0},
+            "bottom": {"angle_in_deg": 0.0, "height_in_mm": 0.0},
+        },
+    },
+}
+
+coax_meta = {
+    "name": "C000RG1",
+    "type": "coax",
+    "production": {
+        "enrichment": {"val": 0.855, "unc": 0.015},
+    },
+    "geometry": {
+        "height_in_mm": 84,
+        "radius_in_mm": 38.25,
+        "borehole": {"radius_in_mm": 6.75, "depth_in_mm": 73},
+        "groove": {"depth_in_mm": 2, "radius_in_mm": {"outer": 20, "inner": 17}},
+        "pp_contact": {"radius_in_mm": 17, "depth_in_mm": 0},
+        "taper": {
+            "top": {"angle_in_deg": 45, "height_in_mm": 5},
+            "bottom": {"angle_in_deg": 45, "height_in_mm": 2},
+            "borehole": {"angle_in_deg": 0, "height_in_mm": 0},
+        },
+    }
+}
+```
+
+Now we can build all the logical volumes and place them in the world volume:
+
+```python
+# create logical volumes for the two HPGe detectors
+bege_l = hpges.make_hpge(bege_meta, name="BEGe_L", registry=reg)
+coax_l = hpges.make_hpge(coax_meta, name="Coax_L", registry=reg)
+
+# create a world volume
+world_s = pg4.geant4.solid.Orb("World_s", 20, registry=reg, lunit="cm")
+world_l = pg4.geant4.LogicalVolume(world_s, "G4_Galactic", "World", registry=reg)
+reg.setWorld(world_l)
+
+# let's make a liquid argon balloon
+lar_s = pg4.geant4.solid.Orb("LAr_s", 15, registry=reg, lunit="cm")
+lar_l = pg4.geant4.LogicalVolume(lar_s, "G4_lAr", "LAr_l", registry=reg)
+pg4.geant4.PhysicalVolume([0, 0, 0], [0, 0, 0], lar_l, "LAr", world_l, registry=reg)
+
+# now place the two HPGe detectors in the argon
+pg4.geant4.PhysicalVolume([0, 0, 0], [5, 0, -3, "cm"], bege_l, "BEGe", lar_l, registry=reg)
+pg4.geant4.PhysicalVolume([0, 0, 0], [-5, 0, -3, "cm"], coax_l, "Coax", lar_l, registry=reg)
+
+# finally create a small radioactive source
+source_s = pg4.geant4.solid.Tubs("Source_s", 0, 1, 1, 0, 2*pi, registry=reg)
+source_l = pg4.geant4.LogicalVolume(source_s, "G4_BRAIN_ICRP", "Source_L", registry=reg)
+pg4.geant4.PhysicalVolume([0, 0, 0], [0, 5, 0, "cm"], source_l, "Source", lar_l, registry=reg)
+```
+
+Note how we also created a small cylinder to represent a radioactive source
+later in the simulation.
+
+Now we can quickly visualize the result, still with *pyg4ometry*:
+
+```python
+# start an interactive VTK viewer instance
+viewer = pg4.visualisation.VtkViewerColoured(materialVisOptions={"G4_lAr": [0, 0, 1, 0.1]})
+viewer.addLogicalVolume(reg.getWorldVolume())
+viewer.view()
+```
+
+![Geometry visualization](img/tutorial-pyg4-view.jpg)
+
+By following instructions in the <project:./install.rst> section, you should
+have access to the `remage` executable. We are now ready to simulate some
+particle physics with it.
+
+Like any other Geant4-based application, we need to configure the simulation
+with a macro file. Standard Geant4 commands as well as custom commands (see the
+<project:./rmg-commands.rst>) are available.
+
+At the beginning of the file, we have to register the "sensitive detectors" (in
+our simple case, the two HPGes and the LAr). *remage* offers several types of
+predefined detectors, targeting different physical quantities of the particles
+that interact with them. HPGes are of type `Germanium`, while the LAr is of
+type `scintillator`. Their difference in terms of simulation output will be
+clear later, while inspecting it. As per specification of the
+`/RMG/Geometry/RegisterDetector` command, we need to provide a unique numeric
+identifier that will be used to label the detector data in the simulation
+output:
+
+```text
+/RMG/Geometry/RegisterDetector Germanium BEGe 001
+/RMG/Geometry/RegisterDetector Germanium Coax 002
+/RMG/Geometry/RegisterDetector Scintillator LAr 003
+```
+
+Now we can initialize the simulation. Additionally, let's setup some Geant4
+visualization to look at the tracks:
+
+```text
+/run/initialize
+
+# create a scene
+/vis/open OI
+/vis/scene/create
+/vis/sceneHandler/attach
+
+# draw the geometry
+/vis/drawVolume
+
+# setup better colors
+/vis/viewer/set/defaultColour black
+/vis/viewer/set/background white
+
+# and also show trajectories and particle hits
+/vis/scene/add/trajectories smooth
+/vis/scene/add/hits
+/vis/scene/endOfEventAction accumulate
+```
+
+Now with the actual physics. We want to start ten 1 MeV gammas from the
+radioactive source:
+
+```text
+/RMG/Generator/Confine Volume
+/RMG/Generator/Confinement/Physical/AddVolume Source
+
+/RMG/Generator/Select GPS
+/gps/particle gamma
+/gps/ang/type iso
+/gps/energy 1000 keV
+
+/run/beamOn 50
+```
+
+We can finally pass the GDML geometry and the macro to the `remage` executable
+and look at the result!
+
+```console
+$ remage --interactive --gdml-files geometry.gdml vis-gammas.mac
+```
+
+Interactions in HPGes and in LAr are marked in red and blue, respectively.
+
+![Simulation visualization](img/tutorial-g4-view.jpg)
+
+:::{tip}
+With Apptainer, additional tweaks are required in order to allow for graphics to be displayed, e.g.
+```console
+$ apptainer run \
+    --env DISPLAY=$DISPLAY \
+    --env XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR \
+    -B $XDG_RUNTIME_DIR \
+    path/to/remage_latest.sif --interactive --gdml-file geometry.gdml
+```
+and similarly with Docker.
+:::
+
+:::{tip}
+If `remage` from the Apptainer image refuses to run simulations, this might be
+due to some of your environment variables from outside the container. Give
+`--cleanenv` a try.
+:::