:py:mod:`tlm_adjoint.firedrake.assembly`
========================================

.. py:module:: tlm_adjoint.firedrake.assembly

.. autoapi-nested-parse::

   Finite element assembly operations with Firedrake.

   ..
       !! processed by numpydoc !!


Module Contents
---------------

.. py:class:: Assembly(x, rhs, *, form_compiler_parameters=None, match_quadrature=None)




   
   Represents assignment to the result of finite element assembly:

   .. code-block:: python

       x = assemble(rhs)

   The forward residual :math:`\mathcal{F}` is defined so that :math:`\partial
   \mathcal{F} / \partial x` is the identity.

   :arg x: A variable defining the forward solution.
   :arg rhs: A :class:`ufl.form.BaseForm`` to assemble. Should have arity 0 or
       1, and 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
       `parameters['tlm_adjoint']['Assembly']['match_quadrature']`.















   ..
       !! processed by numpydoc !!
   .. py:method:: drop_references()

      
      Drop references to variables which store values.
















      ..
          !! processed by numpydoc !!

   .. py:method:: forward_solve(x, deps=None)

      
      Compute the forward solution.

      Can assume that the currently active :class:`.EquationManager` is
      paused.

      :arg X: A variable or a :class:`Sequence` of variables storing the
          solution. May define an initial guess, and should be set by this
          method.
      :arg deps: A :class:`tuple` of variables, defining values for
          dependencies. Only the elements corresponding to `X` may be
          modified. `self.dependencies()` should be used if not supplied.















      ..
          !! processed by numpydoc !!

   .. py:method:: subtract_adjoint_derivative_actions(adj_x, nl_deps, dep_Bs)

      
      Subtract terms from other adjoint right-hand-sides.

      Can be overridden for an optimized implementation, but otherwise uses
      :meth:`.Equation.adjoint_derivative_action`.

      :arg adj_X: The adjoint solution. A variable or a :class:`Sequence` of
          variables. Should not be modified.
      :arg nl_deps: A :class:`Sequence` of variables defining values for
          non-linear dependencies. Should not be modified.
      :arg dep_Bs: A :class:`Mapping` whose items are `(dep_index, dep_B)`.
          Each `dep_B` is an :class:`.AdjointRHS` which should be updated by
          subtracting adjoint derivative information computed by
          differentiating with respect to `self.dependencies()[dep_index]`.















      ..
          !! processed by numpydoc !!

   .. py:method:: adjoint_jacobian_solve(adj_x, nl_deps, b)

      
      Compute an adjoint solution.

      :arg adj_X: Either `None`, or a variable or :class:`Sequence` of
          variables defining the initial guess for an iterative solve. May be
          modified or returned.
      :arg nl_deps: A :class:`Sequence` of variables defining values for
          non-linear dependencies. Should not be modified.
      :arg B: The right-hand-side. A variable or :class:`Sequence` of
          variables storing the value of the right-hand-side. May be modified
          or returned.
      :returns: A variable or :class:`Sequence` of variables storing the
          value of the adjoint solution. May return `None` to indicate a
          value of zero.















      ..
          !! processed by numpydoc !!

   .. py:method:: tangent_linear(tlm_map)

      
      Derive an :class:`.Equation` corresponding to a tangent-linear
      operation.

      :arg tlm_map: A :class:`.TangentLinearMap` storing values for
          tangent-linear variables.
      :returns: An :class:`.Equation`, corresponding to the tangent-linear
          operation.















      ..
          !! processed by numpydoc !!