Merge pull request #418 from tlm-adjoint/jrmaddison/docs

FEniCS/Firedrake backends: Documentation updates

docs/source/conf.py

@@ -15,7 +15,8 @@
                   "*/firedrake/__init__.py",
                   "*/firedrake/backend.py",
                   "*/firedrake/backend_code_generator_interface.py",
-                  "*/firedrake/backend_overrides.py"]
+                  "*/firedrake/backend_overrides.py",
+                  "*/override.py"]
 autoapi_add_toctree_entry = False
 autoapi_options = []
 

tlm_adjoint/fenics/backend_interface.py

@@ -261,17 +261,17 @@ def _is_alias(self):
 
 
 class Function(backend_Function):
-    """Extends the backend `Function` class.
+    """Extends the DOLFIN `Function` class.
 
-    :arg space_type: The space type for the :class:`Function`. `'primal'`,
+    :arg space_type: The space type for the :class:`.Function`. `'primal'`,
         `'dual'`, `'conjugate'`, or `'conjugate_dual'`.
-    :arg static: Defines whether the :class:`Function` is static, meaning that
+    :arg static: Defines whether the :class:`.Function` is static, meaning that
         it is stored by reference in checkpointing/replay, and an associated
         tangent-linear variable is zero.
-    :arg cache: Defines whether results involving the :class:`Function` may be
+    :arg cache: Defines whether results involving the :class:`.Function` may be
         cached. Default `static`.
 
-    Remaining arguments are passed to the backend `Function` constructor.
+    Remaining arguments are passed to the DOLFIN `Function` constructor.
     """
 
     def __init__(self, *args, space_type="primal", static=False, cache=None,
@@ -288,9 +288,9 @@ def __init__(self, *args, space_type="primal", static=False, cache=None,
 
 
 class ZeroFunction(Function, Zero):
-    """A :class:`Function` which is flagged as having a value of zero.
+    """A :class:`.Function` which is flagged as having a value of zero.
 
-    Arguments are passed to the :class:`Function` constructor, together with
+    Arguments are passed to the :class:`.Function` constructor, together with
     `static=True` and `cache=True`.
     """
 
@@ -374,12 +374,12 @@ def subtract_adjoint_derivative_action_backend_constant_vector(x, alpha, y):
 
 
 def to_fenics(y, space, *, name=None):
-    """Convert a variable to a FEniCS `Function`.
+    """Convert a variable to a DOLFIN `Function`.
 
     :arg y: A variable.
     :arg space: The space for the return value.
     :arg name: A :class:`str` name.
