firedrake.adjoint package

Submodules

firedrake.adjoint.assembly module

firedrake.adjoint.assembly.annotate_assemble(assemble)

firedrake.adjoint.blocks module

class firedrake.adjoint.blocks.AssembleBlock(form, ad_block_tag=None)

Bases: AssembleBlock, Backend

block_helper

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.Backend

Bases: object

backend

compat

class firedrake.adjoint.blocks.ConstantAssignBlock(other, ad_block_tag=None)

Bases: ConstantAssignBlock, Backend

block_helper

class firedrake.adjoint.blocks.DirichletBCBlock(*args, **kwargs)

Bases: DirichletBCBlock, Backend

block_helper

class firedrake.adjoint.blocks.FunctionAssignBlock(func, other, ad_block_tag=None)

Bases: FunctionAssignBlock, Backend

block_helper

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.FunctionMergeBlock(func, idx, ad_block_tag=None)

Bases: Block, Backend

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for evaluating the adjoint of the block that corresponds to one dependency. If one considers the adjoint action a vector right multiplied with the Jacobian matrix, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. adj_inputs (list): A list of the adjoint input values, determined by the outputs list. block_variable (BlockVariable): The block variable of the dependency corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_adj method. Default is None.

Returns:

An object of a type consistent with the adj_value type of block_variable: The resulting product.

evaluate_hessian_component(inputs, hessian_inputs, adj_inputs, block_variable, idx, relevant_dependencies, prepared=None)

This method must be overridden.

The method should implement a routine for evaluating the hessian of the block. It is preferable that a “Forward-over-Reverse” scheme is used. Thus the hessians are evaluated in reverse (starting with the last block on the tape).

evaluate_tlm()

Computes the tangent linear action and stores the result in the tlm_value attribute of the outputs.

This method will by default call the evaluate_tlm_component method for each output.

Args:

markings (bool): If True, then each block_variable will have set marked_in_path attribute indicating

whether their tlm components are relevant for computing the final target tlm values. Default is False.

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.FunctionSplitBlock(func, idx, ad_block_tag=None)

Bases: Block, Backend

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for evaluating the adjoint of the block that corresponds to one dependency. If one considers the adjoint action a vector right multiplied with the Jacobian matrix, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. adj_inputs (list): A list of the adjoint input values, determined by the outputs list. block_variable (BlockVariable): The block variable of the dependency corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_adj method. Default is None.

Returns:

An object of a type consistent with the adj_value type of block_variable: The resulting product.

evaluate_hessian_component(inputs, hessian_inputs, adj_inputs, block_variable, idx, relevant_dependencies, prepared=None)

This method must be overridden.

The method should implement a routine for evaluating the hessian of the block. It is preferable that a “Forward-over-Reverse” scheme is used. Thus the hessians are evaluated in reverse (starting with the last block on the tape).

