Cl Hill form is monotonic, so it cannot represent the measured lift peak near S~0.5

[cvrt-jh]

Description

Split out of #218 / #229 so it doesn't expand that PR.

ballistics.py models lift as a saturating Hill function:

CL_SATURATION = 0.32
CL_HALF_SP = 0.15
# Cl = CL_SATURATION * Sp / (CL_HALF_SP + Sp)

That form is monotonic increasing and asymptotically flat. Measured golf-ball Cl is not: it rises, peaks around spin ratio S ≈ 0.5, then falls. So above roughly S ≈ 0.35 no choice of the two constants can match reality — the shape is wrong, not the numbers.

This is measurable on the capture already in the repo. Same 24 shots, same RK4 integrator, same resolve_launch/simulate path — the only thing changed is the Cd/Cl functional form, each fitted to its own optimum:

form	OVERALL	driver	7-iron	pitching wedge
current: Cd = a+bS, Cl = c·S/(d+S) (4 param)	3.97	1.75	2.96	6.26
quadratic: Cd = a+bS+cS², Cl = d+eS+fS² (6 param)	1.99	1.07	0.98	3.33

Roughly half the overall error, and it nearly halves the wedge column — which is exactly where #229 stays weak. Wedges in that capture sit at Sp 0.376-0.632, i.e. right where the Hill form flattens but real Cl is peaking and turning over.

Two independent reasons to think the quadratic is the right shape rather than just more parameters:

1. Published models use it. Ferguson, McNally & McPhee (2022, ISEA 14, open access) fit exactly Cd = a+bS+cS², Cl = d+eS+fS² to N = 1040 shots (GCQuad launch conditions + FlightScope X3 carry/apex/offline, Titleist Pro V1, S = 0.02-0.75) and report 2.51 m / 2.74 yd carry MAE. Quintavalla (2002) and Smits & Smith (1994) are the other standard references, both non-monotonic in S. Lyu/Kensrud/Smith (2018, ISEA) also state outright that lift "had a non-linear dependence on spin (fit with a 2nd order polynomial)".

2. Fitting it here reproduces their constants. Fitted to our 24 shots the quadratic gives [0.1346, 0.9438, -0.7351, 0.0548, 1.2258, -0.9196], against their published [0.1304, 0.9287, -0.8259, 0.0504, 1.2031, -1.1490] from 1040 shots. Two independent datasets converging on nearly the same coefficients is decent evidence the form is right and the fit isn't noise.

What did you expect to happen?

Not necessarily a change — mainly a decision, since it's architectural and I'd rather ask than assume.

Option A — switch Cl/Cd to 2nd-order polynomials in S. Better accuracy, aligns with the literature the file already cites, keeps everything else (RK4, Magnus geometry, spin decay) untouched. Costs: 4 constants become 6, and Cl must be clamped at >= 0 since a downward parabola eventually goes negative outside the fitted range.

Option B — leave it. Defensible if you'd rather not widen the parameter count on 24 shots of ground truth, and the current form is fine for driver/iron Sp.

Related structural gaps I noticed while looking, listed only so they're on the record — not proposing to fix them here:

• No Reynolds-number dependence anywhere (grep -ci reynolds ballistics.py = 0). Ferguson, Quintavalla and Smits & Smith all include it; Lyu et al. measured Cd falling 0.5 -> 0.2 across the drag crisis. Cd = f(S) alone conflates speed and spin.
• No moment coefficient. Spin decay is a fixed 4%/s exponential rather than aerodynamic; Ferguson fits C_M = g·S.
• Spin axis is constant through flight — no precession. Fine for carry, matters for curve.

Happy to implement whichever you prefer, or to leave it as a documented limitation. Worth noting these need refitting together if #169 (altitude air density) lands, since air density and the coefficients trade off against each other.

Area

Ballistics / physics model

[cvrt-jh]

Update, now that #229 is merged. Thanks both for the review and the merge.

We ran the five-session archive @johnpacino shared against the coefficients that just landed, and we think it points toward Option A here. Nothing below argues against what was merged, which is a clear improvement. The question is whether the 4-constant Hill form is the right ceiling to stop at.

The archive is 417 shots across driver, 5i, 7i, 9i and sand wedge, against the 24 shots this issue was raised on.

Method

For each shot we take the TrackMan launch conditions (ball speed, launch angle, spin rate, spin axis), run openflight.ballistics.simulate() unchanged, and compare the result to TrackMan's own measured carry and apex.

The only difference between the two arms is the body of _cd and _cl. Integrator, spin decay, ball constants and everything else are identical.

Inputs, so the run is reproducible:

