Methodology

Physics: the standard formula

The core is the standard cycling power balance you'll find in Martin 1998, Kreuzotter, Gribble, and every textbook: a Newton solver that balances pedal power against three resistance forces and one inertial term, iterated per-split until power matches resistance.

P_pedal · (1 − drivetrain_loss) =
   ½ · ρ(altitude, temp) · CdA · v_air² · v_ground   (aero drag)
 + Crr(surface) · m · g · cos(θ)        · v_ground   (rolling)
 + m · g · sin(θ)                       · v_ground   (gradient)
 + m · a                                · v_ground   (inertia)

Same formula. ρ, CdA, Crr, draft, and effort each get filled in per split, not per ride.

Modifiers above the standard formula

The standard physics handles a smooth tarmac TT in still air at sea level. Real races have cobbles, headwinds, peloton drafts, mountain altitude, summer heat, and tactical attacks. Each modifier below is a documented departure from "use one number for the whole ride":

• Per-surface Crr. Tarmac, cobble, gravel, hardpack, mud: different surfaces, different rolling resistance. Default comes from OSM surface=* + smoothness=*tags per split, mapped to a Crr value by surface quality (good / moderate / rough / severe). On top of that, a curated database of named sectors (Arenberg + Carrefour de l'Arbre cobbles, Strade Bianche white roads, Unbound chunky-flint gravel, Muur van Geraardsbergen pavé, …) overrides OSM where its tagging is sparse or misclassifies the surface. Wet sectors add a rain-decay factor scaled by the past 72 h of precipitation history at the sector coordinates, decayed with a 12 h dry-time half-life on tarmac (longer on cobbles or shaded gravel). 10 mm of rain that fell 24 h ago still leaves the sector measurably damp. When the rough-surface fraction (pavé or gravel) crosses ≥ 12 %, the planner also swaps its defaults to a cobbled or gravel profile (paceline draft, surface-appropriate effort targets) instead of a peloton road-race one. Crr is resolved per-meter, not averaged across the route.
• Asymmetric wind. Per-split headwind is the dot product of forecast wind (Open-Meteo archived hourly history at the sector lat/lon) and the split's heading. Tailwinds go through the same equation, not "wind speed = average across ride".
• Tier-aware draft schedules. Draft factor isn't one number. Baseline 0.58 (peloton/paceline) refit 2026-04-25 from 64 cohort rides with explicit draft annotation. For WT pros on race or cobbled intents the baseline is replaced by a tier-aware schedule that captures bunch fragmentation through the race: bunch phase (heavy domestic shelter, low effective draft) then selection, chase, solo finale. Trip-averaged draft lands around 0.49 on a long monument (LBL), 0.67 on the 250 km Olympic road race, 0.77 on Roubaix. Amateur schedules use higher phase factors throughout because amateur fields fragment earlier and don't get the team-coordinated late selection.
• Power-duration curve as effort ceiling. Effort is PDC-aware: 0.75 on a 4 h ride sustains a different absolute IF than 0.75 on a 20-min TT. The PDC is fitted from the rider's last 90 days of FITs (intervals.icu integration) or back-solved from tier + FTP when no archive exists.
• Heat / altitude / fatigue. Heat > 25 °C derates sustainable power by ~0.9 %/°C up to 35 °C, then ~1.5 %/°C above, anchored to Tatterson et al. (2000): 6.5 % power loss at 32 °C vs 23 °C in trained cyclists. Altitude > 1500 m derates by 1.6 %/100 m (acclimatized) or 2.0 %/100 m (unacclimatized), slopes calibrated above the Wehrlin & Hallén (2006) lab corridor of 1.0-1.2 %/100 m to match the cohort's observed 8 % drop at 2000 m on alpine rides (Marmotte, Galibier, TdF mountain stages). Long-ride fatigue picks one of three profiles by intent: standard (onset 1.0 h), endurance (onset 1.5 h), ultra (onset 2.5 h). After onset, sustainable power decays at 3-5 %/h to a 60 % floor.
• Two-pass duration refinement. Pass 1 plans at a bootstrap 28 km/h. Pass 2 refines weather, sector wetness, temperature, and the PDC duration bucket using Pass 1's actual time estimate. The refinement matters most on stage TTs: bootstrap 28 km/h would put a 32 km Olympic TT at ~69 min, dropping the PDC into the 1-hour bucket (1.0 × FTP). Actual finish ~36 min lives in the 30-min bucket (~1.04 × FTP). Skipping Pass 2 leaves TT watt targets several percent low and the predicted time correspondingly slow.
• CdA calibration ranges. Pro/amateur gap is huge. The model's TT bound is 0.17-0.24 (mass_inference.py:75): WT TT specialists at the bottom (Ganna ~0.175, Evenepoel ~0.17: estimates from Castelli wind-tunnel commentary in cycling press, not peer-reviewed), road-bike-with-clip-ons amateur club TTs at the top. WT road 0.25-0.30, amateur drops 0.38-0.45, hoods 0.45-0.50. The 0.40 slider default is amateur-drops; run bpm calibrate on a flat ride of yours for a ~0.02 refinement.

How this was built: Power Guide reverse engineering

The first piece was getting the prediction onto the Edge, before any modeling work began.

Garmin Power Guide is a per-segment wattage target overlaid on a course. The two FIT messages behind it (352 for the Power Guide header, 353 for per-split targets) are undocumented. The Garmin FIT SDK doesn't expose them; reverse engineers have noted them in passing on GitHub but no public tool writes them. Sam decoded the messages from binary dumps of Edge-saved Power Guide files: opened a few in a hex inspector, cross-referenced field IDs against the SDK's known message families, mapped each field to the corresponding UI knob (target watts as % of FTP, distance, grade, heading), and confirmed the layout by writing test files and re-reading them on a real Edge. The full RE write-up sits in the repo under src/bike_power_model/writer.py + the round-trip tests in tests/test_writer.py.

How this was built: the model

With the FIT writer working, the model itself was the next problem. Garmin's native Power Guide is gradient-only: it can't see Arenberg or a Zeeland headwind. So the model accreted, one stage at a time:

1. Martin-1998 power balance → predict any stage's time from FTP + mass + CdA.
2. Per-surface Crr (OSM surface=* tags) → tarmac, cobble, gravel, hardpack stop sharing one Crr.
3. Asymmetric wind from Open-Meteo archived history → real weather, not "average".
4. Per-sector overrides DB → curated values for named sectors (cobble, gravel, hardpack) where OSM tagging is sparse or wrong.
5. Tier-aware draft schedules → pros, cat-2s, sportive groups shelter differently.
6. Two-pass duration refinement → TT predictions tighten from +3.4 % to +0.2 %.
7. Per-rider PDC from FIT archive → effort=1.0 means rider's actual ceiling, not category-default.
8. Heat / altitude / fatigue / W'-balance / corner-radius / sector-aware rain decay → diminishing-returns refinements.

Every step was driven by a stage where the prediction was off. The validator runs ~200 pro + amateur rides every commit; the headline number on this page is the result of 18 months of "the model says X, the rider did Y, why is the gap there".

OTS-stamped predictions: pre-race proofs + live-model reruns

Some pre-race predictions in validation_predictions/are OpenTimestamps-stamped to Bitcoin before the gun. Each stamp proves the prediction existed at that moment with no hindsight tuning. That's the integrity claim. The cohort headlines above (built from running the live model on a held-out validation set) are the anchor for "what can this thing actually do". The per-race OTS numbers below are reference.

Re-running the four pre-Romandie OTS-stamped classics through the live model today: LBL 1.96 % → 1.82 % (slightly better), FW 2.47 % → 3.35 % (close), Amstel 2.80 % → 4.06 % (moderate drift), Brabantse Pijl 3.80 % → 7.89 % (largest drift). The shift correlates with stamp age: LBL was stamped two days before the spring physics refresh and lands closest; BP was stamped twelve days before and drifts most. Some races got marginally better, some worse. I'd rather ship more accurate physics and lose a flattering MAE on a single race than hold onto numbers that don't survive a closer look.

Most of the recent physics improvements (draft, fatigue, altitude, heat, cornering) only fire when the model knows what kind of effort the rider is doing. A road race uses a different draft model than a time trial. A TT uses different aero defaults. A gravel race uses different rolling resistance. The same numerical inputs can mean different things in different contexts.

The Romandie prologue is the cleanest demonstration. The input carried CdA 0.25 for Pogi: a sensible value for his road races. On a TT bike that CdA means the rider is sitting up rather than tucked into an aero position, which is rare for a pro doing a TT. The TT context tells the model to expect ~0.19 for a specialist his size. Knowing it's a TT (not just an aero number) is what tells the model which calibration to apply. (I updated the prologue input from 0.25 to 0.19.)

Romandie stages 1-5 re-stamped 2026-04-29. The earlier stamps were generated by a script that wasn't passing the ride type to the model, so the model fell back to flat physics with no context-aware calibration. The re-stamps land before each stage starts. The prologue (already raced) was not re-stamped: the original stamp is the locked pre-race proof.

Good, bad, and honest gaps