{"id":21120253,"url":"https://github.com/ivanyashchuk/fecr","last_synced_at":"2025-07-08T20:31:33.751Z","repository":{"id":54265155,"uuid":"308649406","full_name":"IvanYashchuk/fecr","owner":"IvanYashchuk","description":"Easy interoperability with Automatic Differentiation libraries through NumPy interface to Firedrake and FEniCS","archived":false,"fork":false,"pushed_at":"2023-11-12T11:58:12.000Z","size":52,"stargazers_count":15,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-04T10:21:21.329Z","etag":null,"topics":["automatic-differentiation","dolfin-adjoint","fem","fenics","firedrake"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IvanYashchuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-30T14:10:09.000Z","updated_at":"2025-01-24T20:59:46.000Z","dependencies_parsed_at":"2023-01-20T11:51:00.059Z","dependency_job_id":null,"html_url":"https://github.com/IvanYashchuk/fecr","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/IvanYashchuk/fecr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvanYashchuk%2Ffecr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvanYashchuk%2Ffecr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvanYashchuk%2Ffecr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvanYashchuk%2Ffecr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IvanYashchuk","download_url":"https://codeload.github.com/IvanYashchuk/fecr/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IvanYashchuk%2Ffecr/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264343601,"owners_count":23593756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automatic-differentiation","dolfin-adjoint","fem","fenics","firedrake"],"created_at":"2024-11-20T03:05:52.106Z","updated_at":"2025-07-08T20:31:33.492Z","avatar_url":"https://github.com/IvanYashchuk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Finite Element Chain Rules \u0026middot; [![Build FEniCS](https://github.com/ivanyashchuk/fecr/workflows/FEniCS/badge.svg)](https://github.com/ivanyashchuk/fecr/actions?query=workflow%3AFEniCS+branch%3Amaster) [![Build Firedrake](https://github.com/ivanyashchuk/fecr/workflows/Firedrake/badge.svg)](https://github.com/ivanyashchuk/fecr/actions?query=workflow%3AFiredrake+branch%3Amaster) [![codecov](https://codecov.io/gh/IvanYashchuk/fecr/branch/master/graph/badge.svg?token=5TCRI7OT6E)](https://codecov.io/gh/IvanYashchuk/fecr)\n\nEasy interoperability with Automatic Differentiation libraries through NumPy interface to Firedrake and FEniCS.\n\n## Overview\nThis package provides a high-level interface for evaluating derivatives of [FEniCS](http://fenicsproject.org) and [Firedrake](http://firedrakeproject.org/) models.\nIt is intended to be used as the backend for extending Automatic Differentiation (AD) libraries to support FEniCS and Firedrake solvers.\n\nAutomatic tangent linear and adjoint solvers for FEniCS/Firedrake problems are derived with [dolfin-adjoint/pyadjoint](http://www.dolfin-adjoint.org/en/latest/).\nThese solvers make it possible to use forward and reverse modes Automatic Differentiation with FEniCS/Firedrake.\n\nThis package is used for building bridges between FEniCS/Firedrake and:\n* JAX in [jax-fenics-adjoint](https://github.com/IvanYashchuk/jax-fenics-adjoint/),\n* PyMC3 (Theano) in [fenics-pymc3](https://github.com/IvanYashchuk/fenics-pymc3),\n* Julia's ChainRules.jl in [PyFenicsAD.jl](https://github.com/IvanYashchuk/PyFenicsAD.jl).\n\nCurrent limitations:\n* Composition of forward and reverse modes for higher-order derivatives is not implemented yet.\n* Differentiation with respect to mesh coordinates is not implemented yet.\n\n## API\nThe package includes 5 functions:\n\n - two functions for converting between NumPy and FEniCS/Firedrake: `to_numpy`, `from_numpy`,\n - `evaluate_primal` - computes the output of a FEniCS/Firedrake function and saves a corresponding computational graph,\n - `evaluate_pullback` - propagates the derivative information from outputs to inputs (reverse-mode AD),\n - `evaluate_pushforward` - propagates the derivative information from inputs to outputs (forward-mode AD).\n\n## Example\nHere is the demonstration of solving the [Poisson's PDE](https://en.wikipedia.org/wiki/Poisson%27s_equation)\non the 2D square domain and calculating the result of multiplying a vector with the solution Jacobian matrix (_du/df_) using the reverse mode Automatic Differentiation.\n```python\nimport numpy as np\n\nimport firedrake\nimport firedrake_adjoint\nimport ufl\n\nfrom functools import partial\n\nfrom fecr import evaluate_primal, evaluate_pullback\nfrom fecr import from_numpy\n\n# Create mesh for the unit square domain\nn = 10\nmesh = firedrake.UnitSquareMesh(n, n)\n\n# Define discrete function spaces and functions\nV = firedrake.FunctionSpace(mesh, \"CG\", 1)\nW = firedrake.FunctionSpace(mesh, \"DG\", 0)\n\n# Define Firedrake template representation of NumPy input\ntemplates = (firedrake.Function(W),)\n\n# This function takes Firedrake types as arguments and returns a Firedrake Function (solution)\ndef firedrake_solve(f):\n    # This function inside should be traceable by firedrake_adjoint\n    u = firedrake.Function(V, name=\"PDE Solution\")\n    v = firedrake.TestFunction(V)\n    inner, grad, dx = ufl.inner, ufl.grad, ufl.dx\n    F = (inner(grad(u), grad(v)) - f * v) * dx\n    bcs = [firedrake.DirichletBC(V, 0.0, \"on_boundary\")]\n    firedrake.solve(F == 0, u, bcs)\n    return u\n\n# Let's build a decorator which transforms NumPy input to Firedrake types input\n# and returns NumPy representation of Firedrake output\nnumpy_firedrake_solve = partial(evaluate_primal, firedrake_solve, templates)\n\n# Let's create a vector of ones with size equal to the number of cells in the mesh\nf = np.ones(W.dim())\nu = numpy_firedrake_solve(f)[0] # u is a NumPy array now\nu_firedrake = from_numpy(u, firedrake.Function(V)) # we need to explicitly provide template function for conversion\n\n# Now let's evaluate the vector-Jacobian product\nnumpy_output, firedrake_output, firedrake_inputs, tape = numpy_firedrake_solve(f)\ng = np.ones_like(numpy_output)\n\n# `vjp_out` is the result of (implicitly) multiplying the vector `g` with the solution Jacobian du/df\nvjp_out = evaluate_pullback(firedrake_output, firedrake_inputs, tape, g)\n```\n\nCheck the `tests/` folder for the additional usage examples.\n\n## Installation\nFirst install [FEniCS](https://fenicsproject.org/download/) or [Firedrake](https://firedrakeproject.org/download.html).\nThen install [dolfin-adjoint](http://www.dolfin-adjoint.org/en/latest/) for FEniCS with:\n\n    python -m pip install git+https://github.com/dolfin-adjoint/pyadjoint.git@2023.0.0\n\nor for Firedrake with:\n\n    python -m pip install git+https://github.com/dolfin-adjoint/pyadjoint.git@master\n\nThen install [fecr](https://github.com/IvanYashchuk/fecr) with:\n\n    python -m pip install git+https://github.com/IvanYashchuk/fecr@master\n\n\n## Reporting bugs\n\nIf you found a bug, create an [issue].\n\n[issue]: https://github.com/IvanYashchuk/fecr/issues/new\n\n## Asking questions and general discussion\n\nIf you have a question or anything else, create a new [discussion]. Using issues is also fine!\n\n[discussion]: https://github.com/IvanYashchuk/fecr/discussions/new\n\n## Contributing\n\nPull requests are welcome from everyone.\n\nFork, then clone the repository:\n\n    git clone https://github.com/IvanYashchuk/fecr.git\n\nMake your change. Add tests for your change. Make the tests pass:\n\n    pytest tests/firedrake_backend  # or pytest tests/fenics_backend\n\nCheck the formatting with `black` and `flake8`. Push to your fork and [submit a pull request][pr].\n\n[pr]: https://github.com/IvanYashchuk/fecr/pulls\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanyashchuk%2Ffecr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivanyashchuk%2Ffecr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanyashchuk%2Ffecr/lists"}