Methodology, validation & limitations

Last updated: 23 July 2026

CoffeeScope is a real-time, browser-based multiphysics simulator of coffee extraction. This page documents 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.

1. What is modeled

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:

Percolation and flow (Darcy)

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, and its drive is not scripted: the boiler is simulated as a closed volume. The sealed headspace holds a fixed charge of trapped air (ideal-gas bookkeeping) plus saturation vapour at the water temperature (Magnus curve); stove power heats the lumped water-plus-aluminium mass through the base while it loses heat to the surroundings. When the head pressure beats atmosphere plus the hydrostatic lift, water is pushed up the funnel tube and through the coffee bed — the flow rate through the puck is the same Darcy law as every other brewer — and every millilitre that leaves the boiler enlarges the gas volume, feeding back on the pressure. The quiet early dribble, the delivery ramp, the late pressure rise and the sputter finale all emerge from that PV thermodynamics rather than being prescribed.

Extraction kinetics — compound families

A reduced linear-driving-force model with resolved compound families. Solubles travel in three transport envelopes — fast (extracts early and at lower temperature), slow (late, favored by heat and fine grind), and a refractory pool that only the most aggressive brews reach — each with an Arrhenius temperature dependence, grind-surface scaling and saturation back-pressure. Within those envelopes the model resolves nine compound families with separate reaction kinetics: fruit esters, other aromatics, organic acids, sugars and caramels, bitter CGA-lactones, woody phenolics, astringent tannins, roasty Maillard melanoidins, and caffeine on its own channel. Esters, aromatics and acids lead the extraction; sugars run slightly behind; tannins arrive late and grow with over-extraction; melanoidins need near-boil heat; and hot water destroys part of the fragile esters in the bed. Roast level and bean age recolor the family pools (acids and esters fade dark and stale, bitter lactones and woody phenolics grow), and the taste axes read the family concentrations in the cup — acidity from acids, sweetness from sugars, body from melanoidins, aroma from the surviving volatiles, astringency from tannins — so roast, staleness and bean character move flavour causally rather than by proxy. Grind is described by both a median size and a spread (fines extract fast and bitter; boulders lock up solids and lower yield). Caffeine finishes early everywhere and deliberately does not track flavour yield.

Heat transport

Five-point conduction, convection advected with the flow, wall loss to the surroundings (cup-material dependent), and free-surface and falling-stream heat exchange with room air. On the moka, the aluminium walls conduct boiler heat into the bed and collector. The cup's free surface loses water and volatiles by true evaporation (Magnus vapour-pressure drive), so a hot cup slowly concentrates and sheds aroma while a cold one keeps both; the auto-drip's warming plate stews hardest. Optional preheat warms the brewer and/or receiver walls (a warm-wall reservoir that decays back toward room temperature), and brewing over ice melts real ice — latent heat of fusion, 0 °C dilution and a live remaining-ice readout — so an iced brew lands genuinely cold, dilute, and aroma-retaining. The cup keeps cooling and developing after the brew finishes — and the extraction chemistry runs on the local temperature field throughout (Arrhenius), so heat loss feeds straight back into what dissolves.

CO₂ bloom and degassing

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 transport

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.

Pouring and per-brewer schedulers

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.

2. How it is verified

• Deterministic replay. The engine uses no 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.
• Conservation checks. State is stored as conserved quantities (pore liquid volume, dissolved masses, grounds masses, heat), and the test gate asserts mass closure across the whole domain.
• A behavioural gate of over 100 assertions. 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's insensitivity to pour pattern, 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.
• One sealed, versioned kernel, pinned by golden trajectories. The physics runs in a single Rust/WebAssembly kernel carrying a version stamp. Every release must reproduce a golden suite of full brew trajectories to 10⁻⁹ across scenarios covering every solver path (gravity, immersion, pressure, moka, resolved-momentum, excavation, warming plate), and the kernel's batched substep is additionally held bit-identical against a per-pass dispatch of the same kernel — a structural witness that the orchestration cannot drift. A freshness gate fails if the goldens and the shipped kernel version ever disagree.

3. What informed it

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.

4. Calibration & validation status

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:

• Filter / pour-over: the SCA Gold Cup window — roughly 18–22% extraction yield and ~1.15–1.45% TDS.
• Moka: deliberately over-extracted; the test asserts yield inside a Navarini-derived window (≈26.5–32%).
• French press: a plateau extraction yield near 20.7 ± 1.1% (Liang 2021).
• Cross-brewer orderings: the relative behaviour between brewers, grinds, temperatures, ratios and pour patterns is checked for the correct direction and sign, not only absolute values.

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.

5. What it cannot do

Stated plainly, so nobody over-reads the output:

• It does not model paper-wall bypass or channeling to the filter. Water that races down the wall of a real dripper, or a localized channel punching through to the paper, is not represented. Uneven extraction is modeled as a radial permeability proxy, not as a true 3-D channel.
• The formulation is axisymmetric. A spiral pour's azimuthal (swirl) momentum is not resolved in the shipped model — swirl exists only as an unpromoted research flag that is off by default. What the model does capture about pour pattern is how evenly the pour lands, not the true 3-D circulation of a circling pour.
• Pour-pattern differences in the cup are honestly second-order. Center versus spiral versus concentric mostly change bed evenness; with a well-made bed the cup-level yield, TDS and drawdown stay near-identical, and the tests hold them to a tight honesty band. CoffeeScope will not tell you a spiral pour transforms the cup, because in this model it largely does not.
• Bloom infiltration ponds more than a real dry bed would. Wetting a truly dry bed is a complex, hydrophobic, partially-channeled process; the current model lets bloom water pool somewhat more than it should.
• Known chemistry simplifications. Water chemistry (GH/KH) and a bypass-valve schedule are not modeled. Acid species (phosphoric, malic, citric) are flattened into one kinetic pool — acidity character still comes from the static per-bean acid profile, not the kinetics. Staling's cardboard/oxidized-lipid defect note is not modeled (stale reads as flat + drying, which is the right direction but not the full character). Fermented/overripe processing always reads as positive aroma — there is no boozy/solventy defect direction. "Sugars" lumps free sugars with caramels as a perceived-sweetness carrier. Ester heat loss is mechanistically volatilization but is modeled as an in-bed sink. Permeability is a tuned dimensionless scale, not a physical m² value.
• It is a teaching simulator, not a measurement. Results are indicative and will not perfectly match any real brew.

6. Who builds it, and how often it changes

CoffeeScope is built by Lasse Thomsen (Denmark), PhD in applied physics. The model changes as often as new physics is introduced or improved — which is frequent, for a project this young — but the physics kernel is versioned, and nothing ships unless the verification gate above stays green. This page is dated at the top and is updated when the methodology materially changes.

References

1. Moroney, K.M. et al. — modelling of coffee extraction during brewing (2015/2016).
2. Corrochano, B.R. et al. — flow and extraction in espresso (2015).
3. Cameron, M.I. et al. — systematically improving espresso (2020).
4. Rajaratnam, N. — Turbulent Jets (1976).
5. Beltaos, S. & Rajaratnam, N. — impinging circular turbulent jets (1974).
6. van Rijn, L.C. — sediment pickup functions; Shields incipient-motion criterion.
7. Gianino, C. (2007); King, W. (2008); Navarini, L. et al. (2009) — moka-pot physics.
8. Liang, J. et al. (2021) — French-press extraction.
9. Specialty Coffee Association — "Gold Cup" / control-chart extraction-yield framing.

Privacy Policy →  ·  Terms of Use →