-    :returns: The FEniCS `Function`.
+    :returns: The DOLFIN `Function`.
     """
 
     x = Function(space, space_type=var_space_type(y), name=name)

tlm_adjoint/fenics/caches.py

@@ -301,7 +301,7 @@ def assemble_key(form, bcs, assemble_kwargs):
 
 
 class AssemblyCache(Cache):
-    """A :class:`tlm_adjoint.caches.Cache` for finite element assembly data.
+    """A :class:`.Cache` for finite element assembly data.
     """
 
     def assemble(self, form, *,
@@ -319,8 +319,7 @@ def assemble(self, form, *,
             variables to values.
         :returns: A :class:`tuple` `(value_ref, value)`, where `value` is the
             result of the finite element assembly, and `value_ref` is a
-            :class:`tlm_adjoint.caches.CacheRef` storing a reference to
-            `value`.
+            :class:`.CacheRef` storing a reference to `value`.
 
                 - For an arity zero or arity one form `value_ref` stores the
                   assembled value.
@@ -378,7 +377,7 @@ def linear_solver_key(form, bcs, linear_solver_parameters,
 
 
 class LinearSolverCache(Cache):
-    """A :class:`tlm_adjoint.caches.Cache` for linear solver data.
+    """A :class:`.Cache` for linear solver data.
     """
 
     def linear_solver(self, form, *,
@@ -394,16 +393,15 @@ def linear_solver(self, form, *,
         :arg linear_solver_parameters: Linear solver parameters.
         :arg replace_map: A :class:`Mapping` defining a map from symbolic
             variables to values.
-        :arg assembly_cache: :class:`AssemblyCache` to use for finite element
+        :arg assembly_cache: :class:`.AssemblyCache` to use for finite element
             assembly. Defaults to `assembly_cache()`.
         :returns: A :class:`tuple` `(value_ref, value)`. `value` is a tuple
             `(solver, A, b_bc)`, where `solver` is the linear solver, `A` is
             the assembled matrix, and `b_bc` is a boundary condition
             right-hand-side term which should be added after assembling a
             right-hand-side with homogeneous boundary conditions applied.
             `b_bc` may be `None` to indicate that this term is zero.
-            `value_ref` is a :class:`tlm_adjoint.caches.CacheRef` storing a
-            reference to `value`.
+            `value_ref` is a :class:`.CacheRef` storing a reference to `value`.
         """
 
         if bcs is None:
@@ -441,16 +439,16 @@ def value():
 
 def assembly_cache():
     """
-    :returns: The default :class:`AssemblyCache`.
+    :returns: The default :class:`.AssemblyCache`.
     """
 
     return _assembly_cache
 
 
 def set_assembly_cache(assembly_cache):
-    """Set the default :class:`AssemblyCache`.
+    """Set the default :class:`.AssemblyCache`.
 
-    :arg assembly_cache: The new default :class:`AssemblyCache`.
+    :arg assembly_cache: The new default :class:`.AssemblyCache`.
     """
 
     global _assembly_cache
@@ -462,16 +460,16 @@ def set_assembly_cache(assembly_cache):
 
 def linear_solver_cache():
     """
-    :returns: The default :class:`LinearSolverCache`.
+    :returns: The default :class:`.LinearSolverCache`.
     """
 
     return _linear_solver_cache
 
 
 def set_linear_solver_cache(linear_solver_cache):
-    """Set the default :class:`LinearSolverCache`.
+    """Set the default :class:`.LinearSolverCache`.
 
-    :arg linear_solver_cache: The new default :class:`LinearSolverCache`.
+    :arg linear_solver_cache: The new default :class:`.LinearSolverCache`.
     """
 
     global _linear_solver_cache

tlm_adjoint/fenics/equations.py

@@ -123,7 +123,7 @@ class Assembly(ExprEquation):
 
     :arg x: A variable defining the forward solution.
     :arg rhs: A :class:`ufl.Form` to assemble. Should have arity 0 or 1, and
-        should not depend on the forward solution.
+        should not depend on `x`.
     :arg form_compiler_parameters: Form compiler parameters.
     :arg match_quadrature: Whether to set quadrature parameters consistently in
         the forward, adjoint, and tangent-linears. Defaults to
@@ -278,7 +278,7 @@ class EquationSolver(ExprEquation):
 
     :arg eq: A :class:`ufl.equation.Equation` defining the finite element
         variational problem.
-    :arg x: A `dolfin.Function` defining the forward solution.
+    :arg x: A DOLFIN `Function` defining the forward solution.
     :arg bcs: Dirichlet boundary conditions.
     :arg J: A :class:`ufl.Form` defining a Jacobian matrix approximation to use
         in a non-linear forward solve.
@@ -756,17 +756,14 @@ def expr_new_x(expr, x, *,
 
 def linear_equation_new_x(eq, x, *,
                           annotate=None, tlm=None):
-    """If a symbolic expression for a linear finite element variational
-    problem depends on the symbolic variable representing the problem solution,
+    """If a symbolic expression for a linear finite element variational problem
+    depends on the symbolic variable representing the problem solution `x`,
     then record the assignment `x_old = x`, and replace `x` with `x_old` in the
     symbolic expression.
 
-    Required for the case where a 'new' value is computed by solving a linear
-    finite element variational problem depending on the 'old' value.
-
     :arg eq: A :class:`ufl.equation.Equation` defining the finite element
         variational problem.
-    :arg x: A `dolfin.Function` defining the solution to the finite element
+    :arg x: A DOLFIN `Function` defining the solution to the finite element
         variational problem.
     :arg annotate: Whether the :class:`.EquationManager` should record the
         solution of equations.
@@ -794,7 +791,7 @@ class Projection(EquationSolver):
     """Represents the solution of a finite element variational problem
     performing a projection onto the space for `x`.
 
-    :arg x: A `dolfin.Function` defining the forward solution.
+    :arg x: A DOLFIN `Function` defining the forward solution.
     :arg rhs: A :class:`ufl.core.expr.Expr` defining the expression to project
         onto the space for `x`, or a :class:`ufl.Form` defining the
         right-hand-side of the finite element variational problem. Should not
@@ -814,7 +811,7 @@ def __init__(self, x, rhs, *args, **kwargs):
 
 class DirichletBCApplication(Equation):
     r"""Represents the application of a Dirichlet boundary condition to a zero
-    valued `dolfin.Function`. Specifically this represents:
+    valued DOLFIN `Function`. Specifically this represents:
 
     .. code-block:: python
 
@@ -825,10 +822,10 @@ class DirichletBCApplication(Equation):
     The forward residual :math:`\mathcal{F}` is defined so that :math:`\partial
     \mathcal{F} / \partial x` is the identity.
 
-    :arg x: A `dolfin.Function`, updated by the above operations.
-    :arg y: A `dolfin.Function`, defines the Dirichet boundary condition.
+    :arg x: A DOLFIN `Function`, updated by the above operations.
+    :arg y: A DOLFIN `Function`, defines the Dirichet boundary condition.
 
-    Remaining arguments are passed to `dolfin.DirichletBC`.
+    Remaining arguments are passed to the DOLFIN `DirichletBC` constructor.
     """
 
     def __init__(self, x, y, *args, **kwargs):

tlm_adjoint/fenics/fenics_equations.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-"""This module includes functionality for use with the tlm_adjoint FEniCS
-backend.
+"""This module includes additional functionality for use with FEniCS.
 """
 
 from .backend import (
@@ -214,7 +213,7 @@ def local_solver(self, form, solver_type=None, *,
         :arg replace_map: A :class:`Mapping` defining a map from symbolic
             variables to values.
         :returns: A :class:`tuple` `(value_ref, value)`. `value` is a
-            `dolfin.LocalSolver` and `value_ref` is a :class:`.CacheRef`
+            DOLFIN `LocalSolver` and `value_ref` is a :class:`.CacheRef`
             storing a reference to `value`.
         """
 
@@ -263,7 +262,7 @@ class LocalProjection(EquationSolver):
     performing a projection onto the space for `x`, for the case where the mass
     matrix is element-wise local block diagonal.
 
-    :arg x: A `dolfin.Function` defining the forward solution.
+    :arg x: A DOLFIN `Function` defining the forward solution.
     :arg rhs: A :class:`ufl.core.expr.Expr` defining the expression to project
         onto the space for `x`, or a :class:`ufl.Form` defining the
         right-hand-side of the finite element variational problem. Should not
@@ -486,17 +485,18 @@ class Interpolation(LinearEquation):
     between owned and non-owned nodes in the degree of freedom graph associated
     with the discrete function space for `y`.
 
-    :arg x: A scalar-valued `dolfin.Function` defining the forward solution.
-    :arg y: A scalar-valued `dolfin.Function` to interpolate onto the space for
+    :arg x: A scalar-valued DOLFIN `Function` defining the forward solution.
+    :arg y: A scalar-valued DOLFIN `Function` to interpolate onto the space for
         `x`.
     :arg X_coords: A :class:`numpy.ndarray` defining the coordinates at which
         to interpolate `y`. Shape is `(n, d)` where `n` is the number of
         process local degrees of freedom for `x` and `d` is the geometric
         dimension. Defaults to the process local degree of freedom locations
         for `x`. Ignored if `P` is supplied.
     :arg P: The interpolation matrix. A :class:`scipy.sparse.spmatrix`.
-    :arg tolerance: Maximum permitted distance of an interpolation point from
-        a cell in the mesh for `y`. Ignored if `P` is supplied.
+    :arg tolerance: Maximum permitted distance (as returned by the DOLFIN
+        `BoundingBoxTree.compute_closest_entity` method) of an interpolation
+        point from a cell in the mesh for `y`. Ignored if `P` is supplied.
     """
 
     def __init__(self, x, y, *, x_coords=None, P=None,
@@ -547,14 +547,15 @@ class PointInterpolation(Equation):
 
     :arg X: A scalar variable, or a :class:`Sequence` of scalar variables,
         defining the forward solution.
-    :arg y: A scalar-valued `dolfin.Function` to interpolate.
+    :arg y: A scalar-valued DOLFIN `Function` to interpolate.
     :arg X_coords: A :class:`numpy.ndarray` defining the coordinates at which
         to interpolate `y`. Shape is `(n, d)` where `n` is the number of
         interpolation points and `d` is the geometric dimension. Ignored if `P`
         is supplied.
     :arg P: The interpolation matrix. A :class:`scipy.sparse.spmatrix`.
-    :arg tolerance: Maximum permitted distance of an interpolation point from
-        a cell in the mesh for `y`. Ignored if `P` is supplied.
+    :arg tolerance: Maximum permitted distance (as returned by the DOLFIN
+        `BoundingBoxTree.compute_closest_entity` method) of an interpolation
+        point from a cell in the mesh for `y`. Ignored if `P` is supplied.
     """
 
     def __init__(self, X, y, X_coords=None, *,