reboost 0.7.0__tar.gz → 0.8.1__tar.gz

{reboost-0.7.0 → reboost-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reboost
-Version: 0.7.0
+Version: 0.8.1
 Summary: New LEGEND Monte-Carlo simulation post-processing
 Author-email: Manuel Huber <info@manuelhu.de>, Toby Dixon <toby.dixon.23@ucl.ac.uk>, Luigi Pertoldi <gipert@pm.me>
 Maintainer: The LEGEND Collaboration
@@ -700,10 +700,11 @@ Requires-Dist: hdf5plugin
 Requires-Dist: colorlog
 Requires-Dist: numpy
 Requires-Dist: scipy
-Requires-Dist: numba
+Requires-Dist: numba>=0.60
 Requires-Dist: legend-pydataobj>=1.15.1
 Requires-Dist: legend-pygeom-optics>=0.12.0
 Requires-Dist: legend-pygeom-tools>=0.0.11
+Requires-Dist: legend-pygeom-hpges
 Requires-Dist: hist
 Requires-Dist: dbetto
 Requires-Dist: particle
@@ -728,6 +729,8 @@ Dynamic: license-file
 
 # reboost
 
+[![PyPI](https://img.shields.io/pypi/v/reboost?logo=pypi)](https://pypi.org/project/reboost/)
+[![conda-forge](https://img.shields.io/conda/vn/conda-forge/reboost.svg)](https://anaconda.org/conda-forge/reboost)
 ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/legend-exp/reboost?logo=git)
 [![GitHub Workflow Status](https://img.shields.io/github/checks-status/legend-exp/reboost/main?label=main%20branch&logo=github)](https://github.com/legend-exp/reboost/actions)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

{reboost-0.7.0 → reboost-0.8.1}/README.md

@@ -1,5 +1,7 @@
 # reboost
 
+[![PyPI](https://img.shields.io/pypi/v/reboost?logo=pypi)](https://pypi.org/project/reboost/)
+[![conda-forge](https://img.shields.io/conda/vn/conda-forge/reboost.svg)](https://anaconda.org/conda-forge/reboost)
 ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/legend-exp/reboost?logo=git)
 [![GitHub Workflow Status](https://img.shields.io/github/checks-status/legend-exp/reboost/main?label=main%20branch&logo=github)](https://github.com/legend-exp/reboost/actions)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

{reboost-0.7.0 → reboost-0.8.1}/pyproject.toml

@@ -36,10 +36,11 @@ dependencies = [
     "colorlog",
     "numpy",
     "scipy",
-    "numba",
+    "numba >=0.60",
     "legend-pydataobj >=1.15.1",
     "legend-pygeom-optics >=0.12.0",
     "legend-pygeom-tools >=0.0.11",
+    "legend-pygeom-hpges",
     "hist",
     "dbetto",
     "particle",

{reboost-0.7.0 → reboost-0.8.1}/src/reboost/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.7.0'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.8.1'
+__version_tuple__ = version_tuple = (0, 8, 1)
 
-__commit_id__ = commit_id = 'gbfb61789b'
+__commit_id__ = commit_id = 'g3148f45bd'

{reboost-0.7.0 → reboost-0.8.1}/src/reboost/core.py

@@ -325,8 +325,6 @@ def get_one_detector_mapping(
         out_list = list(output_detector_expression)
 
     for expression_tmp in out_list:
-        func, globs = utils.get_function_string(expression_tmp)
-
         # if no package was imported its just a name
         try:
             objs = evaluate_object(expression_tmp, local_dict={"ARGS": args, "OBJECTS": objects})

{reboost-0.7.0 → reboost-0.8.1}/src/reboost/hpge/psd.py

@@ -262,11 +262,13 @@ def _current_pulse_model(
 
     Consists of a Gaussian, a high side exponential tail and a low side tail:
 
-     .. math::
+    .. math::
 
-       A(t) = A_{max}\times (1-p-p_h)\times \text{Gauss}(t,\mu,\sigma)+ A \times p (1-\text{Erf}((t-\mu)/sigma_i))\times
-        \frac{e^{( t/\tau)}}{2e^{\mu/\tau}} + A \times p_h (1-\text{Erf}(-(t-\mu)/sigma_i))\times
-        \frac{e^{-( t/\tau)}}{2}
+      \begin{align}
+      A(t) = \; &A_\text{max} \times (1-p-p_h) \times \text{Gauss}(t;\mu,\sigma) \\
+        &+ A \times p \; \left(1 - \text{erf}\left(\frac{t-\mu}{\sigma_i}\right)\right) \times \frac{e^{t/\tau}}{2e^{\mu/\tau}} \\
+        &+ A \times p_h \; \left(1 - \text{erf}\left(-\frac{t-\mu}{\sigma_i}\right)\right) \times \frac{1}{2}e^{-t/\tau}
+      \end{align}
 
     Parameters
     ----------
@@ -397,13 +399,13 @@ def get_current_waveform(
     the template.
 
     .. math::
-        A(t) = \sum_i E_i \times N f(t,dt_i,\vector{\theta})
+        A(t) = \sum_i E_i \times N f(t, dt_i, \vec{\theta})
 
     Where:
-        - $f(t)$ is the template
-        - $\vector{\theta}$ are the parameters (sigma, p, tau)
-        - $E_i$ and $dt_i$ are the deposited energy and drift time.
-        - N is a normalisation term
+        - :math:`f(t)` is the template
+        - :math`\vec{\theta}` are the parameters :math:`(\sigma, p, \tau)`
+        - :math:`E_i` and :math:`dt_i` are the deposited energy and drift time.
+        - :math:`N` is a normalisation term
 
     Parameters
     ----------

{reboost-0.7.0 → reboost-0.8.1}/src/reboost/optmap/cli.py

@@ -35,21 +35,7 @@ def optical_cli() -> None:
 
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    # STEP 1: build evt file from stp tier
-    evt_parser = subparsers.add_parser("evt", help="build optmap-evt file from remage stp file")
-    evt_parser_det_group = evt_parser.add_mutually_exclusive_group(required=True)
-    evt_parser_det_group.add_argument(
-        "--geom",
-        help="GDML geometry file",
-    )
-    evt_parser_det_group.add_argument(
-        "--detectors",
-        help="file with detector ids of all optical channels.",
-    )
-    evt_parser.add_argument("input", help="input stp LH5 file", metavar="INPUT_STP")
-    evt_parser.add_argument("output", help="output evt LH5 file", metavar="OUTPUT_EVT")
-
-    # STEP 2a: build map file from evt tier
+    # STEP 1a: build map file from evt tier
     map_parser = subparsers.add_parser("createmap", help="build optical map from evt file(s)")
     map_parser.add_argument(
         "--settings",
@@ -91,42 +77,67 @@ def optical_cli() -> None:
     )
     map_parser.add_argument("output", help="output map LH5 file", metavar="OUTPUT_MAP")
 
-    # STEP 2b: view maps
-    mapview_parser = subparsers.add_parser("viewmap", help="view optical map")
+    # STEP 1b: view maps
+    mapview_parser = subparsers.add_parser(
+        "viewmap",
+        help="view optical map (arrows: navigate slices/axes, 'c': channel selector)",
+        formatter_class=argparse.RawTextHelpFormatter,
+        description=(
+            "Interactively view optical maps stored in LH5 files.\n\n"
+            "Keyboard controls:\n"
+            "  left/right  - previous/next slice along the current axis\n"
+            "  up/down     - switch slicing axis (x, y, z)\n"
+            "  c           - open channel selector overlay to switch detector map\n\n"
+            "Display notes:\n"
+            "  - Cells where no primary photons were simulated are shown in white.\n"
+            "  - Cells where no photons were detected are shown in grey.\n"
+            "  - Cells with values above the colormap maximum are shown in red.\n"
+            "  - Use --hist to choose which histogram to display. 'prob_unc_rel' shows the\n"
+            "    relative uncertainty prob_unc / prob where defined.\n"
+            "  - Use --divide to show the ratio of two map files (this/other)."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  reboost-optical viewmap mymap.lh5\n"
+            "  reboost-optical viewmap mymap.lh5 --channel _1067205\n"
+            "  reboost-optical viewmap mymap.lh5 --hist prob_unc_rel --min 0 --max 1\n"
+            "  reboost-optical viewmap mymap.lh5 --divide other.lh5 --title 'Comparison'"
+        ),
+    )
     mapview_parser.add_argument("input", help="input map LH5 file", metavar="INPUT_MAP")
     mapview_parser.add_argument(
         "--channel",
         action="store",
         default="all",
-        help="default: %(default)s",
+        help="channel to display ('all' or '_<detid>'). Press 'c' in the viewer to switch. default: %(default)s",
     )
     mapview_parser.add_argument(
         "--hist",
-        choices=("nr_gen", "nr_det", "p_det", "p_det_err", "p_det_err_rel"),
+        choices=("_nr_gen", "_nr_det", "prob", "prob_unc", "prob_unc_rel"),
         action="store",
-        default="p_det",
+        default="prob",
         help="select optical map histogram to show. default: %(default)s",
     )
     mapview_parser.add_argument(
         "--divide",
         action="store",
-        help="default: none",
+        help="divide by another map file before display (ratio). default: none",
     )
     mapview_parser.add_argument(
         "--min",
         default=1e-4,
         type=(lambda s: s if s == "auto" else float(s)),
-        help="colormap min value. default: %(default)e",
+        help="colormap min value; use 'auto' for automatic scaling. default: %(default)e",
     )
     mapview_parser.add_argument(
         "--max",
         default=1e-2,
         type=(lambda s: s if s == "auto" else float(s)),
-        help="colormap max value. default: %(default)e",
+        help="colormap max value; use 'auto' for automatic scaling. default: %(default)e",
     )
     mapview_parser.add_argument("--title", help="title of figure. default: stem of filename")
 
-    # STEP 2c: merge maps
+    # STEP 1c: merge maps
     mapmerge_parser = subparsers.add_parser("mergemap", help="merge optical maps")
     mapmerge_parser.add_argument(
         "input", help="input map LH5 files", metavar="INPUT_MAP", nargs="+"
@@ -151,49 +162,10 @@ def optical_cli() -> None:
         help="""Check map statistics after creation. default: %(default)s""",
     )
 
-    # STEP 2d: check map
+    # STEP 1d: check map
     checkmap_parser = subparsers.add_parser("checkmap", help="check optical maps")
     checkmap_parser.add_argument("input", help="input map LH5 file", metavar="INPUT_MAP")
 
-    # STEP 3: convolve with hits from non-optical simulations
-    convolve_parser = subparsers.add_parser(
-        "convolve", help="convolve non-optical hits with optical map"
-    )
-    convolve_parser.add_argument(
-        "--material",
-        action="store",
-        choices=("lar", "pen", "fiber"),
-        default="lar",
-        help="default: %(default)s",
-    )
-    convolve_parser.add_argument(
-        "--map",
-        action="store",
-        required=True,
-        metavar="INPUT_MAP",
-        help="input map LH5 file",
-    )
-    convolve_parser.add_argument(
-        "--edep",
-        action="store",
-        required=True,
-        metavar="INPUT_EDEP",
-        help="input non-optical LH5 hit file",
-    )
-    convolve_parser.add_argument(
-        "--edep-lgdo",
-        action="store",
-        required=True,
-        metavar="LGDO_PATH",
-        help="path to LGDO inside non-optical LH5 hit file (e.g. /stp/detXX)",
-    )
-    convolve_parser.add_argument(
-        "--dist-mode",
-        action="store",
-        default="poisson+no-fano",
-    )
-    convolve_parser.add_argument("--output", help="output hit LH5 file", metavar="OUTPUT_HIT")
-
     # STEP X: rebin maps
     rebin_parser = subparsers.add_parser("rebin", help="rebin optical maps")
     rebin_parser.add_argument("input", help="input map LH5 files", metavar="INPUT_MAP")
@@ -205,24 +177,7 @@ def optical_cli() -> None:
     log_level = (None, logging.INFO, logging.DEBUG)[min(args.verbose, 2)]
     setup_log(log_level)
 
-    # STEP 1: build evt file from hit tier
-    if args.command == "evt":
-        from .evt import build_optmap_evt, get_optical_detectors_from_geom
-
-        _check_input_file(parser, args.input)
-        _check_output_file(parser, args.output)
-
-        # load detector ids from the geometry.
-        if args.geom is not None:
-            _check_input_file(parser, args.geom, "geometry")
-            detectors = get_optical_detectors_from_geom(args.geom)
-        else:
-            _check_input_file(parser, args.detectors, "detectors")
-            detectors = dbetto.utils.load_dict(args.detectors)
-
-        build_optmap_evt(args.input, args.output, detectors, args.bufsize)
-
-    # STEP 2a: build map file from evt tier
+    # STEP 1a: build map file from evt tier
     if args.command == "createmap":
         from .create import create_optical_maps
 
@@ -250,7 +205,7 @@ def optical_cli() -> None:
             geom_fn=args.geom,
         )
 
-    # STEP 2b: view maps
+    # STEP 1b: view maps
     if args.command == "viewmap":
         from .mapview import view_optmap
 
@@ -267,7 +222,7 @@ def optical_cli() -> None:
             histogram_choice=args.hist,
         )
 
-    # STEP 2c: merge maps
+    # STEP 1c: merge maps
     if args.command == "mergemap":
         from .create import merge_optical_maps
 
@@ -281,29 +236,13 @@ def optical_cli() -> None:
             args.input, args.output, settings, check_after_create=args.check, n_procs=args.n_procs
         )
 
-    # STEP 2d: check maps
+    # STEP 1d: check maps
     if args.command == "checkmap":
         from .create import check_optical_map
 
         _check_input_file(parser, args.input)
         check_optical_map(args.input)
 
-    # STEP 3: convolve with hits from non-optical simulations
-    if args.command == "convolve":
-        from .convolve import convolve
-
-        _check_input_file(parser, [args.map, args.edep])
-        _check_output_file(parser, args.output, optional=True)
-        convolve(
-            args.map,
-            args.edep,
-            args.edep_lgdo,
-            args.material,
-            args.output,
-            args.bufsize,
-            dist_mode=args.dist_mode,
-        )
-
     # STEP X: rebin maps
     if args.command == "rebin":
         from .create import rebin_optical_maps

reboost-0.8.1/src/reboost/optmap/convolve.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+import logging
+from typing import NamedTuple
+
+import awkward as ak
+import legendoptics.scintillate as sc
+import numba
+import numpy as np
+from legendoptics import fibers, lar, pen
+from lgdo import lh5
+from lgdo.types import Histogram
+from numba import njit
+from numpy.typing import NDArray
+
+from .numba_pdg import numba_pdgid_funcs
+
+log = logging.getLogger(__name__)
+
+
+OPTMAP_ANY_CH = -1
+
+
+class OptmapForConvolve(NamedTuple):
+    """A loaded optmap for convolving."""
+
+    dets: NDArray
+    detidx: NDArray
+    edges: NDArray
+    weights: NDArray
+
+
+def open_optmap(optmap_fn: str) -> OptmapForConvolve:
+    dets = lh5.ls(optmap_fn, "/channels/")
+    detidx = np.arange(0, dets.shape[0])
+
+    optmap_all = lh5.read("/all/prob", optmap_fn)
+    assert isinstance(optmap_all, Histogram)
+    optmap_edges = tuple([b.edges for b in optmap_all.binning])
+
+    ow = np.empty((detidx.shape[0] + 2, *optmap_all.weights.nda.shape), dtype=np.float64)
+    # 0, ..., len(detidx)-1 AND OPTMAP_ANY_CH might be negative.
+    ow[OPTMAP_ANY_CH] = optmap_all.weights.nda
+    for i, nt in zip(detidx, dets, strict=True):
+        optmap = lh5.read(f"/{nt}/prob", optmap_fn)
+        assert isinstance(optmap, Histogram)
+        ow[i] = optmap.weights.nda
+
+    # if we have any individual channels registered, the sum is potentially larger than the
+    # probability to find _any_ hit.
+    if len(detidx) != 0:
+        map_sum = np.sum(ow[0:-2], axis=0, where=(ow[0:-2] >= 0))
+        assert not np.any(map_sum < 0)
+
+        # give this check some numerical slack.
+        if np.any(
+            np.abs(map_sum[ow[OPTMAP_ANY_CH] >= 0] - ow[OPTMAP_ANY_CH][ow[OPTMAP_ANY_CH] >= 0])
+            < -1e-15
+        ):
+            msg = "optical map does not fulfill relation sum(p_i) >= p_any"
+            raise ValueError(msg)
+    else:
+        detidx = np.array([OPTMAP_ANY_CH])
+        dets = np.array(["all"])
+
+    # check the exponent from the optical map file
+    if "_hitcounts_exp" in lh5.ls(optmap_fn):
+        msg = "found _hitcounts_exp which is not supported any more"
+        raise RuntimeError(msg)
+
+    dets = [d.replace("/channels/", "") for d in dets]
+
+    return OptmapForConvolve(dets, detidx, optmap_edges, ow)
+
+
+def open_optmap_single(optmap_fn: str, spm_det: str) -> OptmapForConvolve:
+    # check the exponent from the optical map file
+    if "_hitcounts_exp" in lh5.ls(optmap_fn):
+        msg = "found _hitcounts_exp which is not supported any more"
+        raise RuntimeError(msg)
+
+    h5_path = f"channels/{spm_det}" if spm_det != "all" else spm_det
+    optmap = lh5.read(f"/{h5_path}/prob", optmap_fn)
+    assert isinstance(optmap, Histogram)
+    ow = np.empty((1, *optmap.weights.nda.shape), dtype=np.float64)
+    ow[0] = optmap.weights.nda
+    optmap_edges = tuple([b.edges for b in optmap.binning])
+
+    return OptmapForConvolve(np.array([spm_det]), np.array([0]), optmap_edges, ow)
+
+
+def iterate_stepwise_depositions_pois(
+    edep_hits: ak.Array,
+    optmap: OptmapForConvolve,
+    scint_mat_params: sc.ComputedScintParams,
+    det: str,
+    map_scaling: float = 1,
+    map_scaling_sigma: float = 0,
+    rng: np.random.Generator | None = None,
+):
+    if edep_hits.particle.ndim == 1:
+        msg = "the pe processors only support already reshaped output"
+        raise ValueError(msg)
+
+    if det not in optmap.dets:
+        msg = f"channel {det} not available in optical map (contains {optmap.dets})"
+        raise ValueError(msg)
+
+    rng = np.random.default_rng() if rng is None else rng
+    res, output_list = _iterate_stepwise_depositions_pois(
+        edep_hits,
+        rng,
+        np.where(optmap.dets == det)[0][0],
+        map_scaling,
+        map_scaling_sigma,
+        optmap.edges,
+        optmap.weights,
+        scint_mat_params,
+    )
+
+    # convert the numba result back into an awkward array.
+    builder = ak.ArrayBuilder()
+    for r in output_list:
+        with builder.list():
+            for a in r:
+                builder.extend(a)
+
+    if res["det_no_stats"] > 0:
+        log.warning(
+            "had edep out in voxels without stats: %d",
+            res["det_no_stats"],
+        )
+    if res["oob"] > 0:
+        log.warning(
+            "had edep out of map bounds: %d (%.2f%%)",
+            res["oob"],
+            (res["oob"] / (res["ib"] + res["oob"])) * 100,
+        )
+    log.debug(
+        "VUV_primary %d ->hits %d (%.2f %% primaries detected in this channel)",
+        res["vuv_primary"],
+        res["hits"],
+        (res["hits"] / res["vuv_primary"]) * 100,
+    )
+    return builder.snapshot()
+
+
+def iterate_stepwise_depositions_scintillate(
+    edep_hits: ak.Array,
+    scint_mat_params: sc.ComputedScintParams,
+    rng: np.random.Generator | None = None,
+    mode: str = "no-fano",
+):
+    if edep_hits.particle.ndim == 1:
+        msg = "the pe processors only support already reshaped output"
+        raise ValueError(msg)
+
+    rng = np.random.default_rng() if rng is None else rng
+    output_list = _iterate_stepwise_depositions_scintillate(edep_hits, rng, scint_mat_params, mode)
+
+    # convert the numba result back into an awkward array.
+    builder = ak.ArrayBuilder()
+    for r in output_list:
+        with builder.list():
+            builder.extend(r)
+
+    return builder.snapshot()
+
+
+_pdg_func = numba_pdgid_funcs()
+
+
+@njit
+def _pdgid_to_particle(pdgid: int) -> sc.ParticleIndex:
+    abs_pdgid = abs(pdgid)
+    if abs_pdgid == 1000020040:
+        return sc.PARTICLE_INDEX_ALPHA
+    if abs_pdgid == 1000010020:
+        return sc.PARTICLE_INDEX_DEUTERON
+    if abs_pdgid == 1000010030:
+        return sc.PARTICLE_INDEX_TRITON
+    if _pdg_func.is_nucleus(pdgid):
+        return sc.PARTICLE_INDEX_ION
+    return sc.PARTICLE_INDEX_ELECTRON
+
+
+__counts_per_bin_key_type = numba.types.UniTuple(numba.types.int64, 3)
+
+
+# - run with NUMBA_FULL_TRACEBACKS=1 NUMBA_BOUNDSCHECK=1 for testing/checking
+# - cache=True does not work with outer prange, i.e. loading the cached file fails (numba bug?)
+# - the output dictionary is not threadsafe, so parallel=True is not working with it.
+@njit(parallel=False, nogil=True, cache=True)
+def _iterate_stepwise_depositions_pois(
+    edep_hits,
+    rng,
+    detidx: int,
+    map_scaling: float,
+    map_scaling_sigma: float,
+    optmap_edges,
+    optmap_weights,
+    scint_mat_params: sc.ComputedScintParams,
+):
+    pdgid_map = {}
+    oob = ib = ph_cnt = ph_det2 = det_no_stats = 0  # for statistics
+    output_list = []
+
+    for rowid in range(len(edep_hits)):  # iterate hits
+        hit = edep_hits[rowid]
+        hit_output = []
+
+        map_scaling_evt = map_scaling
+        if map_scaling_sigma > 0:
+            map_scaling_evt = rng.normal(loc=map_scaling, scale=map_scaling_sigma)
+
+        assert len(hit.particle) == len(hit.num_scint_ph)
+        # iterate steps inside the hit
+        for si in range(len(hit.particle)):
+            loc = np.array([hit.xloc[si], hit.yloc[si], hit.zloc[si]])
+            # coordinates -> bins of the optical map.
+            bins = np.empty(3, dtype=np.int64)
+            for j in range(3):
+                bins[j] = np.digitize(loc[j], optmap_edges[j])
+                # normalize all out-of-bounds bins just to one end.
+                if bins[j] == optmap_edges[j].shape[0]:
+                    bins[j] = 0
+
+            # note: subtract 1 from bins, to account for np.digitize output.
+            cur_bins = (bins[0] - 1, bins[1] - 1, bins[2] - 1)
+            if cur_bins[0] == -1 or cur_bins[1] == -1 or cur_bins[2] == -1:
+                oob += 1
+                continue  # out-of-bounds of optmap
+            ib += 1
+
+            # get probabilities from map.
+            detp = optmap_weights[detidx, cur_bins[0], cur_bins[1], cur_bins[2]] * map_scaling_evt
+            if detp < 0.0:
+                det_no_stats += 1
+                continue
+
+            pois_cnt = rng.poisson(lam=hit.num_scint_ph[si] * detp)
+            ph_cnt += hit.num_scint_ph[si]
+            ph_det2 += pois_cnt
+
+            # get the particle information.
+            particle = hit.particle[si]
+            if particle not in pdgid_map:
+                pdgid_map[particle] = (_pdgid_to_particle(particle), _pdg_func.charge(particle))
+            part, _charge = pdgid_map[particle]
+
+            # get time spectrum.
+            # note: we assume "immediate" propagation after scintillation.
+            scint_times = sc.scintillate_times(scint_mat_params, part, pois_cnt, rng) + hit.time[si]
+
+            hit_output.append(scint_times)
+
+        output_list.append(hit_output)
+
+    stats = {
+        "oob": oob,
+        "ib": ib,
+        "vuv_primary": ph_cnt,
+        "hits": ph_det2,
+        "det_no_stats": det_no_stats,
+    }
+    return stats, output_list
+
+
+# - run with NUMBA_FULL_TRACEBACKS=1 NUMBA_BOUNDSCHECK=1 for testing/checking
+# - cache=True does not work with outer prange, i.e. loading the cached file fails (numba bug?)
+@njit(parallel=False, nogil=True, cache=True)
+def _iterate_stepwise_depositions_scintillate(
+    edep_hits, rng, scint_mat_params: sc.ComputedScintParams, mode: str
+):
+    pdgid_map = {}
+    output_list = []
+
+    for rowid in range(len(edep_hits)):  # iterate hits
+        hit = edep_hits[rowid]
+        hit_output = []
+
+        # iterate steps inside the hit
+        for si in range(len(hit.particle)):
+            # get the particle information.
+            particle = hit.particle[si]
+            if particle not in pdgid_map:
+                pdgid_map[particle] = (_pdgid_to_particle(particle), _pdg_func.charge(particle))
+            part, _charge = pdgid_map[particle]
+
+            # do the scintillation.
+            num_phot = sc.scintillate_numphot(
+                scint_mat_params,
+                part,
+                hit.edep[si],
+                rng,
+                emission_term_model=("poisson" if mode == "no-fano" else "normal_fano"),
+            )
+            hit_output.append(num_phot)
+
+        assert len(hit_output) == len(hit.particle)
+        output_list.append(hit_output)
+
+    return output_list
+
+
+def _get_scint_params(material: str):
+    if material == "lar":
+        return sc.precompute_scintillation_params(
+            lar.lar_scintillation_params(),
+            lar.lar_lifetimes().as_tuple(),
+        )
+    if material == "pen":
+        return sc.precompute_scintillation_params(
+            pen.pen_scintillation_params(),
+            (pen.pen_scint_timeconstant(),),
+        )
+    if material == "fiber":
+        return sc.precompute_scintillation_params(
+            fibers.fiber_core_scintillation_params(),
+            (fibers.fiber_wls_timeconstant(),),
+        )
+    if isinstance(material, str):
+        msg = f"unknown material {material} for scintillation"
+        raise ValueError(msg)
+    return sc.precompute_scintillation_params(*material)