pyfli.solver.forward_model#

Evaluate exponential decay kernels and convolved NumPy forward models.

This module belongs to pyfli.solver and is part of PyFLI least-squares, maximum- likelihood, CPU, GPU, binned, and global FLI fitting routines. Public API includes functions gate_integrated_kernel(), decay_kernel() and model_numpy().

The decay is modelled as it is measured: photon counts per time gate. For a decay with onset h_shift (ns), the expected counts in the gate [a, b) are the integral of the normalized exponential over that gate,

mono: S * [exp(-(max(a, h) - h) / tau) - exp(-(max(b, h) - h) / tau)] bi: S * a1 * […tau1…] + S * (1 - a1) * […tau2…]

which is zero before the onset, continuous (piecewise smooth) in h_shift so a sub-gate delay can be fitted with gradient-based optimizers, and sums to S over all gates – S is the total number of photons of the decay (photon_count_map).

Functions

_gate_integral(a, b, tau, h_shift)

Fraction of a unit-area exponential with onset h_shift inside [a, b).

_gate_width(t)

decay_kernel(t, params, model_type[, h_shift])

Return (kernel, v_shift) on the gates starting at t.

gate_integrated_kernel(gate_start, dt, ...)

Expected counts per gate of the un-convolved decay, integrated over each gate.

model_numpy(t, irf, params, model_type)

Evaluate the NumPy FLI forward model: the gate-integrated decay (onset h_shift) convolved with the normalized IRF, plus the constant v_shift.

negative_lag_gates(h_shift, dt)

Number of gates before t = 0 the kernel must cover so that a decay with onset h_shift < 0 (earlier than the IRF) is shifted, not truncated, by the IRF convolution.
gate_integrated_kernel(gate_start, dt, params, model_type, h_shift=0.0)[source]#

Expected counts per gate of the un-convolved decay, integrated over each gate.

Parameters:

  • gate_start (np.ndarray) – Start time (ns) of every gate; gate k covers [gate_start[k], gate_start[k] + dt). Any shape that broadcasts with the parameters (e.g. (T,), or (1, 1, T) against (H, W, 1) parameter maps).

  • dt (float) – Gate width in ns.

  • params (Any) – (S, tau, v_shift) for "mono-exponential" or (S, a1, tau1, tau2, v_shift) for "bi-exponential"; scalars or arrays broadcastable against gate_start.

  • model_type (str) – "mono-exponential" or "bi-exponential".

  • h_shift (Any) – Decay onset in ns (scalar or broadcastable array).

Returns:

(kernel, v_shift): counts per gate (summing to S over all gates) and the constant offset, which is added after the IRF convolution.

Return type:

tuple[np.ndarray, Any]

decay_kernel(t, params, model_type, h_shift=0.0)[source]#

Return (kernel, v_shift) on the gates starting at t.

The kernel is the gate-integrated decay of gate_integrated_kernel() (zero before the onset h_shift, in ns, and summing to S). Gates are [t_k, t_k + dt) with dt = t[1] - t[0].

Parameters:
Return type:

tuple

negative_lag_gates(h_shift, dt)[source]#

Number of gates before t = 0 the kernel must cover so that a decay with onset h_shift < 0 (earlier than the IRF) is shifted, not truncated, by the IRF convolution. Zero for h_shift >= 0.

Parameters:
Return type:

int

model_numpy(t, irf, params, model_type)[source]#

Evaluate the NumPy FLI forward model: the gate-integrated decay (onset h_shift) convolved with the normalized IRF, plus the constant v_shift.

Parameters:

  • t (np.ndarray) – Gate start times (ns), uniformly spaced.

  • irf (np.ndarray) – Instrument response function aligned with the decay signal.

  • params (Any) – [S, tau, v_shift, h_shift] (mono) or [S, a1, tau1, tau2, v_shift, h_shift] (bi); S is the total photon count of the decay.

  • model_type (str) – FLI model family, such as mono- or bi-exponential.

Returns:

Expected counts per gate, same length as t.

Return type:

np.ndarray