dolfin-adjoint API reference

See also the pyadjoint API reference.

The entire dolfin-adjoint interface should be imported with a single call:

from dolfin import *
from dolfin_adjoint import *

It is essential that the importing of the dolfin_adjoint module happen after importing the dolfin module. dolfin-adjoint relies on overloading many of the key functions of dolfin to achieve its degree of automation.

Overloaded functions

fenics_adjoint.assemble(*args, **kwargs)

When a form is assembled, the information about its nonlinear dependencies is lost, and it is no longer easy to manipulate. Therefore, fenics_adjoint overloads the dolfin.assemble() function to attach the form to the assembled object. This lets the automatic annotation work, even when the user calls the lower-level solve(A, x, b).

fenics_adjoint.assemble_system(*args, **kwargs)

When a form is assembled, the information about its nonlinear dependencies is lost, and it is no longer easy to manipulate. Therefore, fenics_adjoint overloads the dolfin.assemble_system() function to attach the form to the assembled object. This lets the automatic annotation work, even when the user calls the lower-level solve(A, x, b).

fenics_adjoint.solve(*args, **kwargs)

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

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

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

Keyword Arguments:

• adj_cb (function, optional) – callback function supplying the adjoint solution in the interior. The boundary values are zero.

• adj_bdy_cb (function, optional) – callback function supplying the adjoint solution on the boundary. The interior values are not guaranteed to be zero.

• adj2_cb (function, optional) – callback function supplying the second-order adjoint solution in the interior. The boundary values are zero.

• adj2_bdy_cb (function, optional) – callback function supplying the second-order adjoint solution on the boundary. The interior values are not guaranteed to be zero.

fenics_adjoint.project(*args, **kwargs)

The project call performs an equation solve, and so it too must be annotated so that the adjoint and tangent linear models may be constructed automatically by pyadjoint.

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

fenics_adjoint.interpolate(*args, **kwargs)

Interpolation is overloaded to ensure that the returned Function object is overloaded. We are not able to annotate the interpolation call at the moment.

Overloaded objects

class fenics_adjoint.KrylovSolver(*args, **kwargs)

solve(*args, **kwargs)

class fenics_adjoint.LUSolver(*args, **kwargs)

solve(*args, **kwargs)

class fenics_adjoint.NewtonSolver(*args, **kwargs)

solve(*args, **kwargs)

class fenics_adjoint.NonlinearVariationalSolver(problem, *args, **kwargs)

This object is overloaded so that solves using this class are automatically annotated, so that pyadjoint can automatically derive the adjoint and tangent linear models.

solve(*args, **kwargs)

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

class fenics_adjoint.NonlinearVariationalProblem(F, u, bcs=None, J=None, *args, **kwargs)

This object is overloaded so that solves using this class are automatically annotated, so that pyadjoint can automatically derive the adjoint and tangent linear models.

class fenics_adjoint.LinearVariationalSolver(problem, *args, **kwargs)

This object is overloaded so that solves using this class are automatically annotated, so that pyadjoint can automatically derive the adjoint and tangent linear models.

solve(*args, **kwargs)

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

class fenics_adjoint.LinearVariationalProblem(a, L, u, bcs=None, *args, **kwargs)

This object is overloaded so that solves using this class are automatically annotated, so that pyadjoint can automatically derive the adjoint and tangent linear models.

Overloaded types

class fenics_adjoint.Constant(*args, **kwargs)

class fenics_adjoint.DirichletBC(*args, **kwargs)

class fenics_adjoint.Expression(*args, **kwargs)

class fenics_adjoint.Function(*args, **kwargs)

assign(other, *args, **kwargs)

To disable the annotation, just pass annotate=False to this routine, and it acts exactly like the Dolfin assign call.