Merge pull request #2633 from firedrakeproject/JDBetteridge/firedrake…

…_manual The Firedrake Manual
firedrakeproject · Feb 10, 2023 · bbe9ef4 · bbe9ef4
2 parents 8c684e1 + 6fbe5fa
commit bbe9ef4
Show file tree

Hide file tree

Showing 102 changed files with 1,365 additions and 652 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -22,12 +22,18 @@ jobs:
     # part of the jobs
     steps:
       - uses: actions/checkout@v2
+      - name: System dependencies
+        run: |
+          apt-get update --fix-missing
+          apt-get -y dist-upgrade
+          apt-get -y install inkscape texlive-full
       - name: Install
         run: |
           . /home/firedrake/firedrake/bin/activate
           python -m pip install -e .
           python -m pip install sphinx
           python -m pip install sphinxcontrib-bibtex
+          python -m pip install sphinxcontrib-svg2pdfconverter
           python -m pip install bibtexparser
           python -m pip install numpydoc
           python -m pip install git+https://github.com/sphinx-contrib/youtube.git
@@ -42,4 +48,7 @@ jobs:
         run: |
           . /home/firedrake/firedrake/bin/activate
           cd docs
+          make linkcheck
           make html
+          make latex
+          make latexpdf
diff --git a/AUTHORS b/AUTHORS
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -0,0 +1,166 @@
+..
+   This file is generated by team.py using the team.rst_t template and team.ini.
+      DO NOT EDIT DIRECTLY
+   To add your name and/or institution edit the relevant sections of
+      docs/source/team.ini
+
+=======
+AUTHORS
+=======
+
+Firedrake has been contributed to by the following:
+
+Institutions
+------------
+
+Baylor University.............<https://www.baylor.edu>
+
+Durham University.............<https://www.durham.ac.uk>
+
+Imperial College London.......<https://www.imperial.ac.uk>
+
+University of Bath............<https://www.bath.ac.uk>
+
+University of Leeds...........<https://www.leeds.ac.uk>
+
+University of Oxford..........<https://www.ox.ac.uk>
+
+University of Washington......<https://www.washington.edu>
+
+
+
+Individuals
+-----------
+
+Julian Andrej
+
+Nicolas Barral................<https://nicolasbarral.fr>
+
+Nicholas Barton
+
+Tom Bendall
+
+Doru Bercea
+
+Jack Betteridge...............<https://www.imperial.ac.uk/people/j.betteridge>
+
+George Boutsioukis
+
+Nacime Bouziani...............<https://www.imperial.ac.uk/people/n.bouziani18>
+
+Romain Brault
+
+Pablo Brubeck.................<https://www.maths.ox.ac.uk/people/pablo.brubeckmartinez>
+
+Ed Bueler
+
+Henrik Buesing
+
+Justin Chang
+
+Cyrus Cheng
+
+Teodoro Fields Collin
+
+Colin Cotter..................<https://www.imperial.ac.uk/people/colin.cotter>
+
+Joshua Coutinho
+
+Patrick E. Farrell............<https://pefarrell.org>
+
+Simon Funke...................<http://www.simonfunke.com>
+
+Melina Giagiozis
+
+Thomas Gibson
+
+Tim Greaves
+
+Alastair Gregory
+
+Tom Gregory...................<https://www.imperial.ac.uk/people/t.gregory18>
+
+David Ham.....................<https://www.imperial.ac.uk/people/david.ham>
+
+Christopher Hawkes
+
+Miklós Homolya
+
+Christian Jacobs
+
+Darko Janeković
+
+Nick Johnson
+
+Anna Kalogirou
+
+Paul Kelly....................<https://www.imperial.ac.uk/people/p.kelly>
+
+Rob Kirby.....................<https://www.baylor.edu/math/index.php?id=90540>
+
+Stephan Kramer................<https://www.imperial.ac.uk/people/s.kramer>
+
+Tuomas Kärnä..................<https://www.tuomaskarna.com>
+
+Michael Lange.................<https://www.linkedin.com/in/michael-lange-56675994/>
+
+Nicolas Loriant
+
+Fabio Luporini................<https://www.imperial.ac.uk/people/f.luporini12>
+
+Scott MacLachlan..............<https://www.math.mun.ca/~smaclachlan/>
+
+Graham Markall................<https://big-grey.co.uk/>
+
+India Marsden.................<https://www.maths.ox.ac.uk/people/india.marsden>
+
+Geordie McBain
+
+Andrew McRae..................<https://www2.physics.ox.ac.uk/contacts/people/mcraea>
+
+Oliver Meister................<https://www5.in.tum.de/wiki/index.php/Dipl.-Inf._Oliver_Meister>
+
+Lawrence Mitchell.............<https://www.wence.uk/>
+
+Eike Mueller
+
+Reuben W. Nixon-Hill..........<https://www.imperial.ac.uk/people/reuben.nixon-hill10>
+
+Alberto Paganini..............<https://www2.le.ac.uk/departments/mathematics/extranet/staff-material/staff-profiles/alberto-paganini>
+
+Francis Poulin
+
+Florian Rathgeber.............<https://kynan.github.io>
+
+Asbjørn Nilsen Riseth
+
+Hannah Rittich
+
+Thomas Roy
+
+Francis P. Russell
+
+Koki Sagiyama.................<https://www.imperial.ac.uk/people/k.sagiyama>
+
+Tomasz Salwa
+
+Kaho Sato
+
+Ben Sepanski..................<https://bensepanski.github.io>
+
+Daniel Shapero................<https://psc.apl.uw.edu/people/investigators/daniel-shapero/>
+
+Jemma Shipton
+
+Tianjiao (TJ) Sun.............<https://www.doc.ic.ac.uk/~ts2914/>
+
+Sophia Vorderwuelbecke........<https://www.imperial.ac.uk/people/s.vorderwuelbecke18>
+
+Joe Wallwork..................<https://www.imperial.ac.uk/people/j.wallwork16>
+
+Connor Ward...................<https://www.imperial.ac.uk/people/c.ward20>
+
+Florian Wechsung..............<https://florianwechsung.github.io>
+
+Fangyi Zhou
+
diff --git a/demos/DG_advection/DG_advection.py.rst b/demos/DG_advection/DG_advection.py.rst
@@ -80,12 +80,12 @@ exterior facets :math:`\Gamma_\mathrm{ext}` appears exactly once in
 .. math::
 
    \int_\Omega \! \phi \frac{\partial q}{\partial t} \, \mathrm{d} x
