test_forwarddiff.jl's POLAR_MATRICES check flakes at ~4%, and the oper - #292

TL;DR

The POLAR_MATRICES check compares forward AD against a finite difference on a polar table that is piecewise-linear with knots every 5°, and its 1e-5 step spans a knot whenever a panel's converged alpha lands within ~3e-4° of one — which is how CI got 0.0400. Converging the LOOP solve to 1e-11 and taking the difference at 1e-8 keeps the secant inside one cell everywhere I could put it, exactly on a knot included, and the bound goes from 1e-3 to 1e-4 because the measured floor is now 7.1e-8.

What is actually discontinuous

Nothing in VSM. The INVISCID sibling in the same file reads norm_fwd = 11.110746084832735, norm_fd = 11.110746104003324 on this box and the same 17 digits in the ubuntu-1.12-coverage job that failed the POLAR check on #285 — so the solver, the geometry pipeline and both backends are bit-reproducible, coverage build and all.

What is discontinuous is the model the check differentiates. build_interps (src/panel.jl:225) hands linear_interpolation a 5-knot alpha grid, so cl(alpha) is a broken line, and a forward difference straddling one of those corners measures the average of two slopes while forward AD takes one of them. Bisecting the freestream alpha until panel 3's converged alpha sits on the 10° knot, everything else exactly as the test has it:

CI's 0.04001429189872729 sits inside that range, and 300x of margin sits just outside it. Whether a given run lands in the window is decided by the NeuralFoil fixture, which is redrawn every run and does not come out the same twice — that part is #291, and it is why this cannot be fixed by choosing a better operating point.

The two knobs that decide how wide the window is

The step, obviously: the window scales with it. But also rtol, because the LOOP loop stops on normalized_error < rtol (src/solver.jl:1080), so the iteration count is a step function of the input and the converged alpha carries the leftover of whichever iteration it stopped on. Sampling CFz along theta_2 in 2000 steps of the test's own 1e-5, the one iteration-count change in that span moves the finite difference by 1.45e-4 — normalised, 1.05e-4, a tenth of the whole 1e-3 budget, from a step the test does not control. At rtol=1e-11 that staircase is gone (worst jitter 5.3e-6, and that is curvature). Until the solve is that tight, the panel alpha itself wobbles by ~1e-5°, so shrinking the step alone does not help: it is the pair that works.

Scanned across the same knot, offset in degrees of freestream alpha:

The chosen pair never leaves 2.2e-08..7.1e-08 anywhere on that scan. The bound follows: 1e-4 is 1400x above the measured floor and still ten times above the worst the exit staircase can contribute at this step, and it is a tightening, not a loosening.

What I did not do

I did not move the operating point. #287 is right that 320e756's defl_rad reached nothing — delta is exactly 0.0 for every panel, but at an exact delta knot the alpha-direction slope is the same from either cell, and delta is not a differentiated input, so a delta knot cannot produce this. Moving the freestream alpha to maximise clearance from the alpha knots would buy about 1° of margin against a fixture that moves panel alphas by 0.1–0.2° per draw, which is a smaller factor than it sounds and would need moving again the next time the fixture moves.

The INVISCID testset keeps its 1e-5 step and 1e-3 bound: it has no table, so no knot, and it has never flaked.

rtol=1e-11 costs 685 LOOP iterations against 390, out of max_iterations=1500 — and 671–685 across ±10% on every Cl, twenty times the fixture's own spread, so the halve-the-relaxation retry stays far away; warm, the file's wall time is 0.1 s either way, so the CI figure for this testset is compilation. If #284 lands and rtol starts meaning the unrelaxed residual, every number here only improves.

Verification

• Reproduced first: unchanged file at the knot-adjacent operating point (12.810477774611°, panel 3 alpha 9.99995111°) → Expression: rel_err < 0.001 / Evaluated: 0.10032484514560956 < 0.001
• test/solver/test_forwarddiff.jl red before that change, green after at the same operating point (7/7), and green at the committed operating point (7/7, juliaserver, 49.7 s cold)
• Local full suite: agent ci-local — see below · GitHub CI: see below
• Up to date with main (branch parent is 3f75701) · docs not run — no public symbol touched · no REUSE lint in this repo · jetls not installed on this box
• Benchmark: n/a
• Risk: exactly on a knot the check still relies on forward AD and a forward difference choosing the same side of the corner; that held at every offset I measured, but it is a coincidence of convention rather than something the test asserts.

Scope

+5 / −4 in test/solver/test_forwarddiff.jl and nothing else. Not stacked: #285 changes only gamma_loop!'s NONLIN branch. Opened #291 for the fixture that is redrawn every run, which this does not fix.

Closes #287 · task VortexStepMethod.jl-287