Small doc fixes (#499)

* A small shift in notation

* Docs: Clarify ex2-surface mathematical description

* Refactor \boldsymbol -> \bm

* Refactor \mathbf -> \bm

* Sphinx: clear html_static_path

This is needed to avoid the 'html_static_path entry '_static' does not exist' warning

readthedocs/readthedocs.org#1776

* Fix some incosistencies

* Invert inner products (u,v) -> (v,u)

* Add SVG figure for coordinates on the sphere

* doc: use dirhtml on readthedocs

* Improve caption of sphere coords figure

* Add reference to figure in the bps on the cubed-sphere section

Co-authored-by: Jed Brown <[email protected]>

Author: valeriabarra

.readthedocs.yml

@@ -6,6 +6,7 @@ version: 2
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
+  builder: dirhtml
   configuration: doc/sphinx/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub

doc/img/SphereSketch.svg

@@ -15,42 +15,42 @@ of computational device types (selectable at run time). We present here the nota
 and the mathematical formulation adopted in libCEED.
 
 We start by considering the discrete residual :math:`F(u)=0` formulation
-in weak form. We first define the :math:`L^2` inner product
+in weak form. We first define the :math:`L^2` inner product between real-valued functions
 
 .. math::
-   \langle u, v \rangle = \int_\Omega u v d \mathbf{x},
+   \langle v, u \rangle = \int_\Omega v u d \bm{x},
 
-where :math:`d \mathbf{x} \in \mathbb{R}^d \supset \Omega`.
+where :math:`\bm{x} \in \mathbb{R}^d \supset \Omega`.
 
 We want to find :math:`u` in a suitable space :math:`V_D`,
 such that
 
 .. math::
-   \langle v, f(u) \rangle = \int_\Omega v \cdot f_0 (u, \nabla u) + \nabla v : f_1 (u, \nabla u) = 0
+   \langle  \bm v,  \bm f(u) \rangle = \int_\Omega  \bm v \cdot  \bm f_0 (u, \nabla u) + \nabla \bm v :  \bm f_1 (u, \nabla u) = 0
    :label: residual
 
-for all :math:`v` in the corresponding homogeneous space :math:`V_0`, where :math:`f_0`
-and :math:`f_1` contain all possible sources in the problem. We notice here that
-:math:`f_0` represents all terms in :math:numref:`residual` which multiply the test
-function :math:`v` and :math:`f_1` all terms which multiply its gradient :math:`\nabla v`.
-For an n-component problems in :math:`d` dimensions, :math:`f_0 \in \mathbb{R}^n` and
-:math:`f_1 \in \mathbb{R}^{nd}`.
+for all :math:`\bm v` in the corresponding homogeneous space :math:`V_0`, where :math:`\bm f_0`
+and :math:`\bm f_1` contain all possible sources in the problem. We notice here that
+:math:`\bm f_0` represents all terms in :math:numref:`residual` which multiply the (possibly vector-valued) test
+function :math:`\bm v` and :math:`\bm f_1` all terms which multiply its gradient :math:`\nabla \bm v`.
+For an n-component problems in :math:`d` dimensions, :math:`\bm f_0 \in \mathbb{R}^n` and
+:math:`\bm f_1 \in \mathbb{R}^{nd}`.
 
 .. note::
-   The notation :math:`\nabla \boldsymbol v \!:\! f_1` represents contraction over both
+   The notation :math:`\nabla \bm v \!:\! \bm f_1` represents contraction over both
    fields and spatial dimensions while a single dot represents contraction in just one,
-   which should be clear from context, e.g., :math:`v \cdot f_0` contracts only over
+   which should be clear from context, e.g., :math:`\bm v \cdot \bm f_0` contracts only over
    fields.
 
 .. note::
    In the code, the function that represents the weak form at quadrature
    points is called the :ref:`CeedQFunction`. In the :ref:`Examples` provided with the
-   library (in the :file:`examples/` directory), we store the term :math:`f_0` directly
-   into `v`, and the term :math:`f_1` directly into `dv` (which stands for
-   :math:`\nabla v`). If equation :math:numref:`residual` only presents a term of the
-   type :math:`f_0`, the :ref:`CeedQFunction` will only have one output argument,
+   library (in the :file:`examples/` directory), we store the term :math:`\bm f_0` directly
+   into `v`, and the term :math:`\bm f_1` directly into `dv` (which stands for
+   :math:`\nabla \bm v`). If equation :math:numref:`residual` only presents a term of the
+   type :math:`\bm f_0`, the :ref:`CeedQFunction` will only have one output argument,
    namely `v`. If equation :math:numref:`residual` also presents a term of the type
-   :math:`f_1`, then the :ref:`CeedQFunction` will have two output arguments, namely,
+   :math:`\bm f_1`, then the :ref:`CeedQFunction` will have two output arguments, namely,
    `v` and `dv`.
 
 

doc/sphinx/source/FEMtheory.rst.inc

@@ -130,7 +130,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

doc/sphinx/source/conf.py

@@ -20,9 +20,9 @@ find :math:`u \in V^p` such that for all :math:`v \in V^p`
 .. math::
    :label: eq-general-weak-form
 
-   \langle u,v \rangle = \langle f,v \rangle ,
+   \langle v,u \rangle = \langle v,f \rangle ,
 
-where :math:`\langle u,v\rangle` and :math:`\langle f,v\rangle` express the continuous
+where :math:`\langle v,u\rangle` and :math:`\langle v,f\rangle` express the continuous
 bilinear and linear forms, respectively, defined on :math:`V^p`, and, for sufficiently
 regular :math:`u`, :math:`v`, and :math:`f`, we have:
 
@@ -50,13 +50,13 @@ into :math:numref:`eq-general-weak-form`, we obtain the inner-products
 .. math::
    :label: eq-inner-prods
 
-   \langle v,u \rangle = \bm v^T M \bm u , \qquad  \langle f,v\rangle =  \bm v^T \bm b \,.
+   \langle v,u \rangle = \bm v^T M \bm u , \qquad  \langle v,f\rangle =  \bm v^T \bm b \,.
 
 Here, we have introduced the mass matrix, :math:`M`, and the right-hand side,
 :math:`\bm b`,
 
 .. math::
-   M_{ij} :=  (\phi_i,\phi_j), \;\; \qquad b_{i} :=  \langle f, \phi_i \rangle,
+   M_{ij} :=  (\phi_i,\phi_j), \;\; \qquad b_{i} :=  \langle \phi_i, f \rangle,
 
 each defined for index sets :math:`i,j \; \in \; \{1,\dots,n\}`.
 
@@ -70,9 +70,9 @@ The Laplace's operator used in BP3-BP6 is defined via the following variational
 formulation, i.e., find :math:`u \in V^p` such that for all :math:`v \in V^p`
 
 .. math::
-   a(u,v) = \langle f,v \rangle , \,
+   a(v,u) = \langle v,f \rangle , \,
 
-where now :math:`a (u,v)` expresses the continuous bilinear form defined on
+where now :math:`a (v,u)` expresses the continuous bilinear form defined on
 :math:`V^p` for sufficiently regular :math:`u`, :math:`v`, and :math:`f`, that is:
 
 .. math::

doc/sphinx/source/libCEEDapi.rst

@@ -13,25 +13,27 @@ Ex1-Volume
 
 This example is located in the subdirectory :file:`examples/ceed`. It illustrates a
 simple usage of libCEED to compute the volume of a given body using a matrix-free
-application of the mass operator. Arbitrary mesh and solution orders in 1D, 2D and 3D
+application of the mass operator. Arbitrary mesh and solution orders in 1D, 2D, and 3D
 are supported from the same code.
 
 This example shows how to compute line/surface/volume integrals of a 1D, 2D, or 3D
 domain :math:`\Omega` respectively, by applying the mass operator to a vector of
-:math:`\mathbf{1}`\s. It computes:
+:math:`1`\s. It computes:
 
 .. math::
-   I = \int_{\Omega} \mathbf{1} \, dV .
+   I = \int_{\Omega} 1 \, dV .
    :label: eq-ex1-volume
 
 Using the same notation as in :ref:`Theoretical Framework`, we write here the vector
-:math:`u(\mathbf{x})\equiv \mathbf{1}` in the Galerkin approximation,
+:math:`u(x)\equiv 1` in the Galerkin approximation,
 and find the volume of :math:`\Omega` as
 
 .. math::
-   \sum_e \int_{\Omega_e} v(x) \cdot \mathbf{1} \, dV
+   :label: volume-sum
 
-with :math:`v(x) \in \mathcal{V}_p = \{ v \in H^{1}(\Omega_e) \,|\, v \in P_p(\boldsymbol{I}), e=1,\ldots,N_e \}`,
+   \sum_e \int_{\Omega_e} v(x) 1 \, dV
+
+with :math:`v(x) \in \mathcal{V}_p = \{ v \in H^{1}(\Omega_e) \,|\, v \in P_p(\bm{I}), e=1,\ldots,N_e \}`,
 the test functions.
 
 
@@ -42,25 +44,27 @@ Ex2-Surface
 
 This example is located in the subdirectory :file:`examples/ceed`. It computes the
 surface area of a given body using matrix-free application of a diffusion operator.
-Arbitrary mesh and solution orders in 1D, 2D and 3D are supported from the same code.
-
-Similarly to :ref:`Ex1-Volume`, it computes:
+Similar to :ref:`Ex1-Volume`, arbitrary mesh and solution orders in 1D, 2D, and 3D
+are supported from the same code. It computes:
 
 .. math::
-   I = \int_{\partial \Omega} \mathbf{1} \, dS .
+   I = \int_{\partial \Omega} 1 \, dS ,
    :label: eq-ex2-surface
 
-but this time by applying the divergence theorem using a Laplacian.
+by applying the divergence theorem.
 In particular, we select :math:`u(\bm x) = x_0 + x_1 + x_2`, for which :math:`\nabla u = [1, 1, 1]^T`, and thus :math:`\nabla u \cdot \hat{\bm n} = 1`.
 
 Given Laplace's equation,
 
 .. math::
-   -\nabla \cdot \nabla u = 0, \textrm{ for  } \mathbf{x} \in \Omega
+   \nabla \cdot \nabla u = 0, \textrm{ for  } \bm{x} \in \Omega
 
-multiply by a test function :math:`v` and integrate by parts to obtain
+let us multiply by a test function :math:`v` and integrate by parts to obtain
 
 .. math::
     \int_\Omega \nabla v \cdot \nabla u \, dV - \int_{\partial \Omega} v \nabla u \cdot \hat{\bm n}\, dS = 0 .
 
-Since we have chosen :math:`u` such that the boundary integrand is :math:`v 1`, we may evaluate the surface integral by applying the volumetric Laplacian and summing the result.
+Since we have chosen :math:`u` such that :math:`\nabla u \cdot \hat{\bm n} = 1`, the boundary integrand is :math:`v 1 \equiv v`. Hence, similar to :math:numref:`volume-sum`, we can evaluate the surface integral by applying the volumetric Laplacian as follows
+
+.. math::
+   \int_\Omega \nabla v \cdot \nabla u \, dV \approx \sum_e \int_{\partial \Omega_e} v(x) 1 \, dS .