pyfli.irf_deconvolution.fli_solver#

Solve FLI lifetimes and instrument response functions with detector-aware weighting.

This module belongs to pyfli.irf_deconvolution and is part of PyFLI detector- aware IRF deconvolution and joint FLI fitting utilities. Public API includes classes SolverConfig; functions cyclic_conv(), cyclic_corr(), decay_basis(), build_gate_matrix(), project_simplex(), huber_tv_grad(), spatial_laplacian(), fourier_shift(), pin_barycenter(), and fit_decay_pixel().

Functions

_phi(taus, h, t, T, G)

Run the phi routine.

build_gate_matrix(t, T, n_gates, width[, ...])

Build gate matrix.

cyclic_conv(h, f)

Run the cyclic conv routine.

cyclic_corr(u, f)

Run the cyclic corr routine.

decay_basis(taus, t, T)

Run the decay basis routine.

fit_decay_pixel(lam_obs, w, h, t, T, G, cfg)

Fit decay pixel.

fourier_shift(H, s)

Run the fourier shift routine.

huber_tv_grad(h, delta)

Run the huber TV grad routine.

pin_barycenter(H, c_target)

Run the pin barycenter routine.

project_simplex(V)

Run the project simplex routine.

solve_flim(y, detector, det_params, ny, nx, ...)

Run the solve FLI routine.

spatial_laplacian(H, ny, nx)

Run the spatial laplacian routine.

update_irf(H, F, lam_obs, W, G, mu1, mu2, ...)

Update IRF.

Classes

SolverConfig([T, n_models, tau_init, ...])

Run the solver config routine.
cyclic_conv(h, f)[source]#

Run the cyclic conv routine.

Parameters:

  • h (np.ndarray) – IRF, image height, or temporal kernel used by the routine.

  • f (np.ndarray) – Decay basis, distribution, or signal function used by the calculation.

Returns:

Object produced by cyclic conv.

Return type:

Any

cyclic_corr(u, f)[source]#

Run the cyclic corr routine.

Parameters:

  • u (np.ndarray) – Signal vector used by cyclic correlation.

  • f (np.ndarray) – Decay basis, distribution, or signal function used by the calculation.

Returns:

Object produced by cyclic corr.

Return type:

Any

decay_basis(taus, t, T)[source]#

Run the decay basis routine.

Parameters:

  • taus (np.ndarray) – Lifetime grid or lifetime vector in nanoseconds.

  • t (np.ndarray) – Time axis or acquisition period used by the calculation.

  • T (np.ndarray) – Time axis or acquisition period used by the calculation.

Returns:

Exponential decay basis evaluated on the time grid.

Return type:

np.ndarray

build_gate_matrix(t, T, n_gates, width, edge=0.0, eta=None)[source]#

Build gate matrix.

Parameters:

  • t (np.ndarray) – Time axis or acquisition period used by the calculation.

  • T (np.ndarray) – Time axis or acquisition period used by the calculation.

  • n_gates (int) – Number of acquisition gates.

  • width (float) – Gate width used by the gate matrix.

  • edge (float) – Gate edge offset used when building the gate matrix.

  • eta (float | None) – Optional gate efficiency profile.

Returns:

Gate-integration matrix mapping decay samples to gates.

Return type:

np.ndarray

project_simplex(V)[source]#

Run the project simplex routine.

Parameters:

V (np.ndarray) – Vector or matrix evaluated by the simplex projection.

Returns:

Object produced by project simplex.

Return type:

Any

huber_tv_grad(h, delta)[source]#

Run the huber TV grad routine.

Parameters:

  • h (np.ndarray) – IRF, image height, or temporal kernel used by the routine.

  • delta (np.ndarray) – Huber transition value used by the TV gradient.

Returns:

Object produced by huber TV grad.

Return type:

Any

spatial_laplacian(H, ny, nx)[source]#

Run the spatial laplacian routine.

Parameters:

  • H (np.ndarray) – IRF estimate, image stack, or convolution kernel used by the solver.

  • ny (np.ndarray) – Image height used for reshaping flattened arrays.

  • nx (np.ndarray) – Image width used for reshaping flattened arrays.

Returns:

Object produced by spatial laplacian.

Return type:

Any

fourier_shift(H, s)[source]#

Run the fourier shift routine.

Parameters:

  • H (np.ndarray) – IRF estimate, image stack, or convolution kernel used by the solver.

  • s (np.ndarray) – Phasor imaginary coordinate or shift amount.

Returns:

Object produced by fourier shift.

Return type:

Any

pin_barycenter(H, c_target)[source]#

Run the pin barycenter routine.

