geant4-python-application 0.1.0__cp39-cp39-macosx_11_0_arm64.whl

geant4_python_application/gdml.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+basic_gdml = R"""<?xml version="1.0" encoding="utf-8" standalone="no" ?>
+<gdml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:noNamespaceSchemaLocation="http://service-spi.web.cern.ch/service-spi/app/releases/GDML/schema/gdml.xsd">
+
+    <define>
+        <constant name="worldSize" value="1000"/>
+        <constant name="boxSize" value="500"/>
+    </define>
+
+    <solids>
+        <box name="WorldSolid" x="worldSize" y="worldSize" z="worldSize" lunit="mm"/>
+        <box name="boxSolid" x="boxSize" y="boxSize" z="boxSize" lunit="mm"/>
+    </solids>
+
+    <structure>
+        <volume name="boxVolume">
+            <materialref ref="G4_WATER"/>
+            <solidref ref="boxSolid"/>
+        </volume>
+
+        <volume name="World">
+            <materialref ref="G4_AIR"/>
+            <solidref ref="WorldSolid"/>
+
+            <physvol name="box">
+                <volumeref ref="boxVolume"/>
+                <position name="boxPosition" unit="mm" x="0" y="0" z="0"/>
+            </physvol>
+
+        </volume>
+    </structure>
+
+    <setup name="Default" version="1.0">
+        <world ref="World"/>
+    </setup>
+</gdml>
+"""

geant4_python_application/generator.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from geant4_python_application.application import Message
+
+if TYPE_CHECKING:
+    from geant4_python_application.application import Application
+
+
+class Generator:
+    """Configure Geant4's particle gun or General Particle Source (GPS)."""
+
+    def __init__(self, application: Application):
+        self._application = application
+
+    @property
+    def type(self) -> str:
+        return self._application._send_and_recv(
+            Message("generator", "get_type", (), {})
+        )
+
+    @type.setter
+    def type(self, generator_type: str):
+        self._application._send_and_recv(
+            Message("generator", "set_type", (generator_type,), {})
+        )
+
+    def use_gun(self) -> Generator:
+        self.type = "gun"
+        return self
+
+    def use_gps(self) -> Generator:
+        self.type = "gps"
+        return self
+
+    def particle(self, name: str) -> Generator:
+        command = "/gps/particle" if self.type == "gps" else "/gun/particle"
+        self._application.command(f"{command} {name}")
+        return self
+
+    def energy(self, value: float, unit: str = "MeV") -> Generator:
+        command = "/gps/ene/mono" if self.type == "gps" else "/gun/energy"
+        self._application.command(f"{command} {value} {unit}")
+        return self
+
+    def position(self, x: float, y: float, z: float, unit: str = "cm") -> Generator:
+        if self.type == "gps":
+            self._application.command("/gps/pos/type Point")
+            self._application.command(f"/gps/pos/centre {x} {y} {z} {unit}")
+        else:
+            self._application.command(f"/gun/position {x} {y} {z} {unit}")
+        return self
+
+    def direction(self, x: float, y: float, z: float) -> Generator:
+        command = "/gps/direction" if self.type == "gps" else "/gun/direction"
+        self._application.command(f"{command} {x} {y} {z}")
+        return self
+
+    def commands(self, commands: list[str]) -> Generator:
+        """Apply advanced source commands such as GPS distributions."""
+        self._application.commands(commands)
+        return self

