Source code for pyfli.simulator.main_common

# pyfli/simulator/main_common.py

"""
Shared engine-wrapping pipelines for the continuous (ICCD-style) and discrete
(TCSPC-style) simulator pairs.

``combined/main_factory.py`` (:class:`~pyfli.simulator.combined.main_factory.MacroSimulator`,
:class:`~pyfli.simulator.combined.main_factory.TCSPCSimulator`, wrapping
:class:`~pyfli.simulator.combined.simulator_engine.FLIEngine`) and
``separate/main_factory_gen.py`` (:class:`~pyfli.simulator.separate.main_factory_gen.ContinuousSimulator`,
:class:`~pyfli.simulator.separate.main_factory_gen.PhotonCountSimulator`, wrapping
:class:`~pyfli.simulator.separate.model_simulator.FLIModelSimulator`) implement the identical
noise/scaling pipeline; they differ only in which engine class they wrap, the names of
a few methods on that engine, and whether the "mono" branch trims the returned maps
dict. Subclasses declare those differences as class attributes; this module owns the
actual pipeline math so it is defined exactly once.
"""

from typing import Any

import numpy as np

from .distributions import ParameterSampler
from .noise_models import NoiseEngine


def _build_maps(
    p: Any,
    photon_count: Any,
    mono_only_maps: bool,
    jitter_bins: float,
    dt: float,
    v_shift: float = 0.0,
) -> dict[Any, Any]:
    """
    Build the parameter-maps dict, optionally trimmed for mono pixels, in the solver's
    convention: ``photon_count_map`` is ``S``, ``v_shift_map`` the mean background per bin,
    ``h_shift_map`` the jitter delay in ns (``h_shift_jit_map`` is the same delay in bins).
    """
    shifts = {
        "h_shift_jit_map": jitter_bins,
        "h_shift_map": jitter_bins * dt,
        "v_shift_map": v_shift,
    }
    if mono_only_maps and p["mono"]:
        return {
            "tau_map": p["tau"],
            "photon_count_map": photon_count,
            "mono_map": p["mono"],
            **shifts,
        }
    return {
        "tau1_map": p["tau1"],
        "tau2_map": p["tau2"],
        "alpha1_map": p["f"],
        "A1_map": p["A1"],
        "A2_map": p["A2"],
        "fret_efficiency_map": p["E"],
        "tau_mean_map": p["tau1"] * p["f"] + p["tau2"] * (1 - p["f"]),
        "photon_count_map": photon_count,
        "mono_map": p["mono"],
        **shifts,
    }


