Source code for pyfli.simulator.sim_engine_common

# pyfli/simulator/sim_engine_common.py

"""
Shared IRF/timing setup, cycles-range validation, and TCSPC photon-binning logic
for the sampling engines wrapped by the "combined" and "separate" simulator pairs.

This module belongs to :mod:`pyfli.simulator` and is part of PyFLI synthetic FLI/FLIM
data generation, hardware noise modeling, calibration, and validation tools.

:class:`~pyfli.simulator.combined.simulator_engine.FLIEngine` and
:class:`~pyfli.simulator.separate.model_simulator.FLIModelSimulator` both wrap a
single IRF into per-pixel decay/parameter sampling and TCSPC photon-histogram
simulation; they differ in how lifetime parameters are sampled and how many
exponential components the analytical decay supports. :class:`BaseFLIEngine`
owns the parts that are identical between them — IRF validation, timing setup,
``n_cycles`` range normalization, photon-to-amplitude fraction conversion, the
expected decay (the solver's :func:`~pyfli.cm_funcs.forward_model.model_numpy`), and the
IRF-convolution/pile-up/binning tail of the TCSPC simulation — so that logic is
defined exactly once.
"""

from typing import Any

import numpy as np

from pyfli.cm_funcs.forward_model import (
    decay_kernel,
    model_numpy,
    validate_excitation,
    validate_gate_width,
)

from .noise_models import NoiseEngine
from .sim_helper import irf_picker


