proposal: Evaluate marimo as Jupyter notebook replacement for tutorials

[joelaforet]

Motivation

• mupt-examples currently stores 14 Jupyter notebooks (~6 MB total), where 97%+ of file size is embedded output (PNG images, HTML tables, widget state JSON)
• Git diffs on .ipynb files are effectively unreadable -- JSON with base64-encoded images
• Current testing relies on nbval-lax (a third-party pytest plugin) via manual shell scripts; no CI/CD exists
• nbval-lax only validates "did it crash?" -- it cannot assert correctness of outputs
• Jupyter's execution model allows hidden state: cells can be run out of order, deleted variables persist, leading to notebooks that fail to reproduce

Proposal

Evaluate marimo as a replacement for Jupyter notebooks in mupt-examples. Marimo notebooks are stored as pure .py files, eliminating output bloat and enabling meaningful git diffs.

This is an exploratory proposal -- not a commitment to switch. I will investigate feasibility over the coming weeks by converting a pilot notebook and validating compatibility with our scientific Python stack.

Marimo vs Jupyter: Comparison

Advantages of Marimo

Feature	Jupyter	Marimo
File format	JSON with embedded outputs (~6 MB)	Pure Python .py files (~22 KB for equivalent content)
Git diffs	Unreadable (base64 images, cell metadata noise)	Standard Python diffs
Testing	Requires nbval plugin; only tests "does it run?"	Native pytest support; embed real assertions as test_* cells
Reproducibility	Cells can run out of order; hidden state accumulates	Reactive DAG execution; no hidden state possible
Expensive cells	No built-in gating; accidental re-execution of GPU cells	mo.stop() + mo.ui.run_button() to gate expensive cells behind user interaction
Script execution	Requires nbconvert or papermill	python notebook.py works directly
App mode	Requires Voila or similar	marimo run notebook.py serves as read-only web app
Conversion	N/A	marimo convert notebook.ipynb -o notebook.py for automated migration

Risks and Concerns

Concern	Assessment
RDKit 2D molecule rendering	Marimo supports _repr_html_/_repr_png_ protocols. RDKit Mol objects should render via last-expression or mo.as_html(). Needs validation.
matplotlib 3D plots	Natively supported. mo.mpl.interactive() adds pan/zoom. Low risk.
rich.progress.track progress bars	Would fall back to text output. Can optionally replace with mo.status.progress_bar. Low risk.
IPython.display.display() calls	Not available in marimo. Mechanical replacement with last-expression or mo.as_html(). Low risk.
Variable redefinition across cells	Marimo requires each global variable to be defined in exactly one cell (DAG constraint). Some notebooks may need variable renaming or cell merging. One-time migration cost.
No ipywidgets support	Marimo uses its own widget system. No current notebooks use ipywidgets directly, but this blocks future nglview/py3Dmol integration. Medium concern for future 3D molecular visualization.
Team familiarity	Marimo is newer and less widely known than Jupyter. Learning curve for contributors.
Ecosystem maturity	Marimo is actively developed but younger than Jupyter. Some edge cases may not be covered.

Compatibility with Current Notebook Portfolio

Category	Notebooks	Key Dependencies	Expected Compatibility
examples_repr/	5 notebooks	mupt, rdkit, matplotlib, numpy, scipy	High -- standard scientific Python
examples_system/	4 notebooks	mupt, rdkit, matplotlib, openff, openmm, MDAnalysis	High -- but OpenMM GPU cells need mo.stop() gating
examples_DPD/	4 notebooks	hoomd, mbuild, flowermd, gsd, numpy	High -- mostly text/file output, no rich display
examples_MDAnalysis/	1 notebook	(empty placeholder)	N/A

Testing Improvements

The strongest argument for marimo is the testing story:

• Current: py.test --nbval-lax --current-env notebook.ipynb -- tests only that cells execute without error
• With marimo: pytest notebook.py -- can embed real assertions like def test_atom_count(universe): assert len(universe.atoms) == 3618
• CI integration: Trivially add pytest examples_repr/*.py examples_system/*.py to GitHub Actions (no CI exists today)

Proposed Investigation Plan

1. Pilot conversion: Convert mol_from_scratch_basic.ipynb (smallest, simplest notebook) using marimo convert
2. Validate rendering: Confirm RDKit molecule depictions and matplotlib plots render correctly
3. Validate testing: Add test_* cells with real assertions, run with pytest
4. Assess variable refactoring: Quantify how much manual cleanup is needed for the DAG constraint
5. Decision point: Based on pilot results, decide whether to proceed with full migration
6. If proceeding: Batch convert remaining notebooks, starting with examples_repr/ (lowest risk), then examples_system/
7. Add CI: GitHub Actions workflow for automated notebook testing on PR

Backward Compatibility

Marimo can export back to .ipynb format (marimo export ipynb notebook.py), so users who prefer Jupyter can still obtain notebook files. This could be automated in CI if needed.

References

• marimo documentation
• marimo: Coming from Jupyter guide
• marimo: Testing with pytest
• marimo: Working with expensive notebooks

[timbernat]

Thanks for offering to investigate, and for the detailed write-up! Looping in @dwhswenson for advice, as he helped me set up the nbval testing and may have some experience with marimo. A few things worth mentioning:

no CI/CD exists
CI integration: Trivially add pytest examples_repr/.py examples_system/.py to GitHub Actions (no CI exists today)
via manual shell scripts;

Definitely not the case, the nbval notebook testing in this repo has been part of the CI in the main toolkit for at least 6 months; every PR you've made there has included nbval runs invoked via the notebook_tests_master.sh script found in this repo. There's nothing inherently "manual" about a shell script; it can be called directly by a human user (as I frequently do when editing notebook tests) or my another script or process, such as a GitHub CI workflow.

Current: py.test --nbval-lax --current-env notebook.ipynb -- tests only that cells execute without error

That's not an accident, the nbval scripts run smoke tests meant to check that updates to the core library don't cause any of the examples to break. The reason for not including the CI call in this repo is to avoid circular/duplicated dependencies, viz the examples requiring the main toolkit to be runnable.

nbval-lax only validates "did it crash?" -- it cannot assert correctness of outputs
With marimo: pytest notebook.py -- can embed real assertions like def test_atom_count(universe): assert len(universe.atoms) == 3618

The basic --nbval call, and even --nbval-lax with the #NBVAL_CHECK_OUTPUT directive can validate cell outputs, comparing to reference run of a notebook (see docs). The bigger issue is that for examples with any kind of stochasticity, e.g. generating conformers, assembling random topologies, running simulations, etc., it becomes much trickier to have a baseline "truth" value to compare outputs to, regardless of what tool you use for that test.

Current testing relies on nbval-lax (a third-party pytest plugin)
Requires nbconvert or papermill

True, though the additional dependencies get installed when one installs jupyterlab/nbval. This will nearly always be the case with non-stdlib libraries, e.g. marimo also has third-party dependencies, viz. narwhals, uvicorn, starlette, etc.

a well-documented problem affecting >1/3 of public Jupyter notebooks

Can you provide where this is documented?