Merge branch 'main' into optical-touchable

.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

.gitattributes

@@ -1 +1,2 @@
 docs/rmg-commands.md linguist-generated=true
+.git_archival.txt  export-subst

.github/workflows/main.yml

@@ -37,7 +37,7 @@ jobs:
         run: |
           mkdir build
           cd build
-          cmake -DRMG_BUILD_EXAMPLES=1 ..
+          cmake -DRMG_BUILD_EXAMPLES=1 -DBUILD_TESTING=ON -DRMG_BUILD_DOCS=OFF ..
           make
           make install
 

.gitignore

@@ -1,6 +1,9 @@
+# CMake generated
 /include/RMGConfig.hh
+/python/remage/cpp_utils.py
 /docs/Doxyfile
 /docs/conf.py
+
 /docs/_build
 /docs/_doxygen
 /docs/api
@@ -24,13 +27,74 @@ bookmarkFile
 
 compile_commands.json
 
-# junk
-*.DS_Store
+# editors
+*~
 *.swp
 *.swo
-.mypy_cache
-__pycache__
-*.dat
 
 # python
+
+# Environments
+.env
 .venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# setuptools_scm
+python/*/_version.py
+
+# ruff
+.ruff_cache/
+
+# OS specific stuff
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

.pre-commit-config.yaml

@@ -35,14 +35,13 @@ repos:
       - id: rst-inline-touching-normal
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: "v3.3.3"
+    rev: "v3.4.2"
     hooks:
       - id: prettier
         types_or: [yaml, markdown, html, css, scss, javascript, json]
-        args: [--prose-wrap=always]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.7.4"
+    rev: "v0.8.6"
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
@@ -80,7 +79,7 @@ repos:
         additional_dependencies: ["validate-pyproject-schema-store[all]"]
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: "0.29.4"
+    rev: "0.30.0"
     hooks:
       - id: check-dependabot
       - id: check-github-workflows
@@ -98,7 +97,7 @@ repos:
         types_or: [c++]
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: v19.1.5
+    rev: v19.1.6
     hooks:
       - id: clang-format
         types_or: [c++]

CITATION.cff

@@ -19,3 +19,6 @@ authors:
   - family-names: Esch
     given-names: Eric
     email: eric.esch@uni-tuebingen.de
+  - family-names: Dixon
+    given-names: Toby
+    orcid: https://orcid.org/0000-0001-8787-6336

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
 project(
   remage
-  VERSION 0.5.0
+  VERSION 0.6.2 # TODO: get this dynamically
   DESCRIPTION "Simulation framework for HPGe-based experiments"
   LANGUAGES C CXX) # C is needed for Geant4's HDF5 support
 
@@ -175,6 +175,20 @@ message(STATUS "CMAKE_CXX_STANDARD is c++" ${CMAKE_CXX_STANDARD})
 
 add_subdirectory(src)
 
+# let's now look for python, needed for the remage python wrapper and tests
+find_package(Python3 REQUIRED COMPONENTS Interpreter)
+
+execute_process(
+  COMMAND "${Python3_EXECUTABLE}" -m venv --help
+  RESULT_VARIABLE VENV_AVAILABLE
+  OUTPUT_QUIET ERROR_QUIET)
+
+if(NOT VENV_AVAILABLE EQUAL 0)
+  message(FATAL_ERROR "Python3 is installed, but the 'venv' module is missing.")
+endif()
+
+add_subdirectory(python)
+
 option(RMG_BUILD_DOCS "Build remage documentation" OFF)
 if(RMG_BUILD_DOCS)
   add_subdirectory(docs)
@@ -185,6 +199,7 @@ if(RMG_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()
 
+message(STATUS "Test/validation suite support: BUILD_TESTING=${BUILD_TESTING}")
 include(CTest)
 add_subdirectory(tests)
 

cmake/cpp_config.py.in

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+REMAGE_CPP_EXE_PATH = "@REMAGE_CPP_EXE_PATH@"

docs/CMakeLists.txt

@@ -19,10 +19,9 @@ file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
 # configure target that runs Doxygen
 add_custom_command(
   OUTPUT ${DOXYGEN_INDEX_FILE}
-  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} > /dev/null
   DEPENDS ${DOXYFILE_IN} ${REMAGE_PUBLIC_HEADERS}
-  MAIN_DEPENDENCY ${DOXYFILE_OUT}
-  COMMENT "Running Doxygen")
+  MAIN_DEPENDENCY ${DOXYFILE_OUT})
 
 add_custom_target(
   doxygen ALL
@@ -60,16 +59,18 @@ configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${SPHINX_SOURCE}/conf.py @
 
 add_custom_command(
   OUTPUT ${SPHINX_INDEX_FILE}
-  COMMAND ${SPHINX_EXECUTABLE} -b html -Dbreathe_projects.remage=${DOXYGEN_OUTPUT_DIR}/xml
+  COMMAND ${SPHINX_EXECUTABLE} -q -b html -Dbreathe_projects.remage=${DOXYGEN_OUTPUT_DIR}/xml
           ${SPHINX_SOURCE} ${SPHINX_BUILD}
   WORKING_DIRECTORY ${SPHINX_SOURCE}
   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")
+  ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
 
 # Nice named target so we can run the job easily
-add_custom_target(sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
+add_custom_target(
+  sphinx ALL
+  DEPENDS ${SPHINX_INDEX_FILE}
+  COMMENT "Generating Sphinx docs")
 
 # Add an install target to install the docs
 include(GNUInstallDirs)

docs/developer.md

@@ -17,6 +17,33 @@ your GitHub username):
 $ git clone git@github.com:yourusername/remage.git
 ```
 
+## That `remage` executable...
+
+To enhance _remage_'s capabilities without requiring complex C++ code, we
+implemented a Python wrapper. This wrapper handles input preprocessing, invokes
+the `remage-cpp` executable, and performs output postprocessing. While this
+approach slightly complicates the build system, it significantly reduces the
+amount of code to write and maintain.
+
+The C++ code resides in the `src` directory, with the `remage-cpp` executable
+built from `src/remage.cc`. The Python code is organized as a package under the
+`python` directory, where the `cli.py` module provides the _remage_ command-line
+interface.
+
+At build time, CMake compiles `remage-cpp` and installs the Python package in
+the build area. The Python package and its dependencies (see `pyproject.toml`)
+are installed into a virtual environment, ensuring an isolated environment with
+all required dependencies. The Python wrapper is configured to use the
+`remage-cpp` executable from the build area.
+
+This setup is replicated during installation, targeting the install prefix. A
+key advantage of this approach is enabling the use of the _remage_ executable in
+unit tests, which run on _remage_ from the build area.
+
+Information about the C++ part of _remage_ is forwarded to the Python wrapper
+via the `cmake/cpp_config.py.in` file, which is configured by CMake at build
+time and moved into the package source folder.
+
 ## Installing dependencies
 
 ```{include} _dependencies.md
@@ -35,6 +62,10 @@ $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
 $ make install
 ```
 
+```{tip}
+A list of available Make targets can be printed by running `make help`.
+```
+
 ## Code style
 
 A set of [pre-commit](https://pre-commit.com) hooks is configured to make sure
@@ -75,15 +106,18 @@ tarball. This can be downloaded and inspected from the GitHub actions run page:
 navigate to "Actions", select the CI run of interest, scroll to the bottom of
 the page.
 
-Cheatsheet:
+:::{tip} Cheatsheet:
 
 ```console
 $ ctest --print-labels # see all defined test labels
 $ ctest -L vis # run only tests with label "vis"
 $ ctest -R basics-mt/print-volumes.mac # run only this test
 ```
 
-If you want to open a fanci UI to check the output of `vis` tests, you may
+:::
+
+:::{tip}
+If you want to open a fancy UI to check the output of `vis` tests, you may
 achieve it by:
 
 1. `cd` to `test/confinement`
@@ -93,6 +127,54 @@ achieve it by:
    the very beginning (after `/control/execute`)
 1. run the visualization with
    `remage -i -g gdml/geometry.gdml -- macros/themacro.mac`
+   :::
+
+### Configuring CMake
+
+You may add a new test with the
+[`add_test()`](https://cmake.org/cmake/help/latest/command/add_test.html) CMake
+command. Use the `category/test-name` convention to name tests. Here are few
+examples:
+
+If the test is supposed to run the `remage` executable, you can use the
+`REMAGE_PYEXE`, which stores its path:
+
+```cmake
+add_test(NAME basics/test COMMAND ${REMAGE_PYEXE} [<arg>...])
+```
+
+If you want to use the low-level `remage-cpp` executable, you can directly use
+the `remage-cli-cpp` target:
+
+```cmake
+add_test(NAME basics/test COMMAND remage-cli-cpp [<arg>...])
+```
+
+If you want to run a Python script, the recommended interpreted to use is the
+one from the virtual environment set up in the build area by CMake. Its path is
+stored in the `PYTHONPATH` variable:
+
+```cmake
+add_test(NAME basics/test COMMAND ${PYTHONPATH} script.py)
+```
+
+In case a simulation output file needs to be generated with _remage_, before a
+series of tests is ran with Python scripts, one can do so with a fixture:
+
+```cmake
+add_test(
+  NAME germanium/gen-output
+  COMMAND ${REMAGE_PYEXE} -g gdml/geometry.gdml -w -o output.lh5 -- macros/run.mac)
+set_tests_properties(germanium/gen-output PROPERTIES FIXTURES_SETUP output-fixture)
+
+add_test(NAME germanium/bremsstrahlung COMMAND ${PYTHONPATH} ./test_brem.py)
+set_tests_properties(germanium/bremsstrahlung PROPERTIES FIXTURES_REQUIRED output-fixture)
+
+add_test(NAME germanium/e-range COMMAND ${PYTHONPATH} ./test_e_range.py)
+set_tests_properties(germanium/e-range PROPERTIES FIXTURES_REQUIRED output-fixture)
+```
+
+For more complete examples, have a look at the existing tests.
 
 ## Documentation
 

docs/index.md

@@ -6,9 +6,11 @@ _remage_ is a modern C++ simulation framework for germanium experiments.
 
 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 {doc}`tutorial` or the provided
-[examples](https://github.com/legend-exp/remage/tree/main/examples). :::
+```{warning}
+ A proper user guide is not available yet. In the meanwhile, users can have a
+look at the {doc}`tutorial` or the provided
+[examples](https://github.com/legend-exp/remage/tree/main/examples).
+```
 
 In the simplest application, the user can simulate in an existing GDML geometry
 through the `remage` executable: