"""
Evaluate exponential decay kernels and convolved NumPy forward models.
This module belongs to :mod:`pyfli.cm_funcs` and is the single forward model shared by the
PyFLI solver, reconstruction, Laguerre, simulator and phasor packages. Public API includes
functions :func:`gate_integrated_kernel`, :func:`decay_kernel` and
:func:`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``).
``shift_method`` selects the convolution: ``"zero_pad"`` (default) convolves linearly,
with the decay zero before the onset and after the window; ``"circular"`` is the
steady-state periodic model for a window equal to one laser period (TCSPC/SPAD), where
earlier pulses' tails wrap around
(:func:`pyfli.reconstruction.common_reconstruct.periodic_gate_integral` convolved by
:func:`pyfli.reconstruction.common_reconstruct.circular_convolve`).
``excitation`` places the excitation of each IRF gate: ``"bin_start"`` (default) at the
gate start, as pyfli's simulators do; ``"uniform"`` spread uniformly over the gate
``[h, h + dt)``, as in a real instrument, i.e. the gate integral averaged over the onset.
``gate_width`` (default ``dt``) is the width of the detection gates that start every
``dt``; set it only when the IRF was not itself recorded through the same gate (a gated
IRF already contains the gate), e.g. for overlapping ICCD gates with a laser-pulse IRF.
"""
from typing import Any
import numpy as np
from pyfli.reconstruction.common_reconstruct import (
circular_convolve,
periodic_gate_integral,
)
SHIFT_METHODS = ("zero_pad", "circular")
MODEL_TYPES = ("mono-exponential", "bi-exponential")
EXCITATIONS = ("bin_start", "uniform")
[docs]
def validate_model_type(model_type: Any) -> str:
"""Check `model_type` is one of :data:`MODEL_TYPES` (catches e.g. a ``p0`` passed in its place)."""
if not isinstance(model_type, str) or model_type not in MODEL_TYPES:
raise ValueError(f"model_type must be one of {MODEL_TYPES}, got {model_type!r}")
return model_type
_EPS = 1e-8
[docs]
def validate_excitation(excitation: Any) -> str:
"""Check `excitation` is one of :data:`EXCITATIONS`."""
if excitation not in EXCITATIONS:
raise ValueError(f"excitation must be one of {EXCITATIONS}, got {excitation!r}")
return excitation
[docs]
def validate_gate_width(gate_width: Any) -> float | None:
"""Check `gate_width` is ``None`` or a positive finite width in ns."""
if gate_width is None:
return None
width = float(gate_width)
if not np.isfinite(width) or width <= 0:
raise ValueError(f"gate_width must be positive and finite, got {gate_width!r}")
return width
def _xp(x: Any) -> Any:
if type(x).__module__.split(".")[0] == "torch":
import torch
return torch
return np
def _positive(v: Any, xp: Any) -> Any:
return xp.clamp(v, min=0.0) if xp is not np else np.maximum(v, 0.0)
def _uniform_gate_integral(a: Any, b: Any, tau: Any, h_shift: Any, dt: float) -> Any:
"""
Fraction of a unit-area exponential inside ``[a, b)`` with its onset uniform over
``[h_shift, h_shift + dt)``: with ``Q(v) = v+ + tau expm1(-v+ / tau)``,
``[Q(b') - Q(b' - dt) - Q(a') + Q(a' - dt)] / dt`` (``x' = x - h_shift``); for
``a' >= dt`` the closed form ``tau / dt (1 - e^{-dt/tau}) (e^{-(a'-dt)/tau} - e^{-(b'-dt)/tau})``.
"""
xp = _xp(tau)
a1 = a - h_shift
b1 = b - h_shift
def q(v: Any) -> Any:
vp = _positive(v, xp)
return vp + tau * xp.expm1(-vp / tau)
overlap = (q(b1) - q(b1 - dt) - q(a1) + q(a1 - dt)) / dt
x = _positive(a1 - dt, xp)
y = _positive(b1 - dt, xp)
tail = (tau / dt) * (-xp.expm1(-dt / tau)) * (xp.exp(-x / tau) - xp.exp(-y / tau))
return xp.where(a1 >= dt, tail, overlap)
def _periodic_cdf_integral(v: Any, tau: Any, period: float, xp: Any) -> Any:
"""``R(v) = int_0^v Psi(u) du`` of the steady-state cumulative count ``Psi``."""
r = v % period
n = (v - r) / period
c = -xp.expm1(-period / tau)
return (
period * n * (n - 1.0) / 2.0
+ n * (period / c - tau)
+ n * r
+ (r + tau * xp.expm1(-r / tau)) / c
)
def _uniform_periodic_gate_integral(
a: Any, b: Any, tau: Any, h_shift: Any, dt: float, period: float
) -> Any:
"""
Steady-state periodic counterpart of :func:`_uniform_gate_integral`:
``[R(b') - R(b' - dt) - R(a') + R(a' - dt)] / dt`` with ``a'`` reduced to
``[0, period)``; a gate inside ``[dt, period]`` uses the closed form divided by
``1 - e^{-period/tau}``.
"""
xp = _xp(tau)
a1 = a - h_shift
b1 = b - h_shift
offset = a1 - a1 % period
a1 = a1 - offset
b1 = b1 - offset
def r(v: Any) -> Any:
return _periodic_cdf_integral(v, tau, period, xp)
general = (r(b1) - r(b1 - dt) - r(a1) + r(a1 - dt)) / dt
x = _positive(a1 - dt, xp)
y = _positive(b1 - dt, xp)
inside = (
(tau / dt)
* (-xp.expm1(-dt / tau))
* (xp.exp(-x / tau) - xp.exp(-y / tau))
/ (-xp.expm1(-period / tau))
)
return xp.where((a1 >= dt) & (b1 <= period), inside, general)
[docs]
def gate_fraction(
a: Any,
b: Any,
tau: Any,
h_shift: Any,
dt: float,
period: float | None = None,
excitation: str = "bin_start",
) -> Any:
"""
Fraction of the photons of a unit-area exponential (lifetime `tau`, onset `h_shift`)
in the gate ``[a, b)``: single decay (``period=None``) or periodic steady state, with
the excitation at the IRF-gate start or uniform over ``[h_shift, h_shift + dt)``.
NumPy arrays or torch tensors.
"""
xp = _xp(tau)
tau_safe = xp.clamp(tau, min=_EPS) if xp is not np else np.clip(tau, _EPS, None)
if excitation == "uniform":
if period is None:
return _uniform_gate_integral(a, b, tau_safe, h_shift, dt)
return _uniform_periodic_gate_integral(a, b, tau_safe, h_shift, dt, period)
if period is None:
if xp is np:
return _gate_integral(a, b, tau, h_shift)
a_eff = xp.maximum(a, h_shift) - h_shift
b_eff = xp.maximum(b, h_shift) - h_shift
return xp.exp(-a_eff / tau_safe) - xp.exp(-b_eff / tau_safe)
return periodic_gate_integral(a, b, tau_safe, h_shift, period, expm1=xp.expm1)
def _gate_integral(a: np.ndarray, b: np.ndarray, tau: Any, h_shift: Any) -> np.ndarray:
"""Fraction of a unit-area exponential with onset `h_shift` inside ``[a, b)``."""
tau_safe = np.clip(tau, _EPS, None)
a_eff = np.maximum(a, h_shift) - h_shift
b_eff = np.maximum(b, h_shift) - h_shift
return np.exp(-a_eff / tau_safe) - np.exp(-b_eff / tau_safe)
[docs]
def gate_integrated_kernel(
gate_start: np.ndarray,
dt: float,
params: Any,
model_type: str,
h_shift: Any = 0.0,
period: float | None = None,
excitation: str = "bin_start",
gate_width: float | None = None,
) -> tuple[np.ndarray, Any]:
"""
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 spacing (and IRF bin 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).
period : float | None
Laser period in ns for the steady-state periodic decay
(:func:`~pyfli.reconstruction.common_reconstruct.periodic_gate_integral`);
``None`` for a single decay that is zero before the onset.
excitation : str
``"bin_start"`` or ``"uniform"`` (see the module docstring).
gate_width : float | None
Detection-gate width in ns; ``None`` means ``dt`` (gates tile the window).
Returns
-------
tuple[np.ndarray, Any]
``(kernel, v_shift)``: counts per gate (summing to ``S`` over all gates, or over
gates tiling one `period`, times ``gate_width / dt``) and the constant offset,
which is added after the IRF convolution.
"""
validate_excitation(excitation)
width = validate_gate_width(gate_width)
a = np.asarray(gate_start, dtype=float)
b = a + dt if width is None else a + width
def fraction(tau: Any) -> np.ndarray:
if excitation == "uniform":
return gate_fraction(a, b, tau, h_shift, dt, period, "uniform")
if period is None:
return _gate_integral(a, b, tau, h_shift)
return periodic_gate_integral(a, b, np.clip(tau, _EPS, None), h_shift, period)
if model_type == "mono-exponential":
S, tau, v_shift = params
kernel = S * fraction(tau)
else:
S, a1, tau1, tau2, v_shift = params
kernel = S * (a1 * fraction(tau1) + (1.0 - a1) * fraction(tau2))
return kernel, v_shift
def _gate_width(t: np.ndarray) -> float:
t = np.asarray(t, dtype=float)
return float(t[1] - t[0]) if t.size > 1 else 1.0
[docs]
def validate_shift_method(
shift_method: str, t_acq: float | None = None, t_laser: float | None = None
) -> str:
"""
Check `shift_method` is in :data:`SHIFT_METHODS` and, for ``"circular"`` with both
periods given, that the acquisition window equals the laser period (ns).
"""
if shift_method not in SHIFT_METHODS:
raise ValueError(
f"shift_method must be one of {SHIFT_METHODS}, got {shift_method!r}"
)
if (
shift_method == "circular"
and t_acq is not None
and t_laser is not None
and not np.isclose(t_acq, t_laser)
):
raise ValueError(
"shift_method='circular' needs the acquisition window to equal the laser "
f"period, got {t_acq} ns vs {t_laser} ns"
)
return shift_method
def _period(t: np.ndarray, shift_method: str) -> float | None:
validate_shift_method(shift_method)
return np.asarray(t).size * _gate_width(t) if shift_method == "circular" else None
[docs]
def decay_kernel(
t: np.ndarray,
params: Any,
model_type: str,
h_shift: float = 0.0,
shift_method: str = "zero_pad",
excitation: str = "bin_start",
gate_width: float | None = None,
) -> tuple:
"""Return (kernel, v_shift) on the gates starting at `t`.
The kernel is the gate-integrated decay of :func:`gate_integrated_kernel` (zero
before the onset `h_shift`, in ns, and summing to ``S``; periodic over the window
``len(t) * dt`` for ``shift_method="circular"``). Gates are ``[t_k, t_k + dt)``
with ``dt = t[1] - t[0]`` (``[t_k, t_k + gate_width)`` when given); `excitation` as
in :func:`gate_integrated_kernel`.
"""
kernel, v_shift = gate_integrated_kernel(
t,
_gate_width(t),
params,
model_type,
h_shift=h_shift,
period=_period(t, shift_method),
excitation=excitation,
gate_width=gate_width,
)
return kernel, float(v_shift)
[docs]
def negative_lag_gates(h_shift: Any, dt: float, gate_width: float | None = None) -> int:
"""
Number of gates before ``t = 0`` the kernel must cover so that a decay with onset
`h_shift` < 0 (earlier than the IRF), or seen by gates wider than ``dt``, is shifted,
not truncated, by the IRF convolution: lags ``m`` with ``m dt + gate_width > h``.
Zero for ``h_shift >= 0`` and ``gate_width <= dt``.
"""
h = np.asarray(h_shift, dtype=float)
h = h[np.isfinite(h)]
earliest = float(h.min()) if h.size else 0.0
if dt <= 0:
return 0
width = validate_gate_width(gate_width)
if width is None:
return int(np.ceil(max(-earliest, 0.0) / dt))
return int(max(0.0, -(np.floor((earliest - width) / dt) + 1.0)))
[docs]
def model_numpy(
t: np.ndarray,
irf: np.ndarray,
params: Any,
model_type: str,
shift_method: str = "zero_pad",
excitation: str = "bin_start",
gate_width: float | None = None,
) -> np.ndarray:
"""
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.
shift_method : str
``"zero_pad"`` (linear convolution) or ``"circular"`` (periodic steady state;
the window ``len(t) * dt`` must be one laser period).
excitation : str
``"bin_start"`` (default) or ``"uniform"`` excitation within each IRF gate.
gate_width : float | None
Detection-gate width in ns (``None``: ``dt``); see the module docstring.
Returns
-------
np.ndarray
Expected counts per gate, same length as `t`.
"""
params = np.asarray(params, dtype=float)
h_shift = float(params[-1])
kernel_params = params[:-1]
t = np.asarray(t, dtype=float)
n = t.size
dt = _gate_width(t)
irf = np.asarray(irf, dtype=float)
irf_sum = irf.sum()
irf_norm = irf / irf_sum if irf_sum > 0 else irf
period = _period(t, shift_method)
options = {"excitation": excitation, "gate_width": gate_width}
if period is not None:
kernel, v_shift = gate_integrated_kernel(
np.arange(n) * dt, dt, kernel_params, model_type, h_shift, period, **options
)
return circular_convolve(kernel, irf_norm) + float(v_shift)
n_neg = negative_lag_gates(h_shift, dt, gate_width)
lags = np.arange(-n_neg, n) * dt
kernel, v_shift = gate_integrated_kernel(
lags, dt, kernel_params, model_type, h_shift=h_shift, **options
)
convolved = np.convolve(kernel, irf_norm, mode="full")[n_neg : n_neg + n]
return convolved + float(v_shift)