-   = \int_\Omega \! q \nabla \cdot (\phi \vec{u}) \, \mathrm{d} x
-   - \int_{\Gamma_\mathrm{int}} \! \widetilde{q}(\phi_+ \vec{u} \cdot \vec{n}_+
-     + \phi_- \vec{u} \cdot \vec{n}_-) \, \mathrm{d} S
-   - \int_{\Gamma_\rlap{\mathrm{ext, inflow}}} \phi q_\mathrm{in} \vec{u} \cdot
-   \vec{n} \, \mathrm{d} s
-   - \int_{\Gamma_\rlap{\mathrm{ext, outflow}}} \phi q \vec{u} \cdot
+   &= \int_\Omega \! q \nabla \cdot (\phi \vec{u}) \, \mathrm{d} x\\
+   &\quad- \int_{\Gamma_\mathrm{int}} \! \widetilde{q}(\phi_+ \vec{u} \cdot \vec{n}_+
+     + \phi_- \vec{u} \cdot \vec{n}_-) \, \mathrm{d} S\\
+   &\quad- \int_{\Gamma_{\mathrlap{\mathrm{ext, inflow}}}} \phi q_\mathrm{in} \vec{u} \cdot
+   \vec{n} \, \mathrm{d} s\\
+   &\quad- \int_{\Gamma_{\mathrlap{\mathrm{ext, outflow}}}} \phi q \vec{u} \cdot
    \vec{n} \, \mathrm{d} s
    \qquad \forall \phi \in V.
 
@@ -307,7 +307,7 @@ The last step is to make the animation and save it to a file. ::
       print("Failed to write movie! Try installing `ffmpeg`.")
 
 This demo can be found as a script in
-`DG_advection.py <DG_advection.py>`__.
+:demo:`DG_advection.py <DG_advection.py>`.
 
 
 .. rubric:: References

diff --git a/demos/benney_luke/benney_luke.py.rst b/demos/benney_luke/benney_luke.py.rst
@@ -10,8 +10,7 @@ Benney-Luke equations: a reduced water wave model
     The work is based on the article "Variational water wave
     modelling: from continuum to experiment" by Onno Bokhove and Anna
     Kalogirou :cite:`2015:lmscup`. The authors gratefully
-    acknowledge funding from EPSRC grant no. `EP/L025388/1
-    <http://gow.epsrc.ac.uk/NGBOViewGrant.aspx?GrantRef=EP/L025388/1>`__
+    acknowledge funding from EPSRC grant no. EP/L025388/1
     with a link to the Dutch Technology Foundation STW for the project
     "FastFEM: behavior of fast ships in waves".
 