Parameters:

  • H (np.ndarray) – IRF estimate, image stack, or convolution kernel used by the solver.

  • c_target (np.ndarray) – Target barycenter used to pin the IRF shift.

Returns:

Object produced by pin barycenter.

Return type:

Any

class SolverConfig(T=12.5, n_models=2, tau_init=(0.5, 2.0), tau_bounds=(0.05, 8.0), tau_sep=1.4, rho1=0.02, rho2=0.1, outer_iters=8, irf_inner_iters=250, irf_step=0.5, estimate_irf=True, pin_global_shift=False, verbose=True)[source]#

Bases: object

Run the solver config routine. controls model count, lifetime bounds, regularization, IRF update iterations, and logging behavior.

Parameters:

  • T (float) – Time axis or acquisition period used by the calculation.

  • n_models (int) – Number of mixture models or candidate components to fit.

  • tau_init (tuple) – Initial lifetime vector for pixel-wise exponential fitting.

  • tau_bounds (tuple) – Lower and upper lifetime bounds for fitted exponential components.

  • tau_sep (float) – Minimum separation enforced between fitted lifetimes.

  • rho1 (float) – Penalty weight for the first regularized optimization term.

  • rho2 (float) – Penalty weight for the second regularized optimization term.

  • outer_iters (int) – Number of outer optimization iterations.

  • irf_inner_iters (int) – Number of inner iterations used when updating the IRF estimate.

  • irf_step (float) – Step size for IRF updates.

  • estimate_irf (bool) – If True, update the IRF during optimization.

  • pin_global_shift (bool) – If True, keep the global IRF shift fixed during optimization.

  • verbose (bool) – If True, report progress and diagnostic messages during processing.

T: float = 12.5#
n_models: int = 2#
tau_init: tuple = (0.5, 2.0)#
tau_bounds: tuple = (0.05, 8.0)#
tau_sep: float = 1.4#
rho1: float = 0.02#
rho2: float = 0.1#
outer_iters: int = 8#
irf_inner_iters: int = 250#
irf_step: float = 0.5#
estimate_irf: bool = True#
pin_global_shift: bool = False#
verbose: bool = True#
fit_decay_pixel(lam_obs, w, h, t, T, G, cfg)[source]#

Fit decay pixel.

Parameters:

  • lam_obs (np.ndarray) – Observed photon-rate array after detector conversion.

  • w (np.ndarray) – Weight vector, image width, or basis vector used by the routine.

  • h (np.ndarray) – IRF, image height, or temporal kernel used by the routine.

  • t (np.ndarray) – Time axis or acquisition period used by the calculation.

  • T (np.ndarray) – Time axis or acquisition period used by the calculation.

  • G (np.ndarray) – Phasor real coordinate.

  • cfg (Any) – Configuration object or keyword dictionary used by the algorithm.

Returns:

Object produced by fit decay pixel.

Return type:

Any

update_irf(H, F, lam_obs, W, G, mu1, mu2, ny, nx, cfg)[source]#

Update IRF.

Parameters:

  • H (np.ndarray) – IRF estimate, image stack, or convolution kernel used by the solver.

  • F (np.ndarray) – Forward model matrix or decay estimate used by the solver.

  • lam_obs (np.ndarray) – Observed photon-rate array after detector conversion.

  • W (np.ndarray) – Weight matrix or vector applied in the optimization objective.

  • G (np.ndarray) – Phasor real coordinate.

  • mu1 (np.ndarray) – Auxiliary optimization variable for the first regularized update.

  • mu2 (np.ndarray) – Auxiliary optimization variable for the second regularized update.

  • ny (np.ndarray) – Image height used for reshaping flattened arrays.

  • nx (np.ndarray) – Image width used for reshaping flattened arrays.

  • cfg (Any) – Configuration object or keyword dictionary used by the algorithm.

Returns:

Object produced by update IRF.

Return type:

Any

solve_flim(y, detector, det_params, ny, nx, gate_spec, cfg, h_init=None)[source]#

Run the solve FLI routine.

Parameters:

  • y (np.ndarray) – Observed signal, target data, or coordinate array.

  • detector (str) – Detector model name used to select weighting or conversion logic.

  • det_params (np.ndarray) – Detector model parameters used for observation weighting.

  • ny (np.ndarray) – Image height used for reshaping flattened arrays.

  • nx (np.ndarray) – Image width used for reshaping flattened arrays.

  • gate_spec (np.ndarray) – Gate timing specification used by the detector model.

  • cfg (SolverConfig) – Configuration object or keyword dictionary used by the algorithm.

  • h_init (np.ndarray | None) – Initial IRF estimate supplied to the solver.

Returns:

Object produced by solve FLI.

Return type:

Any