pyfli.reconstruction.common_reconstruct#

Functions

_periodic_exponential_cdf(x, tau, h_shift, ...)

_relative_change(old, new)

bi_reconstruction(t, tau1, tau2, A1, A2)

bi_reconstruction_torch(t, tau1, tau2, A1, A2)

circular_convolve(x, h[, axis])

Circular convolution y[n] = sum_m x[m] h[(n - m) mod N] along axis (inputs broadcast, both of length N there): the discrete periodic measurement model F = I (*) f over one repetition period, under which phasors factorise, z_k(F) = z_k(I) z_k(f).

circular_convolve_torch(x, h[, dim])

Torch form of circular_convolve() (differentiable).

decay_histogram(taus, fractions, irf, period)

Expected fraction of the emitted photons in each of the n gates tiling one period (gate_starts()), for a decay whose photons come from exponential components taus with photon fractions fractions, each excitation at the start of an IRF gate (irf normalised here).

fourier_shift(x, shift)

Delay x by shift samples (fractional; scalar or broadcast against x.shape[:-1]) along the last axis with the phase ramp e^{-2 pi i k shift / N}: x[n] -> x[n - shift] circularly, exact for integer shifts and for band-limited periodic signals.

gate_starts(period, n_gates)

Start times m * period / n_gates, m = 0..n_gates-1, of n_gates equal gates covering [0, period): the time axis of the fitters, reconstruction, simulators and phasors (linspace(0, period, n_gates, endpoint=False)).

irls(solve, predict, x0[, variance_floor, ...])

Iteratively reweighted least squares for Poisson counts: each round solves the weighted problem with the variance frozen at max(mu, variance_floor) of the previous round, x_{r+1} = solve(x_r, residual_variance(predict(x_r))), until change(x_r, x_{r+1}) < tol (default: largest element-wise relative change) or max_rounds.

mono_reconstruction(t, tau[, S])

mono_reconstruction_torch(t, tau[, S])

periodic_bin_exponential(tau, n_bins, period)

Fraction of the photons of a periodically excited mono-exponential decay (lifetime tau, any shape S) that falls in each of n_bins equal bins covering one repetition period (same time unit as tau).

periodic_gate_integral(a, b, tau, h_shift, ...)

Fraction of the photons of a periodically excited exponential (lifetime tau, onset h_shift after each pulse, repetition period) that falls in [a, b), in steady state.

periodic_instrument_exponential(tau, n_bins, ...)

Per-bin photon distribution of a periodically excited mono-exponential decay as a real time-resolved instrument records it: excitation (IRF) photons arrive anywhere inside their bin, not at its start, so this is the decay kernel that, circularly convolved with the binned IRF, gives the binned measurement when the IRF density is uniform within each bin.

residual_variance(model, data, weighting[, ...])

Per-gate variance v_k of weighted least squares sum_k (d_k - mu_k)^2 / v_k (NumPy arrays or torch tensors): "irls" max(mu_k, variance_floor) from the model held fixed (Poisson variance; see irls()), "neyman" max(d_k, 1) from the data, "none" 1.

weighted_linear_lstsq(V, d[, variance, ...])

Per-pixel solution of min_c sum_t (d_t - (V c)_t)^2 / v_t + lam sum_k p_k c_k^2 with lam = reg_strength * mean_k sum_t V_tk^2 / v_t, by QR of the sqrt-weighted, penalty-augmented design.

periodic_bin_exponential(tau, n_bins, period)[source]#

Fraction of the photons of a periodically excited mono-exponential decay (lifetime tau, any shape S) that falls in each of n_bins equal bins covering one repetition period (same time unit as tau). In steady state the tails of all earlier pulses add up to the same exponential shape, so bin k receives exp(-k dt / tau) (1 - exp(-dt / tau)) / (1 - exp(-period / tau)) with dt = period / n_bins. Returns S + (n_bins,), summing to 1 along the last axis.

periodic_instrument_exponential(tau, n_bins, period)[source]#

Per-bin photon distribution of a periodically excited mono-exponential decay as a real time-resolved instrument records it: excitation (IRF) photons arrive anywhere inside their bin, not at its start, so this is the decay kernel that, circularly convolved with the binned IRF, gives the binned measurement when the IRF density is uniform within each bin. With x = dt / tau and dt = period / n_bins:

  • bin 0: 1 - (1 - e^-x) / x (decays starting and ending in the excitation bin) plus the wrapped tails of earlier pulses;

  • bin m >= 1: e^(-m x) (1 - e^-x)(e^x - 1) / x, divided by 1 - exp(-period / tau) for the periodic steady state.

Its discrete Fourier transform at the laser frequency equals the continuous phasor 1 / (1 - i omega tau) up to ~1e-4, so IRF-calibrated phasors of such data lie on the universal semicircle. periodic_bin_exponential() is the kernel when every excitation is at a bin start (pyfli’s PhotonCountSimulator). Returns S + (n_bins,), summing to 1 along the last axis.

