build(cmake): honor BUILD_TESTING and run simg4ox via ctest (#378)

This branch aligns Simphony's testing setup with standard CMake/CTest behavior and moves the existing `simg4ox` integration check under `ctest`.

The main goals are:

- respect `BUILD_TESTING` in the project tree
- make build-tree tests discoverable and runnable through `ctest`
- ensure external drivers such as Spack can enable tests and invoke `ctest` in a conventional way
- remove duplicated CI execution for `test_simg4ox.sh`

## Motivation

Before this change, test subdirectories were added unconditionally, which made the project less friendly to standard CMake testing flows and to package-manager driven builds.

In addition, `simg4ox` was validated via a standalone shell script instead of a registered CTest test. That meant CI and external tooling had to know about the script separately instead of relying on `ctest` as the single test entry point.

## What Changed

### Top-level CMake testing behavior

- define `BUILD_TESTING` using the standard CMake pattern
- default `BUILD_TESTING` to `PROJECT_IS_TOP_LEVEL`
- continue to `include(CTest)` even when `BUILD_TESTING=OFF`
- gate all `*/tests` subdirectories behind `if(BUILD_TESTING)`

This gives the expected behavior in both cases:

- top-level builds get tests by default
- subproject/package-manager builds do not force this project's tests on unless explicitly requested

Keeping `CTest` included even with `BUILD_TESTING=OFF` means external drivers can still run `ctest` and see an empty test set rather than missing test configuration.

### `simg4ox` CTest integration

- add a dedicated top-level [tests/CMakeLists.txt](tests/CMakeLists.txt) to register `Integration.simg4ox`
- run `simg4ox` from CTest using `$<TARGET_FILE:simg4ox>`
- use a fixed CTest working directory created from CMake
- keep the wrapper script minimal and focused on launching the executable and comparison step

This turns the existing `tests/test_simg4ox.sh` flow into a normal CTest integration test instead of an external ad hoc command.

### A/B comparison script cleanup

- move the old `tests/compare_ab.py` to [optiphy/ana/compare_ab.py](optiphy/ana/compare_ab.py)
- remove the old `tests/compare_ab.py`
- keep the script serving the same core purpose: compare A/B event outputs and validate the expected Geant4-version-dependent mismatch indices

Placing it under `optiphy/ana` makes it easier to treat as a reusable analysis/helper script rather than a one-off test-local file.

### CI cleanup

- remove the separate `tests/test_simg4ox.sh` invocation from `.github/workflows/build-pull-request.yaml`
- rely on the existing `ctest --test-dir "$SIMPHONY_BUILD" --output-on-failure` step to run `Integration.simg4ox`

This avoids running the same test twice in PR CI.

Author: plexoos

.github/workflows/build-pull-request.yaml

@@ -186,7 +186,6 @@ jobs:
       - name: Run tests
         run: |
           docker run --rm --gpus 'device=1' ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }} bash -lc 'ctest --test-dir "$SIMPHONY_BUILD" --output-on-failure'
-          docker run --rm --gpus 'device=1' ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }} tests/test_simg4ox.sh
           docker run --rm --gpus 'device=1' ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }} tests/test_GPURaytrace.sh
           docker run --rm --gpus 'device=1' ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }} tests/test_triangulated.sh
           docker run --rm --gpus 'device=1' ${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }} tests/test_triangulated_multi.sh

CMakeLists.txt

@@ -13,6 +13,12 @@ endif()
 
 project(simphony VERSION 0.6.0 LANGUAGES CXX CUDA)
 
+# Use CMake's standard testing option, but avoid enabling this project's tests
+# by default when Simphony is pulled in as a subproject.
+if(NOT DEFINED BUILD_TESTING)
+    set(BUILD_TESTING ${PROJECT_IS_TOP_LEVEL} CACHE BOOL "Build the testing tree.")
+endif()
+
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
@@ -24,6 +30,8 @@ set(CMAKE_CUDA_EXTENSIONS OFF)
 set(BUILD_SHARED_LIBS ON)
 
 include(GNUInstallDirs)
+# Keep CTest included even when BUILD_TESTING=OFF so external drivers can run
+# ctest and observe an empty test set rather than a missing configuration.
 include(CTest)
 include(CheckLinkerFlag)
 
@@ -53,19 +61,23 @@ set(GPHOX_INSTALL_FULL_DATADIR "${CMAKE_INSTALL_FULL_DATADIR}/${PROJECT_NAME}")
 set(GPHOX_BUILD_PTX_DIR "${PROJECT_BINARY_DIR}/ptx")
 
 add_subdirectory(sysrap)
-add_subdirectory(sysrap/tests)
 add_subdirectory(CSG)
-add_subdirectory(CSG/tests)
 add_subdirectory(qudarap)
-add_subdirectory(qudarap/tests)
 add_subdirectory(CSGOptiX)
-add_subdirectory(CSGOptiX/tests)
 add_subdirectory(u4)
-add_subdirectory(u4/tests)
 add_subdirectory(g4cx)
-add_subdirectory(g4cx/tests)
 add_subdirectory(src)
 
+if(BUILD_TESTING)
+    add_subdirectory(sysrap/tests)
+    add_subdirectory(CSG/tests)
+    add_subdirectory(qudarap/tests)
+    add_subdirectory(CSGOptiX/tests)
+    add_subdirectory(u4/tests)
+    add_subdirectory(g4cx/tests)
+    add_subdirectory(tests)
+endif()
+
 # Optional DD4hep integration plugins
 find_package(DD4hep QUIET COMPONENTS DDG4 DDCore)
 if(DD4hep_FOUND)

