Notebooks in stormpy

[volkm]

Some considerations on notebooks for the stormpy documentation.

Jupyter notebook

Current status quo: We have jupyter notebooks which are tracked on git as files .ipynb.

Pros

• Jupyter notebooks are widely used with a good ecosystem (slides through RISE, etc)
• Integration with sphinx for automatic documentation
• Integration with binder to run in webbrowser (through hosting Docker images)
• Tests check that generated output matches with output in notebooks

Cons

• JSON format of .iypnb does not play nicely with git and tracking changes is hard.
• Executing requires Jupyterlab
• Cell order can be arbitrary

Jupytext

Jupytext is an extension for Jupyter and allows to store Jupyter notebooks as Python files. Stormvogel currently uses Jupytext

Pros

• part of Jupyter ecosystem, all features from Jupyter still supported
• Git integration works
• Allows paired notebooks for pairing notebook and Python file.
• also allows the marimo format now

Cons

• cons from Jupyter (except Git integration) still apply
• Outputs are missing in Python file and testing on outputs not easily possible
• (I personally find the percent format of the Python file not nice to read)

Marimo

Marimo aims to replace Jupyter notebooks.

Pros

• Stores Python file with annotations, better support for Git
• Notebooks (stored as Python files) can be executed even without marimo
• Better reproducibility, tracks dependencies between cells, reactive execution of changed cell and dependencies
• Import from and export to Jupyter notebooks. So conversion is possible
• (I personally find it more modern than Jupyter and it seems a bit more fun to work with)

Neutral

• Support for executing code in webbrowser via WASM. But stormpy will never fully support this due to Storm backend. (Could be interesting for Stormvogel)
• AI integration (but must be enabled)
• Open-source but company behind which very much seems to influence the development

Cons

• Variables can only be assigned within one cell, needs either private variables or renaming. But this also forces better coding.
• ecosystem not so large (no real slide support, etc)
• Testing needs explicit asserts
• Export to Markdown or HTML is possible for the website, but it comes with own layout and might not nicely integrate with Sphinx

The last two points could be handled by converting the marimo notebook to Jupyter notebook and then following the existing workflow.

Summary

All in all, I think Jupytext + Jupyter or Marimo are both good ways to go. With the conversion between different formats, switching should also not be the biggest effort.

I personally lean a bit towards migration to marimo because it seems a bit more smoother to work with and the enforcement of reproducibility is a good idea.

[volkm]

Cell ordering can also be achieved in Jupyter with e.g. IPyflow

[sjunges]

I want to add Myst to the list (often branded as Jupyter book 2.0). It seems very mature. I also tried Marimo and while it has some fancy options, it was (for more text-heavy parts) still quite inmature (e.g., the latex macro support is very limited).

[volkm]

Myst would allow to use both Markdown and Notebooks. It seems like one can integrate both.