# ivanyashchuk/fecr architecture

> Architecture diagram of the GitHub repository ivanyashchuk/fecr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ivanyashchuk/fecr
- Repository: https://github.com/ivanyashchuk/fecr

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User/Client Code (NumPy, JAX, PyMC3, ChainRules.jl)"]:::client

    subgraph "FECR Core"
        CF["Conversion Functions (helpers)"]:::core
        Core["Core Functions (evaluate_primal, evaluate_pushforward, evaluate_pullback) (core)"]:::core
        BA["Backend Abstraction (_backends)"]:::core
        AD["AD Operations (dolfin-adjoint integration)"]:::external
        CF -->|"transforms-input"| Core
        Core -->|"calls"| BA
        Core -->|"triggers"| AD
    end

    subgraph "Finite Element Backends"
        FEN["FEniCS Integration (tests/fenics_backend)"]:::backend
        FIR["Firedrake Integration (tests/firedrake_backend)"]:::backend
    end

    A -->|"provides-input"| CF
    BA -->|"interfaces"| FEN
    BA -->|"interfaces"| FIR
    AD ---|"differentiation-flow"| Core

    click CF "https://github.com/ivanyashchuk/fecr/blob/master/fecr/helpers.py"
    click Core "https://github.com/ivanyashchuk/fecr/blob/master/fecr/core.py"
    click BA "https://github.com/ivanyashchuk/fecr/blob/master/fecr/_backends.py"
    click FEN "https://github.com/ivanyashchuk/fecr/tree/master/tests/fenics_backend"
    click FIR "https://github.com/ivanyashchuk/fecr/tree/master/tests/firedrake_backend"

    classDef client fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef core fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef backend fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef external fill:#FF9999,stroke:#333,stroke-width:2px;
```
