Skip to content
trbrewerPublic

About

Evidence-first espresso process modeling: papers become typed components, components face validation gates, and every conclusion retains its limits.

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,169 Commits

Folders and files

Puckworks logo for physics-based espresso modeling — a teal espresso cup with gears above the puckworks wordmark and the line 'tested physics for espresso'.

puckworks

Continuous integration test status Latest tagged GitHub release Supported Python versions 3.10 to 3.13 Project license is MIT

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.

External espresso data — start here

Data guide: sources, inspection limits and access. Private originals remain outside Git.

🧪 Full Laboratory Tour
visit every model independently
🔗 Espresso Model Relay
follow one illustrative pull through linked models
☕ Guided Espresso Pull
run one recipe stage by stage
📋 Quickstart
browse the espresso models
Open the Full Laboratory Tour in Google Colab Open the Espresso Model Relay in Google Colab Open the Guided Espresso Pull in Google Colab Open the Puckworks CPU quickstart in Google Colab

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.


The espresso pull, modeled stage by stage

An espresso shot is a chain of physical steps:

The espresso pull as a chain of physical stages: grind, form the puck, deliver pressure and water, wet the puck, move water through it, change the puck, and extract material into the cup.

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.

What you can run today

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), runs grudeva2025.reduced only as its registered gates (#73), and is not a digital twin, optimizer, or taste predictor. See docs/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), gives grudeva2025.reduced zero calls — no compatible hand-off, not a rights block (#73) — and is not a digital twin, optimizer, or taste predictor. See docs/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_bdf model 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. See docs/GUIDED_ESPRESSO_PULL.md and 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-pull and python -m puckworks.product.lab for deterministic, scriptable, reproducible runs.
  • Contributor Codespaces — the dynamic development UI. Open a GitHub Codespace (.devcontainer/ installs .[dev,viz,webapp]), then streamlit 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-batch workflow (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, currently NOT_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.

Data used to check the models

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.

Experimental data Puckworks needs

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.

How Puckworks checks its work

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.

How evidence moves through Puckworks, as a six-step single column: (1) a paper or dataset, to (2) a model card capturing the physics, parameters, assumptions and the conditions where each model applies, to (3) a testable model module with a checked data handoff between stages and a record of where it came from, to (4) automated scientific checks comparing it with equations, published curves, or independent data and showing known gaps rather than hiding them, to (5) an evidence-aware result with every number labelled measured, derived, fitted, predicted or simulated, to (6) what to measure next, or what the data cannot yet support. A dashed feedback loop returns from step 6 to step 1 because uncertainty guides the next experiment.

The science, in depth

Research records and longer reads:

  • Completed espresso review and source execution.
  • The public-value work — docs/PUBLIC_VALUE.md maps 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 in docs/public/README.md.
  • The paper behind the flat-valley result — docs/submission/PAPER_A_JFE_MANUSCRIPT.md is 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.

Project pulse

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.

Install the public release

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.

Choose your path

Current limits — what Puckworks deliberately does not claim

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.

Contribute

  1. Write the model card from docs/cards/TEMPLATE.md before coding.
  2. Implement under puckworks/models/<key>/, using typed contracts.
  3. Register in puckworks/models/__init__.py with assumptions and the conditions where it applies.
  4. 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.

References

Published sources and cards are listed below.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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.

  13. 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.

  14. 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.

  15. 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.

  16. 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.

  17. 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.

  18. 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.

  19. 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.

  20. 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.

  21. 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.

  22. 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.

  23. 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.

  24. 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.

  25. 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.

  26. 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.

  27. 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.

  28. 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.

  29. Ribes, S. "Radial uniformity of espresso extractions." Slide deck (Decent community), 2020. No DOI is recorded in the model card. Related cards: ribes2020.

  30. 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.

  31. 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.

  32. 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.

  33. 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.

  34. 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.

  35. 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.

  36. 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.

  37. 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.

  38. Maille (2024), Measuring Coffee Extraction Kinetics at Early Time Scales. Sheffield PhD thesis. Card.

  39. 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.

  40. SCI-MD-007-R1 cards: Dias, Viencz, Acre, and register package.

  41. Melrose et al. (2019), packed-bed preprint. Card.

  42. Maille et al. (2021), particle swelling. DOI; data card.

  43. Matias et al. (2023), Physics of Fluids 35, 123611. Card and benchmark.

Puckworks synthesis and sourcing notes

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.

Developers and citation

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.

About

Evidence-first espresso process modeling: papers become typed components, components face validation gates, and every conclusion retains its limits.

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages