DOLFINx-adjoint Blocks API

The following is the API of the blocks implemented in the DOLFINx-adjoint package, which is used within the pyadjoint framework.

class dolfinx_adjoint.blocks.AssembleBlock(form: Form, ad_block_tag: str | None = None, jit_options: dict | None = None, form_compiler_options: dict | None = None, entity_maps: Sequence[EntityMap] | None = None)

Block for assembling a symbolic UFL form into a tensor.

Parameters:

• form – The UFL form to assemble.

• ad_block_tag – Tag for the block in the adjoint tape.

• jit_options – Dictionary of options for JIT compilation.

• form_compiler_options – Dictionary of options for the form compiler.

• entity_maps – Dictionary mapping meshes to entity maps for assembly.

compute_action_adjoint(adj_input: float | Vector, arity_form: int, form: Form | None = None, c_rep: Coefficient | Constant | None = None, space: FunctionSpace | None = None, dform: Form | None = None)

This computes the action of the adjoint of the derivative of form wrt c_rep on adj_input.

In other words, it returns:

\[\left\langle\left(\frac{\partial form}{\partial c_{rep}}\right)^*, adj_{input} \right\rangle\]

• If form has arity 0, then \(\frac{\partial form}{\partial c_{rep}}\) is a 1-form and adj_input a float, we can simply use the * operator.