optiphy/ana/compare_ab.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+compare_ab.py : pass/fail comparison of A/B event records
+=========================================================
+
+Validates persisted `record.npy` outputs from paired A/B event directories by
+comparing aligned Opticks/G4 records and checking the known
+Geant4-version-dependent mismatch indices.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from optiphy.geant4_version import detect_geant4_version, geant4_series
+
+
+EXPECTED_DIFF = {
+    "11.3": [14, 22, 32, 34, 40, 81, 85],
+    "11.4+": [0, 30, 32, 34, 42, 69, 78, 85, 86],
+}
+
+
+def expected_diff_for_version(version):
+    return EXPECTED_DIFF[geant4_series(version)]
+
+
+def load_records(base, a_record, b_record):
+    a_path = base / a_record
+    b_path = base / b_record
+
+    if not a_path.is_file():
+        raise FileNotFoundError(f"Missing Opticks record file: {a_path}")
+    if not b_path.is_file():
+        raise FileNotFoundError(f"Missing Geant4 record file: {b_path}")
+
+    return np.load(a_path), np.load(b_path)
+
+
+def compare_records(a, b):
+    if a.shape != b.shape:
+        raise AssertionError(f"Shape mismatch: {a.shape} != {b.shape}")
+
+    # Geant4 and Opticks record one-step-shifted sequences for this geometry,
+    # so compare aligned slices directly, including time.
+    a_cmp = a[:, 1:]
+    b_cmp = b[:, :-1]
+
+    return [
+        index
+        for index, (a_row, b_row) in enumerate(zip(a_cmp, b_cmp))
+        if not np.allclose(a_row, b_row, rtol=0.0, atol=1e-5)
+    ]
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base", default=".", help="directory containing the A/B event outputs")
+    parser.add_argument(
+        "--a-record",
+        default="ALL0_no_opticks_event_name/A000/record.npy",
+        help="path to the A-side record.npy relative to --base",
+    )
+    parser.add_argument(
+        "--b-record",
+        default="ALL0_no_opticks_event_name/B000/f000/record.npy",
+        help="path to the B-side record.npy relative to --base",
+    )
+    args = parser.parse_args()
+
+    base = Path(args.base).resolve()
+    geant4_version = detect_geant4_version()
+    expected_diff = expected_diff_for_version(geant4_version)
+
+    a, b = load_records(base, Path(args.a_record), Path(args.b_record))
+    diff = compare_records(a, b)
+
+    print(f"BASE={base}")
+    print(f"A_SHAPE={a.shape}")
+    print(f"B_SHAPE={b.shape}")
+    print(f"GEANT4_VERSION={geant4_version}")
+    print(f"EXPECTED_DIFF={expected_diff}")
+    print(f"ACTUAL_DIFF={diff}")
+
+    if diff != expected_diff:
+        raise AssertionError(f"Mismatch indices differ: expected {expected_diff}, got {diff}")
+
+
+if __name__ == "__main__":
+    main()

tests/CMakeLists.txt

@@ -0,0 +1,20 @@
+find_package(Python3 REQUIRED COMPONENTS Interpreter)
+find_program(BASH_EXECUTABLE bash REQUIRED)
+
+set(SIMPHONY_SIMG4OX_TEST_WORKDIR "${CMAKE_CURRENT_BINARY_DIR}/simg4ox")
+file(MAKE_DIRECTORY "${SIMPHONY_SIMG4OX_TEST_WORKDIR}")
+
+add_test(
+    NAME Integration.simg4ox
+    COMMAND ${CMAKE_COMMAND} -E env
+            REPO_DIR=${PROJECT_SOURCE_DIR}
+            PYTHON=${Python3_EXECUTABLE}
+            SIMG4OX_BIN=$<TARGET_FILE:simg4ox>
+            ${BASH_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test_simg4ox.sh
+)
+
+set_tests_properties(Integration.simg4ox PROPERTIES
+    WORKING_DIRECTORY "${SIMPHONY_SIMG4OX_TEST_WORKDIR}"
+    LABELS "integration"
+    TIMEOUT 120
+)

tests/compare_ab.py

@@ -1,8 +1,16 @@
 #!/usr/bin/env bash
 
-set -e
+set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+REPO_DIR=${REPO_DIR:-$(cd "${SCRIPT_DIR}/.." && pwd)}
 
-simg4ox -g "$SCRIPT_DIR/geom/raindrop.gdml" -m "$SCRIPT_DIR/run.mac"
-python3 "$SCRIPT_DIR/compare_ab.py"
+SIMG4OX_BIN=${SIMG4OX_BIN:-simg4ox}
+PYTHON=${PYTHON:-python3}
+
+export OPTICKS_HOME="${REPO_DIR}"
+export GPHOX_CONFIG_DIR="${GPHOX_CONFIG_DIR:-${REPO_DIR}/config}"
+export PYTHONPATH="${REPO_DIR}${PYTHONPATH:+:${PYTHONPATH}}"
+
+"${SIMG4OX_BIN}" -g "${REPO_DIR}/tests/geom/raindrop.gdml" -m "${REPO_DIR}/tests/run.mac" -c dev
+"${PYTHON}" "${REPO_DIR}/optiphy/ana/compare_ab.py"