FastPedestal + optimizations in the cluster finder (#341)

Optimized pedestal tracking with FastPedestal and performance improvements to the cluster finder. 
- ~2x faster hitting 14k FPS on benchmark dataset on 16 core threadripper pro


**Changes**
- No bounds check on interior of frame. (only within half of a cluster)
(~15% improvement)
- Cache threshold (std*n_rms) Biggest improvement comes from not
computing std for each access
- Cache pedestal subtracted frame
- Switched to FastPedestal which assumes we reached steady state

**Things tried but rejected:**
- Always store cluster values, commit on val==max (~15% drop in frame
rate)

**Options**
- using 16 bit clusters and 16 bit pedestal. (slows down the single
threaded case but allow us to reach 12k with multi threading)

**Other notes on performance**
- Passing in memory frames from python and doing nothing: 0.8us/frame
- Passing + pedestal subtraction: 28us/frame
- Passing + pedestal + cluster finding (no store): 652us/frame
- Passing + pedestal + cluster finding: 886 us/frame

python/aare/Cluster.py

@@ -1,6 +1,6 @@
 from . import _aare 
 import numpy as np
-from .ClusterFinder import _type_to_char
+from .factory import _type_to_char
 
 
 def Cluster(x : int, y : int, data, cluster_size=(3,3), dtype = np.int32):
@@ -21,4 +21,4 @@ def Cluster(x : int, y : int, data, cluster_size=(3,3), dtype = np.int32):
     except AttributeError:
         raise ValueError(f"Unsupported combination of type and cluster size: {dtype}/{cluster_size} when requesting {class_name}")
    
-    return cls(x, y, data) 
+    return cls(x, y, data)

python/aare/ClusterFinder.py

@@ -1,21 +1,10 @@
 # SPDX-License-Identifier: MPL-2.0
 from . import _aare
 import numpy as np
+from .factory import _type_to_char
 
 _supported_cluster_sizes = [(2,2), (3,3), (5,5), (7,7), (9,9),]
 
-def _type_to_char(dtype):
-    if dtype == np.int32:
-        return 'i'
-    elif dtype == np.float32:
-        return 'f'
-    elif dtype == np.float64:
-        return 'd'
-    elif dtype == np.int16:
-        return 'i16'
-    else:
-        raise ValueError(f"Unsupported dtype: {dtype}. Only np.int32, np.float32, and np.float64 are supported.")
-
 def _get_class(name, cluster_size, dtype):
     """
     Helper function to get the class based on the name, cluster size, and dtype.

python/aare/FastPedestal.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MPL-2.0
+
+import numpy as np
+
+from .factory import _get_typed_class
+
+
+def _get_fast_pedestal_class(dtype):
+    return _get_typed_class("FastPedestal", dtype)
+
+
+def FastPedestal(rows, cols, n_samples=1000, dtype=np.float64):
+    """Create an empty per-pixel running pedestal.
+
+    This factory hides the dtype suffix used by the templated C++ bindings.
+    Call ``add_init_frame()`` exactly ``n_samples`` times before using the
+    statistics or calling ``push_ema()``. Subsequent frames have weight
+    ``1 / n_samples`` in the running mean and population variance.
+
+    Args:
+        rows: Number of image rows.
+        cols: Number of image columns.
+        n_samples: Initialization frame count and steady-state update-weight
+            denominator.
+        dtype: Output dtype for the mean, variance, and standard deviation.
+            Supported values are ``np.float64``, ``np.float32``, and
+            ``np.int16``.
+    """
+    cls = _get_fast_pedestal_class(dtype)
+    return cls(rows, cols, n_samples)
+
+
+def from_file(filename, n_samples=1000, skip_first=0, dtype=np.float64):
+    """Create a FastPedestal from frames in a file.
+
+    After ignoring ``skip_first`` frames, the next ``n_samples`` frames
+    initialize the pedestal. Every remaining frame is then applied as a
+    steady-state update. Input frames are read as uint16 data.
+
+    Args:
+        filename: Input image file.
+        n_samples: Number of frames used for initialization.
+        skip_first: Number of leading frames to ignore.
+        dtype: Output dtype for the mean, variance, and standard deviation.
+
+    Raises:
+        RuntimeError: If fewer than ``n_samples`` frames remain after
+            ``skip_first`` or ``n_samples`` is zero.
+    """
+    cls = _get_fast_pedestal_class(dtype)
+    return cls.from_file(
+        filename, n_samples=n_samples, skip_first=skip_first
+    )
+
+
+FastPedestal.from_file = from_file

python/aare/__init__.py

@@ -5,6 +5,16 @@ from . import _aare
 from . import transform
 from . import experimental
 
+from ._aare import (
+    FastPedestal_d,
+    FastPedestal_f,
+    FastPedestal_i16,
+    Pedestal_d,
+    Pedestal_f,
+    Pedestal_i16,
+    ClusterFinder_Cluster3x3i,
+    VarClusterFinder,
+)
 from ._aare import (
     File,
     JungfrauDataFile,
@@ -20,6 +30,7 @@ from ._aare import corner
 # from ._aare import ClusterFinderMT, ClusterCollector, ClusterFileSink, ClusterVector_i
 
 from ._version import __version__
+from .FastPedestal import FastPedestal
 from .ClusterFinder import ClusterFinder, ClusterCollector, ClusterFinderMT, ClusterFileSink, ClusterFile
 from .ClusterVector import ClusterVector
 from .Cluster import Cluster

python/aare/factory.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MPL-2.0
+
+import numpy as np
+
+from . import _aare
+
+
+_TYPE_TO_CHAR = {
+    np.dtype(np.int32): "i",
+    np.dtype(np.float32): "f",
+    np.dtype(np.float64): "d",
+    np.dtype(np.int16): "i16",
+}
+
+
+def _type_to_char(dtype):
+    """Return the suffix used by bindings instantiated for ``dtype``."""
+    try:
+        return _TYPE_TO_CHAR[np.dtype(dtype)]
+    except (KeyError, TypeError):
+        supported = ", ".join(str(dtype) for dtype in _TYPE_TO_CHAR)
+        raise ValueError(
+            f"Unsupported dtype: {dtype}. Supported dtypes are {supported}."
+        ) from None
+
+
+def _get_typed_class(name, dtype):
+    """Return a bound class named ``<name>_<dtype suffix>``."""
+    class_name = f"{name}_{_type_to_char(dtype)}"
+    try:
+        return getattr(_aare, class_name)
+    except AttributeError:
+        raise ValueError(
+            f"Unsupported dtype for {name}: {dtype} "
+            f"(binding {class_name} is not available)."
+        ) from None