• Spin axis comes from the per-stroke SpinAxis field (on 406 of 417 shots, median magnitude 6.7 deg). Passing 0 instead costs about 0.6 yd RMSE.
• Air density is computed per session from Environment.Altitude and Temperature via the standard ISA relation. Altitude ranges 0 to 476 ft across the sessions and ShowNormalizedData is false, so these are raw numbers under real conditions and one fixed rho is wrong for all five.
• Shots are classified with the rule your 2026-07-22 export already encodes: |LaunchDirection| >= 8 shank, LaunchAngle < 8 skull. Recomputing reproduces your labels 25 of 25, so the definition is yours, not a filter we invented.
• Reference values are TrackMan Carry and MaxHeight, which are metres in the export while the comparison files are yards. That cost us a debugging round.

Result on 279 clean shots

Ferguson et al. (2022) published quadratics exactly as printed (a=0.1304, b=0.9287, c=-0.8259; d=0.0504, e=1.2031, f=-1.1490):

	Hill (as merged in #229)	Ferguson quadratic
carry RMSE	3.48 yd	1.91 yd
carry MAE	2.79 yd	1.58 yd
bias	-0.47 yd	-0.27 yd

Per club, Ferguson is ahead in all five (n, Hill RMSE, Ferguson RMSE): 9i 176 / 3.22 / 1.61, driver 33 / 4.10 / 1.90, 5i 32 / 3.35 / 2.58, 7i 30 / 3.90 / 1.96, SW 8 / 4.73 / 3.82.

Bootstrap over 2000 resamples: Ferguson ahead in 2000/2000, RMSE gap 95% CI 1.28 to 1.86 yd. The gap does not look like sampling noise, though a bootstrap only speaks to this dataset.

It also holds across shot quality (RMSE, Hill vs Ferguson): good 3.48 / 1.91, unknown 5.63 / 2.55, skull 12.08 / 3.61, shank 7.87 / 2.76, all 416 shots 4.83 / 2.20.

Worth flagging: an earlier run of ours had Ferguson losing badly on shanks. That was our own spin-axis bug, not the model. With the measured axis fed in it reverses, and we would otherwise have reported the opposite conclusion to you.

The apex comparison

MaxHeight is on every stroke, and as far as we can tell nothing in OpenFlight has ever been fitted against apex, which makes it an independent target:

model	apex RMSE	apex MAE	bias
pre-#229 constants	5.23	4.80	-4.80
Hill as merged in #229	4.41	4.10	-3.99
Ferguson quadratic	1.00	0.63	-0.61

The bias column is what interests us. Both Hill variants sit about 4 yd low, consistently rather than randomly, and #229 only moved that from -4.80 to -3.99 while cutting carry error by two thirds. Our reading is that the saturating form cannot supply enough lift through the mid-Sp range where irons live, so the re-fit compensates on carry by trading against drag rather than fixing the curve shape. We could be over-reading one metric, but matching carry and apex together is harder to hit by coincidence than carry alone.

These coefficients are external and were never fitted to this data, so it is a held-out comparison against a published N=1040 fit, not anything we tuned.

The mechanism matches what this issue described. Hill saturates and is monotonic; Ferguson peaks at Sp = 0.524 then falls. Above Sp ~ 0.15 Hill under-predicts Cl by 0.011, rising to 0.129 at Sp = 0.55.

What this does not establish

• The high-Sp end is thin. Only 13 clean shots above Sp 0.35, from two clubs, 8 wedges total. That is exactly where the forms diverge most, so we would not claim the peak location is confirmed. The result rests on the 0.20-0.35 band (174 shots) and on apex.
• One player, one ball, one launch monitor. Five sessions beats one, but it is still a single source.
• Carry and apex only. Lateral dispersion, landing angle and hang time are all in the exports and none are validated here.
• No re-fit attempted, which might beat Ferguson's constants or might just overfit.

Recommendation

We lean toward Option A, Cd and Cl as second-order polynomials in S, 4 constants to 6. Two ways to land it:

1. Adopt Ferguson's published constants directly. Zero fitting, external provenance, 1.91 yd carry and 1.00 yd apex on shots it never saw.
2. Re-fit the quadratic against this archive. Possibly better, but the constants would then be fitted to the data we validate on, so it needs a holdout split.

We prefer 1, and would only do 2 alongside a committed holdout fixture.

Happy to open the PR either way, or to leave it if you would rather keep the 4-constant form and document the limitation. Small change to ballistics.py, and the carry-accuracy budget test from #219 already covers the regression surface.

Reproducible from the archive with three scripts, happy to share them. Controls to check the harness can actually fail: a zero-lift monkeypatch moves carry RMSE to 57.14 and apex to 16.66, both restoring exactly. The join is carry-cross-checked on every row, 416 of 417, no mismatches.

---

AI disclosure: we used Claude to write the comparison scripts and run the statistics. We checked the harness against the module, verified the numbers, and found the spin-axis bug noted above ourselves. Conclusions and recommendation are ours.