UpstreamDrift Physics Models: Ball Flight, Impact, Putting and Injury
Plain-Language Summary
Pinned UpstreamDrift defaults for putting, ball flight, impact, bunker, grip, metrics, and injury heuristics at a fixed commit, compared with AffineDrift derivations. Site–code disagreements are flagged with tracker links rather than silently rewriting textbook equations.
Key Takeaways
- UpstreamDrift putting roll applies a five-sevenths scaled slope gravity term in pure roll (skid still uses full g), matching the site’s rolling law at the pin reviewed here.
- Hole capture in code follows a chord bound near 1.64 m/s centre speed, not the finite-ball or Penner forms on the site.
- Default ball-flight APIs differ from the Naruo quartic treatment on the impact reference page; carry can spread tens of yards across registered models.
- Injury heuristics in code use discrete spinal load bands that do not match ch. 21 spine derivations verbatim.
- MISMATCH callouts link code-side remediation to UpstreamDrift #15010 and #15011 without changing site derivations here.
State: Implementation inventory. Every equation below is quoted from UpstreamDrift source at commit 4a1c5f43 (protected main on 2026-11-16). CI re-verifies this pin with python3 -m scripts.check_upstreamdrift_physics_models. AffineDrift theory pages (Impact Mechanics and Ball Flight, The Physics of the Rolling Putt, Simulating the Green, The Physics of Golf ch. 21) remain the site’s derivations. Where they disagree with this inventory, the disagreement is flagged with a tracking link. Code-side corrections are tracked in UpstreamDrift #15010 (ball flight, putting, impact) and UpstreamDrift #15011 (injury heuristics). This page addresses AffineDrift #5624.
Pin and How to Read the Tables
| Shorthand | Path under UpstreamDrift |
|---|---|
| SP | src/shared/python |
| Rust kernel | rust_core/upstream-physics/src |
MISMATCH rows name both sides and link a tracker. CODE ONLY rows document behaviour with no conflicting site derivation yet.
Putting and Green Simulation
Roll Acceleration on a Slope
In SP putting_dynamics/solver.py, _derivative starts from the small-slope gradient \(-g\,\nabla h\), then branches by mode:
- SLIDE: full in-plane gradient \(g_{x,y} = -g\,\nabla h\).
- ROLL: the same components scaled by \(5/7\) (rigid-sphere rolling inertia partition, #15010).
The site rolling law in putting-roll-models uses \(\dot{\mathbf v} = \mathbf g_\parallel/(1+\alpha) - a_0\cos\beta\,\hat{\mathbf v}\), which is the same \(5/7\) gravity partition for pure roll when \(\alpha=2/5\).
Pure-roll slope forcing in putting_dynamics now matches the site’s \((5/7)g\) rolling law. Skid still uses the full gradient. The module-level docstring still states -g grad h without the roll partition — an UpstreamDrift documentation gap, not a runtime disagreement.
Hole-Capture Speed
Centre capture bound in code (capture_speed_mps):
\[ v_{\mathrm{capture}} = 2\sqrt{R_h^2 - b^2}\,\sqrt{\frac{g}{2r}}, \]
with HOLE_RADIUS_M = 0.054 m and ball radius from GOLF_BALL_RADIUS_M (~0.021335 m). At \(b=0\) this is ~1.64 m/s.
| Rule | Centre speed | Off-centre law | Where documented |
|---|---|---|---|
UpstreamDrift putting_dynamics |
~1.64 m/s | chord \(\propto\sqrt{R_h^2-b^2}\) | this page; solver.py |
| AffineDrift finite-ball construction | ~1.31 m/s | clearance \(D_h - R\) | putting-roll-models |
| Penner historical fit | ~1.63 m/s | \(\approx 1.63[1-(b/R_h)^2]\) | same companion |
| Tools / explorer proxy | ~0.82 m/s effective radius | speed-threshold proxy | green-simulation §4 |
The putting tile runs the chord bound above, not the finite-ball or Penner forms on the site. Tracker: UpstreamDrift #15010.
Other putting_dynamics Defaults
Documented at the pin (tile putting_green in src/config/models.yaml):
| Quantity | Default | Source module |
|---|---|---|
| Static hold | mu_static = 0.08 |
friction.py |
| Sliding friction | mu_slide = 0.40 |
friction.py |
| Roll onset speed | \(v_{\mathrm{roll}}=(v+0.4s)/1.4\) | solver.py (_apply_roll_onset) |
| Grain law | \(\mu \leftarrow \mu[1 - g_{\mathrm{str}}\cos(\theta_v-\theta_{\mathrm{grain}})]\) | friction.py |
| Speed-dependent roll | \(\mu_r(v)=\mu_{r0}(1+k_v v)\), default \(k_v=0\) | friction.py |
| Stop speed | v_stop_mps = 0.005 |
friction.py |
| Airborne bounce COR | GREEN_RESTITUTION = 0.78 |
physics_constants.py |
| Integrator | RK4, DT_S = 0.002 s |
solver.py |
| Stimp → \(\mu_r\) | \(v_{\mathrm{release}}=1.83\) m/s, \(\mu_r=v_{\mathrm{release}}^2/(2gS)\) | friction.py |
Turf-condition multipliers (dry 0.9 … frosted 1.4) live in SP putting_dynamics/turf.py and surfaces.py. See Simulating the Green §4.1 for a provider comparison column.
Stimpmeter Ramp Release
Closed form at zero groove half-width (stimpmeter.py):
\[ v = \sqrt{\frac{2 g h}{1 + \frac{2}{5}(R/r_{\mathrm{eff}})^2}}}, \qquad r_{\mathrm{eff}}=\sqrt{R^2-b^2}. \]
Default \(b=0\) gives ~1.911 m/s; the friction law still calibrates against the measured 1.83 m/s release. The friction.py docstring quotes V-groove contact radius ~\(0.87\,r\); putting-roll-models derives \(r_c/R\approx 0.9537\) from a 145° groove.
Document the 1.83 / 1.885 / 1.911 m/s chain explicitly when comparing Stimp to roll distance. Tracker: UpstreamDrift #15010.
Ball Flight and Atmosphere
Registered Python Flight Models
SP physics/flight_models.py exposes a registry (FlightModelRegistry). Coefficient sets:
Waterloo–Penner (constant spin, no decay):
\[ C_D = 0.21 + 0.05 S + 0.02 S^2, \qquad C_L = \min\left(0.155,\; 0.70\, S^{0.645}\right), \]
with \(S=\omega r/|{\mathbf v}_{\mathrm{rel}}|\) (spin ratio). Provenance string in code cites Penner (2003) and TrackMan calibration PRs (#5845, #7530).
MacDonald–Hanzely: constant cd=0.225, cl=0.20, exponential spin decay `d/dt = -0.05,$.
Constant-coefficient catalogue (each optional spin decay in \(/s\)):
| Name | \(C_D\) | \(C_L\) | Spin decay |
|---|---|---|---|
| Nathan | 0.22 | 0.24 | 0.03 |
| Ballantyne | 0.20 | 0.18 | 0.02 |
| J. Cole | 0.23 | 0.22 | 0.04 |
| Rospie DL | 0.21 | 0.19 | 0.03 |
| Charry L3 | 0.24 | 0.21 | 0.05 |
Rust Trajectory Kernel
rust_core/upstream-physics/src/aerodynamics.rs: drag-crisis $C_D$ via tanh on Reynolds number; lift cap MAX_LIFT_COEFFICIENT = 0.26; Penner lift \(0.70\,S^{0.645}\). ball_flight.rs integrates \(d\omega/dt = -k\omega\) with \(k\) from SPIN_DECAY_RATE_S (0.05 /s, source string “Trackman Data” in physics_constants.py).
Impact mechanics develops Naruo–Mizota–Shimozono quartic \(C_D\), \(C_L\) and a torque-based spin decay; none of the registry models or the Rust kernel implements that tuple as the default API path. At 167 mph, 10.9°, 2686 rpm the review recorded ~22 yd carry spread across Rust, Waterloo–Penner and constant-coefficient models (#5624). Tracker: UpstreamDrift #15010.
Atmosphere Density
SP/physics/atmosphere.py:
\[ T(z) = T_0 - L z,\quad p(z) = p_0\left(\frac{T(z)}{T_0}\right)^{g/(R_{\mathrm{specific}} L)},\quad \rho = \frac{p}{R_{\mathrm{specific}} T}. \]
Argument semantics: temperature_c is the sea-level reference temperature; it is lapsed to altitude. It is not the local air temperature at the tee unless altitude is zero.
Calling air_density(1600, 30) returns the density for ~19.6 °C at 1600 m, not 30 °C at altitude (#5624 verification). Document this when wiring environmental UI fields.
Impact and Gear Effect
SP physics/impact_model/ default ImpactParameters:
| Parameter | Code default | Typical site example |
|---|---|---|
cor |
0.83 (DRIVER_COR) |
0.8–0.9 in examples; 0.83 in ch. 28 |
friction_coefficient |
0.4 | 0.18 in impact reference |
contact_duration |
0.0005 s | 0.45 ms in ball_impact.py; 0.45–0.5 ms on site |
clubhead_moi |
\(4.5\times 10^{-4}\) kg·m² | \(4\times 10^{-4}\) in site examples |
| Rigid-body solve | scalar effective mass \(1/(1/M + r^2/I)\); club \(\boldsymbol\omega\) unchanged | full inertia-tensor impulse in site derivation |
Gear-effect add-on (impact_model/utils.py, heuristic):
\[ \omega_h = \mathrm{gear\_factor}\, h_{\mathrm{offset}}\, |{\mathbf v}|\, 350\ \mathrm{rad\,s^{-1}}, \quad \omega_v = \mathrm{gear\_factor}\, v_{\mathrm{offset}}\, |{\mathbf v}|\, 150\ \mathrm{rad\,s^{-1}}, \]
default gear_effect_factor = 0.5. The site impact reference states that a fixed universal gear ratio is not justified without geometry and calibration.
Off-centre centred-impact agreement does not extend to gear spin or friction defaults. Tracker: UpstreamDrift #15010.
Injury Screening Module
SP injury/spinal_load_analysis.py applies banded labels to heuristic loads:
| Metric | Safe | Caution | High risk |
|---|---|---|---|
| Compression | \(<4\times BW\) | \(4\)–\(6\times BW\) | \(>6\)–\(8\times BW\) |
| Shear | \(<0.5\times BW\) | \(0.5\)–\(1.0\times BW\) | \(>1.0\)–\(1.5\times BW\) |
| X-factor stretch | \(<45^\circ\) | \(45\)–\(55^\circ\) | \(>55\)–\(65^\circ\) |
| Transition time | \(>0.30\) s | \(0.20\)–\(0.30\) s | \(<0.15\)–\(0.20\) s |
Module docstrings call these “evidence-based”; The Physics of Golf ch. 21 argues that body-weight multiples are not universal tissue-failure thresholds.
Treat tool outputs as a heuristic screen, not a clinical decision. Tracker: UpstreamDrift #15011.
Bunker, Grip and Metric Definitions (Shorter Inventory)
BunkerShot3D (G12)
src/bunkershot3d/: resistive-force / Drucker–Prager / MPM tiers. Solver envelope marks many clubhead-speed cases BEYOND_VALIDATION when Froude number exceeds literature limits (~0.4 in 3D-RFT addendum; code runs ~25–113 in cited review). See docs/bunkershot3d/README.md in UpstreamDrift; no AffineDrift article yet.
Grip Contact (G14)
SP grip_contact/: bushing surrogate stiffness, R_EFF_M = 0.04 m lever for rotational stiffness, design_damping targets \(\zeta = 0.7\) (damping.py), friction bands in friction_band.py. Defaults are engineering placeholders, not fitted (module docstring). Tile grip_wrench_plots. Site wrench theory: two-hand wrench companion.
Analysis Metrics (G15)
| Name in UI | Code definition | Caveat |
|---|---|---|
| X-factor stretch | max \(\lvert d/dt\rvert\) of proxy in kinematic_sequence.py vs max Euler-yaw difference in spinal_load_analysis.py |
same label, different definitions |
| “Efficiency” | peak club KE / max total energy (energy_metrics.py) |
not a standard mechanical efficiency |
Site–Code Numeric Crosswalk
Values below are defaults at the pin; see PARAMETERS.md for the site symbol table extended with UpstreamDrift columns.
| Quantity | AffineDrift site (typical) | UpstreamDrift physics_constants / runtime |
|---|---|---|
| \(g\) | 9.81 m/s² | 9.80665 m/s² |
| Ball mass | 0.0456–0.04593 kg | 0.04593 kg |
| Ball radius | 0.02135–0.021335 m | 0.021335 m (Python); 0.02135 m some Rust paths |
| \(\rho_{\mathrm{air}}\) | 1.2–1.225 kg/m³ | 1.225 kg/m³ at sea level |
| Drag / lift laws | Naruo quartic | Penner power law + caps; Reynolds drag crisis in Rust |
| Spin decay | \(C_M\) or \(\beta V/R\) forms | \(k=0.05\)/s exponential in Rust / MacDonald–Hanzely |
| Head MOI | \(4\times 10^{-4}\) kg·m² | \(4.5\times 10^{-4}\) kg·m² |
| Face friction | 0.18 (example) | 0.4 default |
| Hole radius | 53.975 mm | 54 mm |
| Capture (centre) | 1.31 / 1.63 m/s (site rules) | ~1.64 m/s (code chord) |
| Roll slope gravity | \((5/7)\mathbf g_\parallel\) in derived roll law | \((5/7)\mathbf g_\parallel\) in ROLL; full \(\mathbf g_\parallel\) in SLIDE |
| Critical grade @ Stimp 10 | ~7.84 % (site formula) | ~7.84 % (\(=(7/5)\mu_r\) moving threshold at Stimp 10; static rest uses mu_static) |
Citation
@online{olson2026,
author = {Olson, Dieter},
title = {UpstreamDrift {Physics} {Models:} {Ball} {Flight,} {Impact,}
{Putting} and {Injury}},
date = {2026-11-11},
url = {https://affinedrift.com/articles/upstreamdrift-physics-models.html},
langid = {en},
abstract = {Implementation inventory for shared UpstreamDrift physics
modules at commit 4a1c5f43: putting roll and capture rules,
registered flight models and Rust kernel parameters, gear-effect and
impact defaults, injury load bands, and ancillary bunker and metrics
paths. Each row cites module locations and records mismatches
against AffineDrift site models with links to AffineDrift \#5624 and
UpstreamDrift \#15010/\#15011.}
}