SIAMFANL.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$\n",
    "\\newcommand{\\reg}{{}^\\textsuperscript{\\textcircled{\\textsc r}}}\n",
    "\\newcommand{\\ml}{{\\bf L}}\n",
    "$\n",
    "# Solving Nonlinear Equations with Iterative Methods: <br> Solvers and Examples in Julia<br>   C. T. Kelley\n",
    "\n",
    "Copyright C. T. Kelley, 2020"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To Betty Thomas Kelley"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Preface and Software](#Preface-and-Software)\n",
    "\n",
    "- [Preface for the notebook](#Preface-for-the-notebook)\n",
    "\n",
    "- [Preface for the print book](#Preface-for-the-print-book)\n",
    "\n",
    "- [Computing Environment for the Book](#Computing-Environment-for-the-Book)\n",
    "\n",
    "- [Learning Julia](#Learning-Julia)\n",
    "\n",
    "- [How to get the software](#How-to-get-the-software)\n",
    "\n",
    "- [The Repositories](#The-Repositories)\n",
    "\n",
    "- [Software License](LICENSE-CODE.md)\n",
    "\n",
    "- [Text License (ie the notebook)](LICENSE-TEXT.md)\n",
    "\n",
    "[Chapter 1: Introduction](SIAMFANLCh1.ipynb)\n",
    "\n",
    "- [Solvers for Chapter 1: __nsolsc.jl__, __secant.jl__, and __ptcsolsc.jl__](SIAMFANLCh1s.ipynb)\n",
    "\n",
    "[Chapter 2: Finding the Newton Step with Gaussian Elimination](SIAMFANLCh2.ipynb)\n",
    "\n",
    "- [Solvers for Chapter 2: nsol.jl and ptcsol.jl](SIAMFANLCh2s.ipynb)\n",
    "\n",
    "[Chapter : Newton-Krylov Methods](SIAMFANLCh3.ipynb)\n",
    "\n",
    "- [Solvers for Chapter 3: nsoli.jl and ptcsoli.jl](SIAMFANLCh3s.ipynb)\n",
    "\n",
    "[Chapter 4: Anderson Acceleration](SIAMFANLCh4.ipynb)\n",
    "- [Solver for Chapter 4: aasol.jl](SIAMFANLCh4s.ipynb)\n",
    "\n",
    "[Chapter 5: Case Studies](SIAMFANLCh5.ipynb)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Preface and Software"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preface for the notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook is a more interactive version of the print book. I encourage you to play with the examples, \n",
    "make up your own, and explore the algorithmic parameters. I hope it's more fun to play with this than to just\n",
    "read text. However, the print book is more useful when you need to look something up or want to bookmark a few\n",
    "pages while working on your own projects. \n",
    "\n",
    "The older book \n",
    "<cite data-cite=\"ctk:newton\"><a href=\"siamfa.html#ctk:newton\">(Kel03)</cite>\n",
    "had listings of source code in an appendix and descriptions of the solvers in the main part of the text. \n",
    "We do that differently here. The description of the algorithms in the notebook is taken from the print book, but for the discussion of the software and most of the examples, we convert the notebook to $\\LaTeX$ and incorporate that directly into the chapters of the print book.\n",
    "\n",
    "I hope that the three parts of this project, print book, notebook, and the solver package make one coherent thing.    \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preface for the print book"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "This book on solvers for nonlinear equations\n",
    "is a user-oriented guide to algorithms and implementation.\n",
    "It is a sequel to \n",
    "<cite data-cite=\"ctk:newton\"><a href=\"siamfa.html#ctk:newton\">(Kel03)</cite>,\n",
    "which used MATLAB® for \n",
    "the solvers and examples. This book uses Julia \n",
    "<cite data-cite=\"Juliasirev\"><a href=\"siamfa.html#Juliasirev\">(BEKS17)</cite>\n",
    "and adds new material\n",
    "on pseudo-transient continuation, mixed-precision solvers, and\n",
    "Anderson acceleration.\n",
    "    \n",
    "Roughly a third of each of the first three chapters are taken from\n",
    "<cite data-cite=\"ctk:newton\"><a href=\"siamfa.html#ctk:newton\">(Kel03)</cite>.\n",
    "The new material includes new and more detailed\n",
    "examples, pseudo-transient continuation, new codes for the solvers\n",
    "and examples, and all the source codes in github repositories.\n",
    "Chapter 4 on Anderson acceleration and the case studies in Chapter 5\n",
    "are completely new.\n",
    "\n",
    "Each of the first four chapters has a component created as a print\n",
    "book in $\\LaTeX$ and a final section created as an\n",
    "IJulia (Jupyter) notebook. I combined\n",
    "the two formats in slightly different ways in the print book and notebook\n",
    "versions, so the correspondence between the two is not exact. The fifth\n",
    "chapter on case studies was written as a print book and then mapped into\n",
    "the notebook.\n",
    "\n",
    "\n",
    "The purpose of the book is to show, via algorithms\n",
    "in pseudocode and Julia and with several examples, how one\n",
    "can choose an appropriate iterative method for a given problem and\n",
    "write an efficient solver or apply one written by others.\n",
    "\n",
    "This book is intended to\n",
    "complement my larger book complement my larger book \n",
    "<cite data-cite=\"ctk:roots\"><a href=\"siamfa.html#ctk:roots\">(Kel95)</cite>,\n",
    "which focuses on in-depth\n",
    "treatment of convergence theory, but does not discuss the details of\n",
    "solving particular problems, implementation in any particular language,\n",
    "or evaluating a solver for a given problem.\n",
    "\n",
    "The computational examples in this book were\n",
    "done with Julia 1.7.2 on various Apple computers.\n",
    "The Julia codes for the solvers are in a Julia package.\n",
    "I provide a suite of Jupyter notebooks to enable the reader to run all\n",
    "the examples in the book and play with them. If you are reading this, you are running the first of\n",
    "those notebooks.\n",
    "\n",
    "I have found that Julia is an excellent environment for a project\n",
    "like this, which unifies a print book, a package of solvers, and an\n",
    "interactive notebook. I have used all the solvers in my own research\n",
    "and many of the examples come from that research.\n",
    "\n",
    "I have written the codes with a goal of\n",
    "readability by a Julia novice who knows some\n",
    "numerical analysis. In particular, \n",
    "I have made the algorithmic parameters very easy to find. \n",
    "I have also\n",
    "put the methods for managing the iteration such as the line search,\n",
    "error reporting, and the logic for updating Jacobians and preconditioners,\n",
    "in an directory that is easy for the interested reader to find and\n",
    "for the less interested reader to ignore.\n",
    "I have sacrificed a\n",
    "good deal of abstraction, some generality, and a bit of performance\n",
    "for clarity.\n",
    "    \n",
    "The solvers\n",
    "were designed for production work on desktop and laptop computers\n",
    "to solve small-to medium-scale\n",
    "problems having at most a few tens of thousands of unknowns.\n",
    "Very large-scale problems on leadership-class computers\n",
    "are best done with software\n",
    "(Trilinos <cite data-cite=\"trilinos\"><a href=\"siamfa.html#trilinos\">(HBH<sup>+</sup>05)</cite>,\n",
    "PETSc <cite data-cite=\"petsc-web-page\"><a href=\"siamfa.html#petsc-web-page\">(BAA<sup>+</sup>19)</cite>\n",
    "SunDials <cite data-cite=\"sundials\"><a href=\"siamfa.html#sundials\">(HBG<sup>+</sup>05)</cite>)\n",
    "designed for that purpose.\n",
    "\n",
    "\n",
    "We assume that the reader has a good understanding of elementary\n",
    "numerical analysis at the level of \n",
    "<cite data-cite=\"atkelem\"><a href=\"siamfa.html#atkelem\">(Atk89)</cite>,\n",
    "and of numerical linear algebra at the level of \n",
    "<cite data-cite=\"demmel\"><a href=\"siamfa.html#demmel\">(Dem97)</cite>,\n",
    "<cite data-cite=\"IIbook\"><a href=\"siamfa.html#IIbook\">(Ips09)</cite>, and\n",
    "<cite data-cite=\"trefbau\"><a href=\"siamfa.html#trefbau\">(TB96)</cite>. A student who\n",
    "has had, or is taking, a course from one of these books is well prepared.\n",
    "We will also use some deeper results from\n",
    "numerical linear algebra and will refer the reader to \n",
    "<cite data-cite=\"higham\"><a href=\"siamfa.html#higham\">(Hig96)</cite>\n",
    "for those.\n",
    "\n",
    "The examples are closely coupled to the text and\n",
    "the reader will get the most out of\n",
    "this book if she/he has an elementary knowledge of Julia.\n",
    "If the reader has good skills in numerical work in another high-level\n",
    "language then learning Julia at the level one needs to work\n",
    "through this\n",
    "book is not difficult and can be done while reading the book.\n",
    "\n",
    "The reader should know (or learn!) Julia and its ecosystem\n",
    "well enough to use the package manager,\n",
    "install packages, use modules, start a notebook, and to do basic tasks in\n",
    "numerical methods (LU, SVD, QR) in Julia. You should also know\n",
    "how to use github to clone repositories and put\n",
    "them where they need to go. A reader with that minimal knowledge of github and\n",
    "Julia should be able to install and understand the codes,\n",
    "play with the algorithms, and wreak havoc.\n",
    "\n",
    "\n",
    "Unfortunately, there is no introduction to the language aimed at\n",
    "the numerical analyst, as there is for Matlab \n",
    "<cite data-cite=\"nick_matlab\"><a href=\"siamfa.html#nick_matlab\">(HH05)</cite>.\n",
    "One very good reference is the paper \n",
    "<cite data-cite=\"Juliasirev\"><a href=\"siamfa.html#Juliasirev\">(BEKS17)</cite>.\n",
    "The full manual \n",
    "<cite data-cite=\"Julia20\"><a href=\"siamfa.html#Julia20\">(Pro20)</cite> and the online guide\n",
    "<cite data-cite=\"JuliaWeb\"><a href=\"siamfa.html#JuliaWeb\">(Ame20)</cite>\n",
    "also very useful.\n",
    "    \n",
    "\n",
    "Parts of this book are based on research supported by the National\n",
    "Science Foundation, the US Department of Energy,\n",
    "and the Army Research Office, most recently\n",
    "by NSF grants\n",
    "OAC-1740309,\n",
    "DMS-1745654,\n",
    "DMS-1906446,\n",
    "Department of Energy grant DE-NA003967,\n",
    "and\n",
    "ARO grant W911NF-16-1-0504.\n",
    "\n",
    "Any opinions, findings, and conclusions or\n",
    "recommendations expressed in this material are those of the author and\n",
    "do not necessarily reflect the views of the National\n",
    "Science Foundation, the Department of Energy,\n",
    "or the Army Research Office.\n",
    "\n",
    "In addition to the many people who influenced\n",
    "<cite data-cite=\"ctk:newton\"><a href=\"siamfa.html#ctk:newton\">(Kel03)</cite> and\n",
    "<cite data-cite=\"ctk:roots\"><a href=\"siamfa.html#ctk:roots\">(Kel95)</cite>,\n",
    "I want\n",
    "to particularly thank\n",
    "Jerry Bernholc,\n",
    "Wei Bian,\n",
    "Emil Briggs,\n",
    "Luis Chacon,\n",
    "Xiaojun Chen,\n",
    "Kevin Clarno,\n",
    "Austin Ellis,\n",
    "Tom Evans,\n",
    "Elizabeth Greenspan,\n",
    "Steven Hamilton,\n",
    "Michael Herbst,\n",
    "Nick Higham,\n",
    "Ilse Ipsen,\n",
    "Elena Jakubikova,\n",
    "Randy LeVeque,\n",
    "Antoine Levitt,\n",
    "Lin Lin,\n",
    "Wenchang Lu,\n",
    "Juan Meza,\n",
    "Zack Morrow,\n",
    "James Nance,\n",
    "Chung-Wei Ng,\n",
    "Sheehan Olver,\n",
    "Roger Pawlowski,\n",
    "Benoit Pasquier,\n",
    "Liqun Qi,\n",
    "Stuart Slattery,\n",
    "Alex Toth,\n",
    "Romain Veltz,\n",
    "Homer Walker,\n",
    "Jeff Willert,\n",
    "Chao Yang,\n",
    "and a few hundred MA 784 students\n",
    "for their inspiration as I got this project into shape.\n",
    "    \n",
    "C. T. Kelley<br>\n",
    "Raleigh, North Carolina<br>\n",
    "April, 2022\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Computing Environment for the Book"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The results in this book and the docstrings in the codes\n",
    "were obtained on a 2019 Apple iMac with an Intel 8-Core I9 CPU using\n",
    "Julia 1.7.2 and the MKL BLAS. The results, especially the tables of errors,\n",
    "will differ from our depending on your choice of BLAS and the architecture\n",
    "of your computer. In particular, if you use OpenBLAS, the default\n",
    "with Julia, you will see small differences from our results.\n",
    "\n",
    "The notebooks have been tested with Julia 1.7.2 and 1.6.5.\n",
    "Versions 1.7.0 and 1.6.4 have bugs that cause problems with the notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learning Julia"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unfortunately, there is no introduction to the language aimed at\n",
    "the numerical analyst, as there is for Matlab \n",
    "<cite data-cite=\"nick_matlab\"><a href=\"siamfa.html#nick_matlab\">(HH05)</cite>.\n",
    "There are many online resources for Julia and you should take some care to\n",
    "stick to the ones for version 1.0 and above. We recommend that you use the\n",
    "latest version of Julia. \n",
    "\n",
    "    \n",
    "If you are a Julia novice, it will take some experimentation to get\n",
    "comfortable. One very good reference is the paper \n",
    "<cite data-cite=\"Juliasirev\"><a href=\"siamfa.html#Juliasirev\">(BEKS17)</cite>. You should read this first.\n",
    "The full manual \n",
    "<cite data-cite=\"Julia20\"><a href=\"siamfa.html#Julia20\">(Pro20)</cite> and the online guide\n",
    "<cite data-cite=\"JuliaWeb\"><a href=\"siamfa.html#JuliaWeb\">(Ame20)</cite>\n",
    "also very useful. There is also a recent Julia-centric\n",
    "entry-level numerical linear algebra book\n",
    "<cite data-cite=\"NLA_Julia\"><a href=\"siamfa.html#NLA_Julia\">(DW21)</cite>.\n",
    "If you are coming from Matlab, your best bet is to start off by\n",
    "learning\n",
    "how linear algebra works in Julia. The Wiki \n",
    "<cite data-cite=\"JuliaWiki\"><a href=\"siamfa.html#JuliaWiki\">(Con20)</cite>\n",
    "is good.\n",
    "    \n",
    "    \n",
    "There are many resources at\n",
    "<https://julialang.org/learning>.\n",
    "\n",
    "- There are general introductions to\n",
    "Julia that are aimed a more general audiences or introductory computer\n",
    "science courses. A good example of such a book is \n",
    "<cite data-cite=\"LauensDowney\"><a href=\"siamfa.html#LauensDowney\">(LD19)</cite>,\n",
    "which is also available at\n",
    "<https://benlauwens.github.io/ThinkJulia.jl/latest/book.html>.\n",
    "\n",
    "\n",
    "- The Julia youtube channel <https://www.youtube.com/channel/UC9IuUwwE2xdjQUT_LMLONoA> has several useful tutorials.\n",
    "\n",
    "\n",
    "- Two useful and fast introcutions are the video\n",
    "<https://www.youtube.com/watch?v=8h8rQyEpiZA&t> and the collection of web pages\n",
    "<cite data-cite=\"JuliaWeb\"><a href=\"siamfa.html#JuliaWeb\">(Ame20)</cite> <https://techytok.com/from-zero-to-julia>.\n",
    "\n",
    "\n",
    "- The discourse at __julialang.org__ <https://discourse.julialang.org> is a welcoming environment for the novice.\n",
    "\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to get the software"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you are reading this, you've found the notebook and probably have installed the package. __If you have not installed the package, type this at the REPL prompt or in a code cell in the notebook.__\n",
    "\n",
    "\n",
    "```julia\n",
    "import Pkg; Pkg.add(\"SIAMFANLEquations\")\n",
    "```\n",
    "in the REPL. When you add __SIAMFANLEquations.jl__ Julia will automatically install the packages it needs. That takes some time, but all you need to do is wait. To use the solvers and examples you will need to type\n",
    "```julia\n",
    "using SIAMFANLEquations\n",
    "using SIAMFANLEquations.TestProblems\n",
    "using SIAMFANLEquations.Examples\n",
    "```\n",
    "at the REPL prompt.\n",
    "\n",
    "\n",
    "The notebooks for the individual chapters get the packages organized in the first code window, which you __must run!__ Your best bet is to do __run all__ as the first step before playing with the notebooks. Nothing in the notebooks should take a long time to run.\n",
    "\n",
    "I am assuming you've followed the directions in the README for the repo and cloned the whole works. I will use the module __/src/NotebookSIAMFANL.jl__ in the notebooks. That module has the examples from the book organized in a sensible way.\n",
    "\n",
    "In addition to the packages you'll need for __SIAMFANLEquations.jl__, you will need __BenchmarkTools.jl__ and    \n",
    "__PyPLot.jl__. To install these type\n",
    "\n",
    "```julia\n",
    "import Pkg; Pkg.add(\"BenchmarkTools\")\n",
    "import Pkg; Pkg.add(\"PyPlot\")\n",
    "```\n",
    "in the REPL\n",
    "\n",
    "The project has three parts:\n",
    "\n",
    "- a print book <cite data-cite=\"ctk:fajulia\"><a href=\"siamfa.html#ctk:fajulia\">(Kel22)</cite>,\n",
    "- the notebooks in this repository <cite data-cite=\"ctk:notebooknl\"><a href=\"siamfa.html#ctk:notebooknl\">(Kel22b)</cite>,\n",
    "- the Julia package SIAMFANLEquations.jl <cite data-cite=\"ctk:siamfanl\"><a href=\"siamfa.html#ctk:siamfanl\">(Kel22c)</cite>\n",
    "which includes the sovlers, test problems, and examples.\n",
    "\n",
    "The first cell in each notebook is an invisible markdown cell with the LaTeX commands I need. Do not mess with that.\n",
    "\n",
    "As you will see, that first code cell in each chapter has the single line\n",
    "\n",
    "```julia\n",
    "include(\"fanote_init.jl\")\n",
    "```\n",
    "at the start.\n",
    "\n",
    "This is a Julia script that contains the commands\n",
    "\n",
    "```julia\n",
    "using SIAMFANLEquations\n",
    "using SIAMFANLEquations.TestProblems\n",
    "using SIAMFANLEquations.Examples\n",
    "using LinearAlgebra\n",
    "using BandedMatrices\n",
    "using BenchmarkTools    \n",
    "using PyPLot\n",
    "push!(LOAD_PATH,\"./src\")\n",
    "using NotebookSIAMFANL\n",
    "```\n",
    "The script gets the dependencies and puts the functions for the examples where they need to be.\n",
    "\n",
    "These first two cells __must__ run before you can do anything with the notebook. That's one reason that __run all__ before starting is a good idea.\n",
    "\n",
    "The Julia codes for the figures in the print book and the notebooks are in the [Notebook/src](./src) directory.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dependencies\n",
    "\n",
    "While we have tried to minimize dependencies,\n",
    "you will still need several Julia packages to use the solvers and run the\n",
    "test problems and examples. Installing the package\n",
    "SIAMFANLEquations should automatically make sure you have the ones for\n",
    "the solvers, examples, and test problems.\n",
    "\n",
    "- For the solvers: BandedMatrices, LaTeXStrings, LinearAlgebra, Printf, SuiteSparse, SparseArrays, Test\n",
    "\n",
    "- For the the test problems and examples: Everything for the solvers and: AbstractFFTs, FFTW, FastGaussQuadrature\n",
    "\n",
    "   - The case studies in [Chapter 5](SIAMFANLCh5.ipynb) use both the TestProblems and Examples submodules.\n",
    "\n",
    "- For the notebooks: everything for the solvers, test problems, and, examples plus: BenchmarkTools, IJulia, PyPlot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solvers, Test Problems, and Examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The solvers and test problems\n",
    "are part of __SIAMFANLEquations__ the Julia package. The solvers\n",
    "are located in __/src/Solvers__. The core codes and the relevant chapters ar\n",
    "\n",
    "\n",
    "- [Chapter 1](SIAMFANLCh1.ipynb): Solvers for scalar equations __nsolsc.jl__, __secant.jl__,\n",
    "and __ptsolsc.jl__ in the __/src/Solvers/Chapter1__ subdirectory,\n",
    "    \n",
    "- [Chapter 2](SIAMFANLCh2.ipynb): Solvers with Gaussian elimination \n",
    "__nsol.jl__ and __ptcsol.jl__\n",
    "    \n",
    "- [Chapter 3](SIAMFANLCh3.ipynb): Newton-Krylov solvers __nsoli.jl__ and __ptcsoli.jl__\n",
    "\n",
    "   - GMRES (__kl_gmres.jl__) and BiCGStab (__kl_bicgstab.jl__) linear solvers in __/src/Solvers/LinearSolvers__\n",
    "   subdirectory.\n",
    "\n",
    "- [Chapter 4](SIAMFANLCh4.ipynb): Anderson acceleration __aasol.jl__\n",
    "    \n",
    "- [Chapter 5](SIAMFANLCh5.ipynb): Case studies: Most of the solvers from Chapters 2, 3, and 4. The \n",
    "case studies are in the __src/TestProblems/CaseStudies__ subdirectory.\n",
    "   \n",
    "\n",
    "The Krylov linear solver(s) for [Chapter 3](SIAMFANLCh3.ipynb)\n",
    "can be used for general problems, but have been designed\n",
    "to couple with the nonlinear solvers. In particular, they are aware of any data the\n",
    "function, Jacobian-vector product, or preconditioner may need.\n",
    "\n",
    "The test problems and examples are also part of the package\n",
    "because they are used\n",
    "for continuous integration (aka unit testing). The test problems are\n",
    "in the __/src/TestProblems__ directory and the examples in\n",
    "__/src/Examples__. Both the test problems and examples are submodules\n",
    "of __SIAMFANLEquation__}. The Julia codes for the figures in the\n",
    "print book and Notebooks are in the\n",
    "__Notebook/src__ directory.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Repositories"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Julia package and the notebooks are in two GitHub repositories.\n",
    "The repositories are separate because the Julia package manager will\n",
    "put the solver package in the __.julia__ subdirectory of your home\n",
    "directory, which is not a convenient place for the notebooks.\n",
    "\n",
    "Each repository has an archival __FA20__ branch which is the one use to produce\n",
    "this book. The master branches are the ones I use for fixing post-publication\n",
    "errors and bugs. The README files on the repositories begin with up-to-date\n",
    "accounts of the status of the package and notebooks.\n",
    "\n",
    "The README files also tell you which version of Julia created the\n",
    "repository. Your best bet is to use the latest version of Julia. If\n",
    "your organization limits software installation, you may have to use the\n",
    "Long Term Support (LTS) version of Julia, which is currently 1.6.5.\n",
    "\n",
    "The github repositories each have an archival {\\bf FA20} \n",
    "branch. The archival branches\n",
    "are the ones that were current when the book was printed. These are\n",
    "\n",
    "-- https://github.com/ctkelley/SIAMFANLEquations.jl/tree/FA20\n",
    "\n",
    "-- https://github.com/ctkelley/NotebookSIAMFANL/tree/FA20\n",
    "\n",
    "Clone these repositories to have the version which produced the book. The\n",
    "version you get from the package manager when you install\n",
    "the package may have a version number larger that 1.0 as I make\n",
    "corrections or update the codes. I will refer to that\n",
    "version as the stable branch.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Notebook Repository\n",
    "\n",
    "The README file for the notebook repository\n",
    "explains how to set up the notebook and the solver package.\n",
    "The first step is to clone the repository and put the directory in\n",
    "a convenient place.\n",
    "\n",
    "The root directory contains all the __ipynb__ notebook files,\n",
    "an html file for the bibliography [siamfa.html](siamfa.html), and\n",
    "a Julia script __fanote_init.jl__. Each notebook runs\n",
    "some $\\LaTeX$ commands in the first (invisible) cell and __fanote\\_init.jl__\n",
    "in the second. You should run these two cells before doing anything with\n",
    "a notebook.\n",
    "\n",
    "#### Codes for the examples\n",
    "\n",
    "The __/src__ subdirectory of the Notebook repository has codes that produced\n",
    "the figures and tables in the book. These codes use the examples\n",
    "and test problems from the package.\n",
    "\n",
    "#### Notebook Versions\n",
    "\n",
    "The notebooks have been most recently\n",
    "tested with Julia 1.7.2 and 1.6.5.\n",
    "We recommend that you use the latest version of Julia.\n",
    "\n",
    "The archival repository is\n",
    "\n",
    "https://github.com/ctkelley/NotebookSIAMFANL/tree/FA20\n",
    "\n",
    "\n",
    "This is the repository which I used to produce the print book. Versions\n",
    "with numbers larger than 1.0 are for bug fixes and error correction in\n",
    "the text.\n",
    "\n",
    "The version at\n",
    "\n",
    "https://github.com/ctkelley/NotebookSIAMFANL\n",
    "\n",
    "is the version I am constantly updating. There should be no harm in\n",
    "cloning that repository and using it.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Package Repository\n",
    "\n",
    "__SIAMFANLEquations.jl__ is a registered Julia package. The repository\n",
    "has many subdirectories (for example __/test__ and __/docs__) that most\n",
    "readers of this book can ignore. We provide more detail about the\n",
    "organization of the package repository in the [Appendix A](Appendices/AppendixA.ipynb).\n",
    "\n",
    "The __/src__ subdiretory has the codes for the solvers, test problems,\n",
    "and examples. I will point the reader to the relevant files for each\n",
    "chapter at the beginning of the chapter.\n",
    "\n",
    "You should not need to look at the __/src/Tools__ directory. The files\n",
    "in that directory manage the internal data structures for the solvers and\n",
    "assemble the output tuples. The only file in __/src/Tools__\n",
    "of algorithmic interest is __armijo.jl__, which manages the line\n",
    "search.\n",
    "\n",
    "The archival branch at\n",
    "\n",
    "https://github.com/ctkelley/SIAMFANLEquations.jl/tree/FA20\n",
    "\n",
    "contains the files I used to create the book.\n",
    "\n",
    "\n",
    "The documentation for the stable branch is at\n",
    "\n",
    "https://ctkelley.github.io/SIAMFANLEquations.jl/stable/\n",
    "\n",
    "I built this documentation with the __Documenter.jl__\n",
    "\\cite{documenter} package. It is far less complete than the notebooks.\n",
    "The files that generate the docs are stored in the __/src/docs__ directory.\n",
    "\n",
    "The master (dev) branch of the package repository is\n",
    "\n",
    "https://github.com/ctkelley/SIAMFANLEquations.jl\n",
    "\n",
    "I would not advise you to use that branch because I will be\n",
    "changing it as I correct errors and bugs. I will make no changes\n",
    "that alter the user interface to the codes. The branch you get with\n",
    "the Juila package manager is the stable branch. Use that one.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next notebook = [Chapter 1: Introduction](SIAMFANLCh1.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 1.10.0",
   "language": "julia",
   "name": "julia-1.10"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.10.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}