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