@@ -53,10 +52,18 @@ Note that the Neumann boundary conditions have been used to remove every surface
 
 .. math::
 
-  \int_{\Omega} \frac{\phi^{n+1/2}-\phi^n}{\frac{1}{2}\!dt}\,v + \frac{\mu}{2}\nabla\left(\frac{\phi^{n+1/2}-\phi^n}{\frac{1}{2}\!dt}\right)\cdot\nabla v + \eta^n\,v + \frac{\epsilon}{2}\nabla\phi^{n+1/2}\cdot\nabla\phi^{n+1/2}\,v \,dx\,dy &= 0 \\
-  \int_{\Omega} q^{n+1/2}\,v - \frac{2}{3}\nabla\phi^{n+1/2}\cdot\nabla v \,dx\,dy &= 0 \\
-  \int_{\Omega} \frac{\eta^{n+1}-\eta^n}{dt}\,v + \frac{\mu}{2}\nabla\left(\frac{\eta^{n+1}-\eta^n}{dt}\right)\cdot\nabla v - \frac{1}{2}\Bigl( \left(1+\epsilon\eta^{n+1}\right) + \left(1+\epsilon\eta^n\right) \Bigr)\nabla\phi^{n+1/2}\cdot\nabla v - \mu\nabla q^{n+1/2}\cdot\nabla v \,dx\,dy &= 0 \\
-  \int_{\Omega} \frac{\phi^{n+1}-\phi^{n+1/2}}{\frac{1}{2}\!dt}\,v + \frac{\mu}{2}\nabla\left(\frac{\phi^{n+1}-\phi^{n+1/2}}{\frac{1}{2}\!dt}\right)\cdot\nabla v + \eta^{n+1}\,v + \frac{\epsilon}{2}\nabla\phi^{n+1/2}\cdot\nabla\phi^{n+1/2}\,v \,dx\,dy &= 0 \\
+  \int_{\Omega} \frac{\phi^{n+1/2}-\phi^n}{\frac{1}{2}\!dt}\,v + \frac{\mu}{2}\nabla\left(\frac{\phi^{n+1/2}-\phi^n}{\frac{1}{2}\!dt}\right)\cdot\nabla v \hspace{8em}\\
+  + \eta^n\,v + \frac{\epsilon}{2}\nabla\phi^{n+1/2}\cdot\nabla\phi^{n+1/2}\,v \,dx\,dy &= 0 \\\\
+  %
+  \int_{\Omega} q^{n+1/2}\,v - \frac{2}{3}\nabla\phi^{n+1/2}\cdot\nabla v \,dx\,dy &= 0 \\\\
+  %
+  \int_{\Omega} \frac{\eta^{n+1}-\eta^n}{dt}\,v + \frac{\mu}{2}\nabla\left(\frac{\eta^{n+1}-\eta^n}{dt}\right)\cdot\nabla v \hspace{8em}\\
+  - \frac{1}{2}\Bigl( \left(1+\epsilon\eta^{n+1}\right) + \left(1+\epsilon\eta^n\right) \Bigr)\nabla\phi^{n+1/2}\cdot\nabla v \hspace{4em}\\
+  - \mu\nabla q^{n+1/2}\cdot\nabla v \,dx\,dy &= 0 \\\\
+  %
+  \int_{\Omega} \frac{\phi^{n+1}-\phi^{n+1/2}}{\frac{1}{2}\!dt}\,v + \frac{\mu}{2}\nabla\left(\frac{\phi^{n+1}-\phi^{n+1/2}}{\frac{1}{2}\!dt}\right)\cdot\nabla v \hspace{8em}\\
+  + \eta^{n+1}\,v + \frac{\epsilon}{2}\nabla\phi^{n+1/2}\cdot\nabla\phi^{n+1/2}\,v \,dx\,dy &= 0 \\\\
+  %
   \int_{\Omega} q^{n+1}\,v - \frac{2}{3}\nabla\phi^{n+1}\cdot\nabla v \,dx\,dy &= 0.
 
 Furthermore, we note that the Benney-Luke equations admit asymptotic solutions (correct up to order :math:`\epsilon`). The "exact" solutions can be found by assuming one-dimensional travelling waves of the type
@@ -214,7 +221,7 @@ We are now ready to enter the main time iteration loop::
 
 The output can be visualised using `paraview <http://www.paraview.org/>`__.
 