geant4_python_application/geometry.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+"""Pure-Python GDML geometry generators.
+
+These helpers expand regular layouts into ordinary GDML placements.  They are
+useful where an official example uses a live ``G4VPVParameterisation`` callback:
+the geometry is equivalent at initialization time, but there is no callback
+during tracking.
+"""
+
+
+def linear_array_gdml(
+    count: int,
+    *,
+    spacing_mm: float = 20.0,
+    box_size_mm: float = 10.0,
+    material: str = "G4_Si",
+    world_material: str = "G4_AIR",
+) -> str:
+    """Return GDML containing ``count`` equally spaced boxes along x."""
+    if count < 1:
+        raise ValueError("count must be at least one")
+    if spacing_mm <= 0 or box_size_mm <= 0:
+        raise ValueError("spacing_mm and box_size_mm must be positive")
+    extent = (count - 1) * spacing_mm + box_size_mm
+    world_x = max(100.0, extent + 4.0 * spacing_mm)
+    placements = []
+    x0 = -0.5 * (count - 1) * spacing_mm
+    for index in range(count):
+        x = x0 + index * spacing_mm
+        placements.append(
+            f'''      <physvol name="cell_{index}">
+        <volumeref ref="CellVolume"/>
+        <position name="cell_position_{index}" unit="mm" x="{x:.12g}" y="0" z="0"/>
+      </physvol>'''
+        )
+    return f'''<?xml version="1.0" encoding="UTF-8" ?>
+<gdml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://service-spi.web.cern.ch/service-spi/app/releases/GDML/schema/gdml.xsd">
+  <solids>
+    <box name="WorldSolid" lunit="mm" x="{world_x:.12g}" y="100" z="100"/>
+    <box name="CellSolid" lunit="mm" x="{box_size_mm:.12g}" y="40" z="40"/>
+  </solids>
+  <structure>
+    <volume name="CellVolume"><materialref ref="{material}"/><solidref ref="CellSolid"/></volume>
+    <volume name="World">
+      <materialref ref="{world_material}"/><solidref ref="WorldSolid"/>
+{chr(10).join(placements)}
+    </volume>
+  </structure>
+  <setup name="Default" version="1.0"><world ref="World"/></setup>
+</gdml>
+'''

