The riemann_book repository is an interactive educational resource that presents the theory and practice of Riemann problems for hyperbolic partial differential equations through executable Jupyter notebooks. Created by David I. Ketcheson, Randall J. LeVeque, and Mauricio del Razo Sarmina, this project bridges the gap between mathematical theory and computational implementation by allowing readers to run and modify code directly within the learning environment.
The repository serves as the source material for a published SIAM book titled "Riemann Problems and Jupyter Solutions: Theory and Approximate Solvers for Hyperbolic PDEs," released in 2020. The book is available in multiple formats including print, ebook, and as rendered HTML notebooks on the SIAM website. The repository maintains a specific FA16 branch that corresponds to the exact notebooks included in the published SIAM book, while the master branch may receive updates beyond the original publication.
The content is organized into two main parts. Part I covers the Riemann problem and its solution, beginning with foundational concepts in the Introduction notebook and progressing through increasingly complex systems. It includes notebooks on scalar advection, acoustics, Burgers equation, traffic flow, nonconvex scalar problems, shallow water equations, shallow water with tracers, and the Euler equations for ideal gas dynamics. Part II focuses on approximate solvers, introducing basic approximation types and then applying them to scalar problems, shallow water systems, and gas dynamics, with a comparative analysis of different solvers using PyClaw.
The repository is written primarily in HTML with supporting Python code, reflecting its nature as both a computational and educational resource. It is classified across multiple scientific computing domains including Riemann solvers, hyperbolic PDEs, conservation laws, numerical methods, computational fluid dynamics, shock waves, discontinuities, and wave propagation. The project maintains connections with related repositories in the clawpack ecosystem, specifically clawpack/pyclaw and clawpack/clawpack, as well as ipython/ipython, indicating its role within a broader computational framework.
The repository provides multiple pathways for users to engage with the material. Users can run notebooks locally using Docker, which eliminates installation complexity by providing a pre-configured image with all dependencies. Alternatively, notebooks can be executed manually after installing required dependencies including a Fortran compiler. For users without local setup capabilities, the repository supports cloud-based execution through Binder, allowing free access to a temporary notebook server without any local installation.
The code in the repository is released under the 3-Clause BSD License, while the text content is protected under the CC-BY-NC-ND Creative Commons license. This dual licensing approach distinguishes between the executable code samples and the educational narrative. The project includes a Dockerfile for building custom Docker images and references bookbook for local PDF compilation. Activity tracking shows minimal recent engagement, with a single tracked contributor event and a median issue or pull request response latency of over 5100 hours, suggesting the repository may be in a stable maintenance phase following the book's publication.