• If form has arity 1 then \(\frac{\partial form}{\partial c_{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.

Parameters:

• adj_input – The input to the adjoint operation, typically a scalar or vector.

• arity_form – The arity of the form, i.e., 0 for scalar, 1 for vector, 2 for matrix etc.

• form – The UFL form to differentiate if dform is not provided.

• c_rep – The coefficient or constant with respect to which the derivative is taken.

• space – The function space associated with the c_rep to form an ufl.Argument in.

• dform – Pre-computed derivative form, \(\frac{\partial form}{\partial c_{rep}}\).

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.

class dolfinx_adjoint.blocks.DirichletBCBlock(value: Function | Constant, dofs: ndarray[tuple[Any, ...], dtype[int32]], V: FunctionSpace | None = None, ad_block_tag: str | None = None)

A block representing a DirichletBC in the adjoint framework.

Parameters:

• value – The value of the Dirichlet BC.

• dofs – An array of degree-of-freedom indices in V where the BC should be applied.

• V – The function space associated with the Dirichlet BC.

• ad_block_tag – An optional tag to identify this block in the adjoint framework.

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

Return this bc’s contribution to the adjoint action.

adj_inputs[0] is the boundary reaction the consuming solve block(s) already computed (see _ProblemBlockBase._mask_reaction_to_bc/prepare_evaluate_adj), already living on this bc’s own constrained space – no reduction needed here: types.dirichletbc._pack_bc_value always packs the bc’s value into a Function on exactly that space before this block is ever created, whatever the original value was (a plain Function, a broadcasting Constant, or a general expression), so this block’s single dependency and the masked reaction always agree.

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

Return this bc’s contribution to the Hessian action.

Same pass-through as evaluate_adj_component, applied to the second-order boundary reaction (prepare_evaluate_hessian’s _adj_sol2_bdy) instead of the first-order one – the entire Hessian-action contribution for a Dirichlet bc control (see dolfinx-adjoint-knowledge’s scratch/boundary-control/spec.md for why).

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

Return this bc’s own tangent-linear value: itself a (plain, untracked) DirichletBC, with its value replaced by the perturbation direction.

A bc perturbation is not an ordinary right-hand-side contribution – it enters the tangent-linear solve as an inhomogeneous condition (u_dot = g_dot on this bc’s dofs, see HomogeneousBCLinearProblem.tlm_bcs/solve()), consumed by _ProblemBlockBase.prepare_evaluate_tlm. Built plain (dolfinx.fem.dirichletbc, not the overloaded dolfinx_adjoint one) so it is never itself tape-recorded – it exists only for this one TLM evaluation, not as a new control.

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)

Return the (aliased) bc, having first resynced its live g.x.array from the value’s own checkpoint at this tape position.

DirichletBC._ad_create_checkpoint/_ad_restore_at_checkpoint (types/dirichletbc.py) both return self – the bc’s own “checkpoint” aliases the live bc object rather than snapshotting a value – so nothing else writes a replayed/perturbed value back into bc.g’s array. prepared (this block’s single dependency’s own, correctly-checkpointed value, from prepare_recompute_component) is exactly that value: writing it into bc.g here, at the position in the tape this block itself occupies (always before any solve block that consumes bc, since the bc must be constructed first), is what makes a later solve block see the right value regardless of which tape position is being replayed. See dolfinx-adjoint-knowledge’s scratch/boundary-control/issues/02 for what breaks without this.

class dolfinx_adjoint.blocks.ExprInterpolationBlock(expr: Expr, func_to: Function, ad_block_tag: str | None = None, petsc_mat: bool = False)

Block for interpolating a UFL expression with runtime-evaluated Jacobians via scifem.

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.

class dolfinx_adjoint.blocks.FunctionAssignBlock(other: inexact | int | float | Function | Expr, func: Function, ad_block_tag: str | None = None)

Block for assigning data directly to a dolfinx_adjoint.Function on the tape.

This block handles the assignment of a linear combination of “dolfinx_adjoint.Function objects or constants to a target dolfinx_adjoint.Function.

Parameters:

• other – The right-hand side of the assignment, which can be a dolfinx_adjoint.Function, a dolfinx_adjoint.Constant, or a linear combination of dolfinx_adjoint.Function objects.

• func – The target dolfinx_adjoint.Function to which the assignment is made.

• ad_block_tag – Optional tag for identifying the block in the adjoint tape. If not provided, a default tag will be generated.

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.

class dolfinx_adjoint.blocks.InterpolationBlock(func_from: Function, func_to: Function, ad_block_tag: str | None = None, petsc_mat: bool = False)

Block for interpolating a dolfinx.fem.Function into another space.

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.

class dolfinx_adjoint.blocks.LinearProblemBlock(a: ufl.Form, L: ufl.Form, *, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, u: Function | None = None, P: ufl.Form | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, kind: Any = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None, ad_block_tag: str | None = None, problem: LinearProblem = ...)

class dolfinx_adjoint.blocks.LinearProblemBlock(a: Sequence[Sequence[ufl.Form]], L: Sequence[ufl.Form], *, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, u: Sequence[Function] | None = None, P: Sequence[Sequence[ufl.Form]] | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, kind: Any = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None, ad_block_tag: str | None = None, problem: LinearProblem = ...)

The pyadjoint tape block recorded by a {py:class}`~dolfinx_adjoint.LinearProblem` solve.

See _ProblemBlockBase’s own docstring for the shared adjoint/TLM/Hessian machinery; this subclass supplies the pieces genuinely specific to a linear a/L residual.

class dolfinx_adjoint.blocks.NonlinearProblemBlock(F: ufl.Form, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, u: Function | None = None, J: ufl.Form | None = None, P: ufl.Form | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, kind: Any = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None, ad_block_tag: str | None = None, problem: NonlinearProblem = ...)

class dolfinx_adjoint.blocks.NonlinearProblemBlock(F: Sequence[ufl.Form], bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, u: Sequence[Function] | None = None, J: Sequence[Sequence[ufl.Form]] | None = None, P: Sequence[Sequence[ufl.Form]] | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, kind: Any = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None, ad_block_tag: str | None = None, problem: NonlinearProblem = ...)

The pyadjoint tape block recorded by a {py:class}`~dolfinx_adjoint.NonlinearProblem` solve.

See _ProblemBlockBase’s own docstring for the shared adjoint/TLM/Hessian machinery; this subclass supplies the pieces genuinely specific to a nonlinear F residual.

class dolfinx_adjoint.blocks.NonmatchingInterpolationBlock(func_from: Function, func_to: Function, cells, interpolation_data, tol: float = 1e-06, maxit: int = 15, red_op=None, ad_block_tag: str | None = None, use_petsc: bool = False)

Block for interpolating a dolfinx.fem.Function between non-matching meshes.

Uses fenicsx_ii to explicitly build the transfer matrix $J$ across non-matching grids, ensuring exact parallel mathematical transposes for the Adjoint and Hessian passes.

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.