From c4b9d84425fc1cddbdae5aa52e373789a673307e Mon Sep 17 00:00:00 2001 From: "James R. Maddison" Date: Mon, 23 Oct 2023 16:07:44 +0100 Subject: [PATCH] Documentation updates --- docs/source/conf.py | 3 +- tlm_adjoint/fenics/backend_interface.py | 18 +++---- tlm_adjoint/fenics/caches.py | 24 ++++----- tlm_adjoint/fenics/equations.py | 23 ++++---- tlm_adjoint/fenics/fenics_equations.py | 23 ++++---- tlm_adjoint/fenics/functions.py | 52 +++++++++--------- tlm_adjoint/firedrake/block_system.py | 49 +++++++++-------- tlm_adjoint/firedrake/caches.py | 24 ++++----- tlm_adjoint/firedrake/equations.py | 11 ++-- tlm_adjoint/firedrake/firedrake_equations.py | 3 +- tlm_adjoint/firedrake/functions.py | 56 +++++++++++--------- tlm_adjoint/firedrake/hessian_system.py | 6 +-- 12 files changed, 145 insertions(+), 147 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 24458ada..16b3ffb9 100644 --- a/docs/source/conf.py +++ b/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 = [] diff --git a/tlm_adjoint/fenics/backend_interface.py b/tlm_adjoint/fenics/backend_interface.py index 23f91de4..87ec02af 100644 --- a/tlm_adjoint/fenics/backend_interface.py +++ b/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) diff --git a/tlm_adjoint/fenics/caches.py b/tlm_adjoint/fenics/caches.py index 118b251f..387bf8c1 100644 --- a/tlm_adjoint/fenics/caches.py +++ b/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,7 +393,7 @@ 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 @@ -402,8 +401,7 @@ def linear_solver(self, form, *, 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 diff --git a/tlm_adjoint/fenics/equations.py b/tlm_adjoint/fenics/equations.py index 141fd8f5..0f61082d 100644 --- a/tlm_adjoint/fenics/equations.py +++ b/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): diff --git a/tlm_adjoint/fenics/fenics_equations.py b/tlm_adjoint/fenics/fenics_equations.py index 67b0bf88..f4f0c646 100644 --- a/tlm_adjoint/fenics/fenics_equations.py +++ b/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,8 +485,8 @@ 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 @@ -495,8 +494,9 @@ class Interpolation(LinearEquation): 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, *, diff --git a/tlm_adjoint/fenics/functions.py b/tlm_adjoint/fenics/functions.py index 7c45107d..654cc371 100644 --- a/tlm_adjoint/fenics/functions.py +++ b/tlm_adjoint/fenics/functions.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -"""This module includes functionality for handling :class:`ufl.Coefficient` -objects and boundary conditions. +"""This module includes functionality for interacting with FEniCS variables +and Dirichlet boundary conditions. """ from .backend import ( @@ -254,24 +254,24 @@ def constant_value(value=None, shape=None): class Constant(backend_Constant): - """Extends the backend `Constant` class. + """Extends the DOLFIN `Constant` class. :arg value: The initial value. `None` indicates a value of zero. :arg name: A :class:`str` name. - :arg domain: The domain on which the :class:`Constant` is defined. - :arg space: The space on which the :class:`Constant` is defined. - :arg space_type: The space type for the :class:`Constant`. `'primal'`, + :arg domain: The domain on which the :class:`.Constant` is defined. + :arg space: The space on which the :class:`.Constant` is defined. + :arg space_type: The space type for the :class:`.Constant`. `'primal'`, `'dual'`, `'conjugate'`, or `'conjugate_dual'`. :arg shape: A :class:`tuple` of :class:`int` objects defining the shape of the value. - :arg comm: The communicator for the :class:`Constant`. - :arg static: Defines whether the :class:`Constant` is static, meaning that + :arg comm: The communicator for the :class:`.Constant`. + :arg static: Defines whether the :class:`.Constant` 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:`Constant` may be + :arg cache: Defines whether results involving the :class:`.Constant` may be cached. Default `static`. - Remaining arguments are passed to the backend `Constant` constructor. + Remaining arguments are passed to the DOLFIN `Constant` constructor. """ def __init__(self, value=None, *args, name=None, domain=None, space=None, @@ -332,9 +332,9 @@ def _tlm_adjoint__var_interface_update_state(self): class ZeroConstant(Constant, Zero): - """A :class:`Constant` which is flagged as having a value of zero. + """A :class:`.Constant` which is flagged as having a value of zero. - Arguments are passed to the :class:`Constant` constructor, together with + Arguments are passed to the :class:`.Constant` constructor, together with `static=True` and `cache=True`. """ @@ -378,8 +378,8 @@ def derivative(expr, x, argument=None, *, def eliminate_zeros(expr, *, force_non_empty_form=False): - """Apply zero elimination for :class:`tlm_adjoint.fenics.functions.Zero` - objects in the supplied :class:`ufl.core.expr.Expr` or :class:`ufl.Form`. + """Apply zero elimination for :class:`.Zero` objects in the supplied + :class:`ufl.core.expr.Expr` or :class:`ufl.Form`. :arg expr: A :class:`ufl.core.expr.Expr` or :class:`ufl.Form`. :arg force_non_empty_form: If `True` and if `expr` is a :class:`ufl.Form`, @@ -434,14 +434,14 @@ def eliminate_zeros(expr, *, force_non_empty_form=False): class DirichletBC(backend_DirichletBC): - """Extends the backend `DirichletBC`. + """Extends the DOLFIN `DirichletBC` class. :arg static: A flag that indicates that the value for the - :class:`DirichletBC` will not change, and which determines whether - calculations involving this :class:`DirichletBC` can be cached. If + :class:`.DirichletBC` will not change, and which determines whether + calculations involving this :class:`.DirichletBC` can be cached. If `None` then autodetected from the value. - Remaining arguments are passed to the backend `DirichletBC` constructor. + Remaining arguments are passed to the DOLFIN `DirichletBC` constructor. """ # Based on FEniCS 2019.1.0 DirichletBC API @@ -464,7 +464,7 @@ def __init__(self, V, g, sub_domain, *args, self._tlm_adjoint__homogeneous = _homogeneous def homogenize(self): - """Homogenize the :class:`DirichletBC`, setting its value to zero. + """Homogenize the :class:`.DirichletBC`, setting its value to zero. """ if self._tlm_adjoint__static: @@ -475,9 +475,9 @@ def homogenize(self): self._tlm_adjoint__homogeneous = True def set_value(self, *args, **kwargs): - """Set the :class:`DirichletBC` value. + """Set the :class:`.DirichletBC` value. - Arguments are passed to the base class `set_value` method. + Arguments are passed to the DOLFIN `DirichletBC.set_value` method. """ if self._tlm_adjoint__static: @@ -487,10 +487,10 @@ def set_value(self, *args, **kwargs): class HomogeneousDirichletBC(DirichletBC): - """A :class:`DirichletBC` whose value is zero. + """A :class:`.DirichletBC` whose value is zero. - Arguments are passed to the :class:`DirichletBC` constructor, together with - `static=True`. + Arguments are passed to the :class:`.DirichletBC` constructor, together + with `static=True`. """ # Based on FEniCS 2019.1.0 DirichletBC API @@ -602,7 +602,7 @@ def ufl_domains(self): class ReplacementConstant(Replacement): - """Represents a symbolic constant, but has no value. + """Represents a symbolic DOLFIN `Constant`, but has no value. """ def __init__(self, x): @@ -612,7 +612,7 @@ def __init__(self, x): class ReplacementFunction(Replacement): - """Represents a symbolic backend `Function`, but has no value. + """Represents a symbolic DOLFIN `Function`, but has no value. """ def function_space(self): diff --git a/tlm_adjoint/firedrake/block_system.py b/tlm_adjoint/firedrake/block_system.py index f222304d..6e670ebe 100644 --- a/tlm_adjoint/firedrake/block_system.py +++ b/tlm_adjoint/firedrake/block_system.py @@ -3,9 +3,9 @@ r"""This module implements solvers for linear systems defined in mixed spaces. -The :class:`System` class defines the block structure of the linear system, and -solves the system using an outer Krylov solver. A custom preconditioner can be -defined via the `pc_fn` callback to :meth:`System.solve`, and this +The :class:`.System` class defines the block structure of the linear system, +and solves the system using an outer Krylov solver. A custom preconditioner can +be defined via the `pc_fn` callback to :meth:`.System.solve`, and this preconditioner can itself e.g. make use of further Krylov solvers. This provides a Python interface for custom block preconditioners. @@ -15,7 +15,7 @@ A u = b, -a :class:`System` instead solves the linear problem +a :class:`.System` instead solves the linear problem .. math:: @@ -49,9 +49,9 @@ 2. Where the matrix :math:`A` is singular and :math:`b` is orthogonal to the left nullspace of :math:`A`. Typically one would then choose :math:`U` and :math:`V` so that their columns respectively span the left - nullspace and nullspace of :math:`A`, and the :class:`System` then seeks - a solution to the original problem subject to the linear constraints - :math:`V^* C u = 0`. + nullspace and nullspace of :math:`A`, and the :class:`.System` then + seeks a solution to the original problem subject to the linear + constraints :math:`V^* C u = 0`. Function spaces are defined via Firedrake function spaces, and :class:`Sequence` objects containing Firedrake function spaces or similar @@ -644,9 +644,9 @@ def pc_constraint_correct_soln(self, u, b): class BlockNullspace(Nullspace): """Nullspaces for a mixed space. - :arg nullspaces: A :class:`Nullspace` or a :class:`Sequence` of - :class:`Nullspace` objects defining the nullspace. `None` indicates a - :class:`NoneNullspace`. + :arg nullspaces: A :class:`.Nullspace` or a :class:`Sequence` of + :class:`.Nullspace` objects defining the nullspace. `None` indicates a + :class:`.NoneNullspace`. """ def __init__(self, nullspaces): @@ -749,8 +749,8 @@ def mult_add(self, x, y): class PETScMatrix(Matrix): - r"""A :class:`Matrix` associated with a :class:`petsc4py.PETSc.Mat` - :math:`A` mapping :math:`V \rightarrow W`. + r"""A :class:`tlm_adjoint.firedrake.block_system.Matrix` associated with a + :class:`petsc4py.PETSc.Mat` :math:`A` mapping :math:`V \rightarrow W`. :arg arg_space: Defines the space `V`. :arg action_space: Defines the space `W`. @@ -768,11 +768,11 @@ def mult_add(self, x, y): def form_matrix(a, *args, **kwargs): - """Construct a :class:`PETScMatrix` associated with a given sesquilinear + """Construct a :class:`.PETScMatrix` associated with a given sesquilinear form. :arg a: A :class:`ufl.Form` defining the sesquilinear form. - :returns: The :class:`PETScMatrix`. + :returns: The :class:`.PETScMatrix`. Remaining arguments are passed to the :func:`firedrake.assemble.assemble` function. @@ -793,9 +793,10 @@ class BlockMatrix(Matrix): :arg arg_spaces: Defines the space `V`. :arg action_spaces: Defines the space `W`. :arg block: A :class:`Mapping` defining the blocks of the matrix. Items are - `((i, j), block)` defining a :class:`ufl.Form` or :class:`Matrix` for - the block in row `i` and column `j`. A value for `block` of `None` - indicates a zero block. + `((i, j), block)` where the block in the `i` th and `j` th column is + defined by `block`. Each `block` is a + :class:`tlm_adjoint.firedrake.block_system.Matrix` or + :class:`ufl.Form`, or `None` to indicate a zero block. """ def __init__(self, arg_spaces, action_spaces, blocks=None): @@ -944,15 +945,17 @@ class System: :arg action_spaces: Defines the space for `b`. :arg blocks: One of - - A :class:`Matrix` or :class:`ufl.Form` defining :math:`A`. + - A :class:`tlm_adjoint.firedrake.block_system.Matrix` or + :class:`ufl.Form` defining :math:`A`. - A :class:`Mapping` with items `((i, j), block)` where the matrix associated with the block in the `i` th and `j` th column is defined - by `block`. Each `block` is a :class:`Matrix` or :class:`ufl.Form`, - or `None` to indicate a zero block. + by `block`. Each `block` is a + :class:`tlm_adjoint.firedrake.block_system.Matrix` or + :class:`ufl.Form`, or `None` to indicate a zero block. - :arg nullspaces: A :class:`Nullspace` or a :class:`Sequence` of - :class:`Nullspace` objects defining the nullspace and left nullspace of - :math:`A`. `None` indicates a :class:`NoneNullspace`. + :arg nullspaces: A :class:`.Nullspace` or a :class:`Sequence` of + :class:`.Nullspace` objects defining the nullspace and left nullspace + of :math:`A`. `None` indicates a :class:`.NoneNullspace`. :arg comm: Communicator. """ diff --git a/tlm_adjoint/firedrake/caches.py b/tlm_adjoint/firedrake/caches.py index 3cfcb598..729fa5df 100644 --- a/tlm_adjoint/firedrake/caches.py +++ b/tlm_adjoint/firedrake/caches.py @@ -298,7 +298,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, *, @@ -316,8 +316,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. @@ -375,7 +374,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, *, @@ -391,7 +390,7 @@ 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 @@ -399,8 +398,7 @@ def linear_solver(self, form, *, 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: @@ -438,16 +436,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 @@ -459,16 +457,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 diff --git a/tlm_adjoint/firedrake/equations.py b/tlm_adjoint/firedrake/equations.py index dc40c304..3e7ae8a9 100644 --- a/tlm_adjoint/firedrake/equations.py +++ b/tlm_adjoint/firedrake/equations.py @@ -120,7 +120,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 @@ -754,14 +754,11 @@ 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 :class:`firedrake.function.Function` defining the solution to the @@ -828,7 +825,7 @@ class DirichletBCApplication(Equation): :arg y: A :class:`firedrake.function.Function`, defines the Dirichet boundary condition. - Remaining arguments are pass to the :class:`firedrake.bcs.DirichletBC` + Remaining arguments are passed to the :class:`firedrake.bcs.DirichletBC` constructor. """ diff --git a/tlm_adjoint/firedrake/firedrake_equations.py b/tlm_adjoint/firedrake/firedrake_equations.py index 1692c326..86778727 100644 --- a/tlm_adjoint/firedrake/firedrake_equations.py +++ b/tlm_adjoint/firedrake/firedrake_equations.py @@ -1,8 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -"""This module includes functionality for use with the tlm_adjoint Firedrake -backend. +"""This module includes additional functionality for use with Firedrake. """ from .backend import ( diff --git a/tlm_adjoint/firedrake/functions.py b/tlm_adjoint/firedrake/functions.py index ef145744..649421fc 100644 --- a/tlm_adjoint/firedrake/functions.py +++ b/tlm_adjoint/firedrake/functions.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -"""This module includes functionality for handling :class:`ufl.Coefficient` -objects and boundary conditions. +"""This module includes functionality for interacting with Firedrake variables +and Dirichlet boundary conditions. """ from .backend import ( @@ -251,24 +251,25 @@ def constant_value(value=None, shape=None): class Constant(backend_Constant): - """Extends the backend `Constant` class. + """Extends the :class:`firedrake.constant.Constant` class. :arg value: The initial value. `None` indicates a value of zero. :arg name: A :class:`str` name. - :arg domain: The domain on which the :class:`Constant` is defined. - :arg space: The space on which the :class:`Constant` is defined. - :arg space_type: The space type for the :class:`Constant`. `'primal'`, + :arg domain: The domain on which the :class:`.Constant` is defined. + :arg space: The space on which the :class:`.Constant` is defined. + :arg space_type: The space type for the :class:`.Constant`. `'primal'`, `'dual'`, `'conjugate'`, or `'conjugate_dual'`. :arg shape: A :class:`tuple` of :class:`int` objects defining the shape of the value. - :arg comm: The communicator for the :class:`Constant`. - :arg static: Defines whether the :class:`Constant` is static, meaning that + :arg comm: The communicator for the :class:`.Constant`. + :arg static: Defines whether the :class:`.Constant` 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:`Constant` may be + :arg cache: Defines whether results involving the :class:`.Constant` may be cached. Default `static`. - Remaining arguments are passed to the backend `Constant` constructor. + Remaining arguments are passed to the :class:`firedrake.constant.Constant` + constructor. """ def __init__(self, value=None, *args, name=None, domain=None, space=None, @@ -349,9 +350,9 @@ def _tlm_adjoint__var_interface_update_state(self): class ZeroConstant(Constant, Zero): - """A :class:`Constant` which is flagged as having a value of zero. + """A :class:`.Constant` which is flagged as having a value of zero. - Arguments are passed to the :class:`Constant` constructor, together with + Arguments are passed to the :class:`.Constant` constructor, together with `static=True` and `cache=True`. """ @@ -478,8 +479,8 @@ def derivative(expr, x, argument=None, *, def eliminate_zeros(expr, *, force_non_empty_form=False): - """Apply zero elimination for :class:`tlm_adjoint.firedrake.functions.Zero` - objects in the supplied :class:`ufl.core.expr.Expr` or :class:`ufl.Form`. + """Apply zero elimination for :class:`.Zero` objects in the supplied + :class:`ufl.core.expr.Expr` or :class:`ufl.Form`. :arg expr: A :class:`ufl.core.expr.Expr` or :class:`ufl.Form`. :arg force_non_empty_form: If `True` and if `expr` is a :class:`ufl.Form`, @@ -534,14 +535,15 @@ def eliminate_zeros(expr, *, force_non_empty_form=False): class DirichletBC(backend_DirichletBC): - """Extends the backend `DirichletBC`. + """Extends the :class:`firedrake.bcs.DirichletBC` class. :arg static: A flag that indicates that the value for the - :class:`DirichletBC` will not change, and which determines whether - calculations involving this :class:`DirichletBC` can be cached. If + :class:`.DirichletBC` will not change, and which determines whether + calculations involving this :class:`.DirichletBC` can be cached. If `None` then autodetected from the value. - Remaining arguments are passed to the backend `DirichletBC` constructor. + Remaining arguments are passed to the :class:`firedrake.bcs.DirichletBC` + constructor. """ # Based on FEniCS 2019.1.0 DirichletBC API @@ -564,7 +566,7 @@ def __init__(self, V, g, sub_domain, *args, self._tlm_adjoint__homogeneous = _homogeneous def homogenize(self): - """Homogenize the :class:`DirichletBC`, setting its value to zero. + """Homogenize the :class:`.DirichletBC`, setting its value to zero. """ if self._tlm_adjoint__static: @@ -575,9 +577,9 @@ def homogenize(self): self._tlm_adjoint__homogeneous = True def set_value(self, *args, **kwargs): - """Set the :class:`DirichletBC` value. + """Set the :class:`.DirichletBC` value. - Arguments are passed to the base class `set_value` method. + Arguments are passed to :meth:`firedrake.bcs.DirichletBC.set_value`. """ if self._tlm_adjoint__static: @@ -587,10 +589,10 @@ def set_value(self, *args, **kwargs): class HomogeneousDirichletBC(DirichletBC): - """A :class:`DirichletBC` whose value is zero. + """A :class:`.DirichletBC` whose value is zero. - Arguments are passed to the :class:`DirichletBC` constructor, together with - `static=True`. + Arguments are passed to the :class:`.DirichletBC` constructor, together + with `static=True`. """ # Based on FEniCS 2019.1.0 DirichletBC API @@ -702,7 +704,8 @@ def ufl_domains(self): class ReplacementConstant(Replacement): - """Represents a symbolic constant, but has no value. + """Represents a symbolic :class:`firedrake.constant.Constant`, but has no + value. """ def __init__(self, x): @@ -712,7 +715,8 @@ def __init__(self, x): class ReplacementFunction(Replacement): - """Represents a symbolic backend `Function`, but has no value. + """Represents a symbolic :class:`firedrake.function.Function`, but has no + value. """ def function_space(self): diff --git a/tlm_adjoint/firedrake/hessian_system.py b/tlm_adjoint/firedrake/hessian_system.py index 1a2f4d7e..348d004d 100644 --- a/tlm_adjoint/firedrake/hessian_system.py +++ b/tlm_adjoint/firedrake/hessian_system.py @@ -55,8 +55,8 @@ def new_split(self): self.split_space) -# Complex note: It is convenient to define a Hessian matrix action in terms of -# the *conjugate* of the action, i.e. (H \zeta)^{*,T}, e.g. this is the form +# Complex note: It is convenient to define a Hessian action in terms of the +# *conjugate* of the action, i.e. (H \zeta)^{*,T}, e.g. this is the form # returned by reverse-over-forward AD. However complex conjugation is then # needed in a number of places (e.g. one cannot define an eigenproblem directly # in terms of the conjugate of an action, as this is antilinear, rather than @@ -109,7 +109,7 @@ class HessianSystem(System): :arg nullspace: A :class:`.Nullspace` or a :class:`Sequence` of :class:`.Nullspace` objects defining the nullspace and left nullspace of the Hessian matrix. `None` indicates a :class:`.NoneNullspace`. - :arg comm: MPI communicator. + :arg comm: A communicator. """ def __init__(self, H, M, *,