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

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

A class overloading {py:class}`dolfinx.fem.Constant` to support it being used as a control variable in the adjoint framework.

Parameters:

  • domain – The mesh on which the constant is defined.

  • c – The value of the constant. Can be a scalar, a sequence, or a numpy array.

Note

The {py:class}`Constant` class is implemented as a subclass of {py:class}`Function` to leverage the existing functionality for handling function spaces and vectors. The value of the constant is stored in the underlying vector of the function, and the class provides a property to access this value conveniently.

If {py:func}`basix.ufl.real_element` is not available, the class will attempt to use {py:mod}`scifem` to create a function space for the constant (which would then require {py:mod}`scifem` to be installed - pip install scifem).

ufl_id()#

Return the ufl_id of this object.

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.

property index_map: IndexMap#

Return the index map of the function’s vector.

ufl_id()#

Return the ufl_id of this object.

property x: Vector#

Return the underlying vector of the function.

class dolfinx_adjoint.LinearProblem(a: ufl.Form, L: ufl.BaseForm, *, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, u: _Function | None = None, P: ufl.Form | None = None, kind: str | None = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, ad_block_tag: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None)[source]#
class dolfinx_adjoint.LinearProblem(a: Sequence[Sequence[ufl.Form]], L: Sequence[ufl.BaseForm], *, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, u: Sequence[_Function] | None = None, P: Sequence[Sequence[ufl.Form]] | None = None, kind: MaybeBlockedMatrix[str] | None = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, ad_block_tag: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None)

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.

  • petsc_options_prefix – Options prefix for the PETSc solver – auto-generated, unique per LinearProblem, if not supplied.

  • 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) → MaybeBlocked[Function][source]#

Solve the linear problem and return the solution.

class dolfinx_adjoint.NonlinearProblem(F: ufl.form.Form, u: _Function, *, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, J: ufl.form.Form | None = None, P: ufl.form.Form | None = None, kind: str | None = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, ad_block_tag: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None)[source]#
class dolfinx_adjoint.NonlinearProblem(F: Sequence[ufl.form.Form], u: Sequence[_Function], *, bcs: Sequence[dolfinx.fem.DirichletBC] | None = None, J: Sequence[Sequence[ufl.form.Form]] | None = None, P: Sequence[Sequence[ufl.form.Form]] | None = None, kind: MaybeBlockedMatrix[str] | None = None, petsc_options: dict | None = None, petsc_options_prefix: str | None = None, form_compiler_options: dict | None = None, jit_options: dict | None = None, entity_maps: Sequence[dolfinx.mesh.EntityMap] | None = None, ad_block_tag: str | None = None, adjoint_petsc_options: dict | None = None, tlm_petsc_options: dict | None = None)

A nonlinear problem that can be used with adjoint methods.

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

Parameters:

  • F – The residual form.

  • u – Solution vector.

  • bcs – Boundary conditions to apply to the problem.

  • J – The Jacobian form. Computed from F if not supplied.

  • P – Preconditioner for the nonlinear problem.

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

  • petsc_options – Options dictionary for the PETSc SNES solver.

  • petsc_options_prefix – Options prefix for the PETSc solver – auto-generated, unique per NonlinearProblem, if not supplied.

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

property bcs: Sequence[DirichletBC]#

Dirichlet boundary conditions applied to the residual and Jacobian.

{py:class}`dolfinx.fem.petsc.NonlinearProblem` has no bcs attribute of its own (its SNES callbacks close over a fixed bcs list at construction); this property exposes self._bcs under the same name {py:class}`~dolfinx_adjoint.LinearProblem` uses (there, it is the base class’s own attribute), so {py:class}`~dolfinx_adjoint.solvers._ProblemBase`’s shared methods can read/write self.bcs uniformly across both classes.

solve(annotate: bool = True) → MaybeBlocked[Function][source]#

Solve the nonlinear 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, "form_compiler_options" for form compiler options, and "entity_maps" 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.dirichletbc(value, dofs: ndarray[tuple[Any, ...], dtype[int32]], V: FunctionSpace | None = None, **kwargs) → DirichletBC[source]#

Overloaded DirichletBC constructor that creates an adjoint-aware DirichletBC.

Parameters:

  • value – The value of the Dirichlet BC: a dolfinx_adjoint.Function, a dolfinx_adjoint.Constant, or an arbitrary UFL expression built from tracked coefficients. Always packed into a fresh Function on V – use value itself (not bc.g) as the pyadjoint.Control.

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

  • V – The function space being constrained. Defaults to value.function_space when value has one; required otherwise (a general expression has no space of its own to default to).

  • **kwargs – Additional keyword arguments to pass to the dolfinx_adjoint.types.dirichletbc.DirichletBC constructor.

dolfinx_adjoint.enable_disk_checkpointing(dirname: str | PathLike | None = None, comm: Intracomm | None = None, cleanup: bool = True, use_mpio: bool | None = None) → None[source]#

Store the working tape’s checkpoints on disk rather than in memory.

Must be called before any operation is recorded on the working tape, and before enabling a checkpoint schedule on it.

Disk checkpointing is a property of one tape, not of the process: enabling it on a second tape leaves the first tape’s checkpoints, and the file holding them, alone. Each tape’s files live until {py:func}`disable_disk_checkpointing` is called with that tape as the working tape, or until the process exits – nothing can close them implicitly, because closing a shared file is collective and so cannot be driven by garbage collection.

Parameters:

  • dirname – Directory to hold the checkpoint files. A temporary directory is created if this is not given.

  • comm – MPI communicator. Defaults to MPI.COMM_WORLD.

  • cleanup – Whether to delete the checkpoint files, and the temporary directory, on teardown. Pass False to keep them for inspection; they are unreadable by any later run either way.

  • use_mpio – Whether to write one shared file with MPI-IO. The default chooses it when running on more than one process with an MPI-enabled h5py, and falls back to one file per process otherwise. Pass False to force the per-process layout.

dolfinx_adjoint.error_norm(u_ex: Expr, u: Expr, norm_type: Literal['L2', 'H1'] = 'L2', jit_options: dict | None = None, form_compiler_options: dict | None = None, entity_map: dict[Mesh, ndarray[tuple[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.

dolfinx_adjoint.interpolate(u_or_expr, V: FunctionSpace, **kwargs)[source]#

Interpolate a Function or UFL Expression into a different function space.

dolfinx_adjoint.interpolate_nonmatching(u_from: Function, V_to: FunctionSpace, cells=None, interpolation_data=None, tol: float = 1e-06, maxit: int = 15, **kwargs)[source]#

Interpolate a Function into a different function space on a non-matching mesh.