pyfli.reconstruction.common_reconstruct#
Functions
|
|
|
|
|
|
|
|
|
Circular convolution |
|
Torch form of |
|
Expected fraction of the emitted photons in each of the |
|
Delay x by shift samples (fractional; scalar or broadcast against |
|
Start times |
|
Iteratively reweighted least squares for Poisson counts: each round solves the weighted problem with the variance frozen at |
|
|
|
|
|
Fraction of the photons of a periodically excited mono-exponential decay (lifetime |
|
Fraction of the photons of a periodically excited exponential (lifetime tau, onset h_shift after each pulse, repetition period) that falls in |
|
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. |
|
Per-gate variance |
|
Per-pixel solution of |
- periodic_bin_exponential(tau, n_bins, period)[source]#
Fraction of the photons of a periodically excited mono-exponential decay (lifetime
tau, any shapeS) that falls in each ofn_binsequal bins covering one repetitionperiod(same time unit astau). In steady state the tails of all earlier pulses add up to the same exponential shape, so binkreceivesexp(-k dt / tau) (1 - exp(-dt / tau)) / (1 - exp(-period / tau))withdt = period / n_bins. ReturnsS + (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 / tauanddt = 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 by1 - 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’sPhotonCountSimulator). ReturnsS + (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 lengthNthere): the discrete periodic measurement modelF = I (*) fover 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. Withu = x - h_shiftthe cumulative count sincet = h_shiftisPsi(x) = floor(u / T) + (1 - e^{-(u mod T) / tau}) / (1 - e^{-T / tau}), continuous in x and h_shift, and the gate holdsPsi(b) - Psi(a); gates tiling one period sum to 1. Forh_shift = 0ongate_starts()gates this isperiodic_bin_exponential(). Passexpm1=torch.expm1for 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 rampe^{-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, aspyfli.data_cc.irfAligner.IRFAligner.estimate_shift()reports it; delaying the IRF bysgates is the solver’s onseth_shift = s * dt.
- residual_variance(model, data, weighting, variance_floor=1.0)[source]#
Per-gate variance
v_kof weighted least squaressum_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; seeirls()),"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))), untilchange(x_r, x_{r+1}) < tol(default: largest element-wise relative change) or max_rounds. A change returning one value per row ofx(pixels) freezes each row at its own convergence, so a batch reproduces per-pixel runs exactly. At convergencesum_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:
- 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^2withlam = 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());Noneis 1.penalty (
np.ndarray | None) –(K,)penalty weightsp_kfor 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
ngates 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 (irfnormalised 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 withpileup_mode="wrap"and the solver’sshift_method="circular".periodic=False: a single pulse, photons past the period lost, gate-integrated exponentials linearly convolved and truncated, aspileup_mode="truncate"andshift_method="zero_pad".