[docs] class BaseContinuousSimulator: """ Shared ``__call__`` pipeline for MacroSimulator/ContinuousSimulator: samples lifetime parameters, scales the expected decay (the engine's :meth:`~pyfli.simulator.sim_engine_common.BaseFLIEngine.expected_decay`, i.e. the solver's forward model, circular for ``pileup_mode="wrap"``) to a Beta-sampled peak intensity, then applies, in the order of a camera, QE, jitter, shot noise on the signal, dark counts, read noise, rounding and clipping. ``fit_map`` is the expectation of the result before read noise, rounding and clipping (signal + dark counts). Subclasses set the following class attributes: engine_cls : type The engine class to wrap (``FLIEngine`` / ``FLIModelSimulator``). sample_params_name : str Name of the engine method that samples lifetime parameters. analytical_decay_name : str Name of the engine method that returns the clean un-convolved decay (the pipeline itself uses the engine's ``expected_decay``). mono_only_maps : bool Whether ``p["mono"]`` trims the returned maps dict down to ``{tau_map, photon_count_map, mono_map}`` (``True``, as in ``ContinuousSimulator``) or the full map set is always returned regardless of mono status (``False``, as in ``MacroSimulator``). """ engine_cls: type sample_params_name: str analytical_decay_name: str mono_only_maps: bool = False def __init__( self, irf_data: np.ndarray, sensor_type: str = "continuous", **cfg: Any ) -> None: # Toggles self.use_jitter = cfg.get("jitter", True) self.use_dcr = cfg.get("dcr_on", True) self.use_poisson = cfg.get("poisson", True) self.use_qe = cfg.get("qe_on", True) self.use_read_noise = cfg.get("read_noise_on", True) self.use_rounding = cfg.get("round_on", True) self.use_clipping = cfg.get("clip_on", True) self.sensor_type = sensor_type.upper() self.engine = self.engine_cls(irf_data, **cfg) def __call__(self) -> dict[Any, Any]: """ Run the instance as a callable. Returns ------- dict[Any, Any] Dictionary containing the data produced by call. """ p = getattr(self.engine, self.sample_params_name)() # 1. Determine target intensity (A) based on bit-depth alpha_pc, beta_pc = self.engine.params_cfg["pc"] bit_depth = self.engine.params_cfg["bit"] max_adc_val = (2**bit_depth) - 1 A = ParameterSampler.beta_sample(alpha_pc, beta_pc, scale=max_adc_val) unit = self.engine.expected_decay(p) S = A / unit.max() if unit.max() > 0 else 0.0 if self.use_qe: S = S * ParameterSampler.sample_qe(self.sensor_type) jitter = self.engine.sample_jitter() if self.use_jitter else 0.0 signal = self.engine.expected_decay(p, S, jitter) obs = NoiseEngine.apply_poisson(signal) if self.use_poisson else signal.copy() background = 0.0 if self.use_dcr: background = self.engine.params_cfg["dcr"] * (bit_depth / 8.0) obs = NoiseEngine.apply_dcr(obs, background) if self.use_read_noise and self.sensor_type == "CONTINUOUS": hw = ParameterSampler.sample_noise_params(bit_depth, self.sensor_type) obs = NoiseEngine.apply_read_noise(obs, hw["read_sigma"]) if self.use_rounding: obs = np.round(obs) if self.use_clipping: obs = np.clip(obs, 0, max_adc_val) fit_map = signal + background maps = _build_maps( p, S, self.mono_only_maps, jitter, self.engine.dt, background ) return { "raw_data": {"decay": obs, "irf": self.engine.irf}, "results": { "maps": maps, "TR_maps": {"fit_map": fit_map, "residual_map": obs - fit_map}, }, }
[docs] class BaseDiscreteSimulator: """ Shared ``__call__`` pipeline for TCSPCSimulator/PhotonCountSimulator: samples lifetime parameters, runs a TCSPC photon-by-photon histogram (with the timing jitter applied to the photons), and adds dark counts and counter clipping. ``fit_map`` is the exact expectation of the histogram, the engine's :meth:`~pyfli.simulator.sim_engine_common.BaseFLIEngine.expected_decay` (the solver's forward model, circular for ``pileup_mode="wrap"``) plus the dark counts. Subclasses set the following class attributes: engine_cls : type The engine class to wrap (``FLIEngine`` / ``FLIModelSimulator``). sample_params_name : str Name of the engine method that samples lifetime parameters. analytical_decay_name : str Name of the engine method that returns the clean un-convolved decay (the pipeline itself uses the engine's ``expected_decay``). simulate_tcspc_name : str Name of the engine method that runs the TCSPC photon histogram. mono_only_maps : bool As in :class:`BaseContinuousSimulator`. """ engine_cls: type sample_params_name: str analytical_decay_name: str simulate_tcspc_name: str mono_only_maps: bool = False def __init__( self, irf_data: np.ndarray, sensor_type: str = "discrete", **cfg: Any ) -> None: self.use_jitter = cfg.get("jitter", True) self.use_dcr = cfg.get("dcr_on", True) self.use_qe = cfg.get("qe_on", False) # TCSPC is inherently integer-based, but clipping simulates counter overflow self.use_clipping = cfg.get("clip_on", True) self.sensor_type = sensor_type.upper() # TCSPC counters are 16-bit by default cfg.setdefault("bit", 16) self.engine = self.engine_cls(irf_data, **cfg) def __call__(self) -> dict[Any, Any]: """ Run the instance as a callable. Returns ------- dict[Any, Any] Dictionary containing the data produced by call. """ p = getattr(self.engine, self.sample_params_name)() low_cycles, high_cycles = self.engine.params_cfg["cycles"] alpha_cyc, beta_cyc = self.engine.params_cfg["pc"] n_cycles = round( ParameterSampler.sample_beta( alpha_cyc, beta_cyc, scale=high_cycles - low_cycles, offset=low_cycles, ) ) mu_per_cycle = 0.01 bit_depth = self.engine.params_cfg["bit"] max_bin_count = (2**bit_depth) - 1 effective_mu = ( mu_per_cycle * ParameterSampler.sample_qe(self.sensor_type) if self.use_qe else mu_per_cycle ) jitter = self.engine.sample_jitter() if self.use_jitter else 0.0 obs = getattr(self.engine, self.simulate_tcspc_name)( p, n_cycles, effective_mu, jitter ) total_photons_expected = effective_mu * n_cycles background = 0.0 if self.use_dcr: background = self.engine.params_cfg["dcr"] obs = NoiseEngine.apply_dcr(obs, background) fit = self.engine.expected_decay(p, total_photons_expected, jitter, background) if self.use_clipping: obs = np.clip(obs, 0, max_bin_count) maps = _build_maps( p, total_photons_expected, self.mono_only_maps, jitter, self.engine.dt, background, ) return { "raw_data": {"decay": obs, "irf": self.engine.irf}, "results": { "maps": maps, "TR_maps": {"fit_map": fit, "residual_map": obs - fit}, }, }