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

_gate_integral(a, b, tau, h_shift)

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

_gate_width(t)

_period(t, shift_method)

_periodic_cdf_integral(v, tau, period, xp)

R(v) = int_0^v Psi(u) du of the steady-state cumulative count Psi.

_positive(v, xp)

_uniform_gate_integral(a, b, tau, h_shift, dt)

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

_uniform_periodic_gate_integral(a, b, tau, ...)

Steady-state periodic counterpart of _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(x)

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

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

gate_fraction(a, b, tau, h_shift, dt[, ...])

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

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[, gate_width])

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.

validate_excitation(excitation)

Check excitation is one of EXCITATIONS.

validate_gate_width(gate_width)

Check gate_width is None or a positive finite width in ns.

validate_model_type(model_type)

Check model_type is one of MODEL_TYPES (catches e.g. a p0 passed in its place).

validate_shift_method(shift_method[, t_acq, ...])

Check shift_method is in SHIFT_METHODS and, for "circular" with both periods given, that the acquisition window equals the laser period (ns).

validate_model_type(model_type)[source]#

Check model_type is one of MODEL_TYPES (catches e.g. a p0 passed in its place).

Parameters:

model_type (Any)

Return type:

str

validate_excitation(excitation)[source]#

Check excitation is one of EXCITATIONS.

Parameters:

excitation (Any)

Return type:

str

validate_gate_width(gate_width)[source]#

Check gate_width is None or a positive finite width in ns.

Parameters:

gate_width (Any)

Return type:

float | None

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.

Parameters:
Return type:

Any

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; 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 (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:

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

Return type:

tuple[np.ndarray, Any]

validate_shift_method(shift_method, t_acq=None, t_laser=None)[source]#

Check shift_method is in SHIFT_METHODS and, for "circular" with both periods given, that the acquisition window equals the laser period (ns).

Parameters:
Return type:

str

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 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 gate_integrated_kernel().

Parameters:
Return type:

tuple

negative_lag_gates(h_shift, dt, gate_width=None)[source]#

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.

Parameters:
Return type:

int

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

Expected counts per gate, same length as t.

Return type:

np.ndarray