Viviane is writing slides for a talk; she would like to include live SageMath computations in her slides. She also would like to publish her slides online, letting anyone – during and after her talk – browse the slides and play around with the provided examples.
Note: most of this blog can be adapted for any other computational system that can be run in Jupyter like, for mathematics, GAP, Pari/GP, or Singular.
Computing huge subspaces of polynomials: Symmetries to the rescue!, Nicolas M. Thiéry (GitHub repository, Live slides)
Suggestion of solution
We will use the above slides from the repository https://github.com/nthiery/harmonic-modules as running example.
SageMath (Sage for short) is a Python based general purpose system for computational mathematics.
Jupyter is a web application for authoring and sharing documents that contain live code, equations, visualizations and narrative text.
Install Jupyter’s RISE extension in Sage. From the terminal:
sage -pip install RISE echo "jupyter-nbextension install rise --py --sys-prefix" | sage -sh echo "jupyter-nbextension enable rise --py --sys-prefix" | sage -sh
The instructions above assume that the Sage command is available as
sage; otherwise adapt the command accordingly.
The instructions above assume that you have write access to the Sage installation.
The instructions above have a bit of additional complexity because they require accessing
jupyterfrom the Sage distribution; in general, one would just do:
pip install RISE jupyter-nbextension install rise --py --sys-prefix jupyter-nbextension enable rise --py --sys-prefix
The first instruction may fail complaining about OpenSSL. This will happen when Sage has not been compiled with SSL support which is needed for the pip package manager which, alas, happens too often. The installation instructions may help fix that.
Authoring and showing slides
Open the Jupyter notebook that you want to turn into slides – or
create a new one – ; we will assume it’s called
View -> Cell Toolbar -> Slideshow
Choose the role each cell should play: for example start a new slide (Slide), add a fragment to the current slide (Fragment), or don’t show up (Note).
Activate the slideshow by clicking in the corresponding button in the toolbar.
For further details on authoring, showing, and configuring the slideshow, see the RISE documentation.
Publishing the slides on a web page
jupyter nbconvert talk.ipynb --to slides
The produced file
talk.slides.html can then be copied to the web
server. Readers will be able to see and navigate the slides; however
they won’t be able to modify and run the examples.
Publishing live slides on Binder
Add the notebook to a public git repository, for example on github.
Add metadata to that git repository to specify the software required to run the computations. For SageMath, you can add the following Dockerfile at the root of the repository.
Go to mybinder.org
, specify the address of
the git repository (here https://github.com/nthiery/harmonic-modules/
) and the name of the file (here talk.ipynb`). Click launch, and
You can get from the binder page a URL to access directly the live slides.
Note: the SageMath docker image is relatively big. Therefore the first times the slides are accessed, or if it has not been accessed in a while, Binder will typically take a couple minutes to launch: it indeed needs to fetch the base SageMath image, build the new image containing the Jupyter extensions and the notebook, and then copy this image around between it’s various machines (that building the image, that storing them, and those running them).
Instead of publishing on Binder, one may author the slides on cocalc, and use its publish feature. (TODO: double check that RISE works on cocalc).
Instead of using a Jupyter notebook, one may author in HTML (or some format that can be converted to HTML), and use ThebeLab or [SageCell][http://sagecell.sagemath.org/]to enable live computations.
Advantages and drawbacks
Traditionally, most mathematicians author their slides using LaTeX+Beamer, and display and publish them in PDF format.
Authoring slides with Jupyter+RISE tends to be more lightweight
LaTeX+Beamer gives fine control on the layout for authoring complex slides; some fine control can be achieved with Jupyter+RISE, using explicit html+css, but this is not as convenient.
One may include live computations
One may easily include multimedia documents
One may edit the slides on the fly
The semantic structure tends to get lost in PDF files, which goes in the way of accessibility. On the other hand, HTML based documents tend to support well web-based accessibility tools like screen readers.
- Estimate the number of instances;
- Provide a template.
Time and expertise required
Assuming Viviane is familiar with Jupyter, writing her first slides using RISE will take a few minutes and mastering it a few hours.
Assuming Viviane is familiar with version control and Jupyter (basic lab skills taught at Software Carpentry, and the required software required is packaged (conda, debian, docker container, …), the publishing part could take two hours the first time, and minutes later on (typically by having a preconfigured repository where one stores all of one’s presentations)..
What’s new since OpenDreamKit started
- Apparition of Binder;
- Expansion of the Jupyter technology;
- Apparition of RISE
- Better packaging and interfacing of math software.
- Development and contributions to Jupyter interfaces (kernels) for math software (GAP, Pari/GP, SageMath, Singular) and C++; see D.47.
- Contributions to the packaging of math software (GAP, Pari/GP, SageMath, Singular, …); see D3.1 and D3.10;
- Early adoption of Binder;
- Contributions to the deployment of new Binder instances;
- Advertising, training, providing a template (TODO!), …