Simulating the Green
A putting simulator has three jobs: describe the shape of the ground, describe how a rolling ball loses speed on it, and be honest about everything it left out. This article is about how those jobs are actually done — from the four-line differential equation at the core, to the digital elevation maps that make a green "break", to the coin-flip layer that decides whether a putt that should drop actually does.
The green is a landscape, the ball is a marble
Simulators store the green as a height map — the same structure as a topographic map — and at every point the map's local tilt tells the ball which way gravity is nudging it. Add a steady braking force for the grass, a rule for the skid at the start, and a geometry test at the hole, and you have the whole deterministic machine. Everything else is refinement.
Why you run the putt a thousand times
A single simulated putt tells you what a perfect machine would do. Running the same putt a thousand times with small random wobbles in start line, speed, and surface tells you what a human on a real green should expect — a cloud of outcomes rather than a line. The shape of that cloud against the effective size of the hole is where make probability actually comes from.
Scope and Intent
The companion article, The Physics of the Rolling Putt, derives the roll model itself: skid, the five-sevenths transition, the stimpmeter deceleration map, slope as a gravity component, and the capture bound at the hole. This article is about turning that model into software: the representational choices a green simulator must make, the numerical machinery that integrates the model on a real surface, the stochastic layer that separates a physics demo from a useful predictor, and a plain statement of what the project’s own implementation does and does not contain.
The survey is organised around the three decisions every green simulator takes, whether or not its authors noticed taking them:
- How the ball is modelled — the roll ODE and its phase structure.
- How the surface is modelled — analytic planes, meshes, gradient fields.
- How uncertainty is modelled — usually not at all, occasionally well.
Frames and constants follow the roll-model article: \(x\) along the intended start line, \(y\) up, \(z\) right; ball and hole dimensions are the openly published equipment and Rules specifications; stimp \(S\) maps to rolling deceleration \(a = 5.49/S\) m/s². Claims about specific software below are confined to this project’s own repositories, which are public and linkable; commercial simulators are discussed only in terms of the modelling choices any implementation must make, since their internals are not publicly documented and this site does not cite what cannot be verified.
1. The Ball Model: A Hybrid ODE With Two Phases and an Event
Strip the roll-model derivation to its computational skeleton and what remains is a hybrid dynamical system — two smooth vector fields separated by a discrete transition:
Skid phase (contact point sliding at \(\mathbf{u} = \mathbf{v} - \omega R\,\hat{\mathbf v}_{\text{spin}}\)):
\[ \dot{\mathbf v} = -\mu_k g\,\hat{\mathbf u} + g\,\mathbf s(\mathbf x), \qquad \dot\omega = \frac{5\mu_k g}{2R} \]
Roll phase (slip exhausted, \(v = \omega R\)):
\[ \dot{\mathbf v} = -a\,\hat{\mathbf v} + g\,\mathbf s(\mathbf x) \]
where \(\mathbf s(\mathbf x)\) is the local in-plane slope vector supplied by the surface model of §2. The transition is an event, not a time: it fires when the slip speed crosses zero, and on level ground it lands at exactly \(\tfrac57\) of a spinless launch speed. Three implementation notes carry most of the practical difficulty:
Event detection, not fixed stepping. The skid–roll switch and the hole-capture test both occur at states, not times. An integrator that only samples on a fixed grid will step over the transition and inherit a velocity error of order the step size — small per putt, systematic over an ensemble. The standard remedy is any root-finding event locator on top of an RK4/RK45 stepper; the transition variable (slip speed) is smooth and monotone near the crossing, so bisection to machine tolerance costs a few extra function evaluations.
The stopping problem. \(\dot{\mathbf v} = -a\hat{\mathbf v}\) is non-Lipschitz at \(\mathbf v = \mathbf 0\): the ball reaches rest in finite time and the unit vector \(\hat{\mathbf v}\) is undefined there. Naive integrators oscillate or creep at the end of the putt — visible as a ball that “shivers” to a stop. The clean fix is a stopping event (\(v\) below tolerance with in-plane gravity below the static threshold \(\mu_s g\)), after which the state is clamped. On slopes steeper than the runaway grade derived in the companion article (\(\approx a/g\)), the stopping event never fires, and correctly so.
Capture as geometry, not collision. The capture test from the roll-model article — chord length against the free-fall drop, \(b_{\max}(v) = \sqrt{r_h^2 - v^2R/2g}\) — is evaluated when the ball’s path crosses the hole disc. Simulators that instead model the hole as a mesh depression and rely on the general contact solver to “discover” capture buy realism in lip-out animation at the price of extreme sensitivity to mesh resolution and restitution parameters at the lip edge; the hybrid-model test is deterministic, cheap, and matches the derived bound by construction.
2. The Surface Model: From a Tilted Plane to a Gradient Field
2.1 The Hierarchy
Green representations form a ladder of fidelity, and the right rung depends on the question being asked:
| Representation | Slope field \(\mathbf s(\mathbf x)\) | Good for | Fails at |
|---|---|---|---|
| Tilted plane | Constant vector | Closed-form study, unit tests | Any real green |
| Analytic patch (low-order polynomial) | Exact gradient | Controlled experiments, tier/crown features | Local detail |
| Heightfield grid \(h(x_i, z_j)\) | Finite-difference or interpolated gradient | Scanned real greens, general simulators | Sharp features between nodes |
| Triangulated mesh | Per-face constant gradient | Irregular boundaries, fringe/collar | Gradient discontinuities at edges |
The physics consumes only two things from any of these: the local slope vector \(\mathbf s = -\nabla h\) (to first order in slope) for the gravity term, and — in refined models — the local surface normal for the contact frame. Everything else is data structure.
2.2 Heightfields and Their Derivatives
The workhorse is the heightfield: elevations on a regular grid, bilinear or bicubic interpolation between nodes. The subtlety that separates careful implementations from casual ones is that the ball responds to the gradient, not the height. Bilinear interpolation yields a slope field that is discontinuous across cell boundaries; a ball crossing a cell edge feels a step change in break, and on long lag putts the accumulated kinks are visible as faceted trajectories. Bicubic (or B-spline) interpolation gives a continuously differentiable surface at modest cost, and for gradient-driven dynamics it is the correct default. The same consideration governs mesh sources: a laser-scanned or photogrammetric green imported as raw triangles should be resampled onto a smooth interpolant before the ODE ever sees it, or the noise floor of the scan is injected directly into the break.
Grid resolution buys detail linearly and costs memory quadratically, and the relevant scale is set by the physics: features narrower than a few ball diameters are traversed in a few milliseconds and average out of the trajectory; features at the half-metre scale and above are what players read as borrow. A decimetre-class grid with smooth interpolation captures everything the deterministic model can honestly use — finer structure belongs to the stochastic layer of §3, not the mesh.
2.3 What the Slope Field Feeds
With \(\mathbf s(\mathbf x)\) in hand, the simulator’s deterministic loop is complete: integrate the hybrid ODE of §1 through the field, fire the capture test at the hole. Two derived products fall out nearly free, and both are more useful than single trajectories:
- Reachability and runaway maps. Evaluating \(\lVert \mathbf s \rVert\) against \(a/g\) over the whole green marks every point from which a downhill putt cannot stop — the simulator’s version of the hole-location constraint derived in the companion article.
- Aim-and-pace charts. Sweeping launch angle and speed for a fixed ball–hole pair and recording outcomes yields the make-region in the (aim, pace) plane, whose area is the deterministic difficulty of the putt. Its shrinkage with green speed and slope reproduces, quantitatively, the difficulty orderings players describe qualitatively.
3. The Stochastic Layer: Grain, Imperfection, and Dispersion
3.1 Why the Deterministic Model Is a Ceiling
The deterministic machine of §1–§2 answers “what would this putt do on the modelled surface”. It cannot answer “what fraction of well-struck putts go in”, because the gap between those questions is precisely the unmodelled variability: launch execution noise, surface structure below mesh resolution, and slow environmental drift. Three stochastic treatments appear in simulation practice, in increasing order of ambition:
Input dispersion (execution noise). Perturb launch speed and start line with small zero-mean errors and propagate each sample through the deterministic model. This is a direct transplant of the Monte Carlo methodology used elsewhere on this site for swing-parameter variation studies: the model is the function, the stroke errors are the input distribution, and make probability is the pushforward measure of the capture set. It requires no new physics, and it already reproduces the dominant structure of real make-rate curves — in particular the interaction between pace dispersion and the speed-dependent effective hole width \(b_{\max}(v)\): aggressive pace narrows the target and widens the miss cost simultaneously.
Parameter noise (surface statistics). Let the friction constants and the slope field carry spatial noise — \(a(\mathbf x)\) and \(\mathbf s(\mathbf x)\) as random fields with short correlation lengths — representing footprints, repair marks, mowing bands, and the general granularity of living turf. The physical footprint of such noise is well defined even where its parameters are not: perturbations act on the trajectory in proportion to the remaining time to the hole, so late-path noise deflects the ball more than early-path noise for a given amplitude, and slow-arriving putts integrate more surface noise precisely when they are most capturable. That trade-off — dying speed maximises effective hole width but also maximises exposure to surface noise — is the honest formulation of the pace-past-the-hole folklore discussed in the roll-model article, and it only exists in a model that carries a stochastic layer at all.
Directional bias (grain). Grass with a lie direction resists rolling anisotropically: deceleration is larger into the grain than down-grain, and a cross-grain component deflects the ball independently of gravity. Structurally this is a small modification — \(a\) becomes a function of the angle between \(\hat{\mathbf v}\) and a grain field \(\hat{\mathbf g}(\mathbf x)\) — but calibrating the anisotropy honestly requires paired stimpmeter readings with and against grain on the actual turf, and generic constants are folklore until so measured. The model slot exists; the public data to fill it does not.
3.2 Reporting Discipline
A dispersion study is only as honest as its input distributions, and the reporting rules this site applies to swing simulation apply unchanged: state the perturbation model and its parameters next to every make-probability figure; report ensemble sizes and confidence intervals; and never present a deterministic capture boundary as a make rate. The single most common overstatement in putting content — simulated or otherwise — is quoting probabilities whose noise model is undisclosed, which makes the number unreproducible in exactly the way the rigor standard of this project (content-development/RIGOR_GUIDE.md) forbids.
4. What Our Implementation Contains
The putting vertical of the project’s Tools golf suite implements the model of §1–§2 as specified by the roll-model derivation, as part of the broader shared-tools putting simulation program:
- Hybrid skid–roll ODE with the event-detected five-sevenths transition, stimp-parameterised rolling deceleration, and the static-friction stopping condition — with the skid initial condition taken from a low-speed putter impact model (loft-dominated, near-zero launch spin).
- Slope and break as in-plane gravity components over the surface model, including the runaway-grade check for hole and start positions.
- Geometric capture test using the speed-dependent effective hole width, applied on hole-disc crossing.
- Deterministic roll-out visualisation — trajectory, phase boundaries (skid end, capture or stop), and pace/aim sweeps.
- Dual implementations under shared numeric tests, following the project’s parity convention: the same model in the Python engine and the TypeScript front end, pinned together by a shared test suite so the two cannot drift apart silently — the same discipline used for the rate-of-closure explorer.
What It Honestly Does Not Contain
- Grain. The anisotropic-deceleration slot of §3.1 is not populated: no public calibration data meets the project’s sourcing bar, and shipping invented anisotropy constants would be worse than shipping none.
- Dew, moisture, and diurnal drift. Green speed varies through a day; the model treats \(a\) as constant per scenario. Users model a slow green in the morning by changing the stimp input, not by a moisture model.
- Surface imperfection statistics. The deterministic surface is smooth at mesh scale; the random-field layer of §3.1 is methodology the project endorses but has not yet implemented, so simulated make regions are ceilings on real make rates, and the interface says so.
- Lip dynamics. Capture is the geometric bound, not an edge-collision model; near-threshold outcomes (horseshoes, lip-outs) are classified conservatively rather than animated physically.
- Wind. Negligible for the ball on the ground at putting speeds relative to the terms retained, and excluded.
This list is maintained deliberately in public view: each item is a falsifiable absence, and promoting any of them into the model requires the same derivation-or-source standard the rest of the pipeline meets.
5. Where This Sits on the Site
The putting material now forms a closed loop with the impact-mechanics corpus. The impact article establishes the collision physics and the face-dominance of the start line; the reference-point article explains why delivered direction must name its reference point — a caution that applies verbatim to putter deliveries, where a degree of start-line error is a missed three-metre putt; the rotation-induced-spin supplement derives the sphere impulse partition whose surface-side twin is the skid phase; the roll-model article carries that partition across the turf to the hole; and this article turns the assembled physics into software with a stated error budget. The unifying habit is the same one the technology section applies to instruments: say what is measured, what is derived, and what is assumed — and keep the three lists separate.
References
- Companion derivation: The Physics of the Rolling Putt — all physical constants and closed forms used here, with their assumption ledger.
- Project repositories: D-sorganization/Tools (putting vertical; shared-tools putting simulation suite); D-sorganization/rate-of-closure-explorer (the dual-implementation parity pattern).
- R&A and USGA. Rules of Golf and Equipment Rules — hole and ball specifications; USGA Stimpmeter Instruction Booklet — the green-speed measurement the deceleration map calibrates against.
Implementation companion to The Physics of the Rolling Putt.