Writing an Interactive Textbook

By David I. Ketcheson, Randall J. LeVeque, and Mauricio J. del Razo

Mathematics is often taught and illustrated through visual representations that depict both abstract and concrete concepts. Unfortunately, traditional texts are limited to static two-dimensional plots and diagrams, which are not well-suited for illustrating dynamic, time-dependent phenomena or the broad spectrum of situations that can arise with varying parameters. One might refer to this as the “curse of dimensionality” in teaching, wherein the medium has far fewer dimensions than the subject matter.

Another important challenge in computational mathematics is the conveyance of detailed algorithms. High-level pseudocode may not fully communicate important details, while a complete runnable program might interrupt the text’s flow and be difficult for users to digest. Although one can sometimes include elegant and short programs fairly easily (Nick Trefethen’s classic Spectral Methods in MATLAB [2] is an example), this is often not feasible.

While traditional texts have served us well for thousands of years, new media provide exciting possibilities to radically alter the way in which we write textbooks. A number of authors in applied mathematics have already begun to explore opportunities to present material in a much more engaging and illuminating manner. Our goal is to describe some of our own recent experiences in this direction, focusing on a few of the challenges that we faced and how we dealt with them.

Just last year, we published Riemann Problems and Jupyter Solutions [1] as a SIAM text that we wrote entirely as a set of Jupyter notebooks. Though we hope that the softcover book will be a useful resource in its own right, we invite readers to explore the notebooks themselves, as they make it possible to visualize the time-dependent nature of solutions and easily vary parameters to observe their effects. The ambitious reader can even extend the notebooks by modifying the embedded Python code to set up and solve related problems. To facilitate the notebooks’ usage, we provide both a clear list of dependencies and a Dockerfile. We also make it very easy for users to launch an instance on the cloud server Binder; the notebooks can thus run in any browser and do not require the installation of software. Readers who wish to view some of the time-dependent solutions without running the notebooks can consult the pure HTML version with embedded animations. SIAM has kindly allowed the notebooks and HTML rendition to remain open access, and we encourage you to explore the notebooks using the online links. 

The “Riemann problem” in our book refers to a one-dimensional hyperbolic partial differential equation (PDE), together with piecewise-constant initial data. The resulting time-dependent solution consists of waves that propagate away from the initial discontinuity (shocks and/or rarefaction waves in the nonlinear case). The notebooks illustrate a variety of different hyperbolic problems—including acoustics, Burgers’ equation, shallow water equations, and the Euler equations of compressible flow—with dynamic illustrations of the time-dependent solutions and their corresponding changes as the initial data vary. We also illustrate some of the key ideas in the development of cheap-to-compute approximate Riemann solvers, a critical building block for many numerical “shock-capturing methods” for the solution of hyperbolic PDEs. Other textbooks may describe these ideas in more detail, but we believe that the notebook version makes it far easier for readers to understand and explore many of the concepts. Therefore, Riemann Problems and Jupyter Solutions could also serve as a supplement to a broader course that is based on alternative textbooks.

The Jupyter notebook is a browser-based interactive notebook that incorporates Markdown text (including mathematics in LaTeX form), images, computer code, and so-called “widgets” within a JavaScript Object Notation (JSON) file. Users execute notebooks by first starting a notebook server; a computational kernel then executes the code cells within the notebook. We utilize Python for our notebooks, but the notebook interface works with other languages as well, notably Julia and R (as suggested by the name “Jupyter”). The widgets expedite the creation of visualizations with menus, sliders, and other tools that advance time or modify parameters. The visualization updates in real time to reflect the chosen values, and users can modify and execute the computer code directly in the notebooks and immediately see the results. Figure 1 depicts some of the widgets that are used for the shallow water equations.

Figure 1. A Jupyter notebook widget for exploring the solution to the Riemann problem for shallow water equations. Figure courtesy of [1].

Challenges

We encountered a number of unique challenges while writing an interactive textbook. While we always intended our book to exist in multiple formats—notebooks, HTML pages, and PDF/print—we knew that manually synchronizing the different formats would be unwieldy. We designated the Jupyter notebooks as the authoritative format from which we would generate the other formats. Fortunately, the nbconvert tool already facilitates this automatic conversion, at least for a single notebook. By combining it with Thomas Kluyver’s bookbook project and some additional scripting (e.g., to convert all of the widgets into one or two static figures that would make sense in the print version), we adapted it to function for a collection of notebooks. Creating a unified bibliography, incorporating links and LaTeX references across chapters, and applying a set of LaTeX macros throughout the notebooks all required additional work. In the end, we were able to generate a fairly short Python script to convert all of the notebooks into a single LaTeX file that was suitable for the SIAM compositors, who then copyedited and typeset it into the beautiful printed book. We wrote another Python script (again using nbconvert) to turn all of the notebooks into HTML form, incorporating additional processing to change some of the widgets into animations that play in the HTML.

The scripts we used are all included in our book’s GitHub repository. For new projects, we also suggest investigating the latest tools that are available to ease some of these challenges. For example, we discovered the Jupyter Book project too late to use for Riemann Problems and Jupyter Solutions, but it looks very promising.

The Jupyter notebook interface itself has also been rapidly evolving and improving, and one challenge we faced was its evolution during our writing process. In particular, the notebook widget code fundamentally changed multiple times. This occasionally broke the textbook and required several revisions for our code. In order to ensure that the code was always in working order, we used the Travis CI continuous integration service and some test scripts that automatically executed each notebook whenever the book was modified on GitHub. Future changes to libraries will likely continue to pose difficulties, although one can easily specify the required version of Jupyter in the Dockerfile for our now-published book.

Version control tools (such as Git) and the command-line tool “diff” are widely used to facilitate collaborative scientific writing and were particularly essential to our writing process since we live on three different continents. The Jupyter notebook slightly complicated this approach because it uses a JSON format with extra markup, in addition to the text and computer code. It also stores the images and animations that the code produces in a serialized format within the notebook (as embedded PNG files). As a result, notebook files that include the output can be quite large and not at all suitable for diffing. Fortunately, community-developed tools like nbdime and nbstripout allowed us to effectively handle these complications.

Outlook

We are very happy with the finished Riemann Problems and Jupyter Solutions, but we do not expect it to be the final word on interactive texts. On the contrary, we see it as a contribution to the ongoing evolution of textbooks that are taking advantage of improved technology. We hope that our work—along with similar in-progress projects in our community—will inspire other authors to continue innovating and improving our collective ability to communicate and teach mathematics.

David I. Ketcheson is an associate professor of applied mathematics and computational science at King Abdullah University of Science and Technology (KAUST). Randall J. LeVeque is a professor emeritus in the Department of Applied Mathematics at the University of Washington. Mauricio J. del Razo is a postdoctoral researcher in the Department of Mathematics and Computer Science at the Freie Universität Berlin.