Plugins / FLIMKit / Troubleshooting · edit on GitHub

Troubleshooting

Gatekeeper blocks the compiled app on macOS
Right-click → Open on first launch. After that it should run normally.

Machine IRF not found after saving
Restart the app, since a newly built default is picked up at startup, or set it in File > Preferences... > Files, which applies at once.

Per-pixel fitting is very slow
That's expected for large FOVs on CPU. Try increasing --binning to aggregate pixels before fitting, or switch to summed-only mode if you don't need spatial maps. If you have a supported GPU (Apple Silicon, NVIDIA, AMD) and ran python install.py, GPU acceleration is detected and used automatically, no extra flags needed.

--free-tau-perpixel with n_exp ≥ 2 does not go through those GPU backends. It runs a numba Levenberg-Marquardt, on the CPU everywhere and on an NVIDIA GPU through numba.cuda when numba-cuda is installed. On real data that is 140 to 150x faster than the SciPy-per-pixel loop it replaced on a 10-core M4. A 4-thread PC with an RTX A2000 fits 3-component pixels at 76 µs/px on the GPU against 274 µs/px on its CPU. The tail model, a time-varying background, pile-up in the model and more than three components still run SciPy per pixel, as do FLIMKIT_NUMBA_FREETAU=0 and a numba that will not load. FLIMKIT_NUMBA_CUDA=0 keeps the fit on the CPU.

Free τ can be accelerated considerably further by flimkit-accelerator-plugin, an optional add-on with C and CUDA fit backends. It is not required: without it the numba fit above runs, and the fitted values are the same kind of answer either way. Install it, and with auto its backend is tried before numba (see Fit backends). FLIMKIT_FIT_BACKEND=cpu turns it off again.

FLIMKit asks numba for its workqueue threading layer unless NUMBA_THREADING_LAYER is already set. numba's OpenMP layer aborts the process with OMP: Error #15 when PyTorch has already loaded its own OpenMP runtime, which happens as soon as anything touches cell masking or a torch GPU backend. The two layers fit 8,192 pixels in the same time here, 6.2 against 6.3 µs/px, so this costs nothing measurable.

The per-pixel GPU fit works in blocks, and FLIMKIT_GPU_BLOCK_BYTES sets the budget for one block in bytes. The default is 32 MB on CUDA and ROCm and 256 MB on MLX, and either way it is clamped to half of the free device memory. The CUDA default came off an RTX A5000, where anything above 32 MB costs a flat 2x because the card has 6 MB of L2 and the fast region is where the basis and a block stay resident. It does not generalise: an RTX A2000, with less L2, shows no cliff at all and is about 10 per cent slower at 32 MB than at 256 MB. Every budget returns identical lifetimes, so this is speed only.

Tile stitching produces visible seams
Check that the max drift setting isn't too restrictive. If registration looks fine but seams persist, it's likely a sample contrast issue at tile boundaries rather than a registration failure.

ROI holes are lost on GeoJSON import
Known limitation... Only the outer boundary is imported. Donut-shaped ROIs with holes lose the hole geometry on import.

Phasor calibration looks off
Make sure the IRF file is from the same acquisition session. XLSX-based IRFs from FLIM microscope software can vary between sessions, which is why the machine IRF exists.

A plugin is missing, fails to load, or its window misbehaves
See Plugin Troubleshooting. Help > Plugins... lists what loaded and why anything failed.

Lifetimes are slightly higher than FLIM microscope software for the same data
This is expected and systematic. FLIMKit anchors the IRF at the steepest-rise point of the leading edge, which differs from how FLIM microscope software places the IRF. The offset is consistent across acquisitions and does not indicate a fitting problem.