Paper: Caching for fast notebook restarts

Author: dmadisetti

papers/marimo_caching/figs/.gitignore

@@ -0,0 +1,4 @@
+# Generated vector figures. `save_fig` writes both .svg and .png; we
+# track only the .png (vector XML dumps thousands of noisy diff lines).
+# Regenerate locally with `make figures`.
+*.svg

papers/marimo_caching/figs/alg_hash.png

@@ -0,0 +1,16 @@
+// Standalone render of the key-derivation listing, rasterized to PNG
+// and composed into figs/fig1_dispatch.png (see compose_fig1.py).
+// Mirrors the styling the paper previously applied via @preview/algo.
+#import "@preview/algo:0.3.6": code
+
+#set page(width: auto, height: auto, margin: 2pt, fill: none)
+
+#code(
+  fill: rgb(99%, 99%, 99%),
+  stroke: 0.6pt + rgb(70%, 70%, 70%),
+  radius: 2pt,
+  inset: 7pt,
+  row-gutter: 6.5pt,
+  main-text-styles: (size: 8.5pt),
+  line-number-styles: (size: 7.5pt, fill: rgb(45%, 45%, 45%)),
+)[#raw(lang: "py", block: false, "def derive_key(cell, graph, scope) -> HashKey:\n    refs = ScopedVisitor(cell.module).refs         # static analysis\n    refs = normalize_scope(refs, scope)            # UI/state -> values\n    h, kind = sha256(), \"Pure\"                     # no refs: pure cell\n\n    if refs:                                       # content-address first\n        kind = \"ContentAddressed\"\n        refs, serial = content_serialize(refs, scope)\n        for ref in sorted(serial):\n            h.update(serial[ref])                  # buffer-protocol view\n\n    if refs:                                       # substitute producers\n        kind = \"ExecutionPath\"\n        for parent in producing_cells(refs, graph):\n            h.update(derive_key(parent, graph, scope).digest)\n\n    if refs - scoped_refs:                         # same-cell context\n        kind = \"ContextExecutionPath\"\n        h.update(hash_module(cell.context))\n\n    h.update(hash_module(compile(cell.module)))    # bytecode, not source\n    return HashKey(h.digest(), kind)")]

papers/marimo_caching/figs/alg_hash.typ

@@ -0,0 +1,31 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["pillow"]
+# ///
+"""Compose Figure 1: top-down dispatch flow (left) beside the
+rasterized key-derivation listing (right).
+
+Inputs (both rendered at 300 ppi):
+  fig1_dispatch_flow.png  — `dot -Tpng -Gdpi=300 fig1_dispatch.dot`
+  alg_hash.png            — `typst compile --format png --ppi 300 alg_hash.typ`
+
+Output: fig1_dispatch.png, transparent background, panels scaled to a
+common height with a small gutter.
+"""
+
+from PIL import Image
+
+GUTTER = 90  # px at 300 ppi ≈ 7.6 mm
+
+flow = Image.open("fig1_dispatch_flow.png").convert("RGBA")
+alg = Image.open("alg_hash.png").convert("RGBA")
+
+# Scale the listing to the flow's height (flow sets the height budget).
+h = flow.height
+alg = alg.resize((round(alg.width * h / alg.height), h), Image.LANCZOS)
+
+canvas = Image.new("RGBA", (flow.width + GUTTER + alg.width, h), (0, 0, 0, 0))
+canvas.paste(flow, (0, 0), flow)
+canvas.paste(alg, (flow.width + GUTTER, 0), alg)
+canvas.save("fig1_dispatch.png")
+print(f"fig1_dispatch.png: {canvas.width}x{canvas.height}")

papers/marimo_caching/figs/compose_fig1.py

@@ -0,0 +1,65 @@
+// Cache key dispatch — flat three-way fallback, top-down flow.
+// Rendered to figs/fig1_dispatch_flow.png via `make flowchart`, then
+// composed with the rasterized derivation listing (figs/alg_hash.typ)
+// into figs/fig1_dispatch.png by figs/compose_fig1.py.
+//
+// A per-ref dispatch tries three categories in order:
+//   1. Pure              — immutable primitives, hash the value directly.
+//   2. ContentAddressed  — buffer-protocol bytes, hash the buffer.
+//   3. ExecutionPath     — fall back to the producing cell's stored H.
+// All three feed the same sha256 combiner at the bottom, which
+// concatenates the per-ref keys with the cell's compiled bytecode to
+// produce H(cell).
+
+digraph dispatch {
+  rankdir = TB;
+  graph [bgcolor="transparent", fontname="serif", fontsize=11,
+         nodesep=0.25, ranksep=0.32];
+  node  [fontname="serif", fontsize=10, color="#333333", penwidth=0.9,
+         margin="0.10,0.05"];
+  edge  [fontname="serif", fontsize=9, color="#555555", arrowsize=0.7];
+
+  // ── entry ─────────────────────────────────────────────────────
+  ref [label="per ref",
+       shape=box, style="rounded,filled", fillcolor="#f5f5f5"];
+
+  // ── decisions ────────────────────────────────────────────────
+  q_pure [label="immutable?",
+          shape=diamond, style=filled, fillcolor="#e3f2fd"];
+  q_buf  [label="buffer\nprotocol?",
+          shape=diamond, style=filled, fillcolor="#e8f5e9"];
+
+  // ── three terminal categories ────────────────────────────────
+  pure [label="Pure\nsha256(value)",
+        shape=box, style="rounded,filled", fillcolor="#e3f2fd"];
+  ca   [label="ContentAddressed\nsha256(buffer)",
+        shape=box, style="rounded,filled", fillcolor="#e8f5e9"];
+  ep   [label="ExecutionPath\nH(parent)",
+        shape=box, style="rounded,filled", fillcolor="#fff3e0"];
+
+  // ── combiner + output (bottom) ───────────────────────────────
+  src     [label="cell bytecode\nsha256(bytecode)",
+           shape=box, style="rounded,filled", fillcolor="#f5f5f5"];
+  combine [label="combine keys\nsha256(src ‖ k₁ ‖ k₂ ‖ …)",
+           shape=box, style="rounded,filled", fillcolor="#fafafa"];
+  out     [label="H(cell)",
+           shape=oval, style=filled, fillcolor="#fff9c4"];
+
+  // ── flow ────────────────────────────────────────────────────
+  ref     -> q_pure;
+  q_pure  -> pure   [label="yes"];
+  q_pure  -> q_buf  [label="no"];
+  q_buf   -> ca     [label="yes"];
+  q_buf   -> ep     [label="no"];
+
+  pure -> combine;
+  ca   -> combine;
+  ep   -> combine;
+  src  -> combine;
+  combine -> out;
+
+  // decisions on the spine, terminals beside them
+  { rank=same; q_pure; pure; }
+  { rank=same; q_buf -> ca -> ep [style=invis]; }
+  { rank=same; src; combine; }
+}

papers/marimo_caching/figs/fig1_dispatch.dot

@@ -0,0 +1,12 @@
+"""Library code for the paper notebook.
+
+Exposes two names to the figure cells in main.md:
+
+- ``compute``: benchmark primitives, plotting helpers, and the
+  ``claim(condition, label, **values)`` assertion helper.
+- ``save_fig``: writes a matplotlib figure to ``figs/<name>.{svg,png}``.
+"""
+from . import compute
+from .plotting import save_fig
+
+__all__ = ["compute", "save_fig"]