Add optional Numba spatial-grid neck detector

[sergioald]

Summary

Adds an optional exact Numba spatial-grid backend for neck-cutoff detection.

The existing SciPy KDTree implementation remains the default and reference path.

New public control:

neck_detector_backend="kdtree" | "numba_grid"

The neck detector backend is independent of both the flow backend and the geometry unwrap backend.

Implementation

• Adds a serial Numba uniform spatial-grid detector.
• Preserves the strict cutoff threshold (d² < r²).
• Preserves first-admissible-i semantics.
• Preserves closest-j selection.
• Preserves smallest-j tie-breaking.
• Shares the existing refinement, mapping, admissibility, and final original-coordinate validation path with the KDTree reference implementation.
• Keeps kdtree as the default backend.
• Keeps Numba optional and lazily imported.
• Fails before normal run output if numba_grid is explicitly requested without Numba installed.
• Uses a numerical-safety fallback to the KDTree reference for an individual detector call when spatial-grid integer cell coordinates cannot be represented safely.
• Adds CLI, GUI, run-configuration, validation, documentation, and CI support.

Exactness

The benchmark prototype matched the KDTree reference on:

• all 1,710 captured production detector calls;
• all synthetic/adversarial detector cases;
• 40 refinement searches.

The public production-path validation also matched exactly through both 1,000 and 5,000 steps.

At 5,000 steps both backends produced:

• Ns = 2359;
• sinuosity 1.7245401220504077;
• 44 cutoffs;
• identical cutoff-step sequence;
• identical selected cutoff pairs;
• identical points removed;
• identical scalar histories;
• identical checkpoint states;
• identical resonance flags.

Performance

For the validated case-1 5,000-step benchmark prototype, three paired runs gave:

• detector median speedup: ~19.93×;
• geometry median speedup: ~2.71×;
• whole-solver median speedup: ~1.59×.

The final warmed public-production candidate profile measured:

• wall time: 15.723 s;
• neck detector: 0.485 s / 3.08% of wall;
• SEMIANA response: 5.806 s / 36.92% of wall;
• initial geometry uniformization: 3.913 s / 24.89% of wall.

These timings are machine- and workload-specific and are not universal performance guarantees.

Compatibility

• Default remains kdtree.
• Normal installations do not require Numba.
• Existing run_case positional argument order is preserved.
• Older GUI configurations without the new field default to KDTree.
• Flow backend, geometry unwrap backend, and neck detector backend remain independently selectable.
• Optional Numba neck-equivalence tests are included in the dedicated Python 3.12 Numba CI guardrail.

Validation

• Focused neck/geometry tests: pass.
• Full pytest: pass, one expected skip.
• Ruff: pass.
• py_compile: pass.
• git diff --check: pass.

Notes

The numerical-safety fallback is not automatic backend selection and is not a dependency fallback. The selected backend remains numba_grid; only an individual detector call delegates to the KDTree reference when the integer spatial-grid representation is unsafe.