Warning

You are reading a version of the website built against the unstable main branch. This content is liable to change without notice and may be inappropriate for your use case. You can find the documentation for the current stable release here.

firedrake.adjoint_utils.blocks package

Submodules

firedrake.adjoint_utils.blocks.assembly module

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

Bases: Block

adj_state

block_helper

compute_action_adjoint(adj_input, arity_form, form=None, c_rep=None, space=None, dform=None)

This computes the action of the adjoint of the derivative of \(form\) wrt \(c_rep\) on \(adj_input\). In other words, it returns: \(<(dform/dc_rep)*, adj_input>\)

• If \(form\) has arity 0 => \(dform/dc_rep\) is a 1-form and \(adj_input\) a float, we can simply use the \(*\) operator.

• If \(form\) has arity 1 => \(dform/dc_rep\) is a 2-form and we can symbolically take its adjoint and then apply the action on \(adj_input\), to finally assemble the result.

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

tag

firedrake.adjoint_utils.blocks.block_utils module

firedrake.adjoint_utils.blocks.block_utils.isconstant(expr)

Check whether expression is constant type. In firedrake this is a function in the real space Ie: \(firedrake.Function(FunctionSpace(mesh, "R"))\)

firedrake.adjoint_utils.blocks.constant module

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

Bases: Block

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

Parameters:

• 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\)

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.

Parameters:

• 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.

tag

firedrake.adjoint_utils.blocks.constant.constant_from_values(constant, values=None)

Returns a new Constant with \(constant.values()\).

If the optional argument \(values\) is provided, then \(values\) will be the values of the new Constant instead, while still preserving the ufl_shape of \(constant\).

Parameters:

• constant – A constant with the ufl_shape to preserve. values

• (numpy.array) – An optional argument to use instead of

• constant.values().

Returns:

The created Constant of the same type as \(constant\).

Return type:

Constant

firedrake.adjoint_utils.blocks.dirichlet_bc module

class firedrake.adjoint_utils.blocks.dirichlet_bc.DirichletBCBlock(*args, **kwargs)

Bases: Block

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

recompute()

Recomputes the overloaded function with new inputs

and stores the results in the \(checkpoint\) attribute of the outputs.

This method will by default call the \(recompute_component\) method for each output.

Parameters:

markings (bool) – If True, then each block_variable will have set \(is_control_dependent\) attribute indicating whether their checkpoints need to be recomputed for recomputing the final target function value. Default is False.

tag

firedrake.adjoint_utils.blocks.dirichlet_bc.extract_bc_subvector(value, Vtarget, bc)

Extract from value (a function in a mixed space), the sub function corresponding to the part of the space bc applies to. Vtarget is the target (collapsed) space.

firedrake.adjoint_utils.blocks.function module

class firedrake.adjoint_utils.blocks.function.CofunctionAssignBlock(lhs: Cofunction, rhs: Cofunction, ad_block_tag=None, rhs_from_assemble=False)

Bases: Block

Class specifically for the case b.assign(a).

All other cofunction assignment operations are annotated via Assemble. In effect this means that this is the annotation of an identity operation.

Parameters:

• lhs – The target of the assignment.

• rhs – The cofunction being assigned.

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

recompute_component(inputs, block_variable, idx, prepared=None)

Recompute the assignment.

Parameters:

• inputs (list of Function or Constant) – The variable in the RHS of the assignment.

• block_variable (pyadjoint.block_variable.BlockVariable) – The output block variable.

• idx (int) – Index associated to the inputs list.

• prepared – The precomputed RHS value.

Notes

Recomputes the block_variable only if the checkpoint was not delegated to another Function.

Returns:

Return either the firedrake cofunction or \(BlockVariable\) checkpoint to which was delegated the checkpointing.

Return type:

Cofunction

tag

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

Bases: Block

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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=None)

Recompute the assignment.

Parameters:

• inputs (list of Function or Constant) – The variables in the RHS of the assignment.

• block_variable (pyadjoint.block_variable.BlockVariable) – The output block variable.

• idx (int) – Index associated to the inputs list.

• prepared – The precomputed RHS value.

Notes

Recomputes the block_variable only if the checkpoint was not delegated to another Function.

Returns:

Return either the firedrake function or \(BlockVariable\) checkpoint to which was delegated the checkpointing.

Return type:

Function

tag

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

Bases: Block

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

tag

class firedrake.adjoint_utils.blocks.function.SubfunctionBlock(func, idx, ad_block_tag=None)

Bases: Block

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

tag

firedrake.adjoint_utils.blocks.mesh module

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

Bases: Block

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

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

tag

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

Bases: Block

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

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

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.

Parameters:

• 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.

tag

firedrake.adjoint_utils.blocks.solving module

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

Bases: Block

property adj_sol

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of the same type as \(block_variable.saved_output\)

pop_kwargs_keys = ['adj_cb', 'adj_bdy_cb', 'adj2_cb', 'adj2_bdy_cb', 'forward_args', 'forward_kwargs', 'adj_args', 'adj_kwargs']

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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

Parameters:

• 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.

tag

class firedrake.adjoint_utils.blocks.solving.NonlinearVariationalSolveBlock(equation, func, bcs, adj_cache, problem_J, solver_kwargs, **kwargs)

Bases: GenericSolveBlock

adj_state

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\).

Parameters:

• 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:

The resulting product.

Return type:

An object of a type consistent with the adj_value type of \(block_variable\)

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.

Parameters:

• 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\)

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.

Parameters:

• 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.

tag

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

Bases: SolveVarFormBlock

adj_state

block_helper

tag

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

Bases: GenericSolveBlock

adj_state

block_helper

tag

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

Bases: GenericSolveBlock

adj_state

block_helper

tag

class firedrake.adjoint_utils.blocks.solving.Solver(*values)

Bases: Enum

Enum for solver types.

ADJOINT = 1

FORWARD = 0

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

Bases: Block

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

\[M_B * v_B = M_{AB} * v_A,\]

where

• \(M_B\) is the mass matrix on \(V_B\),

• \(M_{AB}\) is the mixed mass matrix for \(V_A\) and \(V_B\),

• \(v_A\) and \(v_B\) are vector representations of the source and target 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.

adj_state

apply_mixedmass(a)

block_helper

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

Evaluate the adjoint to one output of the block

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.

Parameters:

• 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.

tag

firedrake.adjoint_utils.blocks.solving.extract_subfunction(u, V)

If V is a subspace of the function-space of u, return the component of u that is in that subspace.

firedrake.adjoint_utils.blocks.solving.solve_init_params(self, args, kwargs, varform)

Module contents