WIP: Modern practice section

doc/source/P1_poisson.rst

@@ -0,0 +1,66 @@
+.. default-role:: math
+
+.. _poisson:
+
+Revisiting the Poisson problem
+==============================
+
+As well as being an independent field of academic study, the finite
+element method plays an important supporting role for solving boundary value
+problems in the context of scientific enquiry and engineering design. 
+
+It is therefore important to recognise that most users (scientists,
+mathematicians, engineers etc.) of finite element methods are not hugely
+interested in the underlying mathematics or implementation, but in actually
+solving their own problems!
+
+Since its inception in the 1960s specialists in finite elements have written an
+almost uncountable number of software packages for solving finite element
+problems. A small number of these have gone to underpin the now multi-billion
+dollar engineering design and analysis software sector. Packages such as
+ABAQUS, COMSOL Multiphysics and ADINA are now used everyday by hundreds of
+thousands of engineers and scientists across the globe. 
+
+These software packages offer an end-to-end finite element analysis, including
+computer-aided design tools, advanced mesh creation capabilities, finite
+element solution, post-processing and visualisation. Their focus is primarily
+on ease-of-use and robustness. They can solve a pre-defined set of PDEs that
+the user can select from, for example the heat equation, or linear elasticity.
+Customising the PDE and its discretisation usually requires writing a 'user
+element' in a low-level language like C or FORTRAN. Users have little control
+or insight into the precise solution algorithms used, and cannot easily move
+beyond the capabilities that are provided. Most are closed-source, meaning that
+users cannot access or modify the underlying source code. Users with highly
+specific and uncommon problems usually still need to 'code their own', as we
+did in the implementation exercise.
+
+In the last decade a new kind of finite element software relying on automatic
+code generation techniques has emerged. This type of software is aimed at
+engineers, academics and scientists who need to go beyond what fixed
+functionality software described above can provide. Two examples are the FEniCS
+Project and Firedrake that are written and maintained by groups of academics
+and engineers worldwide, including the authors of these notes.
+
+Although these two packages differ in the details, they share the following key
+points:
+
+.. list:
+   * That the variational formulation of a finite element problem can be
+     written in a high-level programming language that closely resembles
+     mathematics as it is on written on the page.
+   * That this high-level representation of a finite element problem can be
+     automatically translated into highly performant computer code that can run
+     on a variety of computer platforms, from laptops to high-performance
+     computers.
+   * That this way of implementing finite element solvers is not only flexible,
+     fast and less error-prone than writing your own from scratch, but can
+     actually be quite fun!
+
+To make a link with what you have already learned in the previous part of the
+course, we will begin by solving the Poisson problem in either FEniCSx or
+Firedrake, depending on the preferences of your instructor. Please click on the
+appropriate link below to access the Python Jupyter Notebook in the Google Colab
+environment:
+
+`Poisson in DOLFINx
+<https://githubtocolab.com/jhale/finite-element-course/blob/jhale/unilu-course/doc/source/notebooks/dolfinx/poisson.ipynb>`__

doc/source/conf.py

@@ -56,7 +56,7 @@
 
 # General information about the project.
 project = u'Finite element course'
-copyright = u'2014-2021, David A. Ham and Colin J. Cotter'
+copyright = u'2014-2022, David A. Ham, Colin J. Cotter and Jack S. Hale'
 
 mathjax_path = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 
@@ -65,9 +65,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2021.0'
+version = '2022.0'
 # The full version, including alpha/beta/rc tags.
-release = '2021.0'
+release = '2022.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -230,8 +230,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'Finiteelementcourse.tex', u'Finite Elements: Analysis and Implementation',
-   u'David A. Ham and Colin J. Cotter', 'manual'),
+  ('index', 'Finiteelementcourse.tex', u'Numerical Methods for Variational Problems',
+   u'David A. Ham, Colin J. Cotter and Jack S. Hale', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -277,7 +277,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'Finiteelementcourse', u'Finite element course Documentation',
-   u'David A. Ham and Colin J. Cotter', 'Finiteelementcourse', 'A masters level finite element course in the Department of Mathematics at Imperial College London',
+   u'David A. Ham, Colin J. Cotter and Jack S. Hale', 'Finiteelementcourse', 'A masters level finite element course in the Department of Mathematics at University of Luxemourg',
    'Miscellaneous'),
 ]
 

doc/source/implementation.rst

@@ -20,27 +20,30 @@ feedback in weeks 4 and 7.
 Formalities and marking scheme
 ------------------------------
 
-The implementation exercise is due at 1300 on Monday 20 March 2023. Submission
-is via GitHub: the last commit pushed to GitHub and dated before the deadline
-will be marked.
+The implementation exercise is due immediately prior to the Summer Semester
+study days/revision period. That is, by 1600 on Friday 2 June 2023. You must
+submit your work by emailing [email protected] the link to your GitHub
+repository and the git hash you are submitting. You can conveniently :ref:`find
+this hash on the commits page for your repository on GitHub <fons:git-hash>`.
+The commit you submit must date from before the deadline!
 
 The marking scheme will be as follows:
 
