dolfinx-adjoint 0.2.0__tar.gz

dolfinx_adjoint-0.2.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Jørgen S. Dokken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

dolfinx_adjoint-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: dolfinx-adjoint
+Version: 0.2.0
+Summary: Automatic differentation compatible with DOLFINx
+Author-email: "Jørgen S. Dokken" <dokken@simula.no>
+License-Expression: MIT
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fenics-dolfinx>=0.10.0
+Requires-Dist: pyadjoint-ad>=2025.10.0
+Requires-Dist: typing_extensions; python_version < "3.11"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pdbpp; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: jupyter-book<2.0; extra == "docs"
+Requires-Dist: jupytext; extra == "docs"
+Requires-Dist: pandas; extra == "docs"
+Requires-Dist: pyvista[all]>0.45; extra == "docs"
+Requires-Dist: networkx; extra == "docs"
+Requires-Dist: pygraphviz; extra == "docs"
+Provides-Extra: all
+Requires-Dist: dolfinx_adjoint[test]; extra == "all"
+Requires-Dist: dolfinx_adjoint[dev]; extra == "all"
+Requires-Dist: dolfinx_adjoint[docs]; extra == "all"
+Dynamic: license-file
+
+# DOLFINx-Adjoint
+
+**DOLFINx-Adjoint** is an algorithmic differentiation (AD) framework for [DOLFINx](https://github.com/FEniCS/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](https://scientificcomputing.github.io/dolfinx-adjoint).
+
+> **Note for Legacy FEnICS Users:** If you are using the legacy FEnICS (`dolfin`) library, please refer to the original [dolfin-adjoint repository](https://github.com/dolfin-adjoint/dolfin-adjoint). 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](https://github.com/funsim/moola) or SciPy via `pyadjoint.ReducedFunctional`.
+
+## Installation
+
+### Dependencies
+
+DOLFINx-Adjoint requires **DOLFINx** (>=0.10.0) and **pyadjoint-ad**.
+
+### via pip
+
+The main way to install the package is via pip:
+
+```bash
+python3 -m pip install dolfinx-adjoint
+```
+
+### Development Install
+
+To install the latest development version directly from the repository, use:
+
+```bash
+python3 -m pip install git+[https://github.com/scientificcomputing/dolfinx-adjoint.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:
+
+```bash
+git clone [https://github.com/scientificcomputing/dolfinx-adjoint.git](https://github.com/scientificcomputing/dolfinx-adjoint.git)
+cd dolfinx-adjoint
+python3 -m pip install -e ".[all]"
+```
+
+### Docker
+
+A pre-built Docker image is automatically published by the CI. You can pull the nightly build which comes with DOLFINx and DOLFINx-Adjoint pre-installed:
+
+```bash
+docker run -ti ghcr.io/scientificcomputing/dolfinx-adjoint:v0.2.0
+```
+
+*(Note: Adjust the tag to the latest release or build).*
+
+## 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:
+<!-- #endregion -->
+
+```python
+import dolfinx
+from mpi4py import MPI
+import pyadjoint
+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")
+uh = dolfinx_adjoint.Function(V, name="State")
+
+# ... Define your UFL forms ...
+
+# Use overloaded solvers
+problem = dolfinx_adjoint.LinearProblem(a, L, u=uh, bcs=[bc])
+problem.solve()
+
+# Assemble the objective scalar using the overloaded assembly
+J_symbolic = 0.5 * ufl.inner(uh - d, uh - d) * 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()
+```
+
+<!-- #region -->
+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](https://scientificcomputing.github.io/dolfinx-adjoint).
+
+## Development and Testing
+
+Code formatting is enforced via `ruff` and type-checking via `mypy`. To set up your local development environment:
+
+```bash
+# 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](LICENSE) for more details.
+<!-- #endregion -->

dolfinx_adjoint-0.2.0/README.md

@@ -0,0 +1,120 @@
+# DOLFINx-Adjoint
+
+**DOLFINx-Adjoint** is an algorithmic differentiation (AD) framework for [DOLFINx](https://github.com/FEniCS/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](https://scientificcomputing.github.io/dolfinx-adjoint).
+
+> **Note for Legacy FEnICS Users:** If you are using the legacy FEnICS (`dolfin`) library, please refer to the original [dolfin-adjoint repository](https://github.com/dolfin-adjoint/dolfin-adjoint). 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](https://github.com/funsim/moola) or SciPy via `pyadjoint.ReducedFunctional`.
+
+## Installation
+
+### Dependencies
+
+DOLFINx-Adjoint requires **DOLFINx** (>=0.10.0) and **pyadjoint-ad**.
+
+### via pip
+
+The main way to install the package is via pip:
+
+```bash
+python3 -m pip install dolfinx-adjoint
+```
+
+### Development Install
+
+To install the latest development version directly from the repository, use:
+
+```bash
+python3 -m pip install git+[https://github.com/scientificcomputing/dolfinx-adjoint.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:
+
+```bash
+git clone [https://github.com/scientificcomputing/dolfinx-adjoint.git](https://github.com/scientificcomputing/dolfinx-adjoint.git)
+cd dolfinx-adjoint
+python3 -m pip install -e ".[all]"
+```
+
+### Docker
+
+A pre-built Docker image is automatically published by the CI. You can pull the nightly build which comes with DOLFINx and DOLFINx-Adjoint pre-installed:
+
+```bash
+docker run -ti ghcr.io/scientificcomputing/dolfinx-adjoint:v0.2.0
+```
+
+*(Note: Adjust the tag to the latest release or build).*
+
+## 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:
+<!-- #endregion -->
+
+```python
+import dolfinx
+from mpi4py import MPI
+import pyadjoint
+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")
+uh = dolfinx_adjoint.Function(V, name="State")
+
+# ... Define your UFL forms ...
+
+# Use overloaded solvers
+problem = dolfinx_adjoint.LinearProblem(a, L, u=uh, bcs=[bc])
+problem.solve()
+
+# Assemble the objective scalar using the overloaded assembly
+J_symbolic = 0.5 * ufl.inner(uh - d, uh - d) * 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()
+```
+
+<!-- #region -->
+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](https://scientificcomputing.github.io/dolfinx-adjoint).
+
+## Development and Testing
+
+Code formatting is enforced via `ruff` and type-checking via `mypy`. To set up your local development environment:
+
+```bash
+# 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](LICENSE) for more details.
+<!-- #endregion -->

dolfinx_adjoint-0.2.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
+
+[project]
+name = "dolfinx-adjoint"
+version = "0.2.0"
+description = "Automatic differentation compatible with DOLFINx"
+authors = [{ name = "Jørgen S. Dokken", email = "dokken@simula.no" }]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+dependencies = [
+      "fenics-dolfinx>=0.10.0",
+      "pyadjoint-ad>=2025.10.0",
+      "typing_extensions; python_version < '3.11'",
+]
+
+
+[project.optional-dependencies]
+test = ["pytest"]
+dev = ["pdbpp", "ipython", "mypy", "ruff"]
+docs = [
+      "jupyter-book<2.0",
+      "jupytext",
+      # "moola@git+https://github.com/funsim/moola.git",
+      "pandas",
+      "pyvista[all]>0.45",
+      "networkx",
+      "pygraphviz"
+]
+all = ["dolfinx_adjoint[test]", "dolfinx_adjoint[dev]", "dolfinx_adjoint[docs]"]
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+testpaths = ["tests"]
+
+[tool.mypy]
+ignore_missing_imports = true
+# Folders to exclude
+exclude = ["docs/", "build/"]
+# Folder to check with mypy
+files = ["src", "tests"]
+
+[tool.ruff]
+src = ["src", "docs", "tests", "examples"]
+line-length = 120
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+      # Pyflakes
+      "F",
+      # Pycodestyle
+      "E",
+      "W",
+      # isort
+      "I001",
+]
+
+
+[tool.ruff.lint.isort]
+known-first-party = ["dolfinx_adjoint"]
+known-third-party = [
+      "basix",
+      "dolfinx",
+      "ffcx",
+      "ufl",
+      "gmsh",
+      "numpy",
+      "pytest",
+      "pyadjoint",
+]
+section-order = [
+      "future",
+      "standard-library",
+      "mpi",
+      "third-party",
+      "first-party",
+      "local-folder",
+]
+
+[tool.ruff.lint.isort.sections]
+"mpi" = ["mpi4py", "petsc4py"]
+
+
+[tool.bumpversion]
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+tag = true
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+current_version = "0.2.0"
+
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+
+[[tool.bumpversion.files]]
+filename = "README.md"
+search = "ghcr.io/scientificcomputing/dolfinx-adjoint:v{current_version}"
+replace = "ghcr.io/scientificcomputing/dolfinx-adjoint:v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "Dockerfile"
+search = "ghcr.io/scientificcomputing/dolfinx-adjoint:v{current_version}"
+replace = "ghcr.io/scientificcomputing/dolfinx-adjoint:v{new_version}"

dolfinx_adjoint-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dolfinx_adjoint-0.2.0/src/dolfinx_adjoint/__init__.py

@@ -0,0 +1,37 @@
+"""Top-level package for dxa."""
+
+from importlib.metadata import metadata
+
+# Start annotation at import
+import pyadjoint as _pyad
+
+from .assembly import assemble_scalar, error_norm
+from .solvers import LinearProblem, NonlinearProblem
+from .types import Constant, Function
+from .types.function import assign
+
+meta = metadata("dolfinx_adjoint")
+__version__ = meta.get("Version")
+__license__ = meta.get("License")
+__author__ = meta.get("Author")
+__email__ = meta.get("Author-email")
+__program_name__ = meta.get("Name")
+
+
+_pyad.set_working_tape(_pyad.Tape())
+_pyad.continue_annotation()
+
+__all__ = [
+    "Constant",
+    "Function",
+    "LinearProblem",
+    "NonlinearProblem",
+    "assemble_scalar",
+    "assign",
+    "error_norm",
+    "__version__",
+    "__author__",
+    "__license__",
+    "__email__",
+    "__program_name__",
+]

dolfinx_adjoint-0.2.0/src/dolfinx_adjoint/assembly.py

@@ -0,0 +1,93 @@
+import typing
+
+from mpi4py import MPI
+
+import dolfinx
+import numpy
+import numpy.typing as npt
+import ufl
+from pyadjoint.overloaded_type import create_overloaded_object
+from pyadjoint.tape import annotate_tape, get_working_tape, stop_annotating
+
+from .blocks.assembly import AssembleBlock
+
+
+def assemble_scalar(form: ufl.Form, **kwargs):
+    """Assemble as scalar value from a form.
+
+    Args:
+        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.
+    """
+    ad_block_tag = kwargs.pop("ad_block_tag", None)
+
+    annotate = annotate_tape(kwargs)
+    with stop_annotating():
+        compiled_form = dolfinx.fem.form(
+            form,
+            jit_options=kwargs.pop("jit_options", None),
+            form_compiler_options=kwargs.pop("form_compiler_options", None),
+            entity_maps=kwargs.pop("entity_maps", None),
+        )
+
+        local_output = dolfinx.fem.assemble_scalar(compiled_form)
+        comm = compiled_form.mesh.comm
+        output = comm.allreduce(local_output, op=MPI.SUM)
+        assert isinstance(output, float)
+
+    output = create_overloaded_object(output)
+
+    if annotate:
+        block = AssembleBlock(form, ad_block_tag=ad_block_tag)
+
+        tape = get_working_tape()
+        tape.add_block(block)
+
+        block.add_output(output.block_variable)
+
+    return output
+
+
+def error_norm(
+    u_ex: ufl.core.expr.Expr,
+    u: ufl.core.expr.Expr,
+    norm_type=typing.Literal["L2", "H1"],
+    jit_options: typing.Optional[dict] = None,
+    form_compiler_options: typing.Optional[dict] = None,
+    entity_map: typing.Optional[dict[dolfinx.mesh.Mesh, npt.NDArray[numpy.int32]]] = None,
+    ad_block_tag: typing.Optional[str] = None,
+    annotate: bool = True,
+) -> float:
+    """Compute the error norm between the exact solution and the computed solution.
+
+    Args:
+        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.
+    """
+    diff = u_ex - u
+    norm = ufl.inner(diff, diff) * ufl.dx
+    if norm_type == "H1":
+        norm += ufl.inner(ufl.grad(diff), ufl.grad(diff)) * ufl.dx
+    return numpy.sqrt(
+        assemble_scalar(
+            norm,
+            jit_options=jit_options,
+            form_compiler_options=form_compiler_options,
+            entity_maps=entity_map,
+            ad_block_tag=ad_block_tag,
+            annotate=annotate,
+        )
+    )

dolfinx_adjoint-0.2.0/src/dolfinx_adjoint/blocks/__init__.py

@@ -0,0 +1,7 @@
+from .assembly import AssembleBlock
+from .function_assigner import FunctionAssignBlock
+
+__all__ = [
+    "AssembleBlock",
+    "FunctionAssignBlock",
+]

dolfinx_adjoint-0.2.0/src/dolfinx_adjoint/blocks/_vector.py

@@ -0,0 +1,77 @@
+import dolfinx
+import numpy as np
+import numpy.typing as npt
+
+
+class _SpecialVector(dolfinx.la.Vector):
+    """Workaround adding __iadd__ to `dolfinx.la.Vector`."""
+
+    def __init__(self, x, function_space: dolfinx.fem.FunctionSpace):
+        super().__init__(x)
+        self._function_space = function_space
+
+    def __iadd__(self, other):
+        self.array[:] += other.array[:]
+        return self
+
+    @property
+    def function_space(self) -> dolfinx.fem.FunctionSpace:
+        return self._function_space
+
+    @property
+    def x(self):
+        return self
+
+    @property
+    def name(self):
+        return "SpecialVector"
+
+
+def _vector(
+    map, bs: int, function_space: dolfinx.fem.FunctionSpace, dtype: npt.DTypeLike = np.float64
+) -> _SpecialVector:
+    """Create a distributed vector.
+
+    Args:
+        map: Index map the describes the size and distribution of the
+            vector.
+        bs: Block size.
+        dtype: The scalar type.
+
+    Returns:
+        A distributed vector.
+    """
+    if np.issubdtype(dtype, np.float32):
+        vtype = dolfinx.cpp.la.Vector_float32
+    elif np.issubdtype(dtype, np.float64):
+        vtype = dolfinx.cpp.la.Vector_float64
+    elif np.issubdtype(dtype, np.complex64):
+        vtype = dolfinx.cpp.la.Vector_complex64
+    elif np.issubdtype(dtype, np.complex128):
+        vtype = dolfinx.cpp.la.Vector_complex128
+    elif np.issubdtype(dtype, np.int8):
+        vtype = dolfinx.cpp.la.Vector_int8
+    elif np.issubdtype(dtype, np.int32):
+        vtype = dolfinx.cpp.la.Vector_int32
+    elif np.issubdtype(dtype, np.int64):
+        vtype = dolfinx.cpp.la.Vector_int64
+    else:
+        raise NotImplementedError(f"Type {dtype} not supported.")
+
+    return _SpecialVector(vtype(map, bs), function_space)
+
+
+def _create_vector(L: dolfinx.fem.Form, space: dolfinx.fem.FunctionSpace) -> _SpecialVector:
+    """Create a Vector that is compatible with a given linear form.
+
+    Args:
+        L: A linear form.
+
+    Returns:
+        A vector that the form can be assembled into.
+    """
+    # Can just take the first dofmap here, since all dof maps have the same
+    # index map in mixed-topology meshes
+    dofmap = L.function_spaces[0].dofmaps(0)  # type: ignore
+    assert space._cpp_object == L.function_spaces[0], "Function space mismatch when creating vector."
+    return _vector(dofmap.index_map, dofmap.index_map_bs, dtype=L.dtype, function_space=space)