Preface.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Preface"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Aims and scope\n",
    "\n",
    "This book addresses an important class of mathematical problems (the *Riemann problem*) for first-order hyperbolic partial differential equations (PDEs).  Such PDEs arise when modeling wave propagation in applications such as fluid dynamics, traffic flow, elasticity, and electromagnetics.  The solution of the Riemann problem captures essential information about such models, and is the key ingredient in modern numerical methods for their solution.\n",
    "\n",
    "The book covers the fundamental ideas related to classical Riemann solutions, including their special structure and the types of waves that arise, as well as the ideas behind fast approximate solvers for the Riemann problem.  The emphasis is on the general ideas, but each chapter delves into a particular application.\n",
    "\n",
    "It is assumed that the reader has some knowledge of hyperbolic problems in advance.  This book is intended to supplement rather than replace standard textbooks on the theory and numerical solution of hyperbolic PDEs.  It should also be useful as a tool for students or researchers seeking to better understand the nature of Riemann solutions to a particular hyperbolic system.\n",
    "\n",
    "The notation generally follows that of <cite data-cite=\"fvmhp\"><a href=\"riemann.html#fvmhp\">(LeVeque 2002)</a></cite>, which covers most of the topics included here and many others. We have kept citations to a minimum in these notebooks, but there are a wealth of other books and papers available in the literature.  In particular, some other books that have substantial discussion of Riemann problems and related topics include \n",
    "<cite data-cite=\"lax:cbms\"><a href=\"riemann.html#lax:cbms\">(Lax 1972)</a></cite>, \n",
    "<cite data-cite=\"rjl:eth\"><a href=\"riemann.html#rjl:eth\">(LeVeque 1990)</a></cite>, \n",
    "<cite data-cite=\"god-rav\"><a href=\"riemann.html#kgod-rav\">(Godlewski and Raviart 1996)</a></cite>, \n",
    "<cite data-cite=\"kroener1997\"><a href=\"riemann.html#kroener1997\">(Kr&ouml;ner 1997)</a></cite>, \n",
    "<cite data-cite=\"trangenstein2009\"><a href=\"riemann.html#trangenstein2009\">(Trangenstein 2009)</a></cite>, \n",
    "<cite data-cite=\"toro2013riemann\"><a href=\"riemann.html#toro2013riemann\">(Toro 2013)</a></cite>, and \n",
    "<cite data-cite=\"hesthaven2018\"><a href=\"riemann.html#hesthaven2018\">(Hesthaven 2018)</a></cite>.  \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Book formats\n",
    "\n",
    "This book is available in three formats:\n",
    "\n",
    " - The traditional print medium, in the form of a physical book.  \n",
    " \n",
    " - As a collection of [Jupyter notebooks](https://jupyter.org/) with executable code and interactive animations, available from the Github repository [https://github.com/clawpack/riemann_book](https://github.com/clawpack/riemann_book).  These are not meant to be read on Github, but copied to a local machine or cloud service and run there; see below.\n",
    " \n",
    " - As a set of [webpages](http://www.clawpack.org/riemann_book/html/Index.html) that are rendered from the Jupyter notebooks.  These webpages contain some animations, but the interactive widgets from the notebooks do not work and it is not possible to modify and re-run cells.\n",
    " \n",
    "For the full experience, run the notebooks!\n",
    "\n",
    "### The print version\n",
    "Most of the figures in this book are generated by Python programs.  Most of the code for those figures is in files in the Github repository linked above, but some of it is included inline in the text at the point where each figure appears.  The reader may choose to skip the code sections, especially on a first reading.\n",
    "\n",
    "### The Jupyter notebook version\n",
    "In the electronic version of this book, each chapter is a Jupyter notebook.  The Jupyter Notebook is a free, open-source web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text.  The notebooks that form this text have some additional benefits not present in the print version:\n",
    "\n",
    "  - Some of the code in the notebooks generates **animations**, showing how solutions vary in time or with respect to a parameter.\n",
    "  - Other code in the notebooks generates **interactive \"widgets\"** that allow the reader to vary multiple parameters or plot different quantities, in order to gain deeper insight and understanding.\n",
    "  - The reader can also **modify the code itself**, perhaps to vary parameters that we (the authors) didn't think of.  We encourage readers to use this to satisfy their own curiosity and enhance their learning.\n",
    "  \n",
    "Although some Python code is included directly in the notebooks, for more clarity much of the code has been \"hidden\" in Python modules that are imported near the top of each module.  We also provide links in each notebook (and each chapter of the printed book) to the online location of these modules in case you wish to dive deeper into the code. Most of this code is in the [exact_solvers](https://github.com/clawpack/riemann_book/tree/master/exact_solvers) subdirectory of the Github repository. Other code used primarily for producing plots can be found in the [utils](https://github.com/clawpack/riemann_book/tree/master/utils) subdirectory.\n",
    "  \n",
    "### How to access and run the Jupyter notebook version\n",
    "In order to run the code in the Jupyter notebook version of the book, you will need to have certain tools and libraries installed on a computer, either locally or in the cloud.  There are multiple convenient ways to do this.\n",
    "\n",
    "  - On your own computer: follow the [installation instructions](https://github.com/clawpack/riemann_book#installation)\n",
    "  - With Docker: follow [these instructions](https://github.com/clawpack/riemann_book/blob/FA16/Docker.md) to use the `Dockerfile` that is included in the Github repository.\n",
    "  - With Binder: The cloud service [binder](https://mybinder.org/) allows you to start up a notebook server running notebooks from any Git repository (assuming it specifies the dependencies properly).  You can try it out for these notebooks at [this link](https://mybinder.org/v2/gh/clawpack/riemann_book/master).\n",
    "    This should start up a notebook server on a [Jupyterhub](https://jupyterhub.readthedocs.io/en/latest/) that lets you execute all the notebooks in your browser with no local installation of the notebooks or dependencies required."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview\n",
    "\n",
    "This book consists of several parts, each divided into several chapters (as independent Jupyter notebooks).   The printed book contains only the first two parts, which cover the fundamentals of exact and approximate solutions of Riemann problems; the remaining parts consist of online notebooks that delve into more advanced topics.  In a graduate course on hyperbolic conservation laws, the first two parts could be incorporated into the curriculum, while the later chapters might provide suggestions for student projects.\n",
    "\n",
    "Part I covers the classical theory of the Riemann problem and its solution, introducing the reader to essential concepts including characteristics; similarity solutions; shock waves and the Rankine-Hugoniot jump conditions; rarefactions and Riemann invariants; genuinely nonlinear and linearly degenerate waves; and entropy conditions.  Building up from scalar hyperbolic PDEs and linear systems, it culminates with discussions of the full Riemann solution for the shallow water and Euler systems.\n",
    "\n",
    "Part II introduces approximate Riemann solvers, which are an essential tool in numerical algorithms for hyperbolic PDEs.  This part discusses the most important approaches to such solvers: from simple Lax-Friedrichs and HLL solvers to linearizations, including Roe solvers.  Potential issues with these methods (such as the need for entropy fixes and lack of positivity) are addressed.  Part II concludes with comparisons of canonical approximate solvers for the shallow water and Euler systems.\n",
    "\n",
    "The [Index.ipynb](Index.ipynb) notebook contains links to the chapters of Parts I and II.\n",
    "\n",
    "The remaining parts are still a work in progress at the time of this writing, and are not included in the print or PDF version of the book.  They can be found in the Github repository and additional topics may be added at a later date.  \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing a book with Jupyter notebooks\n",
    "\n",
    "Although the primary goal of this book is to present the mathematics of Riemann solvers in a novel and educational manner, an additional goal from the beginning has been to explore the use of Jupyter notebooks for this sort of publishing venture, and to help popularize Jupyter notebooks within the applied mathematics community.  We believe that notebooks are a great tool for both teaching and research, and an exciting new format for publishing.  It has been an interesting challenge to figure out ways to present material that works well in the notebooks and that also translates into [html files](http://www.clawpack.org/riemann_book/html/Index.html) and a physical book, and we hope that our experiences not only help convey the subject matter but also can serve as a template for other publishing projects or as an impetus to develop better approaches.\n",
    "\n",
    "All of the notebooks and associated Python code are of course available in the github repository, and in addition we have written some [wiki pages](https://github.com/clawpack/riemann_book/wiki) on various other tools we have found useful in developing this book.  In particular, [bookbook](https://github.com/takluyver/bookbook) has been used in converting notebooks to latex/pdf files, and tools for working with notebooks such as [nbdime](https://github.com/jupyter/nbdime) and [nbstripout](https://github.com/kynan/nbstripout) have been invaluable for helping to manage modifications to notebooks in the context of [git](https://git-scm.com/).  Without git and github this project would have never come together, since the three authors have been employed on three different continents for most this project, and many discussions about how to do things, what to include, how to edit notebooks, etc. have taken place via pull requests on github.  As of this writing there are 183 [closed pull requests](https://github.com/clawpack/riemann_book/pulls?q=is%3Apr+is%3Aclosed) on this repository, which provide a history of many of our discussions and decisions.\n",
    "\n",
    "Numerous other books and lecture notes have been written that make extensive use of Jupyter notebooks, and they are also becoming increasingly popular as a supplement to research publications.  See the [Gallery of interesting Jupyter notebooks](https://github.com/jupyter/jupyter/wiki/A-gallery-of-interesting-Jupyter-Notebooks) for other examples and inspiration.  We hope that more applied mathematicians will explore this platform for future publications."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Acknowledgments\n",
    "\n",
    "We are indebted to the people who created the tools we have used to develop these notebooks, and in particular to the developers of Jupyter.  Fernando Perez and several others helped us out at many points during the development of this book.  Jake Vanderplas originally developed the JSAnimation package for us to use in Clawpack, and helped us with a number of other notebook issues. \n",
    "\n",
    "The initial idea for this book arose during discussions at the Clawpack Developers Workshop held at the University of Utah, just before the 2015 SIAM Conference on Computational Science and Engineering.  Many members of the Clawpack community have helped support this project, in particular Kyle Mandli, an early adopter who has provided valuable feedback, as did Lisa Davis.\n",
    "\n",
    "We are delighted that SIAM will be publishing the printed version of these notebooks, and are appreciative of their willingness to support this experiment, and of their patience as we have worked out various kinks in the process.  We are also very pleased that they have allowed the notebook repository to remain freely available on github, with licensing that allows you to not only use the notebooks but to adapt them for your own non-commercial purposes.  Although running the notebooks is the best way to experience this material, we hope you will also buy the book and support SIAM -- or better yet, write your own book and publish with them."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  },
  "toc": {
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": "block",
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}