[docs] def model_spec(p: dict[str, Any]) -> tuple[str, tuple[float, ...]]: """``(model_type, lifetime parameters)`` of a sampled pixel, in the solver's order.""" if p.get("mono", False) and "tau" in p: return "mono-exponential", (p["tau"],) return "bi-exponential", (p["f"], p["tau1"], p["tau2"])
[docs] class BaseFLIEngine: """ Shared setup and helpers for FLI sampling engines. The config keys ``excitation`` (``"bin_start"`` default, or ``"uniform"`` IRF photons spread over their bin) and ``gate_width`` (ns, gated continuous sensors only) select the forward-model options of :func:`pyfli.cm_funcs.forward_model.model_numpy` for both the photons and the expected decay. Parameters ---------- irf_full : np.ndarray Full instrument response function sampled over the decay window. laser_feq : int Laser repetition frequency used by the simulation. seed : int | None Seed for reproducible random sampling. """ def __init__( self, irf_full: np.ndarray, laser_feq: int = 80, seed: int | None = None, ) -> None: irf, _ = irf_picker(irf_full) # Timing and Normalization irf_sum = irf.sum() if not np.isfinite(irf_sum) or irf_sum <= 0: raise ValueError( f"Invalid IRF: sum={irf_sum}. IRF must be non-negative and non-zero." ) self.irf = irf / irf_sum self.rng = np.random.default_rng(seed) self.laser_period = 1000 / laser_feq # N bins each of width dt covering [0, laser_period); endpoint-exclusive self.dt = self.laser_period / len(self.irf) self.t = np.arange(len(self.irf)) * self.dt @staticmethod def _normalize_cycles_range(n_cycles: int | tuple[int, int]) -> tuple[int, int]: """ Normalizes ``n_cycles`` into a validated ``(low, high)`` range. A bare int is the upper bound, with the lower bound fixed at 1000. A ``(low, high)`` tuple sets both bounds explicitly. Both bounds must be >= 1000, and ``high`` must be >= ``low``. """ if isinstance(n_cycles, (int, np.integer)): cycles_range = (1000, int(n_cycles)) else: low_cycles, high_cycles = n_cycles cycles_range = (int(low_cycles), int(high_cycles)) if cycles_range[0] < 1000 or cycles_range[1] < 1000: raise ValueError(f"n_cycles bounds {cycles_range} must both be >= 1000.") if cycles_range[1] < cycles_range[0]: raise ValueError( f"n_cycles upper bound ({cycles_range[1]}) must be >= " f"lower bound ({cycles_range[0]})." ) return cycles_range @staticmethod def _amplitude_fractions(f: float, tau1: float, tau2: float) -> tuple[float, float]: """Pre-exponential amplitude fractions ``(A1, A2)`` of the photon fractions ``(f, 1 - f)``.""" w1 = f / max(tau1, 1e-12) w2 = (1.0 - f) / max(tau2, 1e-12) total = w1 + w2 return (w1 / total, w2 / total) if total > 0 else (f, 1.0 - f) @property def shift_method(self) -> str: """Solver ``shift_method`` matching ``pileup_mode`` (``"wrap"`` is the periodic steady state).""" wrap = self.params_cfg.get("pileup_mode", "wrap") == "wrap" return "circular" if wrap else "zero_pad" @property def excitation(self) -> str: """Excitation within each IRF gate (``params_cfg["excitation"]``, default ``"bin_start"``).""" return validate_excitation(self.params_cfg.get("excitation", "bin_start")) @property def gate_width(self) -> float | None: """Detection-gate width in ns (``params_cfg["gate_width"]``, default the bin width).""" return validate_gate_width(self.params_cfg.get("gate_width"))
[docs] def sample_jitter(self, max_bins: int = 2) -> float: """Timing jitter in bins: an integer roll for ``"circular"``, continuous for ``"zero_pad"``.""" if not max_bins: return 0.0 if self.shift_method == "circular": return float(np.random.randint(-max_bins, max_bins + 1)) return float(np.random.uniform(-max_bins, max_bins))
[docs] def expected_decay( self, p: dict[str, Any], photon_count: float = 1.0, jitter_bins: float = 0.0, v_shift: float = 0.0, ) -> np.ndarray: """Expected counts per gate: the solver's forward model at the pixel's true parameters, delayed by `jitter_bins` (``h_shift = jitter_bins * dt``).""" model_type, lifetimes = model_spec(p) options = (self.excitation, self.gate_width) if self.shift_method == "circular": params = [photon_count, *lifetimes, v_shift, 0.0] base = model_numpy( self.t, self.irf, params, model_type, "circular", *options ) return np.roll(base, int(jitter_bins)) params = [photon_count, *lifetimes, v_shift, jitter_bins * self.dt] return model_numpy(self.t, self.irf, params, model_type, "zero_pad", *options)
[docs] def analytical_decay(self, p: dict[str, Any]) -> np.ndarray: """Noise-free photon fraction per gate before the IRF (onset 0, periodic for ``"wrap"``).""" model_type, lifetimes = model_spec(p) kernel, _ = decay_kernel( self.t, (1.0, *lifetimes, 0.0), model_type, 0.0, self.shift_method, self.excitation, self.gate_width, ) return kernel
def _bin_tcspc_photons(self, times: np.ndarray, jitter_bins: float = 0.0) -> Any: """ Delays photon emission times by an IRF draw (inverse-transform sampling of the IRF's CDF), applies the pile-up/repetitive-excitation window filter, and bins the result into a TCSPC histogram. The jitter delay is a histogram roll by `jitter_bins` for ``"wrap"`` and ``jitter_bins * dt`` ns per photon for ``"truncate"``. With ``excitation="uniform"`` each IRF photon is placed uniformly inside its bin. """ if self.gate_width is not None: raise ValueError( "gate_width applies to gated detection, not TCSPC photons." ) total_photons = len(times) irf_cdf = np.cumsum(self.irf) irf_cdf[-1] = 1.0 irf_bins = np.searchsorted(irf_cdf, self.rng.random(total_photons)) if self.excitation == "uniform": irf_shifts = (irf_bins + self.rng.random(total_photons)) * self.dt else: irf_shifts = irf_bins * self.dt circular = self.shift_method == "circular" delay = 0.0 if circular else jitter_bins * self.dt pileup_mode = self.params_cfg.get("pileup_mode", "wrap") arrival_times = NoiseEngine.tcspc_pileup_filter( times + irf_shifts + delay, self.laser_period, mode=pileup_mode ) bins = (arrival_times / self.dt).astype(np.int32) hist = np.bincount(bins[bins < len(self.t)], minlength=len(self.t)) if circular: hist = np.roll(hist, int(jitter_bins)) return hist.astype(np.float64)