evaluate_tlm_component(inputs, tlm_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for computing the tangent linear model of the block that corresponds to one output. If one considers the tangent linear action as a Jacobian matrix multiplied with a vector, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. tlm_inputs (list): A list of the tlm input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_tlm method. Default is None.

Returns:

An object of the same type as block_variable.saved_output: The resulting product.

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.GenericSolveBlock(lhs, rhs, func, bcs, *args, **kwargs)

Bases: GenericSolveBlock, Backend

block_helper

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.InterpolateBlock(interpolator, *functions, **kwargs)

Bases: Block, Backend

Annotates an interpolator.

Consider the block as f with 1 forward model output v, and inputs u and g (there can, in principle, be any number of outputs). The adjoint input is vhat (uhat and ghat are adjoints to u and v respectively and are shown for completeness). The downstream block is J which has input v.

 _             _
|J|--<--v--<--|f|--<--u--<--...
 ¯      |      ¯      |
       vhat    |     uhat
               |
                ---<--g--<--...
                      |
                     ghat

(Arrows indicate forward model direction)

J : V ⟶ R i.e. J(v) ∈ R ∀ v ∈ V

Interpolation can operate on an expression which may not be linear in its arguments.

f : W × G ⟶ V i.e. f(u, g) ∈ V ∀ u ∈ W and g ∈ G.
f = I ∘ expr
I :   X ⟶ V i.e. I(;x) ∈ V ∀ x ∈ X.
                  X is infinite dimensional.
expr: W × G ⟶ X i.e. expr(u, g) ∈ X ∀ u ∈ W and g ∈ G.

Arguments after a semicolon are linear (i.e. operation I is linear)

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

Denote d_u[A] as the gateaux derivative in the u direction. Arguments after a semicolon are linear.

This calculates

uhat = vhat ⋅ d_u[f](u, g; ⋅) (for inputs[idx] ∈ W)
or
ghat = vhat ⋅ d_g[f](u, g; ⋅) (for inputs[idx] ∈ G)

where inputs[idx] specifies the derivative direction, vhat is adj_inputs[0] (since we assume only one block output) and ⋅ denotes an unspecified operand of u' (for inputs[idx] ∈ W) or g' (for inputs[idx] ∈ G) size (vhat left multiplies the derivative).

f = I ∘ expr : W × G ⟶ V
               i.e. I(expr|_{u, g}) ∈ V ∀ u ∈ W, g ∈ G.

Since I is linear we get that

d_u[I ∘ expr](u, g; u') = I ∘ d_u[expr](u|_u, g|_g; u')
d_g[I ∘ expr](u, g; g') = I ∘ d_u[expr](u|_u, g|_g; g').

In tensor notation

uhat_q^T = vhat_p^T I([dexpr/du|_u]_q)_p
or
ghat_q^T = vhat_p^T I([dexpr/dg|_u]_q)_p

the output is then

uhat_q = I^T([dexpr/du|_u]_q)_p vhat_p
or
ghat_q = I^T([dexpr/dg|_u]_q)_p vhat_p.

evaluate_hessian_component(inputs, hessian_inputs, adj_inputs, block_variable, idx, relevant_dependencies, prepared=None)

Denote d_u[A] as the gateaux derivative in the u direction. Arguments after a semicolon are linear.

hessian_input is d_v[d_v[J]](v; v', ⋅) where the direction ⋅ is left unspecified so it can be operated upon.

Warning

NOTE: This comment describes the implementation of 1 block input u. (e.g. interpolating from an expression with 1 coefficient). Explaining how this works for multiple block inputs (e.g. u and g) is currently too complicated for the author to do succinctly!

This function needs to output d_u[d_u[J ∘ f]](u; u', ⋅) where the direction ⋅ will be specified in another function and multiplied on the right with the output of this function. We will calculate this using the chain rule.

J : V ⟶ R i.e. J(v) ∈ R ∀ v ∈ V
f = I ∘ expr : W ⟶ V
J ∘ f : W ⟶ R i.e. J(f|u) ∈ R ∀ u ∈ V.
d_u[J ∘ f] : W × W ⟶ R i.e. d_u[J ∘ f](u; u')
d_u[d_u[J ∘ f]] : W × W × W ⟶ R i.e. d_u[d_u[J ∘ f]](u; u', u'')
d_v[J] : V × V ⟶ R i.e. d_v[J](v; v')
d_v[d_v[J]] : V × V × V ⟶ R i.e. d_v[d_v[J]](v; v', v'')

Chain rule:

d_u[J ∘ f](u; u') = d_v[J](v = f|u; v' = d_u[f](u; u'))

Multivariable chain rule:

d_u[d_u[J ∘ f]](u; u', u'') =
d_v[d_v[J]](v = f|u; v' = d_u[f](u; u'), v'' = d_u[f](u; u''))
+ d_v'[d_v[J]](v = f|u; v' = d_u[f](u; u'), v'' = d_u[d_u[f]](u; u', u''))
= d_v[d_v[J]](v = f|u; v' = d_u[f](u; u'), v''=d_u[f](u; u''))
+ d_v[J](v = f|u; v' = v'' = d_u[d_u[f]](u; u', u''))

since d_v[d_v[J]] is linear in v' so differentiating wrt to it leaves its coefficient, the bare d_v[J] operator which acts on the v'' term that remains.

The d_u[d_u[f]](u; u', u'') term can be simplified further:

f = I ∘ expr : W ⟶ V i.e. I(expr|u) ∈ V ∀ u ∈ W
d_u[I ∘ expr] : W × W ⟶ V i.e. d_u[I ∘ expr](u; u')
d_u[d_u[I ∘ expr]] : W × W × W ⟶ V i.e. d_u[I ∘ expr](u; u', u'')
d_x[I] : X × X ⟶ V i.e. d_x[I](x; x')
d_x[d_x[I]] : X × X × X ⟶ V i.e. d_x[d_x[I]](x; x', x'')
d_u[expr] : W × W ⟶ X i.e. d_u[expr](u; u')
d_u[d_u[expr]] : W × W × W ⟶ X i.e. d_u[d_u[expr]](u; u', u'')

Since I is linear we get that

d_u[d_u[I ∘ expr]](u; u', u'') = I ∘ d_u[d_u[expr]](u; u', u'').

So our full hessian is:

d_u[d_u[J ∘ f]](u; u', u'')
= d_v[d_v[J]](v = f|u; v' = d_u[f](u; u'), v''=d_u[f](u; u''))
+ d_v[J](v = f|u; v' = v'' = d_u[d_u[f]](u; u', u''))

In tensor notation

[d^2[J ∘ f]/du^2|_u]_{lk} u'_k u''_k =
[d^2J/dv^2|_{v=f|_u}]_{ij} [df/du|_u]_{jk} u'_k [df/du|_u]_{il} u''_l
+ [dJ/dv|_{v=f_u}]_i I([d^2expr/du^2|_u]_{lk} u'_k)_i u''_l

In the first term:

[df/du|_u]_{jk} u'_k = v'_j
=> [d^2J/dv^2|_{v=f|_u}]_{ij} [df/du|_u]_{jk} u'_k
= [d^2J/dv^2|_{v=f|_u}]_{ij} v'_j
= hessian_input_i
=> [d^2J/dv^2|_{v=f|_u}]_{ij} [df/du|_u]_{jk} u'_k [df/du|_u]_{il}
= hessian_input_i [df/du|_u]_{il}
= self.evaluate_adj_component(inputs, hessian_inputs, ...)_l

In the second term we calculate everything explicitly though note [dJ/dv|_{v=f_u}]_i = adj_inputs[0]_i

Also, the second term is 0 if expr is linear.

evaluate_tlm_component(inputs, tlm_inputs, block_variable, idx, prepared=None)

Denote d_u[A] as the gateaux derivative in the u direction. Arguments after a semicolon are linear.

For a block with two inputs this calculates

v' = d_u[f](u, g; u') + d_g[f](u, g; g')

where u' = tlm_inputs[0] and g = tlm_inputs[1].

f = I ∘ expr : W × G ⟶ V
               i.e. I(expr|_{u, g}) ∈ V ∀ u ∈ W, g ∈ G.

Since I is linear we get that

d_u[I ∘ expr](u, g; u') = I ∘ d_u[expr](u|_u, g|_g; u')
d_g[I ∘ expr](u, g; g') = I ∘ d_u[expr](u|_u, g|_g; g').

In tensor notation the output is then

v'_l = I([dexpr/du|_{u,g}]_k u'_k)_l + I([dexpr/du|_{u,g}]_k g'_k)_l
     = I([dexpr/du|_{u,g}]_k u'_k + [dexpr/du|_{u,g}]_k g'_k)_l

since I is linear.

prepare_evaluate_adj(inputs, adj_inputs, relevant_outputs)

Runs preparations before evalute_adj_component is ran.

The return value is supplied to each of the subsequent evaluate_adj_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.

Args:

inputs: The values of the inputs adj_inputs: The adjoint inputs relevant_dependencies: A list of the relevant block variables for evaluate_adj_component.

Returns:

Anything. The returned value is supplied to evaluate_adj_component

prepare_evaluate_hessian(inputs, hessian_inputs, adj_inputs, relevant_dependencies)

Runs preparations before evalute_hessian_component is ran for each relevant dependency.

The return value is supplied to each of the subsequent evaluate_hessian_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.

Args:

inputs: The values of the inputs hessian_inputs: The hessian inputs adj_inputs: The adjoint inputs relevant_dependencies: A list of the relevant block variables for evaluate_hessian_component.

Returns:

Anything. The returned value is supplied to evaluate_hessian_component

prepare_evaluate_tlm(inputs, tlm_inputs, relevant_outputs)

Runs preparations before evalute_tlm_component is ran.

The return value is supplied to each of the subsequent evaluate_tlm_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.

Args:

inputs: The values of the inputs tlm_inputs: The tlm inputs relevant_outputs: A list of the relevant block variables for evaluate_tlm_component.

Returns:

Anything. The returned value is supplied to evaluate_tlm_component

prepare_recompute_component(inputs, relevant_outputs)

Runs preparations before recompute_component is ran.

The return value is supplied to each of the subsequent recompute_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.

Args:

inputs: The values of the inputs relevant_outputs: A list of the relevant block variables for recompute_component.

Returns:

Anything. The returned value is supplied to recompute_component

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.MeshInputBlock(mesh, ad_block_tag=None)

Bases: Block

Block which links a MeshGeometry to its coordinates, which is a firedrake function.

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for evaluating the adjoint of the block that corresponds to one dependency. If one considers the adjoint action a vector right multiplied with the Jacobian matrix, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. adj_inputs (list): A list of the adjoint input values, determined by the outputs list. block_variable (BlockVariable): The block variable of the dependency corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_adj method. Default is None.

Returns:

An object of a type consistent with the adj_value type of block_variable: The resulting product.

evaluate_hessian_component(inputs, hessian_inputs, adj_inputs, idx, block_variable, relevant_dependencies, prepared=None)

This method must be overridden.

The method should implement a routine for evaluating the hessian of the block. It is preferable that a “Forward-over-Reverse” scheme is used. Thus the hessians are evaluated in reverse (starting with the last block on the tape).

evaluate_tlm_component(inputs, tlm_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for computing the tangent linear model of the block that corresponds to one output. If one considers the tangent linear action as a Jacobian matrix multiplied with a vector, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. tlm_inputs (list): A list of the tlm input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_tlm method. Default is None.

Returns:

An object of the same type as block_variable.saved_output: The resulting product.

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.MeshOutputBlock(func, mesh, ad_block_tag=None)

Bases: Block

Block which is called when the coordinates of a mesh are changed.

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for evaluating the adjoint of the block that corresponds to one dependency. If one considers the adjoint action a vector right multiplied with the Jacobian matrix, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. adj_inputs (list): A list of the adjoint input values, determined by the outputs list. block_variable (BlockVariable): The block variable of the dependency corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_adj method. Default is None.

Returns:

An object of a type consistent with the adj_value type of block_variable: The resulting product.

evaluate_hessian_component(inputs, hessian_inputs, adj_inputs, idx, block_variable, relevant_dependencies, prepared=None)

This method must be overridden.

The method should implement a routine for evaluating the hessian of the block. It is preferable that a “Forward-over-Reverse” scheme is used. Thus the hessians are evaluated in reverse (starting with the last block on the tape).

evaluate_tlm_component(inputs, tlm_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for computing the tangent linear model of the block that corresponds to one output. If one considers the tangent linear action as a Jacobian matrix multiplied with a vector, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. tlm_inputs (list): A list of the tlm input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_tlm method. Default is None.

Returns:

An object of the same type as block_variable.saved_output: The resulting product.

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class firedrake.adjoint.blocks.NonlinearVariationalSolveBlock(equation, func, bcs, adj_F, dFdm_cache, problem_J, solver_params, solver_kwargs, **kwargs)

Bases: GenericSolveBlock

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

This method should be overridden.

The method should implement a routine for evaluating the adjoint of the block that corresponds to one dependency. If one considers the adjoint action a vector right multiplied with the Jacobian matrix, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. adj_inputs (list): A list of the adjoint input values, determined by the outputs list. block_variable (BlockVariable): The block variable of the dependency corresponding to index idx. idx (int): The index of the component to compute. prepared (object): Anything returned by the prepare_evaluate_adj method. Default is None.

Returns:

An object of a type consistent with the adj_value type of block_variable: The resulting product.

prepare_evaluate_adj(inputs, adj_inputs, relevant_dependencies)

Runs preparations before evalute_adj_component is ran.

The return value is supplied to each of the subsequent evaluate_adj_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.

Args:

inputs: The values of the inputs adj_inputs: The adjoint inputs relevant_dependencies: A list of the relevant block variables for evaluate_adj_component.

Returns:

Anything. The returned value is supplied to evaluate_adj_component

class firedrake.adjoint.blocks.ProjectBlock(v, V, output, bcs=[], *args, **kwargs)

Bases: SolveVarFormBlock

block_helper

class firedrake.adjoint.blocks.SolveLinearSystemBlock(A, u, b, *args, **kwargs)

Bases: GenericSolveBlock

block_helper

class firedrake.adjoint.blocks.SolveVarFormBlock(equation, func, bcs=[], *args, **kwargs)

Bases: GenericSolveBlock

block_helper

class firedrake.adjoint.blocks.SupermeshProjectBlock(source, target_space, target, bcs=[], **kwargs)

Bases: Block, Backend

Annotates supermesh projection.

Suppose we have a source space, \(V_A\), and a target space, \(V_B\). Projecting a source from \(V_A\) to \(V_B\) amounts to solving the linear system

\[ \begin{align}\begin{aligned}M_B * v_B = M_{AB} * v_A,\\where :math:`M_B` is the mass matrix on :math:`V_B`, :math:`M_{AB}` is the mixed mass matrix for :math:`V_A` and :math:`V_B` and :math:`v_A` and :math:`v_B` are vector representations of the source and target :class:`.Function`s.\\This can be broken into two steps: Step 1. form RHS, multiplying the source with the mixed mass matrix; Step 2. solve linear system.\end{aligned}\end{align} \]

apply_mixedmass(a)

block_helper

evaluate_adj_component(inputs, adj_inputs, block_variable, idx, prepared=None)

Recall that the forward propagation can be broken down as

Step 1. multiply \(w := M_{AB} * v_A\); Step 2. solve \(M_B * v_B = w\).

For a seed vector \(v_B^{seed}\) from the target space, the adjoint is given by

Adjoint of step 2. solve \(M_B^T * w = v_B^{seed}\) for w; Adjoint of step 1. multiply \(v_A^{adj} := M_{AB}^T * w\).

evaluate_hessian_component(inputs, hessian_inputs, adj_inputs, block_variable, idx, relevant_dependencies, prepared=None)

This method must be overridden.

The method should implement a routine for evaluating the hessian of the block. It is preferable that a “Forward-over-Reverse” scheme is used. Thus the hessians are evaluated in reverse (starting with the last block on the tape).

evaluate_tlm_component(inputs, tlm_inputs, block_variable, idx, prepared=None)

Given that the input is a Function, we just have a linear operation. As such, the tlm is just the sum of each tlm input projected into the target space.

recompute_component(inputs, block_variable, idx, prepared)

This method must be overridden.

The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.

Args:

inputs (list): A list of the saved input values, determined by the dependencies list. block_variable (BlockVariable): The block variable of the output corresponding to index idx. idx (int): The index of the output to compute. prepared (object): Anything returned by the prepare_recompute_component method. Default is None.

Returns:

An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

firedrake.adjoint.blocks.solve_init_params(self, args, kwargs, varform)

firedrake.adjoint.checkpointing module

A module providing support for disk checkpointing of the adjoint tape.

firedrake.adjoint.checkpointing.checkpointable_mesh(mesh)

Write a mesh to disk and read it back.

Since a mesh will be repartitioned by being written to disk and reread, only meshes read from a checkpoint file are safe to use with disk checkpointing.

The workflow for disk checkpointing is therefore to create the mesh(es) required, and then call this function on them. Only the mesh(es) returned by this function can be used in disk checkpointing.

Parameters:

meshfiredrake.Mesh

The mesh to be checkpointed.

Returns:

firedrake.Mesh

The checkpointed mesh to be used in the rest of the computation.

firedrake.adjoint.checkpointing.continue_disk_checkpointing()

Resume disk checkpointing.

firedrake.adjoint.checkpointing.disk_checkpointing()

Return true if disk checkpointing of the adjoint tape is active.

firedrake.adjoint.checkpointing.enable_disk_checkpointing(dirname=None, comm=<mpi4py.MPI.Intracomm object>, cleanup=True)

Add a DiskCheckpointer to the current tape and switch on disk checkpointing.

Parameters:

dirnamestr

The directory in which the disk checkpoints should be stored. If not specified then the current working directory is used. Checkpoints are stored in a temporary subdirectory of this directory.

commmpi4py.MPI.Intracomm

The MPI communicator over which the computation to be disk checkpointed is defined. This will usually match the communicator on which the mesh(es) are defined.

cleanupbool

If set to False, checkpoint files will not be deleted when no longer required. This is usually only useful for debugging.

firedrake.adjoint.checkpointing.pause_disk_checkpointing()

Pause disk checkpointing and instead checkpoint to memory.

class firedrake.adjoint.checkpointing.stop_disk_checkpointing

Bases: object

A context manager inside which disk checkpointing is paused.

firedrake.adjoint.constant module

class firedrake.adjoint.constant.ConstantMixin(*args, **kwargs)

Bases: OverloadedType

get_derivative(options={})

firedrake.adjoint.dirichletbc module

class firedrake.adjoint.dirichletbc.DirichletBCMixin(*args, **kwargs)

Bases: FloatingType

firedrake.adjoint.function module

class firedrake.adjoint.function.DelegatedFunctionCheckpoint(other)

Bases: CheckpointBase

A wrapper which delegates the checkpoint of this Function to another Function.

This enables us to avoid checkpointing a Function twice when it is copied.

Parameters:

other: BlockVariable

The block variable to which we delegate checkpointing.

restore()

Recover and return the checkpointed object.

class firedrake.adjoint.function.FunctionMixin(*args, **kwargs)

Bases: FloatingType

firedrake.adjoint.interpolate module

firedrake.adjoint.interpolate.annotate_interpolate(interpolate)

firedrake.adjoint.mesh module

class firedrake.adjoint.mesh.MeshGeometryMixin(*args, **kwargs)

Bases: OverloadedType

firedrake.adjoint.projection module

firedrake.adjoint.projection.annotate_project(project)

firedrake.adjoint.solving module

firedrake.adjoint.solving.annotate_solve(solve)

This solve routine wraps the Firedrake solve() call. Its purpose is to annotate the model, recording what solves occur and what forms are involved, so that the adjoint and tangent linear models may be constructed automatically by pyadjoint.

To disable the annotation, just pass annotate=False to this routine, and it acts exactly like the Firedrake solve call. This is useful in cases where the solve is known to be irrelevant or diagnostic for the purposes of the adjoint computation (such as projecting fields to other function spaces for the purposes of visualisation).

The overloaded solve takes optional callback functions to extract adjoint solutions. All of the callback functions follow the same signature, taking a single argument of type Function.

Keyword Args:

adj_cb (function, optional): callback function supplying the adjoint solution in the interior.

The boundary values are zero.

adj_bdy_cb (function, optional): callback function supplying the adjoint solution on the boundary.

The interior values are not guaranteed to be zero.

adj2_cb (function, optional): callback function supplying the second-order adjoint solution in the interior.

The boundary values are zero.

adj2_bdy_cb (function, optional): callback function supplying the second-order adjoint solution on

the boundary. The interior values are not guaranteed to be zero.

ad_block_tag (string, options): tag used to label the resulting block on the Pyadjoint tape. This

is useful for identifying which block is associated with which equation in the forward model.

firedrake.adjoint.solving.get_solve_blocks()

Extract all blocks of the tape which correspond to PDE solves, except for those which correspond to calls of the project operator.

firedrake.adjoint.variational_solver module

class firedrake.adjoint.variational_solver.NonlinearVariationalProblemMixin

Bases: object

class firedrake.adjoint.variational_solver.NonlinearVariationalSolverMixin

Bases: object

Module contents