pyfli.cm_funcs.forward_model#
Evaluate exponential decay kernels and convolved NumPy forward models.
This module belongs to pyfli.cm_funcs and is the single forward model shared by the
PyFLI solver, reconstruction, Laguerre, simulator and phasor packages. 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).
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
(pyfli.reconstruction.common_reconstruct.periodic_gate_integral() convolved by
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.
Functions
|
Fraction of a unit-area exponential with onset h_shift inside |
|
|
|
|
|
|
|
|
|
Fraction of a unit-area exponential inside |
|
Steady-state periodic counterpart of |
|
|
|
Return (kernel, v_shift) on the gates starting at t. |
|
Fraction of the photons of a unit-area exponential (lifetime tau, onset h_shift) in the gate |
|
Expected counts per gate of the un-convolved decay, integrated over each gate. |
|
Evaluate the NumPy FLI forward model: the gate-integrated decay (onset |
|
Number of gates before |
|
Check excitation is one of |
|
Check gate_width is |
|
Check model_type is one of |
|
Check shift_method is in |
- validate_model_type(model_type)[source]#
Check model_type is one of
MODEL_TYPES(catches e.g. ap0passed in its place).
- gate_fraction(a, b, tau, h_shift, dt, period=None, excitation='bin_start')[source]#
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.
- gate_integrated_kernel(gate_start, dt, params, model_type, h_shift=0.0, period=None, excitation='bin_start', gate_width=None)[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; gatekcovers[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 (periodic_gate_integral());Nonefor 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;Nonemeansdt(gates tile the window).
- Returns:
(kernel, v_shift): counts per gate (summing toSover all gates, or over gates tiling one period, timesgate_width / dt) and the constant offset, which is added after the IRF convolution.- Return type:
tuple[np.ndarray,Any]
- validate_shift_method(shift_method, t_acq=None, t_laser=None)[source]#
Check shift_method is in
SHIFT_METHODSand, for"circular"with both periods given, that the acquisition window equals the laser period (ns).
- decay_kernel(t, params, model_type, h_shift=0.0, shift_method='zero_pad', excitation='bin_start', gate_width=None)[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 toS; periodic over the windowlen(t) * dtforshift_method="circular"). Gates are[t_k, t_k + dt)withdt = t[1] - t[0]([t_k, t_k + gate_width)when given); excitation as ingate_integrated_kernel().
- negative_lag_gates(h_shift, dt, gate_width=None)[source]#
Number of gates before
t = 0the kernel must cover so that a decay with onset h_shift < 0 (earlier than the IRF), or seen by gates wider thandt, is shifted, not truncated, by the IRF convolution: lagsmwithm dt + gate_width > h. Zero forh_shift >= 0andgate_width <= dt.
- model_numpy(t, irf, params, model_type, shift_method='zero_pad', excitation='bin_start', gate_width=None)[source]#
Evaluate the NumPy FLI forward model: the gate-integrated decay (onset
h_shift) convolved with the normalized IRF, plus the constantv_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);Sis 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 windowlen(t) * dtmust 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:
Expected counts per gate, same length as t.
- Return type:
np.ndarray