-First/distinction (70-100)  
+Excellent (18-20)  
   All parts of the implementation are correct and all tests pass. The
   code style is always very clear and the implementation of every
   exercise is transparent and elegant.
-Upper second/merit (60-70)
+Good (14-17)
   The implementation is correct but let down somewhat by poor coding
   style. Alternatively, submissions which are correct and well
   written up to and including solving the Helmholtz problem but
   which do not include a correct solution to boundary conditions will
   earn an upper second.
-Lower second/pass (50-60)
+Pass (10-13)
   There are significant failings in the implementation resulting in
   many test failures, and/or the coding style is
   sufficiently poor that the code is hard to understand.
-Fail (0-50)
+Fail (0-9)
   The implementation is substantially incomplete. Correct
   implementations may have been provided for some of the earlier exercises but
   the more advanced parts of the implementation exercise have not been
@@ -54,14 +57,6 @@ possible. The result is that examples that should run in seconds and take
 megabytes of memory instead take gigabytes of memory and many hours to complete.
 Such submissions are incorrect, and will be marked as such.
 
-Extension (mastery) exercise
-----------------------------
-
-Fourth year and masters students must also complete the mastery
-exercise, which is :numref:`mixed` This will be
-worth 20% of the implementation exercise marks and will be marked on
-the same scheme as above.   
-
 Obtaining the skeleton code
 ---------------------------
 
@@ -282,7 +277,7 @@ raising an issue <pop:issue-report>`.
 
     Please don't post large pieces of code to Piazza. Just post minimal examples
     if they help. However always commit and push your work, and post the
-    :ref:`git commit hash <fons:git-hash>` in the repository. The lecturer can
+    :ref:`git commit hash <fons:git-hash>` in the repository. The instructor can
     always find your work from the git hash, so long as you've pushed to GitHub.
 
 Tips and tricks for the implementation exercise

doc/source/index.rst

@@ -1,7 +1,7 @@
 .. only:: latex
 
    ============================================
-   Finite elements, analysis and implementation
+   Numerical Methods for Variational problems
    ============================================
 
    .. raw:: latex
@@ -25,14 +25,17 @@
 
 .. only:: html
 
-   This is the webpage for the `Imperial College London Mathematics
-   <http://www.imperial.ac.uk/maths>`__  module MATH60022/MATH70022 Finite
-   Elements: numerical analysis and implementation. There's an introductory
-   video explaining what the module is about `online here
-   <https://player.vimeo.com/video/426777950?autoplay=1>`__.
+   This is the webpage for the `University of Luxembourg Master in Mathematics
+   <https://wwwen.uni.lu/studies/fstm/master_in_mathematics/programme2>`__  course
+   Numerical Methods for Variational Problems.
 
-   Other people are welcome to make use of the
-   material here. The authors welcome feedback and would particularly
+   This webpage is adapted with permission from the `original
+   <https://finite-element.github.io>`__ authored by Prof. Colin
+   Cotter and Dr. David Ham at Imperial College London. The section on Modern
+   Finite Element practice was authored by Dr. Jack S. Hale at the University
+   of Luxembourg.
+
+   The authors welcome feedback and would particularly
    appreciate an `email <mailto:[email protected]>`__ if this
    material is used to teach anywhere.
 
@@ -44,8 +47,10 @@
    ---------------
 
    The numerical analysis and implementation parts of the module run in
-   parallel. Each has videos and exercises embedded in its notes. This table
-   indicates the progress that you should make through each component each week.
+   parallel. The modern practice part of the module will take place after the
+   numerical analysis and implementation parts. Each part has videos and
+   exercises embedded in its notes. This table indicates the progress that you
+   should make through each component each week.
 
    .. list-table::
         :widths: 10 45 45
@@ -59,35 +64,34 @@
               {number}<def-robin>`.
             - Do the background tutorials and installation work given under
               :doc:`tools` and :doc:`implementation`.
-        *   - 2
+        *   - 3
             - Up to and including :numref:`Exercise
               {number}<exe-1d-lagrange-basis>`.
             - Up to the end of :numref:`quadrature`.
-        *   - 3
+        *   - 5
             - Up to and including :numref:`Definition {number}<P1unisolve>`.
             - Up to and including :numref:`Exercise {number}<ex-vandermonde>`.
-        *   - 4
+        *   - 7
             - Up to and including :numref:`Exercise {number}<exer-argyris>`.
             - Up to and including :numref:`Exercise {number}<ex-tabulate>`.
-        *   - 5
+        *   - 9
             - Up to and including :numref:`Definition
               {number}<def-averaged-taylor>`.
             - Up to the end of :numref:`secfinitelement`.
-        *   - 6
+        *   - 11
             - Up to and including :numref:`Lemma {number}<IerrK1>`.
             - Up to and including :numref:`Exercise {number}<ex-local>`.
-        *   - 7
+        *   - 13
             - Up to and including :numref:`Exercise {number}<exe-pure-neumann>`.
             - Up to the end of :numref:`secfunctionspaces`.
-        *   - 8
+        *   - 15
             - Up to the end of :numref:`fe_problems`.
             - Up to the end of :numref:`secfunctions`.
-        *   - 9
+        *   - 16
             - Up to and including :numref:`Theorem {number}<thm-cea>`.
             - Up to the end of :numref:`secdirichlet`.
-        *   - 10
-            - Up to the end of :numref:`convergence`. For MSc, 4th year MSci
-	      and MRes students - read the mastery material.
+        *   - 16
+            - Up to the end of :numref:`convergence`.
             - Time for the mastery exercise, (catch up time for year 3).
 
    .. image:: _static/brenner_scott.png
@@ -99,17 +103,14 @@
 
    Part 1: Numerical analysis
    --------------------------
-
-   The theory  part of
-   the module will be led by `Prof. Colin Cotter
-   <http://www.imperial.ac.uk/people/colin.cotter>`__. The material is presented
-   by means of a set of lecture notes, with lecture videos interspersed in the
-   notes. 
+
+   The material is presented by means of a set of lecture notes, with lecture
+   videos interspersed in the notes. 
 
    The text for this part of the module is Brenner and Scott *The
