Physics-based models for the espresso pull — from grind and puck structure to water flow, puck change, and extraction.
Puckworks is an open-source research toolkit for the espresso shot: particle size, puck structure, water flow, bed changes, and soluble material delivered to the cup. Each published model remains a separate, testable module, with its conditions of use and supporting measurements.
Data guide: sources, inspection limits and access. Private originals remain outside Git.
Try it now: 🧪 Open the Full Laboratory Tour in Colab (visit every model independently) · 🔗 Follow one illustrative pull through linked models — the Espresso Model Relay · ☕ Run a Guided Espresso Pull in Colab (one recipe, stage by stage) · 📋 Run the quickstart in Colab (browse models)
The Espresso Model Relay is an assumption-rich educational relay, not a validated coupled simulation. It is a separate experience from the Full Laboratory Tour, which remains unchanged.
⬇ Download the latest public release · 🔬 Explore the evidence · 📊 View current project status · 🧭 Learn the architecture · 🛠 Contribute a model or dataset
New session (human or agent)? Start with docs/ONBOARDING.md.
An espresso shot is a chain of physical steps:
This is a conceptual sequence to organize the models. In a real shot the stages overlap and interact — water is still wetting deeper layers while the top is already extracting, and the puck keeps changing throughout.
| Stage | The physical question |
|---|---|
| Grind | How does the grinder setting set particle size and the spread of sizes? |
| Puck formation | How do particle size, shape, packing, and void space set the porous structure? |
| Machine delivery | How do the pump, tubing, trapped air, and puck resistance set pressure and flow? |
| Wetting and filling | How quickly does water invade the initially dry pore space? |
| Flow | How do permeability, viscosity, unevenness, and inertia route water through the puck? |
| Puck change | How do swelling, compaction, fines movement, and dissolution change resistance mid-shot? |
| Extraction | How do soluble compounds leave the particles and travel out with the liquid? |
Library versus Guided Pull. The library contains separate models of brewing stages. Guided Pull runs the Cameron extraction chain from grind to cup. Other components provide alternative models, calibration relationships, reference solvers or exploratory mechanisms; they are not fused into a consensus simulation.
28 registered models, ordered by process stage. Identifiers link to cards with assumptions and limits. "Runs in Guided Pull" identifies the public model chain.
| Stage | Model module | Role | What physics it represents |
|---|---|---|---|
| Grind | wadsworth2026.grindmap |
Calibration / comparison | Maps a grinder dial to measured mean particle radius and size spread. Grinder-specific and not portable to other grinders. (card) |
| Grind | maille2024.phi_closure |
Calibration / comparison | Predicts from a measured particle size distribution what fraction of the soluble material releases fast — fines plus a thin shell on each coarse particle. Instrument-specific (186 µm cut); coarse grinds only, so espresso is an extrapolation. (card) |
| Puck formation | wadsworth2026.permeability |
Calibration / comparison | Permeability from particle size, porosity, and grain angularity. Validated untamped; the tamped range is an extrapolation. (card) |
| Puck formation | brewer2026.pack_generator |
Pore-scale reference | Builds synthetic overlapping-sphere pucks with controlled heterogeneity for pore-scale flow experiments (a Puckworks model). (models) |
| Machine delivery | foster2025.machine_mode |
Executable model (separate) | Couples pump behavior, pipe resistance, trapped-air headspace, and puck filling to predict delivered pressure and flow. Fine grind; nominal pump. (card) |
| Machine delivery | sourcing2026.g3_pump_characteristic |
Source-data constraint | Bounds the pump pressure–flow envelope from manufacturer endpoints and community curves. Endpoints are reference-strength; the curve shape is qualitative. (card) |
| Wetting | foster2025.infiltration |
Executable model (separate) | Tracks a sharp water front advancing through an initially dry puck under a measured or prescribed pressure history. Validated against CT, fine grind. (card) |
| Wetting | sourcing2026.g1_glassbead_analog |
Source-data constraint | Uses glass-bead retention and relative-permeability measurements as a shape prior for wetting. This is an analogy, not coffee-specific validation of absolute values. (card) |
| Flow | brewer2026.lb_reference |
Pore-scale reference solver | Resolves low-Reynolds pore flow with a D3Q19 two-relaxation-time lattice-Boltzmann solver (verification twin; a Puckworks model). (models) |
| Flow | brewer2026.lb_taichi |
Pore-scale reference solver | Accelerated (CPU/GPU) build of the same pore-scale flow physics; the taichi dependency is optional, so it is not run by default. (models) |
| Flow | lee2023.feedback |
Calibration / comparison | Competing flow paths in which extraction changes porosity and permeability, redistributing water. A qualitative fine-grind-dip hypothesis only — the decline needs an unphysical density. (card) |
| Flow | wadsworth2026.inertial |
Executable supporting model | Adds a Forchheimer inertial-resistance correction where Darcy's linear pressure–flow law starts to fail. A regime flag; the fitted constant is extrapolated for tamped coffee. (card) |
| Flow | sourcing2026.g10_liquor_rheology |
Source-data constraint | Supplies coffee-liquid viscosity and density versus temperature and concentration for flow-resistance studies. Measured on soluble-coffee extract and extrapolated to espresso; the bulk-cup effect is near-negligible. (card) |
| Puck change | brewer2026.streamtube |
Executable model (separate) | Uneven flow through parallel, non-exchanging paths whose permeability follows a statistical distribution. Calibrated at low dials; interpolated, not externally validated (a Puckworks model). (models) |
| Puck change | brewer2026.coupled_kappa_t |
Exploratory synthesis | Explores how swelling, compaction, fines movement, and extraction-driven porosity change might combine into a time-varying puck resistance. A framework only — as sound as its shakiest donor branch. (card) |
| Puck change | fasano2000_partI.fines_migration |
Calibration / comparison | Tracks mobile fines, deposition and release, compacted layers, and their effect on Darcy flow. A mechanism demonstration; the closures are ours, not the source paper's. (card) |
| Puck change | mo2023_2.swelling |
Executable model (separate) | Water entering particles, swelling, loss of pore space, and the resulting decline in permeability and flow. The fixed-pressure flow-decay ratio is reproduced; the swelling claim is unvalidated in the source. (card) |
| Puck change | waszkiewicz2025.poroelastic |
Executable model (separate) | Couples puck deformation, pressure, permeability, and dissolution-driven pore change in a saturated poroelastic bed. One rig and coffee; quantitative only above about 5 bar. (card) |
| Extraction | cameron2020.extraction_bdf |
Runs in Guided Pull | One-dimensional saturated extraction with advection, in-particle diffusion, and nonlinear dissolution from fine and coarse particle families. EK43 dial 1.1–2.3; 20 g in / 40 g out class recipes. (card) |
| Extraction | pannusch2024.solver |
Executable model (separate) | Extraction from fine and coarse particles with interphase mass transfer and temperature- and flow-dependent transport. 80–98 °C, 1–3 mL/s; the fitted Sherwood law lacks generality. (card) |
| Extraction | pannusch2024.closures |
Calibration / comparison | Supplies diffusivity, viscosity, density, Sherwood-number, temperature, and equilibrium relationships used by the pannusch extraction model. (card) |
| Extraction | grudeva2026.reduced |
Native publication reference | Independent equation-based fixed-flow extraction with separate wetting and desaturation fronts and spherical grain diffusion. Code verification only; Figures 3/4 fail reference tolerances and Figure 5 references are incomplete. (card) |
| Extraction | grudeva2025.reduced |
Registered scientific check — no common-scenario adapter yet | A reduced asymptotic extraction model with a moving wetting front and fine/coarse particle families (saturated-fines regime; prescribed flow). Its code is a faithful port of the authors' solver, used under Dr. Yoana Grudeva's direct written permission, 2026-08-14, covering code and data (#73, PERMISSION_DOCUMENTED); no SPDX licence — not MIT/CC-BY/public-domain (permission, notices). Runs its registered gates; not a common-scenario lens — its grain-volume basis has no tested conversion to bed-volume (technical, not rights). Evidence unchanged. (card) |
| Extraction | liang2021.desorption |
Calibration / comparison | An immersion-derived equilibrium extraction ceiling and retained-liquid correction. Not itself a flowing-puck model — it supplies a ceiling and a kernel. (card) |
| Extraction | maille2024.two_regime |
Calibration / comparison | Early-time release of five named compounds in a stirred batch vessel, as a fast phase plus a slow phase. The best sub-30-second per-compound data here, but with no bed, pressure or flow, and no yield or strength output. (card) |
| Extraction | moroney2016.surrogate |
Calibration / comparison | A reduced constant-pressure extraction model that captures early release, a plateau, and later wash-through. Qualitative reproduction of the source figure. (card) |
| Extraction | mo2023_2.coupled_bed |
Executable model (separate) | Extraction resolved by bed depth using fine/coarse diffusion, partitioning, and a moving filling front under fixed flow. Type-M, cup mass below ~30 g; absolute yield needs one inventory scale. (card) |
| Extraction | romancorrochano2017.extraction |
Executable model (separate) | Molecular-size-dependent diffusion from spherical coffee grains with partitioning between solid and liquid. Solver verified against the analytic solution; supplies a flow trend, not absolute yield. (card) |
No registered component is currently validated as a universal whole-process coupled espresso model. Each runs, or constrains, its own stage; the Guided Pull executes only the Cameron extraction chain above. The Espresso Model Relay is a separate, assumption-rich product demonstration that illustrates selected hand-offs between components (direct links, documented adapters, and explicit assumptions) without claiming whole-chain validation.
Five public paths (no local setup required):
- Explore the component registry — ▶ Open the quickstart in Google Colab: list the models, read each one's source and the conditions where it applies, and run the automated scientific checks. It installs the latest released wheel after verifying its SHA-256.
- Run the Full Laboratory Tour in your browser — 🧪 Open the Guided Pull Laboratory in Colab: a short form plus one ▶ Run the Laboratory button — no terminal, no code to type. The default Full Laboratory Tour resolves all 28 registered components and runs the 27 that are scientifically and legally available — one common-scenario run of your recipe (Cameron), five native reference cases, and twenty-one registered scientific checks — grouped by espresso stage with a plain-language badge on every card (other modes: Quick Tour, Your Shot Only, Model Library Only). Outputs are never averaged, ranked, or overlaid: a native case is not a prediction of your shot, and a gate pass is not experimental validation. It runs privately in your own Colab runtime (
LOCAL_PRIVATE; not a public-hosting clearance), installs a commit-pinned development preview (0.4.0.dev0), runsgrudeva2025.reducedonly as its registered gates (#73), and is not a digital twin, optimizer, or taste predictor. Seedocs/GUIDED_PULL_LABORATORY.md. - Follow one illustrative pull through linked models — 🔗 Open the Espresso Model Relay in Colab: one hypothetical espresso pull, passed from model to model. At each station it shows what the model calculates, what is handed forward, what had to be assumed, and what the result might mean for the cup. An assumption-rich educational relay, not a validated coupled simulation — a separate experience from the Full Laboratory Tour (which is unchanged). The default fast run authoritatively executes 20 components with 10 explicit, serialized cross-model hand-offs (each labelled direct / documented-adapter / illustrative-assumption), a first-class assumption ledger, Cameron as a baseline (not the whole story), and a dashboard that never averages branches and produces no taste or confidence score. Runs privately (
LOCAL_PRIVATE), givesgrudeva2025.reducedzero calls — no compatible hand-off, not a rights block (#73) — and is not a digital twin, optimizer, or taste predictor. Seedocs/ILLUSTRATIVE_LINKED_PULL.md. - Run a guided espresso pull — ▶ Open the Guided Espresso Pull in Google Colab: enter a bounded recipe and run one coherent, model-backed pull stage by stage, with evidence-labelled traces and honest range warnings. You supply the dose, beverage mass, grinder dial, and pressure; the
cameron2020.extraction_bdfmodel runs; you get extraction-yield, strength, flow, and a stage-by-stage report. It reports chemical composition, not taste; it does not model puck wetting, physical first drip, a dynamic pressure profile, temperature response, or flavor. Seedocs/GUIDED_ESPRESSO_PULL.mdand issue #48. - Explore why the cup hides the clock — ▶ Open the flat-valley interactive: a static, generated explainer of why a good whole-cup endpoint fit can still hide weak parameter identification. Every number is generated from a committed result bundle; no install needed.
Locally, after pip install, the puckworks-pull command-line tool runs the same guided espresso
pull deterministically and writes JSON/Markdown/figures — see docs/GUIDED_ESPRESSO_PULL.md.
In development (0.4.0.dev0, not in the released v0.3.0): the Guided Pull Laboratory exposes the
full component registry and runs the compatible subset as independent model lenses — it never averages
competing mechanisms and is not a digital twin. See docs/GUIDED_PULL_LABORATORY.md.
Ways to run it (novice-first):
- Explore the Laboratory — the browser Colab above: a form + one Run button, no terminal.
- Run privately in Colab — the same notebook runs models privately (
LOCAL_PRIVATE), including ones not yet cleared for public hosting. - Public web Explorer —
apps/lab_public_app.py(PUBLIC_ARTIFACT): browse the full model library with no execution, and run only the per-model, affirmatively rights-cleared components live. Deployment is a maintainer step (docs/DEPLOYMENT.md); no public URL is advertised until a human verifies it signed out. - Advanced — CLI / local Python —
puckworks-pullandpython -m puckworks.product.labfor deterministic, scriptable, reproducible runs. - Contributor Codespaces — the dynamic development UI. Open a GitHub Codespace
(
.devcontainer/installs.[dev,viz,webapp]), thenstreamlit run apps/lab_app.py(LOCAL_PRIVATE) — it runs the development version (0.4.0.dev0), not necessarily the latest release. - Actions — reproducible batch artifacts: the manually dispatched
guided-pull-batchworkflow (workflow_dispatch) builds the current wheel and writes deterministic JSON/Markdown/figure. It is a batch runner, not a live UI. As a public artifact run it applies a rights preflight before any producer: it is gated pending an affirmative rights review of the extraction lens (cameron2020.extraction_bdf, currentlyNOT_REVIEWED), so a public run currently blocks and emits only the rights diagnostic. Local/private inspection is unaffected.
More public stories:
- See why espresso model components do not simply add up — a static, generated interactive showing how adding a swelling branch to an extraction model, through one shared porosity state, makes the prediction worse than a flat baseline (it rejects one tested composition, not swelling in general).
- See how we falsified our own espresso headline — a static, generated analysis autopsy. An attractive interior "fine-grind" extraction-yield maximum weakened once the target was rebuilt on one coherent TDS basis and the raw replicate points were plotted: the corrected cell means are ordered with the middle dial below the coarse dial (no interior maximum), while a model can still draw such a feature without identifying its cause. Every number is generated and bound to the CC-BY Schmieder source. These are grinder-dial positions on one machine and coffee — a dial is not a particle size and does not describe a universal grinder behaviour.
Specialists: the advanced GPU / lattice-Boltzmann notebook remains at
notebooks/espresso_lb_colab.ipynb.
Puckworks uses published measurements to set model inputs, reproduce reported results, and test whether
a model predicts observations it was not fitted to. These are different levels of evidence: an
independent measurement is a stronger test than reproducing a curve that was used to tune the model.
Every dataset and its evidence level is recorded, one row per artifact, in
puckworks/data/MANIFEST.csv.
| Dataset or source family | What the data contains | How Puckworks uses it | Evidence level |
|---|---|---|---|
| Poroelastic flow rig (Waszkiewicz 2025) | 9-bar flow traces, TDS fractions, particle-size distribution, rig constants | Checks the poroelastic bed model and the pump→basket adapter; PSD reference | Independent within-rig; part post-fit reconstruction |
| Grind and permeability (Wadsworth 2026) | Measured mean particle radius, size spread, and untamped Darcy permeability | Sets the grind map and the permeability relationship | Independent measurement |
| Extraction kinetics (Schmieder 2023) | Timed extraction fractions, cup masses, fitted kinetic parameters | Reproduces multi-species extraction kinetics; drives the pannusch closures | Post-fit reconstruction; raw fractions independent |
| Kinetic closures and control chart (Pannusch 2024) | Fitted Sherwood parameters and experimental kinetics (public Mendeley set) | Sets and checks the pannusch extraction closures and solver | Post-fit reconstruction |
| CT infiltration and machine mode (Foster 2025) | Time-resolved micro-CT wetting fronts, headspace, and flow curves | Checks the infiltration front and the machine-mode delivery model | Post-fit, same-campaign CT observations / verification of fitted trajectories |
| Immersion desorption (Liang 2021) | Full-immersion strength/extraction-yield and oven-dry retention | Sets the equilibrium extraction ceiling and retained-liquid kernel | Post-fit reconstruction; retention independent |
| Asymptotic surrogate (Moroney 2016) | Model parameters and a published exit-concentration curve | Reproduces the surrogate extraction model's plateau and wash-through | Reference set / qualitative |
| Reduced multiscale model (Grudeva 2026) | Two named configurations and per-vial extracted masses | Checks the reduced asymptotic extraction model | Reference set / post-fit reconstruction |
| Microstructural diffusion and permeability (Roman-Corrochano 2017) | Measured effective diffusivity, partition, hindrance, and tamped permeability | Sets diffusion in grains and a tamped-bed permeability target | Independent measurement; partition post-fit |
| Microstructure and swelling (Mo 2023) | Micro-CT / SPH flow and granulometry, and a fixed-pressure flow-decay curve | Checks the inertial-flow overlay and the swelling / coupled-bed models | Independent (SPH-derived) / verification |
| Multi-species independent validation (Angeloni 2023) | Caffeine, trigonelline, total solids, lipids, and roast-and-ground inventories | An out-of-fit test on a different machine, coffee, and basket | Independent measurement |
| Fines dynamics (Fasano 2000; Ellero 2019; Smrke 2024) | Transport, discharge and fines/extraction figures | Mechanism demonstrations; Smrke supplies endpoint and partial plotted-flow observations, not an exclusive permeability mechanism (card) | Qualitative / model-output verification; Smrke graphical observations |
| Coffee-liquid rheology (Telis-Romero 2000, 2001; Khomyakov 2020; Sobolík 2002) | Viscosity, density, thermal, and electrical properties of coffee extract vs temperature and concentration | Supplies the liquid-property closures for flow-resistance studies; Sobolík is a third/fourth independent viscosity source that adjudicates the inter-source spread | Source-curve reproduction / reference |
| Reference inputs and engineering constraints | Pump P–Q endpoints, glass-bead retention, basket geometry (Schulman 2011; McKeon Aloe 2022), swelling anchors (Hargarten 2020), roasted composition (Bruno 2026), edge/center yield (Pocket Science 2024), an EY/TDS bracket (Egidi 2024) | Provide physical properties, boundary conditions, and coarse validation brackets rather than validating a whole model | Reference / qualitative |
Not shown here: one machine-logged hydraulic population source is used under permission and is not
redistributed (see puckworks/data/MANIFEST.csv for its access
terms). "Independent" above means data not used to tune the model; "post-fit reconstruction" means the
comparison uses data that helped set the parameters; "verification" means the code reproduces an
equation, table, or published curve; and "reference" data supply a property or boundary condition
rather than validating the whole model.
Puckworks has explicit measurement campaigns — the datasets that would move a model from reproduced
to independently validated and unlock new adapters. Community data can genuinely unlock validation.
See docs/EXPERIMENTAL_DATA_NEEDS.md and propose or submit via the
experimental-data issue form. A data submission
never auto-authorizes a model or an evidence upgrade.
Each model keeps a visible connection to the paper, dataset, assumptions, units, and conditions it came from. Automated scientific checks then compare each implementation with equations, published curves, or independent measurements wherever those exist.
A few precise terms, defined in plain language:
- The model catalog is called the registry in the code (
puckworks/registry.py). - The checked data handoffs between stages are typed interfaces, called contracts in the code
(
puckworks/contracts.py) — strict SI units, validated inputs and outputs. - Where a model or number came from is stored as its source history, called provenance.
- Each model records the conditions where it applies — its validity range.
In the code these automated checks are validation gates. Each reports PASS, FAIL, SKIP, ERROR, or ACKNOWLEDGED_EXCEPTION: FAIL and ERROR make the suite fail, SKIP is never counted as a pass, and an acknowledged exception is reported separately, never laundered into a pass. Every reported number carries an origin label — measured · derived · fitted · predicted · simulated — or is marked unsupported. Puckworks never upgrades one of these evidence labels.
Research records and longer reads:
- Completed espresso review and source execution.
- The public-value work —
docs/PUBLIC_VALUE.mdmaps how readers can understand, check and share Puckworks' data, model disagreements and negative results. Its first interactive, The Cup Hides the Clock, is live (linked above); the generated, evidence-labelled claim cards that back these stories live indocs/public/README.md. - The paper behind the flat-valley result —
docs/submission/PAPER_A_JFE_MANUSCRIPT.mdis a draft manuscript (with a full abstract), "Whole-cup measurements can obscure kinetic parameter localization in espresso extraction models." It shows how a model can match the final cup while leaving the internal extraction rates weakly constrained — the technical write-up behind the interactive. It is a working draft, not yet submitted or peer-reviewed.
Auto-generated from tracked repository state by
tools/update_readme_pulse.py— inventory counts, not scientific claims. Regenerate with--write; CI fails if stale.
| Project pulse | |
|---|---|
| Latest public release | v0.3.0 (puckworks-0.3.0-py3-none-any.whl; not on PyPI) |
| Development source | 0.4.0.dev0 (unreleased) |
| Registered components | 28 |
| Validation gates | 67 total — 66 PASS, 1 ACKNOWLEDGED_EXCEPTION (passed under the documented gate policy) |
| Active outcome | Guided Espresso Pull — v0.3.0 published; awaiting signed-out human Colab acceptance |
| Blocked outcomes | 3 (external sign-off / data) |
| Supported Python | 3.10–3.13 (3.12 primary/release interpreter) |
Development status and the latest public release are shown separately above — do not read the development source as a released capability.
puckworks is not published on PyPI. The canonical distributions are attached to the latest GitHub Release.
Download puckworks-0.3.0-py3-none-any.whl from the release, then:
python -m pip install puckworks-0.3.0-py3-none-any.whl
python -c "import puckworks; s = puckworks.evaluate_all_gates(); print(s.summary_text())"
python -c "import puckworks; print(len(puckworks.components()), 'models registered')"
The same pure-Python wheel is smoke-tested on Windows, macOS, and Linux under Python 3.12;
interpreter CI additionally exercises Python 3.10, 3.12, and 3.13. Per-platform commands and the
support matrix: docs/ACCESSIBILITY.md.
The supported public API is exactly puckworks.__all__; selected commonly-used entry points from
it include evaluate_all_gates, components, get, Component, contracts, validate,
load_builtin_components, GateStatus, GateResult, and GateSuiteResult. See
docs/API.md for the full surface and stability policy; everything else is internal
research tooling. (The Colab notebooks install the v0.3.0 wheel — its API is v0.3.0's __all__,
which may differ from the unreleased main branch.)
Contributors / release builders: python -m pip install -e ".[dev]"; see
CONTRIBUTING.md.
- Enthusiast / layperson → run the Colab quickstart, then read The espresso pull, modeled stage by stage above.
- Researcher → start at docs/ONBOARDING.md, then the model cards in
docs/cards/(the source of truth for each model's physics) and current status. - Contributor → CONTRIBUTING.md and the card-first process; the public API is documented in docs/API.md.
Puckworks is:
- not a universal mega-model, and its models are not fused into one coupled simulation;
- not an automatic channeling detector;
- not a flavor or taste predictor — it reports chemical composition, not sensory quality;
- not a universal recipe optimizer;
- not a replacement for controlled experiments;
- not a mechanism oracle.
The current Guided Pull begins from an already-saturated puck: it does not model dry-puck wetting or physical first drip, holds temperature fixed (no thermal transient), prescribes a constant pressure, and reports chemical composition rather than taste. Most extraction agreements in the underlying science are post-fit reconstruction, not independent validation. The catalog surfaces conflicting constants and per-lineage inventories side by side rather than merging them.
- Write the model card from
docs/cards/TEMPLATE.mdbefore coding. - Implement under
puckworks/models/<key>/, using typed contracts. - Register in
puckworks/models/__init__.pywith assumptions and the conditions where it applies. - Add at least one automated check wired to real data in
puckworks/data/.
Details: CONTRIBUTING.md, docs/API.md, and the doc index docs/CURRENT.md.
Published sources and cards are listed below.
-
Angeloni, S.; Giacomini, J.; Maponi, P.; Perticarini, A.; Vittori, S.; Cognigni, L.; Fioretti, L. "Computer percolation models for espresso coffee: state of the art, results and future perspectives." Applied Sciences 13 (2023): 2688. https://doi.org/10.3390/app13042688. Related cards: angeloni2023.
-
Bruno, R.; Egidi, N.; Fatone, L.; Giacomini, J.; Maponi, P.; Sagratini, G.; Santanatoglia, A.; Trebović, S. "A preliminary model to establish a digital twin for coffee roasting." Scientific Reports 16 (2026): 15857. https://doi.org/10.1038/s41598-026-43923-9. Related cards: bruno2026.
-
Cameron et al. "Systematically improving espresso." Matter 2 (2020): 631–648. https://doi.org/10.1016/j.matt.2019.12.019. Related cards: cameron2020. Source execution.
-
Egidi, N.; Giacomini, J.; Larsson, E.; Perticarini, A. "An improved numerical scheme for coffee extraction yield evaluation." Chaos, Solitons & Fractals 188 (2024): 115625. https://doi.org/10.1016/j.chaos.2024.115625. Related cards: egidi2024.
-
Ellero, M.; Navarini, L. "Simulation of espresso coffee extraction using smoothed particle hydrodynamics." Proc. PARTICLES 2019 (2019): 68–79. No stable external link is recorded in the model card. Related cards: ellero2019.
-
Fasano, A.; Talamucci, F.; Petracco, M. "The espresso coffee problem." In Complex Flows in Industrial Processes (A. Fasano, ed.), 241–280. Springer, 2000. No DOI is recorded in the model card. Related cards: fasano2000_partI.
-
Foster, J.; Lee, W.; Moroney, K.; Prjamkov, D.; Salamon, M.; Smith, A.; Petrassem-de-Sousa, J.; Vynnycky, M. "Dynamics of liquid infiltration into an espresso bed using time-resolved micro-computed tomography: insights from experiment and modeling." Physics of Fluids 37 (2025): 013383. https://doi.org/10.1063/5.0245167. Related cards: foster2025, foster2025_2.
-
Grudeva, Y. "Espresso brewing: mathematical modelling and experiment." PhD thesis, University of Portsmouth, 2023 (no DOI). And: Grudeva, Y.; Moroney, K.; Foster, J. "A multiscale model for espresso brewing: asymptotic analysis and numerical simulation." European Journal of Applied Mathematics 37 (2026): 496–519. https://doi.org/10.1017/S095679252500018X. Related cards: grudeva2025, grudeva2026_2.
-
Hargarten, V. B.; Kuhn, M.; Briesen, H. "Swelling properties of roasted coffee particles." Journal of the Science of Food and Agriculture 100(11) (2020). https://doi.org/10.1002/jsfa.10440. Related cards: hargarten2020.
-
Khomyakov, A. P.; Mordanov, S. V.; Khomyakova, T. V. "The experimental data on the density, viscosity, and boiling temperature of the coffee extract." IOP Conf. Series: Earth and Environmental Science 548 (2020): 022040. https://doi.org/10.1088/1755-1315/548/2/022040. Related cards: khomyakov2020.
-
Lee, W.; Smith, A.; Arshad, S. "Uneven extraction in coffee brewing." Physics of Fluids (2023). The model card records the DOI as https://doi.org/10.1063/5.0138998 but flags the volume and DOI as unverified. Related cards: lee2023.
-
McKeon Aloe, R. "Wafo vs VST: espresso filter basket analysis." Coffee Data Science (Medium), 2022. No DOI is recorded in the model card. Related cards: mckeonaloe2022.
-
Mo, C.; Johnston, D.; Navarini, L.; Suggi Liverani, F.; Ellero, M. "Exploring the link between coffee matrix microstructure and flow properties using combined X-ray microtomography and smoothed particle hydrodynamics simulations." arXiv:2305.03911 (2023). https://arxiv.org/abs/2305.03911. Related cards: mo2023.
-
Mo, C.; Navarini, L.; Suggi Liverani, F.; Ellero, M. "Modelling swelling effects in real espresso extraction using a 1-dimensional coarse-grained model." Journal of Food Engineering (2023). https://doi.org/10.1016/j.jfoodeng.2023.111843. Related cards: mo2023_2.
-
Moroney, K.; Lee, W.; O'Brien, S.; Suijver, F.; Marra, J. "Asymptotic analysis of the dominant mechanisms in the coffee extraction process." SIAM Journal on Applied Mathematics 76(6) (2016): 2196–2217. https://doi.org/10.1137/15M1036658. Related cards: moroney2016.
-
Pannusch, V. B., et al. "Model-based kinetic espresso brewing control chart for representative taste components." Journal of Food Engineering 367 (2024): 111887. https://doi.org/10.1016/j.jfoodeng.2023.111887. Validation dataset: Mendeley https://doi.org/10.17632/y2tz67f6ry.1. Related cards: pannusch2024.
-
Liang, N.; Chan, S.; Ristenpart, W. "An equilibrium desorption model for the strength and extraction yield of full immersion brewed coffee." Scientific Reports 11 (2021): 6904. https://doi.org/10.1038/s41598-021-85787-1. Related cards: liang2021.
-
Pocket Science Coffee. "Espresso water flow part 1: dispersion, puck screens and baskets." Blog, 2024. https://pocketsciencecoffee.com/2024/02/27/espresso-water-flow-part-1-dispersion-puck-screens-and-baskets/. Related cards: pocketscience2024.
-
Perticarini, A. "Predictive Models in Espresso Coffee Percolation." Ph.D. thesis, Universita degli Studi di Camerino, School of Advanced Studies, deposited 28 Feb 2024. No DOI. Related cards: perticarini2024, perticarini2024_3d.
-
Roman-Corrochano, B. "Advancing the engineering understanding of coffee extraction." EngD thesis, University of Birmingham, 2017. No DOI is recorded in the model card (University of Birmingham e-theses repository). Related cards: romancorrochano2017_extraction, romancorrochano2017_permeability.
-
Schmieder, F.; Pannusch, V. B.; Vannieuwenhuyse, A.; Briesen, H.; Minceva, M. "Influence of flow rate, particle size, and temperature on espresso extraction kinetics." Foods 12 (2023): 2871. https://doi.org/10.3390/foods12152871. Related cards: schmieder2023.
-
Schulman, J. "How filter baskets affect espresso taste and barista technique." Home-Barista.com study, 2011. No DOI is recorded in the model card. Related cards: schulman2011, schulman2011_baskets.
-
Telis-Romero, J.; Gabas, A. L.; Polizelli, M. A.; Telis, V. R. N. "Temperature and water content influence on thermophysical properties of coffee extract." International Journal of Food Properties 3(3) (2000): 375–384. https://doi.org/10.1080/10942910009524643. Related cards: telisromero2000.
-
Telis-Romero, J.; Cabral, R. A. F.; Gabas, A. L.; Telis, V. R. N. "Rheological properties and fluid dynamics of coffee extract." Journal of Food Process Engineering 24 (2001): 217–230. https://doi.org/10.1111/j.1745-4530.2001.tb00542.x. Related cards: telisromero2001.
-
Wadsworth et al. Royal Society Open Science 13 (2026): 252031. https://doi.org/10.1098/rsos.252031. Title and author names are not recorded in the model card. Related cards: wadsworth2026, wadsworth2026_grindmap, wadsworth2026_inertial.
-
Waszkiewicz, S.; Myck, M.; Białas, M.; Puciata-Mroczynska, M.; Dzikowski, M.; Szymczak, P.; Lisicki, M. "Under pressure: poroelastic regulation of flow in espresso brewing." arXiv:2512.21528 (2025); code and data on Zenodo. https://arxiv.org/abs/2512.21528. Related cards: waszkiewicz2025.
-
Yasuda, H.; Katsuragi, H.; Katsura, M. "Liquid water transport model in hydrophilic granular." arXiv:2501.13361 (2025). https://arxiv.org/abs/2501.13361. Related cards: g1_glassbead_analog.
-
Moroney, K. M.; O'Connell, K.; Meikle-Janney, T.; O'Brien, S. B. G.; Walker, G. M.; Lee, W. T. "Analysing extraction uniformity from porous coffee beds using mathematical modelling and computational fluid dynamics approaches." PLoS ONE 14(7) (2019): e0219906. https://doi.org/10.1371/journal.pone.0219906. Author-confirmed errata via Cooper, M. "Modeling Extraction," Quantitative Café (2021), https://quantitativecafe.com/2021/11/14/modeling-extraction/. Related cards: moroney2019, cooper2021.
-
Ribes, S. "Radial uniformity of espresso extractions." Slide deck (Decent community), 2020. No DOI is recorded in the model card. Related cards: ribes2020.
-
Ribes, S. "Espresso extraction radial uniformity — BPLUS contact screen." Slide deck (Decent community), 2021. No DOI is recorded in the model card. Related cards: ribes2021.
-
Roman-Corrochano, B.; Melrose, J. R.; Bentley, A. C.; Fryer, P. J.; Bakalis, S. "A new methodology to estimate the steady-state permeability of roast and ground coffee in packed beds." Journal of Food Engineering 150 (2015): 106–116. No DOI is recorded in the model card. Related cards: romancorrochano2015.
-
Gagné, J. "A comparison between standard and low-fines espresso shots." Coffee Ad Astra (blog / Patreon), 2021. No DOI is recorded in the model card. Related cards: gagne2021.
-
Khamitova, G. "Advanced experimental and analytical study for the optimization of the espresso coffee extraction." PhD dissertation, University of Camerino, 2020. No DOI is recorded in the model card. Related cards: khamitova2020.
-
Smrke, S.; Eiermann, A.; Yeretzian, C. "The role of fines in espresso extraction dynamics." Scientific Reports 14 (2024): 5612. https://doi.org/10.1038/s41598-024-55831-x. Related cards: smrke2024.
-
Sobolík, V.; Žitný, R.; Tovcigrecko, V.; Delgado, M.; Allaf, K. "Viscosity and electrical conductivity of concentrated solutions of soluble coffee." Journal of Food Engineering 51 (2002): 93–98. https://doi.org/10.1016/S0260-8774(01)00042-5. Related cards: sobolik2002.
-
Moroney, K.; Lee, W.; O'Brien, S.; Suijver, F.; Marra, J. "Modelling of coffee extraction during brewing using multiscale methods: an experimentally validated model." Chemical Engineering Science 137 (2015): 216–234. https://doi.org/10.1016/j.ces.2015.06.003. Related cards: moroney2015.
-
Vaca Guerra, M.; Harshe, Y. M.; Fries, L.; Rothberg, S.; Palzer, S.; Heinrich, S. "Influence of particle size distribution on espresso extraction via packed bed compression." Journal of Food Engineering 340 (2023): 111301. https://doi.org/10.1016/j.jfoodeng.2022.111301. Related cards: vacaguerra2023a.
-
Maille (2024), Measuring Coffee Extraction Kinetics at Early Time Scales. Sheffield PhD thesis. Card.
-
Gloess, A. N.; Schönbächler, B.; Klopprogge, B.; D'Ambrosio, L.; Chatelain, K.; Bongartz, A.; Strittmatter, A.; Rast, M.; Yeretzian, C. "Comparison of nine common coffee extraction methods: instrumental and sensory analysis." European Food Research and Technology 236 (2013): 607–627. https://doi.org/10.1007/s00217-013-1917-x. Related cards: gloess2013.
-
SCI-MD-007-R1 cards: Dias, Viencz, Acre, and register package.
-
Melrose et al. (2019), packed-bed preprint. Card.
-
Matias et al. (2023), Physics of Fluids 35, 123611. Card and benchmark.
These cards are Puckworks-authored technical notes, not peer-reviewed papers.
- Coupled porosity change over time. Puckworks technical note. Composes poroelastic, swelling, compaction, and fines mechanisms into one exploratory time-varying-resistance model (framework only). Model card.
- Coffee-liquid rheology envelope. Puckworks sourcing note. Aggregates the Telis-Romero (2000, 2001) and Khomyakov (2020) measurements above, with a cross-check paper (https://doi.org/10.1080/10942912.2013.833221); the note records slightly different final DOI digits for the two Telis-Romero papers than their dedicated cards, so the dedicated-card DOIs are used above. Model card.
- Pump characteristic envelope. Puckworks sourcing note. Bounds a vibration-pump pressure–flow envelope from manufacturer catalogues and community hydraulics; no single citable work. Model card.
Puckworks is co-developed by Tim Brewer (@trbrewer) and
Peter Vonk. See AUTHORS.md for what software authorship does and does not imply, and
cite the software via CITATION.cff.
Puckworks is released under the MIT License, covering Puckworks-authored material.
Third-party material on another basis is in THIRD_PARTY_NOTICES.md — today
the Grudeva code and derived vial statistics, under direct written permission (2026-08-14), not
an SPDX licence and not MIT. It is independently developed and is not affiliated with or sponsored
by any employer or company. Contact: t_r_brewer@hotmail.com.