geant4_python_application/io.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+"""VTK / ROOT / external-generator helpers (pure Python, optional deps).
+
+- mesh_to_vtk: write Cartesian energy mesh to legacy VTK STRUCTURED_POINTS.
+- events_to_parquet / events_from_parquet: always available (pyarrow).
+- events_to_root / events_from_root: via uproot if installed.
+- hepmc_to_primaries: minimal HepMC2-ASCII -> awkward primaries.
+"""
+
+from pathlib import Path
+
+import awkward as ak
+import numpy as np
+
+
+def mesh_to_vtk(mesh: np.ndarray, edges: tuple, filename: str | Path) -> Path:
+    """Write (nx,ny,nz) energy mesh to legacy VTK STRUCTURED_POINTS file."""
+    mesh = np.asarray(mesh, dtype=float)
+    if mesh.ndim != 3:
+        msg = f"mesh must be 3D, got shape {mesh.shape}"
+        raise ValueError(msg)
+    nx, ny, nz = mesh.shape
+    if len(edges) != 3:
+        msg = "edges must be (x_edges, y_edges, z_edges)"
+        raise ValueError(msg)
+    origins, spacings = [], []
+    dims = []
+    for n, e in zip((nx, ny, nz), edges):
+        e = np.asarray(e, dtype=float)
+        if len(e) != n + 1:
+            msg = f"edges length {len(e)} inconsistent with mesh dim {n}"
+            raise ValueError(msg)
+        origins.append(float(e[0]))
+        spacings.append(float(e[1] - e[0]) if n > 0 else 1.0)
+        dims.append(n + 1 if False else n)  # points == cells for cell data
+    out = Path(filename)
+    # VTK Fortran ordering: x varies fastest
+    flat = mesh.ravel(order="F")
+    with out.open("w") as f:
+        f.write("# vtk DataFile Version 3.0\n")
+        f.write("geant4 energy mesh\n")
+        f.write("ASCII\n")
+        f.write("DATASET STRUCTURED_POINTS\n")
+        f.write(f"DIMENSIONS {nx} {ny} {nz}\n")
+        f.write(f"ORIGIN {origins[0]} {origins[1]} {origins[2]}\n")
+        f.write(f"SPACING {spacings[0]} {spacings[1]} {spacings[2]}\n")
+        f.write(f"POINT_DATA {nx * ny * nz}\n")
+        f.write("SCALARS energy_keV float 1\n")
+        f.write("LOOKUP_TABLE default\n")
+        for v in flat:
+            f.write(f"{v}\n")
+    return out
+
+
+def events_to_parquet(events: ak.Array, filename: str | Path) -> Path:
+    out = Path(filename)
+    ak.to_parquet(events, out)
+    return out
+
+
+def events_from_parquet(filename: str | Path) -> ak.Array:
+    return ak.from_parquet(Path(filename))
+
+
+def events_to_root(
+    events: ak.Array, filename: str | Path, treename: str = "events"
+) -> Path:
+    """Write flat per-event summary + hits to ROOT via uproot (requires uproot)."""
+    try:
+        import uproot
+    except ImportError as e:
+        msg = "uproot is required for ROOT I/O: pip install uproot"
+        raise ImportError(msg) from e
+    out = Path(filename)
+    # Flatten what ROOT can store: per-event id + deposited energy + nhits.
+    # Full nested step records stay in parquet; ROOT holds analysis summary.
+    import geant4_python_application as g4
+
+    edep = np.asarray(g4.Scoring.energy_deposit(events), dtype=np.float64)
+    ids = (
+        np.asarray(events.id, dtype=np.int64)
+        if "id" in events.fields
+        else np.arange(len(events))
+    )
+    with uproot.recreate(out) as f:
+        f[treename] = {"id": ids, "edep_keV": edep}
+    return out
+
+
+def events_from_root(filename: str | Path, treename: str = "events") -> dict:
+    try:
+        import uproot
+    except ImportError as e:
+        msg = "uproot is required for ROOT I/O: pip install uproot"
+        raise ImportError(msg) from e
+    with uproot.open(f"{filename}:{treename}") as t:
+        return t.arrays(library="np")
+
+
+_PDG_TO_G4 = {
+    11: "e-",
+    -11: "e+",
+    22: "gamma",
+    13: "mu-",
+    -13: "mu+",
+    2112: "neutron",
+    2212: "proton",
+    211: "pi+",
+    -211: "pi-",
+    111: "pi0",
+    321: "kaon+",
+    -321: "kaon-",
+    12: "nu_e",
+    -12: "anti_nu_e",
+    14: "nu_mu",
+    -14: "anti_nu_mu",
+}
+
+
+def hepmc_to_primaries(hepmc_text: str) -> ak.Array:
+    """Parse minimal HepMC2 ASCII (E/P lines) into awkward primaries.
+
+    Expects lines like: P <id> <pdg> <px_GeV> <py> <pz> <E_GeV> ...
+    Position defaults to origin; direction = p/|p|; energy = kinetic approx.
+    Unknown PDG codes fall back to geantino.
+    """
+    records = []
+    for line in hepmc_text.splitlines():
+        s = line.strip().split()
+        if not s or s[0] != "P":
+            continue
+        if len(s) < 7:
+            continue
+        pdg = int(s[2])
+        px, py, pz, e = (float(s[3]), float(s[4]), float(s[5]), float(s[6]))
+        p = float(np.sqrt(px * px + py * py + pz * pz))
+        if p == 0:
+            continue
+        particle = _PDG_TO_G4.get(pdg, "geantino")
+        # awkward primary energy convention in this package: keV numbers?
+        # Application primaries use raw doubles passed to gun in keV? Keep MeV->keV.
+        records.append(
+            {
+                "particle": particle,
+                "energy": e * 1e6,  # GeV -> keV (gun awkward path uses keV)
+                "direction": {"x": px / p, "y": py / p, "z": pz / p},
+                "position": {"x": 0.0, "y": 0.0, "z": 0.0},
+            }
+        )
+    if not records:
+        msg = "no P lines parsed from HepMC text"
+        raise ValueError(msg)
+    return ak.Array(records)

