Package: saturn-notebook
SaturnScreenshotsFeaturesPlain-text format. Notebooks are regular Python files. Different types of
cells are comments with special formatting. Markdown rendering and syntax
highlighting in the terminal thanks torich.Checkpoints. Special checkpoint cells allow to save the state of the session
or individual variables.Terminal graphics support. When usingkittyterminal (or in principle anything
that supports itsgraphics protocol)
matplotlib figures are rendered inline in the terminal.MPI awareness. When running under MPI, only rank 0 will write out the
modified notebook. The REPL will take input on rank 0 and broadcast to other
ranks. It's also possible to suppress output from all ranks other than 0.Ability to convert from Jupyter to Saturn notebooks. This also allows to view
Jupyter notebooks in the terminal.Installationpip install saturn-notebookCommands and optionssaturn show notebook.pyDisplay the notebook in the terminal. No computation is performed. Optional--html OUTPUT.htmlflag will produce HTML output. Use-k, --katexflag to
embedKaTeXheader into the HTML.saturn show notebook.py --html notebook.html -ksaturn run [notebook.py [output.py]]Execute a Python notebook, either modifying it in place, or saving the result
into a new notebookoutput.py. If no inputnotebook.pyis provided, drop
into REPL (-iis implied). When leaving, the REPL will ask whether to save
the resulting notebook.-c, --clean: run from scratch, ignoring the checkpoints.-a, --auto-capture: automatically capture matplotlib figures, withoutshow().-i,--interactive:
drop into REPL (usingptpython)
after all the cells are processed; the results of the REPL interaction will
be added to the notebook.--no-mpi: disable MPI awareness.-n, --dry-run: don't save the result.--only-root-output: under MPI, suppress output from all ranks other than 0.-e,--external notebook.zip: use external zip archivenotebook.zipto store binary content (instead of embedding it inline).Any arguments passed after--will be passed assys.argvto the notebook.saturn run notebook.py -- arguments --to notebooksaturn clean notebook.py [output.py]Remove all binary data from the notebook. Useful for getting rid of large
checkpoints.saturn image notebook.py [i out.png]Savei-th image fromnotebook.pyintoout.png. If the last two
arguments are omitted, show all the images in the notebook together with
their indices.saturn versionShow version of saturn and its dependencies.saturn convert notebook.ipynb [notebook.py]Convert a Jupyter notebook into a Saturn notebook. If the output namenotebook.pyis missing, only show the Jupyter notebook. Optional--html OUTPUT.htmlflag will produce HTML output.saturn extract notebook.py notebook.zipExtract inline binary content into external archive.saturn embed notebook.py notebook.zipEmbed binary content from external archive into the notebook.Cell typesMarkdown cells, prefix#m>#m> # Sample notebook
#m>
#m> Description using markdown **formatting**.Output cells#o>There is not usually a reason to modify these by hand, they are filled by
Saturn with the output of code cells. If they contain PNG information, it's
base64-encoded and wrapped in{{{and}}}to allow automatic folding.#o> <matplotlib.image.AxesImage object at 0x114217550>
#o> png{{{
#o> pngiVBORw0KGgoAAAANSUhEUgAAA8AAAAHgCAYAAABq5QSEAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAP
...
#o> pngGAAAgBQEMAAAACkIYAAAAFL4v5JTyvRQ4v1eAAAAAElFTkSuQmCC
#o> png}}}In Vim withfoldmethod=marker:#o> <matplotlib.image.AxesImage object at 0x114217550>
+--135 lines: o> png--------------------------------------------------Checkpoint cells#chk>These indicate locations, where the code should checkpoint. Checkpointing
serializes the session, which is stored base64-encoded in the same cell. The
cell also stores the hash of the previous code blocks, and the checkpoint is
valid if the prior code blocks haven't changed. By default saturn will resume
from the last valid checkpoint. Same folding markers ({{{and}}}) are used.#chk>{{{
#chk>gANDIJZCQePiVH9SX7wVtBfgrDpcgWu5HUFFiFEeyNF9sVjFcQB9cQEoWAwAAABfX2J1aWx0aW5zX19x
...
#chk>wAyP55wdmz+qIkdBjBrYP3EjdHEkYnWGcSUu
#chk>}}}In Vim withfoldmethod=marker:+-- 36 lines: chk>----------------------------------------------------Variable cells#var> x,y,zThese cells save only the value of the specified variables (which is useful
if the full checkpoint is too big). If all the previous code cells haven't
changed, the cell's saved content is loaded into the specified variables and
the previous code cell is not evaluated.Break cells#---#These are used to break code cells that don't have any other type of a cell
between them.REPL cells#-REPL-#These instruct Saturn to drop into an interactive REPL loop, just like the-ioption. All the cells from the REPL will be inserted after this cell in
the notebook. Afterwards, execution proceeds as normal.Code cellsAll contiguous lines, not marked as one of the above, are grouped together
into code cells.Non-skippable code cells#no-skip#Adding this line anywhere within the code cell will indicate that it
shouldn't be skipped, even if we are restarting from a checkpoint. This is
useful, for example, if a cell is modifyingsys.path, which won't be
captured in a checkpoint.Non-hashable code cells#no-hash#Adding this line anywhere within the code cell will indicate that it
shouldn't be hashed, meaning that changing this cell (or removing it
entirely) won't invalidate the checkpoints below. This should be used only
with cells that don't change any variables, e.g., purely output or plotting
cells.Saturn cells#saturn> external=out.zipThese provide metadata. For now, the only option is to provide the name of
the external zip archive to store the binary content.Vim supportAll the binary (non-human-readable) cell content is wrapped in{{{,}}}markers. Adding the following comment to the notebook, ensures that Vim starts
with all the binary content folded away.# vim: foldmethod=marker foldlevel=0It's also helpful to have Vim recognize the#m>prefix to correctly re-format
markdown cells with thegqcommand. This can be done, for example, by adding
the following to~/.vim/after/ftplugin/python.vim:setlocal comments=b:#,fb:-,b:#m>REPLREPL supports the following keyboard shortcuts:Ctrl-d: exits the REPL.Ctrl-k: inserts a checkpoint cell. Equivalent to typing in#chk>manually.Ctrl-w: exits the REPL and doesn't drop into REPL, even if there are more
REPL cells or-iis provided on the command line.Ctrl-q: exits the REPL and terminates execution of the entire notebook.F10: aborts execution of the entire notebook and doesn't save it out, even if we are not in--dry-runmode.ScreenshotsRunningsamples/simple.py:First run performs full computation and saves the checkpoint, as well as the figure output.Second run resumes from the checkpoint, since no code before it has changed.Vim folds the binary content.