From e3eb1dc4068097f2ef0f42d2a9f4e1a2de3776bc Mon Sep 17 00:00:00 2001 From: Vassil Vassilev Date: Thu, 5 Nov 2026 18:21:31 +0000 Subject: [PATCH] Run the CARTopiaX model in the browser. Notebook 5 only restates the shape of the cancer model. The model itself, CARTopiaX on BioDynaMo, now also builds for wasm32 as a 1.2 MB side module, with one thread and the same output as the native single-thread build. 6_cartopiax.ipynb runs a 60 um organoid for 20 simulated minutes (about 50 s) and plots the model's summary CSV and its snapshots of cells and substance fields. Files under a series' data/ are packed into the archive every kernel downloads at start, so the library is fetched instead by the notebook itself: lazy.load_library(name) downloads /lazy/ once and loads it with cppjit.load_library. The library is the release asset libcartopiax.so, pinned in lite/kernel/SHA256SUMS. Without the asset the site build leaves the notebook out. The notebook is browser-only, so it lives in lite/notebooks rather than in the natively tested cppjit/ series. --- .github/workflows/deploy-pages.yml | 2 +- cppjit/kernel/lazy.py | 16 ++- lite/README-build.md | 1 + lite/README.md | 6 +- lite/kernel/SHA256SUMS | 1 + lite/notebooks/6_cartopiax.ipynb | 178 +++++++++++++++++++++++++++++ tools/build-lite-site.sh | 10 ++ 7 files changed, 210 insertions(+), 4 deletions(-) create mode 100644 lite/notebooks/6_cartopiax.ipynb diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 867a5c6..680e0ad 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -31,7 +31,7 @@ jobs: run: | mkdir -p lite/kernel-artifacts gh release download "$KERNEL_RELEASE" --repo "$GITHUB_REPOSITORY" --dir lite/kernel-artifacts \ - --pattern 'kernel-overlay-*.tar.gz' + --pattern 'kernel-overlay-*.tar.gz' --pattern 'libcartopiax.so' - name: Verify the kernel binaries against the digests committed in lite/kernel/SHA256SUMS run: (cd lite/kernel-artifacts && sha256sum -c --ignore-missing ../kernel/SHA256SUMS) && ls -la lite/kernel-artifacts - name: Build environment (micromamba, host venv, wasm32 env from the lock, kernel overlay) diff --git a/cppjit/kernel/lazy.py b/cppjit/kernel/lazy.py index 0a568e3..a2a65ff 100644 --- a/cppjit/kernel/lazy.py +++ b/cppjit/kernel/lazy.py @@ -55,7 +55,7 @@ def _cpp(): import re as _re -_NAME = _re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+-]*\.(tar\.gz|json)$") +_NAME = _re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+-]*\.(tar\.gz|json|so)$") _BASE = _re.compile(r"^https?://[A-Za-z0-9.:_/%+-]*$") @@ -97,6 +97,20 @@ def ensure(name, verbose=True): print(f"[browser] {name} unpacked in {time.time() - t0:.1f} s ({how})", file=sys.stderr) +def load_library(name, verbose=True): + """Download the shared library `/lazy/` once and load it into the kernel (cppjit.load_library). + For libraries only one notebook needs: files under the notebook's data/ are packed into every kernel's start-up + download, files under lazy/ are fetched by the notebook that asks for them.""" + import cppjit + path = os.path.join(CACHE, name) + if _state.get(name) == "loaded": return path + os.makedirs(CACHE, exist_ok=True); t0 = time.time() + r = str(_cpp().fetch_sync(_url(name), path)) + if not r.isdigit(): raise ImportError(f"sc26 lazy: could not fetch {name}: {r}") + cppjit.load_library(path); _state[name] = "loaded" + if verbose: print(f"[browser] {name}: {int(r) / 1048576:.1f} MB downloaded and loaded in {time.time() - t0:.1f} s", file=sys.stderr) + return path + class _Finder(importlib.abc.MetaPathFinder): """On the first import of a lazy top-level module, fetch and extract it, then defer to the normal finders.""" def find_spec(self, fullname, path=None, target=None): diff --git a/lite/README-build.md b/lite/README-build.md index dab9740..2063801 100644 --- a/lite/README-build.md +++ b/lite/README-build.md @@ -98,6 +98,7 @@ SP=/some/empty/dir OUT=lite/dist bash tools/build-lite-site.sh | wasm32 environment | `lite/env/xeus-kernels.explicit.txt` | micromamba explicit list, 40 packages with md5, emscripten-forge-4x (llvm 23.1.2, emscripten-abi 4.0.9) | | derived environments | `lite/env/{slim,lazy,kernelspecs}-remove.txt` | build-time-only packages dropped; the lazy ones are packed once from xeus-slim into `lite/lazy-packages/` | | kernel overlay | `release asset kernel-overlay-2026-11-03.tar.gz` (35.8 MB) | the files of the kernel build that no package owns: `xcpp.{js,wasm,data}` and the `xcpp23` kernel spec | +| CARTopiaX library | `release asset libcartopiax.so` (1.2 MB) | CARTopiaX at upstream bd30586 and the BioDynaMo core it uses (v1.05.cr-20260812), Emscripten 4.0.9, one thread, as a side module; `6_cartopiax.ipynb` fetches it from `lazy/` with `lazy.load_library`. Built outside this repository: ROOT replaced by stand-in headers (BioDynaMo is built without dictionaries; the random generator follows ROOT's TRandom3 exactly), three small BioDynaMo runtime patches for the browser's file system. Without the asset the build leaves the notebook out | | kernel source patches and pins | `lite/kernel/`, `tools/build-wasm-kernel.sh` | the 27 third-party patches (CppInterOp 4, cppjit 5, xeus-cpp 18, listed in PATCHES.md) plus our WebGPU patch, Vipul's `deploy.yml`, `environment.yml`, `build-environment.yml`, the upstream pack config; `tools/build-wasm-kernel.sh` rebuilds the kernel from them | The explicit-lock environment carries no channel history, so the build passes `--XeusAddon.default_channels` diff --git a/lite/README.md b/lite/README.md index 484413a..146cd96 100644 --- a/lite/README.md +++ b/lite/README.md @@ -1,6 +1,6 @@ # SC26 at home, in the browser -Five notebooks from the SC26 Python tutorial and the C++ series of live-cpp-tutorials, running here without any install. The kernel is C++ (clang-repl compiled +Six notebooks from the SC26 Python tutorial and the C++ series of live-cpp-tutorials, running here without any install. The kernel is C++ (clang-repl compiled to WebAssembly); Python runs inside it and calls the C++ through cppjit, which is the pairing the tutorial is about. 1. `1_call_it.ipynb`: call a C++ header from Python, time it against pure Python. @@ -8,8 +8,10 @@ to WebAssembly); Python runs inside it and calls the C++ through cppjit, which i 3. `3_fit_it.ipynb`: a bouncing ball in C++, fitted to data with BFGS on Clad's exact gradient. 4. `4_higgs_open_data.ipynb`: the four-lepton Higgs mass on CMS 2012 open data, without ROOT, checked against RooFit. 5. `5_tiny_twin.ipynb`: the cancer model's shape in sixty lines of C++, called, composed with Python, calibrated. +6. `6_cartopiax.ipynb`: the cancer model itself (CARTopiaX on BioDynaMo, compiled to WebAssembly), downloaded by + this notebook only, run for a few simulated minutes and looked inside with numpy and matplotlib. Run the cells top to bottom (the first two cells of each notebook set the browser up). The first start downloads the compiler and the Python packages once; after that everything runs locally in your browser tab. The same notebooks -for a laptop (`pip install cppjit numpy scipy matplotlib`) are in `cppjit/` of this repository, and the C++ series under +1 to 5 for a laptop (`pip install cppjit numpy scipy matplotlib`) are in `cppjit/` of this repository, and the C++ series under `cpp/` here is the repository's `xeus-cpp/` series, unchanged. diff --git a/lite/kernel/SHA256SUMS b/lite/kernel/SHA256SUMS index 7f8f7d0..3214861 100644 --- a/lite/kernel/SHA256SUMS +++ b/lite/kernel/SHA256SUMS @@ -1,2 +1,3 @@ 9c863ec09ddc44d6fc86e1817a5d0103fcc5dae08050f376ad6331b8f8421c17 kernel-overlay-2026-11-03.tar.gz 5aef1530c20ac6ddbfad6f1b78cd5926c7f92b45abbf88ad76a2ce13f3240808 cppjit-0.1.0b1.dev0-cp312-cp312-linux_x86_64.whl +e08ce1be40ca7c38e2efd1756edfbdc37800bbc2df63f4525a5865872caa9353 libcartopiax.so diff --git a/lite/notebooks/6_cartopiax.ipynb b/lite/notebooks/6_cartopiax.ipynb new file mode 100644 index 0000000..e4920ae --- /dev/null +++ b/lite/notebooks/6_cartopiax.ipynb @@ -0,0 +1,178 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# 6. The full cancer model, in your browser\n", + "\n", + "Notebook 5 rebuilt the shape of the cancer model in sixty lines. This one runs the model itself:\n", + "[CARTopiaX](https://github.com/compiler-research/CARTopiaX), the agent-based model of CAR T-cells attacking a\n", + "solid tumour (after Luque et al., *Sci. Rep.* 2024), on the [BioDynaMo](https://biodynamo.org) simulation engine.\n", + "CARTopiaX's C++ sources and the part of BioDynaMo they use, 59 files in all, are compiled to WebAssembly into one\n", + "1.2 MB library.\n", + "\n", + "Only this notebook needs the library, so it is not part of the kernel's start-up download: the next cell fetches it\n", + "and loads it into the running C++ kernel. The Python here calls into it through cppjit, as in the other notebooks.\n", + "\n", + "What to expect: the browser gives the model one thread, and one step (0.1 simulated minutes) takes about a quarter\n", + "of a second, so the runs here are minutes of simulated time, not the paper's 30 days. With the same seed the\n", + "numbers are the same as the native single-thread build's, digit for digit." + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "import os, time, numpy as np\n", + "t = time.time()\n", + "lazy.load_library(\"libcartopiax.so\") # the 1.2 MB WebAssembly library, fetched from this site once\n", + "cppjit.cppdef('extern \"C\" const char* cartopiax_simulate(double radius_um, int minutes, int csv_every_steps, int snapshot_every_steps, int seed);')\n", + "print(f\"CARTopiaX loaded in {time.time() - t:.1f} s\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## A tumour organoid meets CAR T-cells\n", + "\n", + "A spherical organoid of radius 60 µm (253 tumour cells) sits in a 1 mm box of tissue. Oxygen diffuses in from the\n", + "box faces and the tumour cells consume it; the tumour cells secrete an immunostimulatory factor. The model's\n", + "treatment schedule infuses 3,957 CAR T-cells at day 0 around the tumour. Every 20 steps the model writes a summary\n", + "row, every 50 steps a snapshot of all cells and of both substance fields.\n", + "\n", + "The run takes about a minute; the model's own console output (its full parameter list) goes to `run.log`." + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "minutes, seed = 20, 42\n", + "t = time.time()\n", + "run = str(cppjit.gbl.cartopiax_simulate(60.0, minutes, 20, 50, seed))\n", + "wall = time.time() - t\n", + "steps = int(minutes / 0.1)\n", + "print(f\"{minutes} simulated minutes = {steps} steps in {wall:.0f} s ({1000 * wall / steps:.0f} ms per step); results in {run}/\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What the model reports\n", + "\n", + "The summary CSV is the model's own output (`output/final_data.csv`); a few of its 23 columns:" + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "csv = np.genfromtxt(f\"{run}/output/final_data.csv\", delimiter=\",\", names=True)\n", + "cols = [\"total_minutes\", \"num_tumor_cells\", \"num_alive_cart\", \"average_oxygen_cancer_cells\", \"average_oxygen_all_cells\"]\n", + "print(\"\".join(f\"{c:>30}\" for c in cols))\n", + "for row in csv: print(\"\".join(f\"{row[c]:30.3f}\" for c in cols))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Looking inside\n", + "\n", + "Each snapshot holds every cell (position, diameter, kind) and both substance fields on the model's 50³ grid (20 µm\n", + "voxels). Below: the cells in a 20 µm thick slab through the centre of the organoid at the last snapshot, over the\n", + "oxygen and the immunostimulatory factor in the same plane. The CAR T-cells start at least 50 µm from the tumour; in\n", + "20 minutes they have barely moved." + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "import matplotlib.pyplot as plt\n", + "snaps = sorted(int(f[6:-4]) for f in os.listdir(run) if f.startswith(\"cells_\"))\n", + "step = snaps[-1]\n", + "cells = np.fromfile(f\"{run}/cells_{step}.f32\", np.float32).reshape(-1, 6) # x, y, z, diameter, kind, oncoprotein\n", + "res, lo, hi, box = open(f\"{run}/oxygen.grid\").read().split(); res, lo, hi = int(res), float(lo), float(hi)\n", + "def field(name, s): return np.fromfile(f\"{run}/{name}_{s}.f32\", np.float32).reshape(res, res, res) # [z, y, x]\n", + "mid, view = res // 2, 200 # the grid's central plane; µm shown either side of the centre\n", + "slab = cells[(np.abs(cells[:, 2]) < 10) & (np.abs(cells[:, 0]) < view) & (np.abs(cells[:, 1]) < view)]\n", + "tumour, cart = slab[slab[:, 4] <= 5], slab[slab[:, 4] >= 6]\n", + "fig, axes = plt.subplots(1, 2, figsize=(11, 4.8))\n", + "for ax, name, label, cmap in ((axes[0], \"oxygen\", \"oxygen (mmHg)\", \"inferno\"), (axes[1], \"immunostimulatory_factor\", \"immunostimulatory factor\", \"viridis\")):\n", + " im = ax.imshow(field(name, step)[mid], origin=\"lower\", extent=(lo, hi, lo, hi), cmap=cmap)\n", + " fig.colorbar(im, ax=ax, shrink=0.8, label=label)\n", + " ax.scatter(tumour[:, 0], tumour[:, 1], s=6, c=\"#2b7a70\", label=f\"tumour cells ({len(tumour)} in view)\")\n", + " ax.scatter(cart[:, 0], cart[:, 1], s=6, c=\"#c9a6ff\", label=f\"CAR T-cells ({len(cart)} in view)\")\n", + " ax.set(xlim=(-view, view), ylim=(-view, view), xlabel=\"x (µm)\", ylabel=\"y (µm)\")\n", + "axes[0].legend(loc=\"upper left\", fontsize=8)\n", + "fig.suptitle(f\"CARTopiaX in the browser, minute {step * 0.1:.0f}: mid-plane slab of a 60 µm organoid\")\n", + "plt.tight_layout(); plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The same two fields along a line through the centre of the organoid, one curve per snapshot: the oxygen dip settles\n", + "within the first snapshot (diffusion is fast at this scale), while the factor the tumour cells secrete keeps spreading outward." + ] + }, + { + "cell_type": "code", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": [ + "x = lo + (np.arange(res) + 0.5) * (hi - lo) / res\n", + "fig, axes = plt.subplots(1, 2, figsize=(11, 3.6))\n", + "for k, s in enumerate(snaps):\n", + " colour = plt.cm.viridis(k / max(1, len(snaps) - 1))\n", + " for ax, name in ((axes[0], \"oxygen\"), (axes[1], \"immunostimulatory_factor\")):\n", + " ax.plot(x, field(name, s)[mid, mid], color=colour, label=f\"minute {s * 0.1:.0f}\")\n", + "axes[0].set(xlabel=\"x (µm)\", ylabel=\"mmHg\", xlim=(-300, 300), title=\"oxygen\")\n", + "axes[1].set(xlabel=\"x (µm)\", xlim=(-300, 300), title=\"immunostimulatory factor\")\n", + "axes[1].legend(fontsize=8)\n", + "plt.tight_layout(); plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Try it\n", + "\n", + "Change `minutes` or `seed` above and rerun from there; one simulated hour is 600 steps, a few minutes here.\n", + "For days of simulated time (the CAR T-cells finding and killing the tumour), run CARTopiaX natively, where it uses\n", + "all your cores; the setup is in the [CARTopiaX repository](https://github.com/compiler-research/CARTopiaX).\n", + "\n", + "What the browser build leaves out: threads (GitHub Pages cannot enable WebAssembly threads), BioDynaMo's ROOT file\n", + "I/O and ParaView export (a small built-in adaptor writes the snapshots used above instead), and user-defined\n", + "random distributions. The model code is CARTopiaX's own, unchanged." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} \ No newline at end of file diff --git a/tools/build-lite-site.sh b/tools/build-lite-site.sh index 1550e62..865e66e 100644 --- a/tools/build-lite-site.sh +++ b/tools/build-lite-site.sh @@ -38,6 +38,15 @@ for nb in sorted(src.glob("*.ipynb")): print(f"[content] {len(list(dst.glob('*.ipynb')))} C++ notebooks -> {dst}") PY cp "$REPO/lite/README.md" "$CONTENT/README.md" +# Browser-only notebooks (lite/notebooks): 6_cartopiax runs the CARTopiaX model from a WebAssembly library that the +# notebook downloads itself (kernel/lazy.py load_library), so the other notebooks do not pay for it. The library is a +# release asset next to the kernel overlay; without it the notebook is left out of the site. +CARTOPIAX_SO=${CARTOPIAX_SO:-${KERNEL_ART:-$REPO/lite/kernel-artifacts}/libcartopiax.so} +if [ -f "$CARTOPIAX_SO" ]; then + "$BUILD_ENV/bin/python" "$REPO/tools/home2lite.py" "$REPO/lite/notebooks" "$CONTENT/cppjit" +else + echo "[content] no $CARTOPIAX_SO: leaving out the CARTopiaX notebook" +fi # lite/labext holds symlinks to the two extensions the site needs (the xeus kernel extension and the notebook UI); the # build environment's other extensions (pyodide, javascript, p5 kernels, themes) stay out. @@ -78,6 +87,7 @@ ls -la "$STATIC"/*.so | awk '{printf " %7.2f MB %s\n",$5/1048576,$9}' # Packages loaded on first import by kernel/lazy.py (not in the start-up set): the tarballs packed from xeus-slim. echo "[site] lazy packages -> $OUT/lazy/" mkdir -p "$OUT/lazy" && cp "$REPO"/lite/lazy-packages/*.tar.gz "$OUT/lazy/" && du -sh "$OUT/lazy" | cut -f1 | xargs echo " lazy packages:" +if [ -f "$CARTOPIAX_SO" ]; then cp "$CARTOPIAX_SO" "$OUT/lazy/libcartopiax.so"; echo " CARTopiaX library: $(du -h "$OUT/lazy/libcartopiax.so" | cut -f1)"; fi # package name -> tarball file, read by kernel/lazy.py at start (lazy.json names packages, not builds) "$BUILD_ENV/bin/python" - "$OUT/lazy" <<'PY' import json, pathlib, re, sys