Skip to main content

DOLFINx-Adjoint

DOLFINx-Adjoint is an algorithmic differentiation (AD) framework for DOLFINx. It allows you to automatically compute the gradients and Hessians of PDE-constrained optimization problems and track your computational graphs through the pyadjoint backend.

Read the Latest Documentation here.

Note for Legacy FEnICS Users: If you are using the legacy FEnICS (dolfin) library, please refer to the original dolfin-adjoint repository. This repository (DOLFINx-Adjoint) is built specifically for the modern DOLFINx environment and is currently under active development. It is intended to eventually support the same comprehensive feature set and capabilities as the legacy version.

Features

  • Automated Adjoints: Seamlessly derive discrete adjoint models from DOLFINx forward models.

  • Overloaded API: Swap out standard dolfinx calls with their dolfinx_adjoint equivalents (e.g., Function, Constant, LinearProblem, NonlinearProblem, assemble_scalar) to automatically record the computational tape.

  • Optimization: Seamless integration with PDE-constrained optimization frameworks like Moola or SciPy via pyadjoint.ReducedFunctional.

Installation

Dependencies

DOLFINx-Adjoint requires DOLFINx (>=0.11.0) and pyadjoint-ad.

via pip

The main way to install the package is via pip:

python3 -m pip install dolfinx-adjoint

via conda

You can also install dolfinx-adjoint via conda which also comes with DOLFINx

conda install -c conda-forge dolfinx-adjoint

Development Install

To install the latest development version directly from the repository, use:

python3 -m pip install git+https://github.com/scientificcomputing/dolfinx-adjoint.git

If you plan to actively modify the code, clone the repository and install the optional dependencies for testing, development, and documentation generation:

git clone https://github.com/scientificcomputing/dolfinx-adjoint.git
cd dolfinx-adjoint
python3 -m pip install -e ".[all]"

The docs extra builds the demos and API docs, but not Moola (used by two of the three demos): PyPI rejects packages that declare a direct git-URL dependency, so it can't be listed in pyproject.toml. Install it separately first if you want to build the docs or run those demos locally:

python3 -m pip install git+https://github.com/funsim/moola.git

Quick Start

Using dolfinx_adjoint is designed to be as close to standard dolfinx syntax as possible. Here is a brief overview of how to track a parameter and assemble an objective functional:

import dolfinx
from mpi4py import MPI
import pyadjoint
import ufl
import dolfinx_adjoint

# Create mesh and function space
mesh = dolfinx.mesh.create_unit_square(MPI.COMM_WORLD, 10, 10)
V = dolfinx.fem.functionspace(mesh, ("Lagrange", 1))

# Use dolfinx_adjoint overloaded types
# This ensures operations are tracked on the pyadjoint tape!
f = dolfinx_adjoint.Function(V, name="Control")
f.interpolate(lambda x: x[0] + x[1])  # Initial guess for control
uh = dolfinx_adjoint.Function(V, name="State")

# Define UFL forms for a simple Poisson problem: - \Delta u = f
u, v = ufl.TrialFunction(V), ufl.TestFunction(V)
a = ufl.inner(ufl.grad(u), ufl.grad(v)) * ufl.dx
L = f * v * ufl.dx

# Set up Dirichlet boundary condition (u = 0 on boundary)
mesh.topology.create_connectivity(mesh.topology.dim - 1, mesh.topology.dim)
exterior_facets = dolfinx.mesh.exterior_facet_indices(mesh.topology)
exterior_dofs = dolfinx.fem.locate_dofs_topological(V, mesh.topology.dim - 1, exterior_facets)
bc = dolfinx.fem.dirichletbc(dolfinx.default_scalar_type(0.0), exterior_dofs, V)

# Use overloaded solvers
problem = dolfinx_adjoint.LinearProblem(a, L, u=uh, bcs=[bc])
problem.solve()

# Define a desired temperature profile 'd' and regularization parameter 'alpha'
x = ufl.SpatialCoordinate(mesh)
d = ufl.sin(ufl.pi * x[0]) * ufl.sin(ufl.pi * x[1])
alpha = dolfinx.fem.Constant(mesh, dolfinx.default_scalar_type(1e-6))

# Assemble the objective scalar using the overloaded assembly
J_symbolic = 0.5 * ufl.inner(uh - d, uh - d) * ufl.dx + 0.5 * alpha * ufl.inner(f, f) * ufl.dx
J = dolfinx_adjoint.assemble_scalar(J_symbolic)

# Create a ReducedFunctional for optimization
control = pyadjoint.Control(f)
Jhat = pyadjoint.ReducedFunctional(J, control)

# Evaluate gradient
gradient = Jhat.derivative()

For more comprehensive examples, such as solving the optimal control of the Poisson equation or time-distributed control problems, check out the demos/ directory or the online documentation.

Development and Testing

Code formatting is enforced via ruff and type-checking via mypy. To set up your local development environment:

# Install development dependencies
python3 -m pip install -e ".[dev,test]"

# Run formatting checks
ruff check .
ruff format --check .

# Run type checking
python3 -m mypy .

# Run tests
python3 -m pytest -vs tests/

License

MIT License. See LICENSE for more details.

Metadata

Release files for dolfinx-adjoint 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dolfinx-adjoint 0.4.0
File Size Uploaded Provenance Actions
dolfinx_adjoint-0.4.0.tar.gz 118.8 kB With provenance Details for dolfinx_adjoint-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dolfinx-adjoint 0.4.0
File Interpreter ABI Platform Actions
dolfinx_adjoint-0.4.0-py3-none-any.whl Python 3 none any Details for dolfinx_adjoint-0.4.0-py3-none-any.whl

Total release size: 204.0 kB

Release files / dolfinx_adjoint-0.4.0.tar.gz

Download URL dolfinx_adjoint-0.4.0.tar.gz
Size 118.8 kB
Tags Source
SHA-256 checksum
How to use checksums
82b462070f12cb987c55a789f25953b75daf46d6dc1368d7cc793598261ab8ba
BLAKE2b-256 checksum
How to use checksums
7923342cd1a8f0fe6be0cd2976cff1dd86547994006226f840157cafb41b4341
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / dolfinx_adjoint-0.4.0-py3-none-any.whl

Download URL dolfinx_adjoint-0.4.0-py3-none-any.whl
Size 85.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a4f33749b400a47c8db60ea04600253658c263343c629513b3a81e490825e9c
BLAKE2b-256 checksum
How to use checksums
7e3be6a6b948847014080d5661fe22d483b570dd8cd21b9ad811a90071f38199
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for dolfinx-adjoint 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dolfinx_adjoint-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page