-A python script version of this demo can be found `here <benney_luke.py>`__.
+A python script version of this demo can be found :demo:`here <benney_luke.py>`.
 
 The Benney-Luke system and weak formulations presented in this demo have also been used to model extreme waves that occur due to Mach reflection through the intersection of two obliquely incident solitary waves. More information can be found in :cite:`Gidel:2017`.
 

diff --git a/demos/burgers/burgers.py.rst b/demos/burgers/burgers.py.rst
@@ -113,4 +113,4 @@ which amount to applying a full LU decomposition as a preconditioner. ::
       t += timestep
       outfile.write(project(u, V_out, name="Velocity"))
     
-A python script version of this demo can be found `here <burgers.py>`__.
+A python script version of this demo can be found :demo:`here <burgers.py>`.
diff --git a/demos/camassa-holm/camassaholm.py.rst b/demos/camassa-holm/camassaholm.py.rst
@@ -247,7 +247,7 @@ Images of the solution at shown below.
 
    Solution at :math:`t = 5.3.`
 
-A python script version of this demo can be found `here <camassaholm.py>`__.
+A python script version of this demo can be found :demo:`here <camassaholm.py>`.
 
 .. rubric:: References
 

diff --git a/demos/demo_references.bib b/demos/demo_references.bib
@@ -44,7 +44,7 @@ @InBook{2015:lmscup
   series =       {LMS Lecture Note Series},
   isbn =         9781107565562,
   url =
-                  {http://www1.maths.leeds.ac.uk/~matak/documents/lms-cup2015.pdf}
+                  {https://www.cambridge.org/core/books/lectures-on-the-theory-of-water-waves/5BA234D75E0067EDBC15B3F3839923DD}
 }
 
 @Article{Gidel:2017,
@@ -246,7 +246,7 @@ @Article{Salwa:2016
   journal = {Extended paper for Int. Conf. on Ocean, Offshore and Arctic Eng., OMAE2016, Busan, South-Korea},
   month = {June},
   year = 2016,
-  url = "http://proceedings.asmedigitalcollection.asme.org/proceeding.aspx?articleID=2570974"
+  url = "https://asmedigitalcollection.asme.org/OMAE/proceedings-abstract/OMAE2016/49972/281268"
 }
 
 @Article{Chin:1999,

diff --git a/demos/eigenvalues_QG_basinmodes/qgbasinmodes.py.rst b/demos/eigenvalues_QG_basinmodes/qgbasinmodes.py.rst
@@ -243,7 +243,7 @@ Below is a plot of the spatial structure of the imaginary part of one of the eig
 .. figure:: eigenmode_imag.png
    :align: center
 
-This demo can be found as a Python script in `qgbasinmodes.py <qgbasinmodes.py>`__.
+This demo can be found as a Python script in :demo:`qgbasinmodes.py <qgbasinmodes.py>`.
 
 .. rubric:: References
 

diff --git a/demos/extruded_continuity/extruded_continuity.py.rst b/demos/extruded_continuity/extruded_continuity.py.rst
@@ -26,12 +26,12 @@ set of equations are then
 .. math::
 
    -\int_\Omega \! q \vec{u_0} \cdot \nabla \phi \, \mathrm{d} x
-   + \int_{\Gamma_\rlap{\mathrm{ext, outflow}}} \! \phi q \vec{u} \cdot \vec{n}
+   + \int_{\Gamma_{\mathrlap{\mathrm{ext, outflow}}}} \! \phi q \vec{u} \cdot \vec{n}
    \, \mathrm{d} s
    + \int_{\Gamma_\mathrm{int}} \! (\phi_+ \vec{u} \cdot \vec{n}_+ +
      \phi_- \vec{u} \cdot \vec{n}_-) \widetilde{q} \, \mathrm{d} S
    \quad = \quad
-   -\int_{\Gamma_\rlap{\mathrm{ext, inflow}}} \phi q_\mathrm{in} \vec{u} \cdot
+   -\int_{\Gamma_{\mathrlap{\mathrm{ext, inflow}}}} \phi q_\mathrm{in} \vec{u} \cdot
    \vec{n} \, \mathrm{d} s \quad \forall \ \phi \in V,
 
 We will take the domain :math:`\Omega` to be the cuboid
@@ -147,4 +147,4 @@ We finally compare our solution to the expected solution: ::
   assert max(abs(out.dat.data - exact.dat.data)) < 1e-10
 
 This demo can be found as a script in
-`extruded_continuity.py <extruded_continuity.py>`__.
+:demo:`extruded_continuity.py <extruded_continuity.py>`.