feat(optiphy): add Geant4 version detection utility (#283)

Add a small utility module in
[optiphy/geant4_version.py](optiphy/geant4_version.py) to detect the
installed Geant4
version and normalize it to the release series expected by `optiphy`.

## Changes
- read the version from `GEANT4_VERSION` when available, with fallback
to `geant4-config --version`
- parse `major.minor.patch` version strings
- map supported releases to `11.3` and `11.4+`
- expose a simple CLI that prints either the raw version or normalized
series
- raise clear errors when the version cannot be detected or is not yet
supported

Author: plexoos

optiphy/geant4_version.py

@@ -0,0 +1,57 @@
+import argparse
+import os
+import re
+import subprocess
+
+
+def parse_geant4_version(version):
+    match = re.fullmatch(r"\s*(\d+)\.(\d+)(?:\.(?:(\d+)|p(\d+))(?:\.beta)?)?\s*", version)
+    if match is None:
+        raise RuntimeError(f"Unable to parse Geant4 version: {version!r}")
+
+    major, minor, patch, patchlevel = match.groups(default="0")
+    return int(major), int(minor), int(patch if patch != "0" else patchlevel)
+
+
+def detect_geant4_version():
+    version = os.environ.get("GEANT4_VERSION")
+    if version:
+        return version.strip()
+
+    try:
+        return subprocess.check_output(["geant4-config", "--version"], text=True).strip()
+    except (OSError, subprocess.CalledProcessError) as err:
+        raise RuntimeError(
+            "Unable to determine Geant4 version. Set GEANT4_VERSION or ensure geant4-config is available."
+        ) from err
+
+
+def geant4_series(version=None):
+    resolved = detect_geant4_version() if version is None else version
+    major, minor, _patch = parse_geant4_version(resolved)
+
+    if (major, minor) == (11, 3):
+        return "11.3"
+    if (major, minor) >= (11, 4):
+        return "11.4+"
+
+    raise RuntimeError(
+        f"Unsupported Geant4 version {resolved!r}. Add support for this release family."
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("field", nargs="?", choices=("version", "series"), default="version")
+    args = parser.parse_args()
+
+    version = detect_geant4_version()
+
+    if args.field == "version":
+        print(version)
+    else:
+        print(geant4_series(version))
+
+
+if __name__ == "__main__":
+    main()

optiphy/test/test_geant4_version.py

@@ -0,0 +1,64 @@
+import re
+
+import pytest
+
+from optiphy.geant4_version import geant4_series, parse_geant4_version
+
+
+@pytest.mark.parametrize(
+    ("version", "expected"),
+    [
+        ("11.3.2", "11.3"),
+        ("11.3.0.beta", "11.3"),
+        ("11.4.0", "11.4+"),
+        ("11.4.p01", "11.4+"),
+        ("11.4.0.beta", "11.4+"),
+        ("11.5.1", "11.4+"),
+        ("12.0.0", "11.4+"),
+        ("12.0.p02", "11.4+"),
+        ("12.0.0.beta", "11.4+"),
+        ("12.1.3", "11.4+"),
+        ("13.0.0", "11.4+"),
+    ],
+)
+def test_geant4_series_supported_versions(version, expected):
+    assert geant4_series(version) == expected
+
+
+@pytest.mark.parametrize("version", ["9.6.1", "9.6.p03", "10.7.4"])
+def test_geant4_series_rejects_older_major_versions(version):
+    with pytest.raises(RuntimeError, match=re.escape(f"Unsupported Geant4 version {version!r}")):
+        geant4_series(version)
+
+
+@pytest.mark.parametrize("version", ["11.2.0", "11.2.0.beta"])
+def test_geant4_series_rejects_unsupported_11_minor(version):
+    with pytest.raises(RuntimeError, match=re.escape(f"Unsupported Geant4 version {version!r}")):
+        geant4_series(version)
+
+
+def test_geant4_series_rejects_unparseable_version():
+    version = "not-a-version"
+    with pytest.raises(RuntimeError, match=re.escape(f"Unable to parse Geant4 version: {version!r}")):
+        geant4_series(version)
+
+
+@pytest.mark.parametrize(
+    ("version", "expected"),
+    [
+        ("11.4", (11, 4, 0)),
+        ("11.4.0", (11, 4, 0)),
+        ("11.4.0.beta", (11, 4, 0)),
+        ("11.4.p01", (11, 4, 1)),
+        ("11.2.0.beta", (11, 2, 0)),
+        ("12.0.p02", (12, 0, 2)),
+    ],
+)
+def test_parse_geant4_version_accepts_supported_patch_formats(version, expected):
+    assert parse_geant4_version(version) == expected
+
+
+@pytest.mark.parametrize("version", ["11.4.p", "11.4-dev", "11.4foo", "11.4.p01foo", "11.4.0.betafoo"])
+def test_parse_geant4_version_rejects_trailing_suffixes(version):
+    with pytest.raises(RuntimeError, match=re.escape(f"Unable to parse Geant4 version: {version!r}")):
+        parse_geant4_version(version)

pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
 ]
 
 [project.scripts]
+geant4-version = "optiphy.geant4_version:main"
 generate-input-photons = "optiphy.tools.generate_input_photons:main"
 plot-csg = "optiphy.tools.plot_csg:main"
 serve-path = "optiphy.tools.serve_path:main"