gate_starts(period, n_gates)[source]#

Start times m * period / n_gates, m = 0..n_gates-1, of n_gates equal gates covering [0, period): the time axis of the fitters, reconstruction, simulators and phasors (linspace(0, period, n_gates, endpoint=False)).

circular_convolve(x, h, axis=-1)[source]#

Circular convolution y[n] = sum_m x[m] h[(n - m) mod N] along axis (inputs broadcast, both of length N there): the discrete periodic measurement model F = I (*) f over one repetition period, under which phasors factorise, z_k(F) = z_k(I) z_k(f).

circular_convolve_torch(x, h, dim=-1)[source]#

Torch form of circular_convolve() (differentiable).

periodic_gate_integral(a, b, tau, h_shift, period, expm1=np.expm1)[source]#

Fraction of the photons of a periodically excited exponential (lifetime tau, onset h_shift after each pulse, repetition period) that falls in [a, b), in steady state. With u = x - h_shift the cumulative count since t = h_shift is Psi(x) = floor(u / T) + (1 - e^{-(u mod T) / tau}) / (1 - e^{-T / tau}), continuous in x and h_shift, and the gate holds Psi(b) - Psi(a); gates tiling one period sum to 1. For h_shift = 0 on gate_starts() gates this is periodic_bin_exponential(). Pass expm1=torch.expm1 for tensors.

fourier_shift(x, shift)[source]#

Delay x by shift samples (fractional; scalar or broadcast against x.shape[:-1]) along the last axis with the phase ramp e^{-2 pi i k shift / N}: x[n] -> x[n - shift] circularly, exact for integer shifts and for band-limited periodic signals. A positive shift delays, as pyfli.data_cc.irfAligner.IRFAligner.estimate_shift() reports it; delaying the IRF by s gates is the solver’s onset h_shift = s * dt.

residual_variance(model, data, weighting, variance_floor=1.0)[source]#

Per-gate variance v_k of weighted least squares sum_k (d_k - mu_k)^2 / v_k (NumPy arrays or torch tensors): "irls" max(mu_k, variance_floor) from the model held fixed (Poisson variance; see irls()), "neyman" max(d_k, 1) from the data, "none" 1.

irls(solve, predict, x0, variance_floor=1.0, max_rounds=20, tol=1e-6, change=None)[source]#

Iteratively reweighted least squares for Poisson counts: each round solves the weighted problem with the variance frozen at max(mu, variance_floor) of the previous round, x_{r+1} = solve(x_r, residual_variance(predict(x_r))), until change(x_r, x_{r+1}) < tol (default: largest element-wise relative change) or max_rounds. A change returning one value per row of x (pixels) freezes each row at its own convergence, so a batch reproduces per-pixel runs exactly. At convergence sum_k (d_k - mu_k) / mu_k * dmu_k/dx = 0, the Poisson likelihood equations.

Parameters:
  • solve (callable) – solve(x, variance) -> (x_new, extra).

  • predict (callable) – predict(x) -> mu, the model counts on the fitted gates.

  • x0 (array_like) – Starting parameters.

Returns:

(x, extra) of the last round.

Return type:

tuple

weighted_linear_lstsq(V, d, variance=None, penalty=None, reg_strength=0.0)[source]#

Per-pixel solution of min_c sum_t (d_t - (V c)_t)^2 / v_t + lam sum_k p_k c_k^2 with lam = reg_strength * mean_k sum_t V_tk^2 / v_t, by QR of the sqrt-weighted, penalty-augmented design.

Parameters:
  • V (np.ndarray) – Design (T, K) shared by all pixels, or (P, T, K) per pixel.

  • d (np.ndarray) – Data (P, T).

  • variance (np.ndarray | None) – (P, T) per-gate variances (residual_variance()); None is 1.

  • penalty (np.ndarray | None) – (K,) penalty weights p_k for reg_strength.

Returns:

(P, K) coefficients.

Return type:

np.ndarray

decay_histogram(taus, fractions, irf, period, periodic=True)[source]#

Expected fraction of the emitted photons in each of the n gates tiling one period (gate_starts()), for a decay whose photons come from exponential components taus with photon fractions fractions, each excitation at the start of an IRF gate (irf normalised here). periodic=True: steady state of the pulse train (photons wrapped over the period), periodic_gate_integral() circularly convolved with the IRF; sums to 1, as pyfli’s photon simulator with pileup_mode="wrap" and the solver’s shift_method="circular". periodic=False: a single pulse, photons past the period lost, gate-integrated exponentials linearly convolved and truncated, as pileup_mode="truncate" and shift_method="zero_pad".

mono_reconstruction(t, tau, S=1.0)[source]#
bi_reconstruction(t, tau1, tau2, A1, A2)[source]#
mono_reconstruction_torch(t, tau, S=1.0)[source]#
bi_reconstruction_torch(t, tau1, tau2, A1, A2)[source]#