[sergioald]

Summary

This PR accelerates the Numba SEMIANA response used by the free-flow solver by replacing the repeated finite-window convolution summation with an algebraically equivalent recursive finite-window formulation.

The optimization preserves the existing:

• jtoll truncation
• endpoint corrections
• SL0 routing
• SL1 sub-resonant routing
• SL1 super-resonant routing
• borderline-resonance fallback
• TOLL=1e-4
• modal coefficients and eigenvalues
• scientific controls and model defaults

The new recurrence is not an infinite-IIR approximation. It explicitly subtracts the contribution leaving the finite jtoll window.

The public Numba path now uses the recursive response only for the validated configuration:

• paral=0
• numba_parallel=False
• numba_fastmath=False
• cached SEMIANA path
• SL0 / SL1

Other execution modes retain the legacy implementation.

The previous cached Numba SEMIANA response is preserved as an internal reference for validation and benchmarking.

Main changes

• Add recursive upstream and downstream finite-window SEMIANA kernels.
• Keep legacy cached SEMIANA kernels available internally.
• Route the validated public serial Numba path to the recursive implementation.
• Add defensive guards preventing recursive SEMIANA from being used with unsupported:
  • parallel mode
  • fastmath
  • uncached response
• Add reusable SEMIANA timing to the long-term parity tooling.
• Add:
  • low-level recurrence parity tests
  • complete flowfield parity tests
  • SL0 / SL1 sub-resonant / SL1 super-resonant coverage
  • borderline-resonance fallback coverage
  • public-selector regression tests
  • large-N performance benchmark
  • 1,000 / 5,000 / 10,000-step trajectory validation tooling
  • design and validation documentation

Numerical validation

Direct finite-window parity

The recursive kernels were compared station-by-station against the legacy cached finite convolution for:

• multiple centreline sizes
• jtoll = 2, 3, intermediate values, near-N, N, and N+1
• upstream and downstream responses
• complex eigenvalues
• shortened physical-boundary windows

Complete flowfield parity was also checked for:

• SL0
• SL1 sub-resonant
• SL1 super-resonant
• borderline SL1 fallback

At N=2500, direct NumPy-reference versus recursive Numba response gave:

• worst max absolute difference: 5.40e-16
• worst RMS difference: 2.66e-16
• worst max relative difference: 7.02e-11
  • using a 1e-12 denominator floor

Resonance flags matched in all tested cases.

Long-term trajectory validation

A 10,000-step A/B comparison was run using:

• A: Numba vertical coefficients + legacy Numba SEMIANA
• B: Numba vertical coefficients + recursive Numba SEMIANA

Both runs:

• completed all 10,000 requested steps
• completed without solver errors
• recorded 109 cutoff events
• matched the complete cutoff-event step sequence
• retained matching resonance classifications at checkpoints

Final values:

Metric	Legacy	Recursive
Steps	10,000	10,000
Cutoffs	109	109
Final Ns	3,338	3,336
Final sinuosity	1.7199176762	1.7191265744

The final two-point Ns difference was investigated separately.

At the shared cutoff event at step 9,996, the existing strict first-hit neck-cutoff rule saw candidate i0=1249 on opposite sides of the cutoff threshold:

• legacy: pair distance was 4.79e-5 above dslim3
• recursive: pair distance was 6.02e-5 below dslim3

This caused:

• legacy to select (1250, 1275)
• recursive to select (1249, 1276)

and therefore remove 28 versus 30 points.

This was confirmed to be threshold sensitivity in the existing cutoff rule, not a SEMIANA indexing error.

Small floating-point trajectory drift begins before the first cutoff; nonlinear evolution, resampling, and discrete cutoff decisions subsequently amplify that drift.

No claim of bitwise-identical long-term trajectories is made.

Performance

Fixed-size SEMIANA benchmark

Median SEMIANA-response speedup increased strongly with centreline size:

N	Speedup
51	~1.02x
250	~1.9x
1,000	~8–9x
2,500	~25x
5,000	~58–60x

This reflects the reduction from repeated finite-window summation toward approximately linear work per response.

10,000-step evolving simulation

Timing	Legacy	Recursive	Speedup
SEMIANA response	211.5 s	41.4 s	~5.11x
Complete flowfield	230.8 s	60.8 s	~3.80x
Whole solver	549.8 s	389.0 s	~1.41x

These timings are machine-specific and are included as indicative performance measurements.

Public selector validation

After switching the public Numba default, a 500-step wiring comparison was run between:

• public default Numba
• explicit recursive strategy

Both runs ended with:

• Ns=1000
• zero cutoffs
• identical sinuosity
• identical resonance flag
• zero differences in:
  • x
  • y
  • s
  • curvature
  • U
  • tracked scalar states

This confirms the public serial Numba path routes to the recursive implementation.

Tests

• Full pytest -q: passed
• Focused Numba tests: passed
• Ruff on changed files: passed
• git diff --check: passed

No scientific parameters, geometry rules, cutoff rules, tolerances, or model defaults were changed.