-   Mathematical Theory of Finite Element Methods*. Imperial College has
-   fortunately paid for PDF access to this book, so it is accessible from
-   the Imperial College network at `Springer Link
+   Mathematical Theory of Finite Element Methods*. The University of Luxembourg has
+   paid for PDF access to this book, so it is accessible from
+   the University of Luxembourg network at `Springer Link
    <http://link.springer.com/book/10.1007%2F978-0-387-75934-0>`__.
 
    However, this course has the material rearranged to synchronise the
@@ -132,21 +133,20 @@
 
    Past exam papers
    ~~~~~~~~~~~~~~~~
-   Please note that for 2015-2018, there was no mastery component in the
-   examination, and so there were four questions. From 2019 on there are
-   four questions plus one mastery question for 4th year/Masters credits.
-   The topic of the Mastery question in 2022 will be the same as the topic
-   of the Mastery question in 2021, i.e. finite element methods for
-   Stokes equations. The topic was different in previous years. 
+   Past examination papers from the Imperial College London course are available here:
 
    * `2015 exam paper <_static/FE2015-exam-revised.pdf>`__ and `solutions <_static/FE2015-exam-soln.pdf>`__
    * `2016 exam paper <_static/FE2016-exam.pdf>`__ and `solutions <_static/FE2016-exam-soln.pdf>`__
    * `2017 exam paper <_static/FEExam-2017.pdf>`__ and `solutions <_static/FEExam-2017-soln.pdf>`__
    * `2018 exam paper <_static/FEExam-2018.pdf>`__ and `solutions <_static/FEExam-2018-soln.pdf>`__
    * `2019 exam paper <_static/FEExam-2019.pdf>`__ and `solutions <_static/FEExam-2019-solns.pdf>`__
+   * `revision checklist <_static/revision-checklist.pdf>`__
    * `2020 exam paper <_static/FEExam-2020.pdf>`__ and `solutions <_static/FEExam-2020-solns.pdf>`__
    * `2021 exam paper <_static/FEExam-2021.pdf>`__ and `solutions <_static/FEExam-2021-solns.pdf>`__
    * `revision checklist  <_static/revision-checklist.pdf>`__
+
+   The examination at the University of Luxembourg will be adapted to the
+   specific needs of the students attending the course.
 
 .. only:: html
 
@@ -157,8 +157,7 @@
     deeper understanding of the finite element method through writing
     software to solve finite element problems in one and two dimensions.
 
-    This part of the module will be taught by `Dr David Ham
-    <http://www.imperial.ac.uk/people/david.ham>`__. The key to this part of the
+    The key to this part of the
     module is to build up a working finite element implementation over the course
     of the term, and thereby to gain a practical understanding of the method.
 
@@ -206,3 +205,26 @@
    8_nonlinear_problems
    9_mixed_problems
    zbibliography
+
+.. only:: html
+
+   Part 3: Modern practice
+   -----------------------
+
+   The modern practice part of the module will close the gap between the
+   theoretical and implementation aspects of the finite element method outlined
+   in parts 1 and 2, and the finite element method as an active topic of
+   research and a key tool of modern scientific and engineering investigation.
+
+   The starting point will be a gentle introduction to the open source DOLFINx
+   or Firedrake software systems for the automatic solution of PDEs using the
+   finite element method.
+
+   This section of the course will be shown as Python Jupyter Notebooks run on
+   the Google Colab cloud computing environment. A Google account is required.
+
+.. toctree::
+   :numbered
+   :maxdepth: 2
+
+   P1_poisson

doc/source/notebooks/dolfinx/.gitignore

@@ -0,0 +1,2 @@
+*.h5
+*.xdmf

doc/source/notebooks/dolfinx/.isort.cfg

@@ -0,0 +1,6 @@
+[settings]
+src_paths = ["demo", "dolfinx", "dolfinx_utils", "test"]
+known_first_party = basix,dolfinx_utils,dolfinx,ffcx,ufl
+known_third_party = gmsh,numpy,pytest
+known_mpi = mpi4py,petsc4py
+sections=FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,MPI,LOCALFOLDER