geant4_python_application/optical.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+"""Minimal optical-materials/surfaces helpers (GDML-based).
+
+Geant4 optical properties (RINDEX, scintillation, WLS, ...) and optical
+surfaces (skin/border) are defined in GDML via <matrix>, <property> and
+<opticalsurface>/<skinsurface>/<bordersurface> tags. This module provides a
+compact, fast-simulating water-scintillator GDML example plus UI-command
+helpers for tuning optical processes at run time.
+"""
+
+optical_water_gdml = R"""<?xml version="1.0" encoding="UTF-8" ?>
+<gdml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://service-spi.web.cern.ch/service-spi/app/releases/GDML/schema/gdml.xsd">
+  <define>
+    <matrix coldim="2" name="WATERRINDEX" values="2.034*eV 1.3435 3.026*eV 1.3545 4.136*eV 1.3608"/>
+    <matrix coldim="2" name="WATERABSLENGTH" values="2.034*eV 20000 4.136*eV 14500"/>
+    <matrix coldim="2" name="SCINTCOMP" values="2.034*eV 1 3.026*eV 1 4.136*eV 1"/>
+    <matrix coldim="1" name="SCINTYIELD" values="50"/>
+    <matrix coldim="1" name="RESOLUTIONSCALE" values="1"/>
+    <matrix coldim="1" name="TIMECONSTANT1" values="1"/>
+    <position name="center" unit="mm" x="0" y="0" z="0"/>
+  </define>
+  <materials>
+    <element Z="1" formula="H" name="Hydrogen"><atom value="1.01"/></element>
+    <element Z="8" formula="O" name="Oxygen"><atom value="16.0"/></element>
+    <material name="WaterScint" state="liquid">
+      <property name="RINDEX" ref="WATERRINDEX"/>
+      <property name="ABSLENGTH" ref="WATERABSLENGTH"/>
+      <property name="SCINTILLATIONCOMPONENT1" ref="SCINTCOMP"/>
+      <property name="SCINTILLATIONYIELD" ref="SCINTYIELD"/>
+      <property name="RESOLUTIONSCALE" ref="RESOLUTIONSCALE"/>
+      <property name="SCINTILLATIONTIMECONSTANT1" ref="TIMECONSTANT1"/>
+      <D unit="g/cm3" value="1"/>
+      <fraction n="0.1119" ref="Hydrogen"/>
+      <fraction n="0.8881" ref="Oxygen"/>
+    </material>
+    <material name="AirOpt" state="gas">
+      <D unit="g/cm3" value="0.00129"/>
+      <fraction n="0.7" ref="Hydrogen"/>
+      <fraction n="0.3" ref="Oxygen"/>
+    </material>
+  </materials>
+  <solids>
+    <box lunit="mm" name="WorldSolid" x="1000" y="1000" z="1000"/>
+    <box lunit="mm" name="ScintSolid" x="500" y="500" z="500"/>
+    <opticalsurface finish="polished" model="glisur" name="ScintSurface" type="dielectric_dielectric" value="1.0"/>
+  </solids>
+  <structure>
+    <volume name="ScintVolume">
+      <materialref ref="WaterScint"/>
+      <solidref ref="ScintSolid"/>
+    </volume>
+    <volume name="World">
+      <materialref ref="AirOpt"/>
+      <solidref ref="WorldSolid"/>
+      <physvol name="scint">
+        <volumeref ref="ScintVolume"/>
+        <positionref ref="center"/>
+      </physvol>
+    </volume>
+    <skinsurface name="ScintSkin" surfaceproperty="ScintSurface">
+      <volumeref ref="ScintVolume"/>
+    </skinsurface>
+  </structure>
+  <setup name="Default" version="1.0">
+    <world ref="World"/>
+  </setup>
+</gdml>
+"""
+
+
+# Compact, self-contained optical geometries used by the Python adaptations of
+# Geant4's LXe and WLS examples.  They intentionally model the transport
+# concepts rather than the examples' custom PMT/sensitive-detector classes.
+lxe_scintillator_gdml = R"""<?xml version="1.0" encoding="UTF-8" ?>
+<gdml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://service-spi.web.cern.ch/service-spi/app/releases/GDML/schema/gdml.xsd">
+  <define>
+    <matrix coldim="2" name="LXeRINDEX" values="6.2*eV 1.59 7.0*eV 1.61 7.5*eV 1.64"/>
+    <matrix coldim="2" name="LXeABSLENGTH" values="6.2*eV 1000 7.5*eV 1000"/>
+    <matrix coldim="2" name="LXeSCINT" values="6.2*eV 0.1 7.0*eV 1.0 7.5*eV 0.1"/>
+    <matrix coldim="1" name="LXeYIELD" values="120"/>
+    <matrix coldim="1" name="LXeRESOLUTION" values="1"/>
+    <matrix coldim="1" name="LXeTIME" values="2.2"/>
+    <matrix coldim="2" name="GasRINDEX" values="1.0*eV 1.0 8.0*eV 1.0"/>
+    <position name="center" unit="mm" x="0" y="0" z="0"/>
+  </define>
+  <materials>
+    <element Z="54" formula="Xe" name="Xenon"><atom value="131.293"/></element>
+    <element Z="7" formula="N" name="Nitrogen"><atom value="14.007"/></element>
+    <material name="LiquidXenon" state="liquid">
+      <property name="RINDEX" ref="LXeRINDEX"/>
+      <property name="ABSLENGTH" ref="LXeABSLENGTH"/>
+      <property name="SCINTILLATIONCOMPONENT1" ref="LXeSCINT"/>
+      <property name="SCINTILLATIONYIELD" ref="LXeYIELD"/>
+      <property name="RESOLUTIONSCALE" ref="LXeRESOLUTION"/>
+      <property name="SCINTILLATIONTIMECONSTANT1" ref="LXeTIME"/>
+      <D unit="g/cm3" value="2.95"/>
+      <fraction n="1" ref="Xenon"/>
+    </material>
+    <material name="NitrogenGas" state="gas">
+      <property name="RINDEX" ref="GasRINDEX"/>
+      <D unit="g/cm3" value="0.001165"/>
+      <fraction n="1" ref="Nitrogen"/>
+    </material>
+  </materials>
+  <solids>
+    <box lunit="mm" name="WorldSolid" x="1000" y="1000" z="1000"/>
+    <box lunit="mm" name="LXeSolid" x="300" y="300" z="300"/>
+    <opticalsurface finish="polished" model="unified" name="LXeSurface" type="dielectric_dielectric" value="1.0"/>
+  </solids>
+  <structure>
+    <volume name="LXeVolume">
+      <materialref ref="LiquidXenon"/>
+      <solidref ref="LXeSolid"/>
+    </volume>
+    <volume name="World">
+      <materialref ref="NitrogenGas"/>
+      <solidref ref="WorldSolid"/>
+      <physvol name="lxe"><volumeref ref="LXeVolume"/><positionref ref="center"/></physvol>
+    </volume>
+    <skinsurface name="LXeSkin" surfaceproperty="LXeSurface"><volumeref ref="LXeVolume"/></skinsurface>
+  </structure>
+  <setup name="Default" version="1.0"><world ref="World"/></setup>
+</gdml>
+"""
+
+
+wls_fiber_gdml = R"""<?xml version="1.0" encoding="UTF-8" ?>
+<gdml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://service-spi.web.cern.ch/service-spi/app/releases/GDML/schema/gdml.xsd">
+  <define>
+    <matrix coldim="2" name="CoreRINDEX" values="2.0*eV 1.60 4.0*eV 1.60"/>
+    <matrix coldim="2" name="CoreABSLENGTH" values="2.0*eV 5000 4.0*eV 5000"/>
+    <matrix coldim="2" name="WLSABSLENGTH" values="2.0*eV 5000 2.8*eV 5 4.0*eV 1"/>
+    <matrix coldim="2" name="WLSEMISSION" values="2.0*eV 0.1 2.4*eV 1.0 2.8*eV 0.1 4.0*eV 0.0"/>
+    <matrix coldim="1" name="WLSTIME" values="0.5"/>
+    <matrix coldim="2" name="CladRINDEX" values="2.0*eV 1.49 4.0*eV 1.49"/>
+    <matrix coldim="2" name="AirRINDEX" values="2.0*eV 1.0 4.0*eV 1.0"/>
+    <position name="center" unit="mm" x="0" y="0" z="0"/>
+  </define>
+  <materials>
+    <element Z="1" formula="H" name="HydrogenWLS"><atom value="1.008"/></element>
+    <element Z="6" formula="C" name="CarbonWLS"><atom value="12.011"/></element>
+    <material name="WLSCore" state="solid">
+      <property name="RINDEX" ref="CoreRINDEX"/>
+      <property name="ABSLENGTH" ref="CoreABSLENGTH"/>
+      <property name="WLSABSLENGTH" ref="WLSABSLENGTH"/>
+      <property name="WLSCOMPONENT" ref="WLSEMISSION"/>
+      <property name="WLSTIMECONSTANT" ref="WLSTIME"/>
+      <D unit="g/cm3" value="1.05"/>
+      <fraction n="0.0774" ref="HydrogenWLS"/><fraction n="0.9226" ref="CarbonWLS"/>
+    </material>
+    <material name="WLSCladding" state="solid">
+      <property name="RINDEX" ref="CladRINDEX"/>
+      <D unit="g/cm3" value="1.19"/>
+      <fraction n="0.0774" ref="HydrogenWLS"/><fraction n="0.9226" ref="CarbonWLS"/>
+    </material>
+    <material name="WLSAir" state="gas">
+      <property name="RINDEX" ref="AirRINDEX"/>
+      <D unit="g/cm3" value="0.0012"/>
+      <fraction n="0.0774" ref="HydrogenWLS"/><fraction n="0.9226" ref="CarbonWLS"/>
+    </material>
+  </materials>
+  <solids>
+    <box lunit="mm" name="WorldSolid" x="100" y="100" z="500"/>
+    <tube aunit="deg" deltaphi="360" lunit="mm" name="CladdingSolid" rmax="1.2" rmin="0" startphi="0" z="400"/>
+    <tube aunit="deg" deltaphi="360" lunit="mm" name="CoreSolid" rmax="1.0" rmin="0" startphi="0" z="400"/>
+  </solids>
+  <structure>
+    <volume name="CoreVolume"><materialref ref="WLSCore"/><solidref ref="CoreSolid"/></volume>
+    <volume name="CladdingVolume">
+      <materialref ref="WLSCladding"/><solidref ref="CladdingSolid"/>
+      <physvol name="fiber_core"><volumeref ref="CoreVolume"/><positionref ref="center"/></physvol>
+    </volume>
+    <volume name="World">
+      <materialref ref="WLSAir"/><solidref ref="WorldSolid"/>
+      <physvol name="fiber"><volumeref ref="CladdingVolume"/><positionref ref="center"/></physvol>
+    </volume>
+  </structure>
+  <setup name="Default" version="1.0"><world ref="World"/></setup>
+</gdml>
+"""
+
+#: Common optical-process UI commands for Geant4 11.2 (apply via app.commands(...)).
+#: Verified against /process/optical/scintillation and /process/optical/cerenkov.
+optical_tuning_commands = [
+    "/process/optical/scintillation/setStackPhotons true",
+    "/process/optical/cerenkov/setMaxPhotons 100",
+    "/process/optical/verbose 1",
+]
+
+
+def scintillation_commands(
+    stack_photons: bool = True, max_cerenkov: int = 100
+) -> list[str]:
+    """Return UI commands tuning scintillation/Cerenkov at run time (Geant4 11.2)."""
+    return [
+        f"/process/optical/scintillation/setStackPhotons {'true' if stack_photons else 'false'}",
+        f"/process/optical/cerenkov/setMaxPhotons {max_cerenkov}",
+    ]

