pyfli.simulator.sim_engine_common#

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 pyfli.simulator and is part of PyFLI synthetic FLI/FLIM data generation, hardware noise modeling, calibration, and validation tools.

FLIEngine and 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. 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 model_numpy()), and the IRF-convolution/pile-up/binning tail of the TCSPC simulation — so that logic is defined exactly once.

Functions

model_spec(p)

(model_type, lifetime parameters) of a sampled pixel, in the solver's order.

Classes

BaseFLIEngine(irf_full[, laser_feq, seed])

Shared setup and helpers for FLI sampling engines.

model_spec(p)[source]#

(model_type, lifetime parameters) of a sampled pixel, in the solver’s order.

Parameters:

p (dict[str, Any])

Return type:

tuple[str, tuple[float, …]]

class BaseFLIEngine(irf_full, laser_feq=80, seed=None)[source]#

Bases: object

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 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.

property shift_method: str#

Solver shift_method matching pileup_mode ("wrap" is the periodic steady state).

property excitation: str#

Excitation within each IRF gate (params_cfg["excitation"], default "bin_start").

property gate_width: float | None#

Detection-gate width in ns (params_cfg["gate_width"], default the bin width).

sample_jitter(max_bins=2)[source]#

Timing jitter in bins: an integer roll for "circular", continuous for "zero_pad".

Parameters:

max_bins (int)

Return type:

float

expected_decay(p, photon_count=1.0, jitter_bins=0.0, v_shift=0.0)[source]#

Expected counts per gate: the solver’s forward model at the pixel’s true parameters, delayed by jitter_bins (h_shift = jitter_bins * dt).

Parameters:
Return type:

ndarray

analytical_decay(p)[source]#

Noise-free photon fraction per gate before the IRF (onset 0, periodic for "wrap").

Parameters:

p (dict[str, Any])

Return type:

ndarray