How ivanyashchuk/fecr works
Main Components
• Frontend/Client Code: User code or external libraries (like JAX, PyMC3/Theano, Julia’s ChainRules.jl) that invoke fecr functionality.
• FECR Core Library: The central module (located in the fecr/ directory) that provides functions such as:
• Conversion between NumPy and FEniCS/Firedrake objects (“to_numpy” and “from_numpy”).
• Evaluating the primal solution (via evaluate_primal).
• Propagating derivatives in reverse (evaluate_pullback) and forward modes (evaluate_pushforward).
• Backend Integrations:
• FEniCS: One branch of functionality and tests in tests/fenics_backend, which interacts with FEniCS.
• Firedrake: Another branch of functionality and tests in tests/firedrake_backend, interfacing with Firedrake.
• Automatic Differentiation and Adjoint Framework: Underlying modules like dolfin-adjoint (pyadjoint) that provide AD capabilities to the finite element solver models.
Relationships and Interactions
• Data/Control Flow:
• The client code sends NumPy input data which is converted into the appropriate FEniCS/Firedrake types within the fecr layer.
• The fecr core function (e.g., evaluate_primal) wraps a finite element solver call, capturing a computational graph along the way.
• Post-solution, the graph is then used to perform differentiation operations by either propagating sensitivities from inputs to outputs (pushforward) or vice versa (pullback).
• Interaction with External Libraries:
• The FECR library is designed as a bridge between the “worlds” of conventional numerical Python solutions and finite element solvers, making extensive use of the established AD and finite element frameworks.
Architectural Patterns and Design Principles
• Separation of Concerns: Clear division between the conversion layer, solver execution, and AD graph manipulation.
• Adapter/Bridge Pattern: Serving as an intermediary that “translates” between NumPy arrays and complex finite element objects while abstracting away the differences between FEniCS and Firedrake.
• Test-Driven Verification: Tests are organized in a dedicated folder, split by backend, further emphasizing modular, interchangeable components.