Add optional Numba geometry unwrap backend

[sergioald]

Summary

Adds an explicit optional Numba backend for the curvature-angle unwrap used by geometry4.

The existing Python implementation remains the reference and default path:

• geometry_unwrap_backend="python" — current reference behavior
• geometry_unwrap_backend="numba" — optional exact serial JIT implementation

The geometry unwrap backend is independent of the existing flow-field backend. Numba remains an optional dependency and installing it does not change the default solver behavior.

Numerical behavior

The Numba implementation preserves the existing unwrap semantics exactly:

• serial execution
• fastmath=False
• cache=False
• last = 0.0
• identical strict < and > comparisons
• identical np.pi / 2.0 * np.pi arithmetic
• identical sequential loop ordering

The Python and Numba paths were bitwise identical in:

• dedicated unwrap tests, including ±π boundary cases
• representative geometry4 comparisons
• short solver integration tests
• 1,000-step production A/B validation
• five paired 5,000-step validation runs
• a final 5,000-step public production-path confirmation

The validated 5,000-step trajectory was identical for both paths:

• final Ns = 2359
• 44 cutoffs
• final sinuosity 1.7245401220504077

Checkpoint arrays and scalars, full histories, cutoff steps, selected pairs, and points removed all matched exactly.

Performance

Five alternating 5,000-step benchmark pairs produced median speedups of:

• curvature stage: 3.342×
• geometry stage: 1.157×
• whole solver: 1.093×

These are machine- and workload-specific measurements, not universal performance claims.

A later single public production-path confirmation also showed a strong curvature-stage improvement:

Metric	Python	Numba	Python / Numba
Total wall	69.253 s	74.989 s	0.924×
Geometry	39.987 s	40.528 s	0.987×
Curvature	7.357 s	1.864 s	3.948×
Flowfield	25.220 s	30.076 s	0.839×

That single run was slower end-to-end because unrelated flowfield timing increased substantially. The five alternating pairs therefore remain the stronger performance estimate. No universal end-to-end speedup is claimed.

Optional dependency and compatibility

• The default Python geometry path does not import or require Numba.
• Requesting the Numba unwrap without Numba installed raises a clear optional-dependency error.
• Unrelated import errors are not masked as missing-Numba errors.
• Existing GUI configurations without the new setting default to python.
• run_config.json records the normalized effective geometry unwrap backend.
• Flow-field backend semantics are unchanged.
• numba_parallel and numba_fastmath continue to apply only to the existing flow backend.

The following combinations remain independent and supported:

• NumPy flow + Python unwrap
• Numba flow + Python unwrap
• NumPy flow + Numba unwrap
• Numba flow + Numba unwrap

Interface changes

Adds:

geometry_unwrap_backend="python" | "numba"

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9035ac8d06

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".