DOLFINx-adjoint API

DOLFINx-adjoint API#

The following is the API of the functions and classes provided by the dolfinx_adjoint package.

Top-level package for dxa.

class dolfinx_adjoint.Function(*args, **kw)[source]#

A class overloading dolfinx.fem.Function to support it being used as a control variable in the adjoint framework.

Parameters:

  • V – The function space of the function.

  • x – Optional vector to initialize the function with. If not provided, a zero vector is created.

  • name – Optional name for the function.

  • dtype – Data type of the function values, defaults to dolfinx.default_scalar_type.

  • **kwargs – Additional keyword arguments to pass to the pyadjoint.overloaded_type.FloatingType constructor.

class dolfinx_adjoint.LinearProblem(a: Form | Iterable[Iterable[Form]], L: Form | Iterable[Form], bcs: Iterable[DirichletBC] | None = None, u: Function | Iterable[Function] | None = None, P: Form | Iterable[Iterable[Form]] | None = None, kind: str | Iterable[Iterable[str]] | None = None, petsc_options: dict | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: dict[Mesh, ndarray[Any, dtype[int32]]] | None = None, ad_block_tag: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None)[source]#

A linear problem that can be used with adjoint methods.

This class extends the dolfinx.fem.petsc.LinearProblem to support adjoint methods.

Parameters:

  • a – The bilinear form representing the left-hand side of the equation.

  • L – The linear form representing the right-hand side of the equation.

  • bcs – Boundary conditions to apply to the problem.

  • u – Solution vector.

  • P – Preconditioner for the linear problem.

  • kind – Kind of PETSc Matrix to assemble the system into.

  • petsc_options – Options dictionary for the PETSc krylov supspace solver.

  • form_compiler_options – Form compiler options for generating assembly kernels.

  • jit_options – Options for just-in-time compilation of the forms.

  • entity_maps – Mapping from meshes that coefficients and arguments are defined on to the integration domain of the forms.

  • ad_block_tag – Tag for adjoint blocks in the tape.

  • adjoint_petsc_options – PETSc options for adjoint problems.

  • tlm_petsc_options – Optional PETSc options for TLM problems.

solve(annotate: bool = True) → Tuple[Function | Iterable[Function], int, int][source]#

Solve the linear problem and return the solution.

dolfinx_adjoint.assemble_scalar(form: Form, **kwargs)[source]#

Assemble as scalar value from a form.

Parameters:

  • form – Symbolic form (UFL) to assemble.

  • kwargs – Keyword arguments to pass to the assembly routine. Includes "ad_block_tag" to tag the block in the adjoint tape, "annotate" to control whether the assembly is annotated in the adjoint tape, "jit_options" for JIT compilation options, and "form_compiler_options" for form compiler options and "entity_map" for assembling with Arguments and coefficients form meshes that has some relation.

dolfinx_adjoint.assign(value: inexact | float | int, function: Function, **kwargs: Unpack[ad_kwargs])[source]#

Assign a value to a dolfinx_adjoint.Function().

Parameters:

  • value – The value to assign to the function.

  • function – The function to assign the value to.

  • *args – Additional positional arguments to pass to the assign method.

  • **kwargs – Additional keyword arguments to pass to the assign method.

dolfinx_adjoint.error_norm(u_ex: Expr, u: Expr, norm_type=typing.Literal['L2', 'H1'], jit_options: dict | None = None, form_compiler_options: dict | None = None, entity_map: dict[Mesh, ndarray[Any, dtype[int32]]] | None = None, ad_block_tag: str | None = None, annotate: bool = True) → float[source]#

Compute the error norm between the exact solution and the computed solution.

Parameters:

  • u_ex – The exact solution as a UFL expression.

  • u – The computed solution as a UFL expression.

  • norm_type – The type of norm to compute, either “L2” or “H1”.

  • jit_options – Optional JIT compilation options.

  • form_compiler_options – Optional form compiler options.

  • entity_map – Optional mapping from mesh entities to submesh entities.

  • ad_block_tag – Optional tag for the block in the adjoint tape.

  • annotate – Whether to annotate the assignment in the adjoint tape.

Returns:

The computed error norm as a float.

Contents