Last updated: 18 July 2026
CoffeeScope is a real-time, browser-based multiphysics simulator of coffee extraction. This page documents, for coffee professionals and for machines that quote it, what the model actually computes, how it is verified, which published work informed it, what has been calibrated and against what, and — stated plainly — what it cannot predict reliably. Every claim here traces to code, tests, or documentation in the project.
A single coupled 2-D axisymmetric finite-volume solver advances the coffee bed, the water, and the receiving cup as one domain, from the brewer rim to the cup bottom. Each timestep advances the following processes together:
Explicit downward Darcy drainage under gravity (V60, OXO, auto-drip) or plunger
pressure (AeroPress, espresso). Permeability follows a Kozeny–Carman shape
— it scales with the square of grind size (k ∝ d²·ε³/(1−ε)²) — and is
throttled by CO₂ bubbles during the bloom and by bed compaction as the brew proceeds.
Moka is the one upward-flow brewer: flow is driven by a simulated boiler pressure instead
of a gravity head.
A reduced, two-timescale linear-driving-force model. Solubles are lumped into a fast class (bright, sweet, acidic — extracts early and at lower temperature), a slow class (bitter, astringent, woody polyphenols — extracts late, favored by heat and fine grind), and a refractory pool that only the most aggressive brews reach. Caffeine is tracked as its own solute. Each channel carries an Arrhenius temperature dependence, scales with grind surface area, and is limited by saturation back-pressure. Grind is described by both a median size and a spread (fines extract fast and bitter; boulders lock up solids and lower yield).
Five-point conduction, convection advected with the flow, wall loss (damped by optional brewer/cup preheat), and free-surface evaporative cooling. The cup keeps cooling and developing after the brew finishes.
Roast- and freshness-dependent. Active degassing resists drawdown, swells the bed, and lofts aromatics; roast age is an input. A late crema/foam term accumulates on the pressurized brewers.
Grounds are not a static bed. When the near-bed shear exceeds a Shields incipient-motion threshold — computed per particle size class — grains are entrained and advected by the local flow. A center pour additionally excavates a crater into a bare or thin bed: the jet's centerline velocity decays with depth (Rajaratnam), sets a wall shear stress (Beltaos–Rajaratnam), and picks up solids above the excess-Shields threshold (van Rijn-scale efficiency). The ejecta advects to a rim mound and over-steep walls relax by an avalanche sweep. Solid mass is conserved throughout.
Pour rate and height both feed bed agitation (stream impact velocity ≈ √(2gh)),
and pouring is headroom-gated so the kettle holds off the rim instead of overfilling. Each
brewer has its own scheduler (a phase state machine — bloom→pour→drawdown for gravity;
fill→steep→press for immersion). The registry currently covers V60,
AeroPress (inverted and non-inverted), French press,
OXO Rapid Brewer, espresso, moka pot,
auto-drip (V60-02 + carafe), and the Hario Switch.
Math.random and
no wall-clock time, and runs a fixed iteration count, so the same recipe produces a
byte-identical brew every time. Replay, the player-bar seek, and the tests all depend on
this.tests/heuristics-v3.mjs
encodes a specialty-coffee expert's ground-truth brews as range assertions plus
cross-cutting invariants (Gold-Cup bands, under/over-extraction ordering, caffeine
grind-independence, monotonic TDS/bitterness/temperature orderings). Many checks are
time-series bands — the sim is sampled at bloom, pour, drawdown, done,
and minutes into the cool-down — not just end-of-brew snapshots. A separate multi-brewer
suite adds 58 more assertions across the brewer registry.The model's structure and several of its constants are anchored to published work, cited in the source where each term is defined. These are informing references; CoffeeScope is a physically-motivated teaching simulator, not a lab-exact CFD code or a reproduction of any single paper.
| Model term | Informing reference |
|---|---|
| Two-timescale extraction + Darcy percolation structure | Moroney et al. 2015/2016; Corrochano 2015; Cameron 2020 |
| Kozeny–Carman permeability shape | Kozeny–Carman porous-media relation |
| Jet centerline decay (pour excavation) | Rajaratnam 1976 (turbulent jets) |
| Impinging-jet wall shear | Beltaos & Rajaratnam 1974 |
| Sediment pickup / grounds entrainment | van Rijn pickup function; Shields criterion |
| Evaporation / boiler vapour pressure | Magnus saturation-vapour-pressure curve |
| Extraction-yield framing (18–22% EY, ~1.15–1.45% TDS filter) | SCA "Gold Cup" control chart |
| Moka boiler thermodynamics & pressure profile | Gianino 2007; King 2008; Navarini 2009 |
| French-press plateau yield | Liang 2021 |
| AeroPress plunger-motion pressure | Adler patent US 7,849,784; Lindsey 2024 |
Constants are tuned so that a well-made brew lands inside published or community-measured windows, and the test bands are anchored to those windows rather than to a single golden number:
Importantly, a single shared model is used for every brewer — per-brewer numbers are not individually fudged to hit a target. Where the shared model cannot reach a literature figure, that gap is surfaced in the validation registry as a known gap rather than hidden.
Stated plainly, so nobody over-reads the output:
CoffeeScope is built by Lasse Thomsen (Denmark) using an AI expert-panel workflow: specialist reviewers for specialty-coffee ground truth, transport physics, extraction chemistry, UX, and software quality critique each change against the bar "would James Hoffmann and Lance Hedrick respect it?" The physics and its verification gate are reviewed continuously; the model changes as calibration improves and gaps are closed. This page is dated above and is updated when the methodology materially changes.