About

The dolfin-adjoint project automatically derives the discrete adjoint and tangent linear models from a forward model written in the Python interface to FEniCS <http://fenicsproject.org>.

These adjoint and tangent linear models are key ingredients in many important algorithms, such as data assimilation, optimal control, sensitivity analysis, design optimisation, and error estimation. Such models have made an enormous impact in fields such as meteorology and oceanography, but their use in other scientific fields has been hampered by the great practical difficulty of their derivation and implementation. In his recent book, Naumann (2011) states that

[T]he automatic generation of optimal (in terms of robustness and efficiency) adjoint versions of large-scale simulation code is one of the great open challenges in the field of High-Performance Scientific Computing.

The dolfin-adjoint project aims to solve this problem for the case where the model is implemented in the Python interface to FEniCS.

News

17.08.2023: dolfin-adjoint 2023.2.0 released, removing pyadjoint and firedrake-adjoint from the Github-repository.

16.08.2023: dolfin-adjoint 2023.1.0 released, supporting ufl_legacy: https://fenicsproject.discourse.group/t/announcement-ufl-legacy-and-legacy-dolfin/11583

16.08.2023: dolfin-adjoint 2023.0.0 released, built based on dolfin prior to introduction of ufl-legacy

16.08.2023: dolfin-adjoint is moved to github_repo.

27.05.2019: dolfin-adjoint 2019.1 released (compatible with FEniCS 2019.1) ChangeLog.rst.

18.02.2019: New example demonstrating the shape-optimisation capabilities of dolfin-adjoint now available

05.10.2018: dolfin-adjoint 2018.1 released (compatible with FEniCS 2018.1) ChangeLog.rst.

08.01.2018: dolfin-adjoint/pyadjoint 2017.2 released (compatible with FEniCS 2017.2) (this website)

dolfin-adjoint/libadjoint 2017.2 released (compatible with FEniCS 2017.2) (documentation)

What is the difference between dolfin-adjoint/dolfin-adjoint and dolfin-adjoint/libadjoint?

31.05.2017: dolfin-adjoint 2017.1 released (compatible with FEniCS 2017.1) ChangeLog.rst.

21.02.2017: dolfin-adjoint 2016.2 is now available as Conda package.

20.12.2016: dolfin-adjoint 2016.2 released (compatible with FEniCS 2016.2) Changelog.rst.

08.9.2016: We now offer Docker images to simplify the installation procedure.

30.8.2016: dolfin-adjoint 2016.1 released (compatible with FEniCS 2016.1) Changelog.rst.

20.8.2015: dolfin-adjoint 1.6 released (compatible with FEniCS 1.6) Changelog.rst.

11.6.2015: P. E. Farrell, S. W. Funke, D. A. Ham and M. E. Rognes were awarded the 2015 Wilkinson prize for numerical software for dolfin-adjoint.

Features

dolfin-adjoint has the following features:

  • Works for both steady and time-dependent problems and for both linear and nonlinear problems.

  • Using it is very easy: given a differentiable forward model, employing dolfin-adjoint involves changing on the order of ten lines of code.

  • The adjoint and tangent linear models exhibit optimal theoretical efficiency. If every forward variable is stored, the adjoint takes 0.2-1.0x the runtime of the forward model, depending on the precise details of the structure of the forward problem.

  • If the forward model runs in parallel, the adjoint and tangent linear models also run in parallel with no modification.

  • If instructed, the adjoint model can automatically employ optimal checkpointing schemes to mitigate storage requirements for long nonlinear runs.

  • Rigorous verification routines are provided, so that users can easily verify for themselves the correctness of the derived models.

  • Solves optimisation problems constrained by partial differential equations by interfacing to powerful optimisation algorithms

For more details, see the features page.

Limitations

To do all this, dolfin-adjoint requires some cooperation from the model developer:

  • Works only with the Python interface of FEniCS.

  • For the adjoint to be consistent, the discretisation must be differentiable.

  • All changes to object values (matrices, vectors, functions) must happen through the FEniCS interface, though custom operations can be recorded manually.

How it works

The traditional approach to deriving adjoint and tangent linear models is called algorithmic differentiation (also called automatic differentiation). The fundamental idea of algorithmic differentiation is to treat the model as a sequence of elementary instructions. An elementary instruction is a simple operation such as addition, multiplication, or exponentiation. Each one of these operations is differentiated individually, and the derivative of the whole model is then composed with the chain rule.

The dolfin-adjoint project is instead based on a very different approach. The model is considered as a graph of high-level operations. This abstraction is similar to the fundamental abstraction of algorithmic differentiation, but operates at a much higher level of abstraction. This idea is implemented in a software library, pyadjoint. When this new idea is combined with the high-level abstraction of the FEniCS system, many of the difficult problems associated with algorithmic differentiation dissolve.

For more technical details on pyadjoint and dolfin-adjoint, see the papers.

Contributors

The dolfin-adjoint project is developed and maintained by the following authors:

License

Like the core FEniCS components, The dolfin-adjoint software is freely available under the GNU LGPL, version 3.