Simulating the Green
A putting simulator links the stroke, the green, and the hole. Each link needs a model. How does the ball start sliding and rolling? How does the green change its motion? Which arrivals count as holed? A convincing animation does not show that these models predict a real putt.
The Map Is Part of the Physics
Local tilt steers the ball, and turf resistance slows it. The ball also spins, so some gravitational energy goes into rotation. A model that ignores rotation can draw the wrong break even with an accurate elevation map.
Why Run Many Putts?
One run answers what happens for one set of inputs. Many runs ask how outcomes change when start line, speed, or surface vary. Those changes can turn a modeled make into a miss, or the reverse. To predict a player, the input spread and the physical model each need independent checks against measurements.
Scope and Intent
The Physics of the Rolling Putt develops the mechanical assumptions behind skid, rolling resistance and hole capture. This companion asks how to implement such a model, how surface and stroke uncertainty interact, and what the project’s existing software actually computes. The distinction matters: agreement between two programs can establish reproducibility of an approximation while both programs retain the same physical error.
The objective is an intelligible chain from delivery → contact → launch → surface motion → capture or leave → scoring consequences. A change upstream alters the input to every later stage. Improving one stage therefore requires checking its interfaces, not merely making that stage more elaborate.
Use a world frame with \(x\) forward along the target line, \(y\) up and \(z\) right. Bold vectors below are three-dimensional unless a horizontal heightfield coordinate is specified. Let \(R\) be ball radius, \(m\) mass, \(I=\alpha mR^2\) its isotropic inertia and \(\mathbf n\) the upward plane normal. The illustrative homogeneous sphere has \(\alpha=2/5\); a real ball’s inertia is a property to identify.
The measured level-green roll-out calibration is \(a_0=v_s^2/(2L_s)\), assuming pure rolling and constant deceleration over distance \(L_s\). With the conventional \(v_s=1.83\) m/s and a reading \(S\) in feet, \(a_0\approx5.49/S\) m/s². This is a conditional calibration, not an exact release-speed derivation from ramp geometry. The companion distinguishes the groove geometry and the empirical convention. The fixed-plane derivations below assume continuous contact and neglect aerodynamic loading, spin about the normal, and deformation except through an effective resistance law.
1. Ball Dynamics and Mode Changes
1.1 Sliding Requires a Contact-Point Velocity
On a fixed plane, the slip at the contact point is
\[ \mathbf u=\mathbf v-R\boldsymbol\omega\times\mathbf n, \qquad \mathbf g_\parallel=\mathbf g-(\mathbf g\cdot\mathbf n)\mathbf n. \]
For \(\mathbf u\ne\mathbf0\), an ideal Coulomb sliding model is
\[ \begin{aligned} \mathbf F_t&=-\mu_kN\frac{\mathbf u}{\|\mathbf u\|},\\ m\dot{\mathbf v}&=m\mathbf g_\parallel+\mathbf F_t,\\ I\dot{\boldsymbol\omega}&=(-R\mathbf n)\times\mathbf F_t, \qquad N=mg\cos\beta . \end{aligned} \]
Here \(\beta\) is the plane’s inclination. Friction opposes slip, which need not point along the center velocity. For a straight level putt, define signed forward spin speed \(s=R\omega\) and signed slip \(u=v-s\). Positive slip slows translation and increases forward spin; overspin, \(u<0\), reverses both changes. Treating every \(s\ge v\) state as pure rolling loses this distinction.
With constant sliding friction, no other tangential loads and no reversal of the travel direction during the transition,
\[ \begin{aligned} t_r&=\frac{|v_0-s_0|}{\mu_k g(1+1/\alpha)},\\ v_r=s_r&=\frac{v_0+\alpha s_0}{1+\alpha}. \end{aligned} \]
The familiar \(v_r=5v_0/7\) follows only for the homogeneous sphere with zero initial spin on level ground. It is not a universal transition speed on a side slope. A vector contact law is needed when the slip and travel directions separate.
1.2 Rolling Couples Translation to Rotation
No-slip rolling requires sufficient contact traction. Gravity’s tangential component accelerates translational and rotational motion. To specify resistance, use an illustrative opposing rolling couple with magnitude
\[ \tau_r=m(1+\alpha)R a_0\cos\beta. \]
This normal-load scaling is a modeling assumption chosen to reproduce the level deceleration \(a_0\). For nonzero rolling speed on a fixed plane it gives
\[ \boxed{\dot{\mathbf v} =\frac{\mathbf g_\parallel}{1+\alpha} -a_0\cos\beta\,\hat{\mathbf v}.} \]
Replacing the first term by \(\mathbf g_\parallel\) treats gravity as if it accelerated a sliding point mass. For \(\alpha=2/5\), it overstates the isolated gravitational acceleration by 40%. That percentage does not describe the error in a whole trajectory: resistance, direction and event timing also change.
An energy check makes the coupling visible. Along a downhill line at speed \(v\), the kinetic energy is \(K=\tfrac12m(1+\alpha)v^2\) and
\[ \dot K=mgv\sin\beta-\tau_r v/R. \]
Under this particular couple law, a moving downhill ball accelerates when \(\tan\beta>(1+\alpha)a_0/g\). For \(S=12\) and the conventional calibration, the threshold is approximately 6.5%, rather than 4.7%. A 5% downhill plane still decelerates the moving ball in this model. These are conditional calculations, not a hole-placement standard.
1.3 Events, Rest and Capture Need Separate Rules
Locate transitions within steps. Fixed-step and adaptive integrators can both use event localization. In the straight sliding reduction, a signed \(u=v-s\) can supply a sign-changing event. The norm \(\|\mathbf u\|\) is nonnegative and nonsmooth at zero; ordinary sign-change bisection cannot automatically locate its zero. General sliding-to-sticking transitions require a declared contact algorithm, tolerance and feasibility check, not an unexplained scalar crossing.
An event root can be accurate relative to an interpolated trajectory while the trajectory itself remains inaccurate. Refine the integration and event tolerances together. A small root tolerance alone gives no machine-precision physical event time. Standard sign-change detection may also miss tangencies or multiple crossings within one step; these limitations are stated in the SciPy event documentation. A putt can cross into and out of a hole disc between two outside samples. Bound the step length relative to the feature, inspect the swept path, or otherwise establish that the event cannot be skipped.
Rest is an equilibrium decision. The unit vector \(\hat{\mathbf v}\) is undefined at zero speed. A low-speed numerical threshold is useful for detecting a candidate stop, but permanent rest requires force and moment balance under a separately declared static traction and rolling-resistance law. Sliding static friction by itself does not define the maximum resisting rolling couple. An uphill ball may momentarily reach zero speed and reverse; variable terrain may later flatten. The moving-downhill threshold above therefore neither proves rest stability nor maps all points from which a putt can never stop. Report a time-limit exit separately from rest.
Capture is another approximation. The companion compares a finite-ball free-fall geometry with a separate historical capture fit. In its central, straight-path finite-ball construction, the horizontal budget is \(D-R\), where \(D\) is hole diameter, giving \(v_c=(D-R)\sqrt{g/(2R)}\approx1.31\) m/s for the declared dimensions. This does not establish a universal capture threshold: off-center geometry, rim contact, spin and deformation change the outcome. The full-domain and off-center assumptions are in the companion.
Do not substitute a point-chord formula and call it the same finite-ball calculation. Nor does choosing a lower central speed threshold establish conservative classification for every off-center arrival. A binary capture proxy can miss a true capture and accept an implausible one. A three-dimensional contact simulation offers a different model, whose rim shape, contact law and discretization also need verification and measurement validation. Neither a detailed animation nor a convenient inequality settles lip-outs by itself.
2. The Surface Is an Input to the Dynamics
2.1 Geometry and Approximation Level
| Representation | Useful Role | Main Qualification |
|---|---|---|
| Tilted plane | Analytic checks and local approximations | Cannot represent changing slope |
| Analytic curved patch | Controlled crowns, tiers and sensitivity studies | Selected shape need not match a measured green |
| Heightfield grid | Measured elevations on a defined domain | Derivatives, measurement error and unresolved features matter |
| Triangular surface | Irregular sampling and boundaries | Piecewise planar gradients jump at edges |
For a small-slope heightfield \(y=h(x,z)\), the horizontal component of gravity projected into the tangent plane is approximately \(-g\nabla h\). Insert the rolling-inertia factor when using this in the rolling equation. Applying the fixed-plane equation locally on a curved surface is an additional reduction. A more complete model accounts for the changing contact frame, the center’s radius-offset surface and curvature-dependent normal acceleration; \(N=mg\cos\beta\) alone need not hold at speed. Sharp features can also violate continuous contact.
The right representation depends on the required output accuracy. A local plane can be useful on a real green. A finer mesh can be less useful if its derivatives mainly express survey noise.
2.2 Interpolation Is Not Measurement Correction
Bilinear interpolation makes height continuous on a consistent grid, but generally leaves gradient jumps at cell boundaries. In a one-dimensional slice with heights 0, 0.01 and 0.03 m at 0.1 m spacing, the adjacent slopes are 0.1 and 0.2 although the shared height agrees. A piecewise model can be integrated, but boundary crossings and observed convergence need attention.
Bicubic patches do not automatically produce a globally \(C^1\) surface: neighboring derivatives must be constructed consistently. Suitable splines can provide smoother derivatives, but can also overshoot measured heights. Smoothness alone neither removes noise nor proves a numerical method’s advertised order across interfaces. Check the actual interpolant, surface boundaries and outputs under refinement instead of declaring one interpolation family universally correct.
Exact interpolation preserves measurement errors at the nodes. A simple height-difference slope estimate magnifies independent elevation uncertainty approximately as \(\sqrt{2}\sigma_h/\Delta\), for spacing \(\Delta\) and node error standard deviation \(\sigma_h\). Correlated survey errors require their covariance. Smoothing or regularized fitting can reduce noise at the cost of bias and lost features; document that trade-off and retain an uncertainty estimate.
There is no universal decimetre grid that captures every relevant feature. A narrow imperfection can change contact or an arrival near the rim, especially at low speed. Conversely, unresolved texture can be represented statistically if that representation is calibrated. Compare predicted path, arrival speed and classification while varying grid spacing, smoothing, integration tolerance and plausible elevation errors. Declare what happens outside the measured domain; a flat continuation is a computational boundary condition, not measured terrain.
2.3 Useful Maps Have Defined Meanings
A map of local downhill acceleration under a chosen resistance law is a local diagnostic. Global reachability depends on launch state, direction, later terrain, boundaries and the stopping rule. It requires trajectory or reachability analysis.
An aim-and-pace chart records the input set that the model classifies as captured. Its raw area has units such as degrees·m/s and changes by \(180/\pi\) when angle units change from radians to degrees. Calling that area intrinsic difficulty is therefore incomplete. Define a common normalized measure or integrate a specified player’s joint input distribution over the capture set. Pace and aim can be correlated; independent spreads are an assumption, not a consequence of the chart.
3. Uncertainty Changes the Question
3.1 From Capture Sets to Conditional Probabilities
Let \(\boldsymbol\theta\) collect uncertain launch inputs and declared surface parameters, and let \(C(\boldsymbol\theta)\) be the model’s capture indicator. For a joint density \(f\), the conditional modeled make probability and an independent Monte Carlo estimate are
\[ \begin{aligned} p_{\rm model}&=\int C(\boldsymbol\theta)f(\boldsymbol\theta)\,d\boldsymbol\theta,\\ \hat p&=\frac1N\sum_{i=1}^{N}C(\boldsymbol\theta_i). \end{aligned} \]
A nominal deterministic result is not a universal probability ceiling. In a synthetic one-dimensional capture interval \([-1,1]\), a nominal input of 1.5 misses. Equal-probability perturbations of \(-1\) and \(+1\) have zero mean but yield a 50% make rate. Conversely, noise can spoil a nominal make. An omitted disturbance has no guaranteed direction of bias.
Sampling launch speed and start line requires no new trajectory physics, but it does require defensible distributions. A stroke-level model can instead perturb face, path, speed and strike location, then propagate their joint effect through impact. Do not perturb both a cause and its downstream consequence independently unless that is the intended uncertainty model. A green-speed parameter shared across a session is different from a fresh independent error on every shot; a fixed footprint is different from newly randomized turf on every numerical time step.
For independent Bernoulli trials with a fixed model and input distribution, the estimated sampling standard error is \(\sqrt{\hat p(1-\hat p)/N}\). At \(\hat p=0.5\) and \(N=1000\), that is about 1.58 percentage points. It excludes uncertainty in the physical model and in the estimated input distribution. Near zero or one, use an appropriate binomial interval rather than treating the zero plug-in standard error as certainty. Correlated samples need a different uncertainty calculation. More runs do not convert illustrative distributions into measured player performance.
3.2 Perturbation Timing Depends on the Mechanism
A simple counterexample corrects an easy intuition trap. For a free transverse double integrator at a fixed terminal time \(T\),
\[ \delta z(T)=\int_0^T(T-t)\,\delta a_z(t)\,dt. \]
A transverse velocity impulse \(\Delta v_z\) at time \(t\) contributes \((T-t)\Delta v_z\). With \(T=4\) s and \(\Delta v_z=0.05\) m/s, an impulse at 0.5 s gives 0.175 m, while one at 3.9 s gives 0.005 m: the early impulse produces 35 times the terminal displacement. Earlier impulses have more time to change position in this example.
A dissipative rolling putt is not this double integrator. Its linearized response depends on the trajectory’s state-transition matrix; comparing arrivals at an event also requires event-time sensitivity. A spatial defect acts during a speed-dependent residence time. Its direction, correlation length, amplitude and local contact effect matter. A small late perturbation can change a near-boundary capture decision even when its effect on final position is small. These distinctions prevent a universal claim that either early noise or late noise always dominates.
Slow arrival can enlarge a model’s capture window, but its effect on perturbation exposure is conditional on the disturbance law. The resulting pace choice should compare make probability and leave consequences under stated assumptions. Deterministic sensitivity analysis can expose the trade-off; stochastic simulation is needed when the desired answer is a probability under a distribution. Neither method supplies an empirically optimal pace without validation.
3.3 Directional Resistance Needs a Vector Law
Changing a scalar \(a\) with heading in \(-a\hat{\mathbf v}\) changes speed but supplies no instantaneous force transverse to \(\mathbf v\). On a sloped trajectory it can still change later break through the time history. To represent a direct transverse resistance component, specify a vector law.
For illustration, \(\mathbf a_r=-D\mathbf v\) with a symmetric positive-semidefinite tensor \(D\) guarantees \(\mathbf v^T\mathbf a_r\le0\) while allowing transverse acceleration. With \(D=\left[\begin{smallmatrix}2&1\\1&2\end{smallmatrix}\right]\) s\(^{-1}\) and \(\mathbf v=(1,0)\) m/s, the acceleration is \((-2,-1)\) m/s². This is a synthetic dissipative example, not a calibrated grass model. Moreover, this tensor law is symmetric under velocity reversal: it cannot alone represent different with-grain and against-grain resistance. That requires a richer directional law and supporting data.
Paired roll distances can constrain part of a directional model; they cannot identify all cross-grain forces, speed dependence and spatial variation. Measurements in additional directions and at relevant speeds, together with slope correction and held-out trajectories, would be needed. No absence of a calibration in this article establishes that the wider literature contains no such data.
4. What the Pinned Implementations Actually Do
This source inspection is dated 2026-09-28. It covers Tools at 96ab281e and the explorer at af7f2682. These versions do not implement every corrected equation and event treatment above. This is a source audit, not a new execution, deployment or physical-validation claim for either provider.
Their ground-plane coordinates use \(x\) forward and \(y\) left. To compare them with this article’s horizontal coordinates, use \((x,z)_{\rm article}=(x,-y)_{\rm code}\). Their positive start azimuth is rightward, so a positive azimuth produces negative code \(y\) velocity. Import and comparison must preserve this convention as well as units.
| Part | Observed Behavior at the Pins | Consequence for Interpretation |
|---|---|---|
| Motion and transitions | Python green.py and TypeScript puttingGreen.ts use fixed 2 ms RK4 steps, holding the mode during each step and switching afterward |
They do not implement within-step root localization. The scalar spin-speed reduction does not resolve general vector slip or overspin |
| Slope term | Both add the full small-slope gravity term during rolling | They omit the \(1/(1+\alpha)\) rolling-inertia factor derived above |
| Level resistance | roll.py and its mirror derive a release speed using a groove contact fraction 0.87, then invert roll-out distance |
This differs from the companion’s declared groove geometry; an empirical 1.83 m/s convention should not be presented as that exact geometry derivation |
| Stopping | The loop exits when speed is at most 0.005 m/s, or its 60 s cap is reached | It contains no static-equilibrium feasibility test there; a capped trajectory is not necessarily a resting ball |
| Surface | Plane or bilinear heightfield; zero slope acceleration outside the grid, with edge-clamped height queries | The mesh is not globally smooth, and the out-of-domain behavior is an extrapolation policy |
| Capture | Sampled-position tests; the surface API uses an effective-radius proxy, while legacy planar calls retain a speed-threshold proxy | Neither is the companion’s finite-ball derivation or a resolved rim-contact calculation |
| Input dispersion | Python variation.py perturbs clubhead speed, face angle, path angle, toe strike offset and read/aim angle through the shared seeded sampler |
Execution variability is implemented. It should not be confused with stochastic surface fields or empirical player calibration |
| Browser dispersion | puttingDispersion.ts implements summary statistics and the report wire; its documentation keeps Monte Carlo execution Python-authoritative |
A report reader is not an independent browser implementation of the sampler |
| Import | PuttingControls.tsx calls puttingGreenImport.ts, selecting the Tools wire or UpstreamDrift topography reader |
The source contains an import path; this review has not qualified every producer/export combination or the live explorer deployment |
The implemented capture proxy uses \(R_h=0.054\) m and \(v_c=R_h\sqrt{g/(2R)}\approx0.819\) m/s, with \(R_{\rm eff}=R_h\sqrt{1-(v/v_c)^2}\) below \(v_c\) and zero above it. The code tests distance from a sampled position to the hole center against that radius. This is neither a continuously localized impact parameter nor Penner’s separate historical fit. At zero speed its effective radius reaches the full hole radius; the finite-ball clearance and lip-contact qualifications remain relevant. The lower central threshold does not justify calling every prediction conservative.
The Python integrator, capture module and TypeScript integrator make these differences inspectable. The TypeScript reference tests pin selected Python-derived results. Passing those fixtures can catch regressions within their coverage; it cannot show that the physical assumptions are correct or guarantee that all future versions agree.
In these inspected motion and surface paths, resistance is isotropic and scenario-constant; there is no resolved moisture evolution, calibrated spatial imperfection field, rim-contact dynamics or aerodynamic force. This is a bounded statement about these modules, not a survey of every component or commercial simulator. Omitting wind does not establish that wind is negligible for every condition or accuracy target. An unimplemented effect should enter the model’s limitation statement and validation plan, rather than acquire invented constants.
5. Connecting the Layers to a Useful Decision
The impact treatment connects putter delivery and contact to launch. The reference-point discussion explains why a velocity or direction must identify its point and frame. A one-degree straight-line direction change gives about 52 mm lateral displacement over 3 m; whether that putt misses depends on the original aim, break, arrival speed and capture model. It is not an unconditional miss theorem.
The rotation-induced-spin treatment and rolling-putt companion connect impulse partition to subsequent slip and roll. Secondary-axis stability addresses rigid-body design ideas under explicit torque and constraint assumptions; it does not establish measured putting benefit. The strokes-gained critique explains why a make/leave distribution also needs a declared scoring benchmark before it becomes a value claim.
For a useful comparison, carry these dependencies through the whole chain. A changed shaft or head can alter delivery variability; altered launch changes both path and arrival speed; a different capture law changes the success set; a different player distribution changes its probability; a different scoring benchmark changes which leaves matter. Holding one layer fixed is a legitimate experiment if that choice is named. It is not evidence that the layer is irrelevant.
A reproducible result should identify the code and surface revision, coordinates and units, inertia and resistance assumptions, event and boundary rules, uncertainty distributions and correlations, sample count and sampling interval method, and convergence checks for the reported outputs. Physical qualification then compares held-out measured paths, speeds and capture outcomes with predictions at the required accuracy. The analytical and synthetic tests accompanying this article check internal consistency; they supply no new turf, player or hardware measurements.
References and Evidence Scope
- The Physics of the Rolling Putt: the assumption ledger, conventional Stimpmeter calibration, groove distinction, finite-ball construction and separate historical capture model. This review leaves that audited companion unchanged.
- SciPy
solve_ivpdocumentation: event functions and limitations of sign-change detection. No SciPy runtime dependency is added by this article. - Pinned Python putting source and pinned browser model source: implementation evidence, including their explicit limits. Source inspection does not confer empirical qualification.
Implementation companion to The Physics of the Rolling Putt.
Citation
@online{olson2026,
author = {Olson, Dieter},
title = {Simulating the {Green}},
date = {2026-08-04},
url = {https://affinedrift.com/articles/green-simulation.html},
langid = {en}
}