Troubleshooting

Triton backend unavailable

Check torch.cuda.is_available(), the input device, and whether Triton imports. Use Linux x86_64 with a supported NVIDIA GPU and driver. The register kernel accepts at most 128 padded slots; the large kernel accepts at most 16384. A macOS install cannot provide a CUDA device.

CPU install works but clustering is slow

Check flashjet._native.HAS_NATIVE. If false, the optional compiler step or shared-library load failed. Reinstall from a wheel, or build from source with a C++17 compiler. HAS_OPENMP=False means the native kernel is single-threaded; it does not mean the kernel is missing.

Invalid input or unexpected jets

Check the (px, py, pz, E) order, energy and momentum units, physical energies, mask shape and device, and padded width. Non-finite masked-in values raise by default. R must be positive. Padding must be masked out.

Results differ slightly

Compare particle assignments separately from summed momenta. Precision, near-ties, autotuning, and CUDA summation order can each matter. See Backends before expecting bitwise agreement with another setup.

GPU memory is exhausted

Reduce batch size or padding. Do not use the cubic torch fallback for large events. If you truncate inputs with n_max, record that choice in your analysis.

A test skips

The CPU suite cannot run CUDA kernels. A green CPU run with GPU skips does not validate Triton. Use the manually dispatched GPU workflow on a registered CUDA runner, and check that its preflight confirms both CUDA and Triton.