Fix filter test/doc claims: retracted DF1 limit-cycle rationale, notch-depth overreach, stale drive-branch wording

This commit is contained in:
2026-07-30 10:56:25 -04:00
parent d2364eb5ac
commit 3cb6b9de21
6 changed files with 182 additions and 140 deletions
+9 -4
View File
@@ -90,10 +90,15 @@ persisted field lands on it rather than on the SEM leg.
and LP **together** across the whole sweep, `bp == 0` throughout. The notch is not tuned in:
HP and LP sit at exactly +90° and 90° at the corner, so equal weights cancel there by
construction. Here the corner magnitude deliberately goes to **zero** at the centre —
measured worst case 88 dB across every rate/cutoff/Q, typically 110 to 145 dB. The fold
makes that structural rather than a runtime near-miss: `m2 = lp - hp` is **exactly** `0.0f`
at the centre, because `cos` and `sin` of π/4 differ by about an ulp of *double*, nine
orders below float's spacing there, so they narrow to one float.
measured worst case 88 dB on the shipped `{250, 1000, 4000}` Hz cutoff grid, typically 110 to
145 dB. Over the full control range (20 Hz 20 kHz, Q 0.1 10) the worst residual is
shallower — 69.8 dB at 192 kHz / 30 Hz / Q=10 — from float conditioning in the folded
`x k·v1` term as `fc/sr → 1e-4` at high Q; it is Q-dependent (Q=0.1 holds 110 dB everywhere)
and still an excellent notch, not a broadband defect. `test_filter.cpp`'s null test covers this
full range with a Q-scaled threshold rather than the flat 74 dB the shipped grid alone would
justify. The fold makes the centre's cancellation structural rather than a runtime near-miss:
`m2 = lp - hp` is **exactly** `0.0f` at the centre, because `cos` and `sin` of π/4 differ by
about an ulp of *double*, nine orders below float's spacing there, so they narrow to one float.
SEM's zero is at the **notch frequency**, not a broadband level sag — off the corner the pair
is still equal-power, so neither law's legs dip. Measuring that requires dividing by each
@@ -11,7 +11,9 @@ namespace reasampler::instrument::engine::filter {
//
// Three properties are load-bearing and none of them are tuning:
// - depth == 0 makes this ALGEBRAICALLY the identity (x / sqrt(1) == x, exact in IEEE), so
// drive = 0 is bit-exact linear with no branch and no special case on the hot path.
// drive = 0 is bit-exact linear whether or not the caller special-cases it. (voice_filter.h
// gates the call on drive != 0 anyway, but as a perf optimization, not because correctness
// needs it.)
// - |softLimit(x, d)| <= |x| for every d, so dropping it into the resonance state update can
// only ever shrink the state. The filter therefore cannot gain energy from the drive stage:
// stability at any Q and any cutoff is structural, not a tuned margin, and it can never