geant4_python_application/scoring.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import awkward as ak
+import numpy as np
+
+if TYPE_CHECKING:
+    from geant4_python_application.application import Application
+
+
+class NativeScoringMesh:
+    """Configure a Geant4 command-based Cartesian scoring mesh.
+
+    This uses Geant4's native ``G4ScoringManager`` commands. It is distinct
+    from :class:`Scoring`, which bins recorded steps in Python after a run.
+    """
+
+    def __init__(
+        self,
+        application: Application,
+        name: str = "mesh",
+        quantity: str = "eDep",
+    ):
+        self.application = application
+        self.name = name
+        self.quantity = quantity
+        self._closed = False
+
+    def box(
+        self,
+        half_size: tuple[float, float, float],
+        bins: tuple[int, int, int],
+        *,
+        unit: str = "mm",
+        center: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    ) -> NativeScoringMesh:
+        """Create a box mesh; ``half_size`` follows Geant4 mesh semantics."""
+        if self._closed:
+            raise RuntimeError("scoring mesh is already closed")
+        sx, sy, sz = half_size
+        nx, ny, nz = bins
+        cx, cy, cz = center
+        self.application.commands(
+            [
+                f"/score/create/boxMesh {self.name}",
+                f"/score/mesh/boxSize {sx} {sy} {sz} {unit}",
+                f"/score/mesh/nBin {nx} {ny} {nz}",
+                f"/score/mesh/translate/xyz {cx} {cy} {cz} {unit}",
+                f"/score/quantity/energyDeposit {self.quantity}",
+                "/score/close",
+            ]
+        )
+        self._closed = True
+        return self
+
+    def dump(self, path: str | Path, *, option: str = "") -> Path:
+        """Dump the native mesh quantity after a run and return its path."""
+        if not self._closed:
+            raise RuntimeError("configure and close the scoring mesh before dumping")
+        output = Path(path).expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        if " " in str(output):
+            raise ValueError("Geant4 scoring output paths cannot contain spaces")
+        suffix = f" {option}" if option else ""
+        self.application.command(
+            f"/score/dumpQuantityToFile {self.name} {self.quantity} {output}{suffix}"
+        )
+        return output
+
+
+class Scoring:
+    """Scoring operations over Geant4 event, track, and step records."""
+
+    @staticmethod
+    def energy_deposit(events: ak.Array, volume: str | None = None) -> ak.Array:
+        """Return deposited energy in keV for each event."""
+        steps = events.track.step
+        energy = steps.energy
+        if volume is not None:
+            energy = energy[steps.volume == volume]
+        return ak.sum(ak.flatten(energy, axis=-1), axis=1)
+
+    @staticmethod
+    def hits(events: ak.Array, volume: str | None = None) -> ak.Array:
+        """Return positive-energy steps, optionally restricted to a volume."""
+        return events.hits(volume)
+
+    @staticmethod
+    def energy_mesh(
+        events: ak.Array,
+        bins: int | tuple[int, int, int] = 10,
+        mesh_range: tuple[tuple[float, float], tuple[float, float], tuple[float, float]]
+        | None = None,
+        volume: str | None = None,
+    ) -> tuple[np.ndarray, tuple[np.ndarray, np.ndarray, np.ndarray]]:
+        """Bin step energy into a Cartesian 3D mesh.
+
+        Positions are in millimetres and mesh values are deposited energy in keV.
+        """
+        hits = Scoring.hits(events, volume)
+        weights = ak.to_numpy(ak.flatten(hits.energy, axis=None))
+        if len(weights) == 0:
+            shape = (bins, bins, bins) if isinstance(bins, int) else bins
+            return np.zeros(shape), (np.array([]), np.array([]), np.array([]))
+
+        points = np.column_stack(
+            [
+                ak.to_numpy(ak.flatten(hits.position.x, axis=None)),
+                ak.to_numpy(ak.flatten(hits.position.y, axis=None)),
+                ak.to_numpy(ak.flatten(hits.position.z, axis=None)),
+            ]
+        )
+        mesh, edges = np.histogramdd(
+            points, bins=bins, range=mesh_range, weights=weights
+        )
+        return mesh, edges