# firedrakeproject/firedrake architecture

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

- Interactive diagram: https://gitdiagram.com/firedrakeproject/firedrake
- Repository: https://github.com/firedrakeproject/firedrake

## Overview

##### Project type and purpose
- Firedrake is not a monolithic web app or microservice suite but a domain-specific, full-stack scientific computing toolchain.
- Its purpose is to take a high-level variational/PDE description (in Python/UFL) and automatically generate/compile efficient low-level code (C/C++ via Cython, PETSc) to solve that PDE in parallel on CPUs.

##### File structure
- Top-level directories denote layers of the toolchain and supporting infrastructure:
– firedrake/         ← core Python API, user-facing constructs (FunctionSpace, Mesh, Solver)
– pyop2/             ← parallel loop abstraction, intermediate representation (IR), scheduling
– tsfc/              ← UFL→GEM→low-level C kernel compiler frontend
– tinyasm/           ← tiny reference assembler
– demos/ docs/ tests/ ← examples, documentation, CI test suite
– docker/ scripts/ CI workflows ← packaging, containerization, automation
- Configuration and build files: setup.py, pyproject.toml, Makefile, requirements-*.txt, .github/workflows/*

##### README for additional insights
- “Automated system for portable solution of PDEs using FEM.”
- High-performance code generation on CPUs.
- Website reference: points to architectural overviews in the docs.

##### Main components and interactions (to represent
a. User layer
– Python scripts / demos invoking Firedrake API
b. Frontend / DSL
– UFL (Unified Form Language) expressions → passed into TSFC
– Firedrake’s Python API (firedrake/*.py)
c. Compiler layer
– TSFC: transforms UFL → GEM → C kernel code (uses COFFEE optimizations)
– tinyasm: optional assembler backend
d. Parallel execution / IR
– PyOP2: takes generated kernels + mesh data → constructs parallel loops (parloops) → schedules to MPI/OpenMP
e. Low-level backends
– Cython wrappers → PETSc solvers, HDF5 I/O, VTK output
– External operators / machine-learning bridges (JAX, PyTorch)
f. Supporting services
– Checkpointing, logging, parameter management, visualization outputs (Paraview, matplotlib)
– Testing harness (pytest suite under tests/)
g. Packaging & CI
– Docker images, GitHub Actions workflows, installation scripts

##### Architectural patterns & design principles
- Layered architecture: clearly separated DSL → compiler → runtime → backends
- Plugin/extension points: external_operators, preconditioners, ML interfacing under firedrake/
- Code-generation pipeline: UFL → GEM → C → Cython → binary
- Parallelism abstraction: PyOP2 hides MPI/OpenMP details behind parloop API
- Strict separation of concerns: each subpackage has a single responsibility

##### Don’t forget
- Component version or directory reference if desired (e.g., firedrake/, pyop2/, tsfc/).
- A footnote for CI/docker/scripts to illustrate the packaging/deployment side.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        User["User script / demos"]:::user
    end
    click User "https://github.com/firedrakeproject/firedrake/tree/master/demos/"

    %% Frontend / DSL
    subgraph "Frontend / DSL"
        API["Firedrake Python API"]:::frontend
    end
    click API "https://github.com/firedrakeproject/firedrake/tree/master/firedrake/"

    %% Compiler Layer
    subgraph "Compiler Layer"
        TSFC["TSFC compiler\n(UFL→GEM→C)"]:::compiler
        TinyASM["TinyASM (optional assembler)"]:::compiler
    end
    click TSFC "https://github.com/firedrakeproject/firedrake/tree/master/tsfc/"
    click TinyASM "https://github.com/firedrakeproject/firedrake/tree/master/tinyasm/"

    %% Runtime / IR
    subgraph "Runtime / IR"
        PyOP2["PyOP2 parloop engine"]:::runtime
    end
    click PyOP2 "https://github.com/firedrakeproject/firedrake/tree/master/pyop2/"

    %% Backends
    subgraph "Low-level Backends"
        CY["Cython / PETSc backend"]:::backend
        PETSc["PETSc solvers & I/O"]:::backend
        Results["Results (HDF5, VTK, Matplotlib)"]:::backend
    end
    click CY "https://github.com/firedrakeproject/firedrake/tree/master/firedrake/cython/"
    click PETSc "https://github.com/firedrakeproject/firedrake/blob/master/firedrake/cython/hdf5interface.pyx"
    click Results "https://github.com/firedrakeproject/firedrake/tree/master/firedrake/output/"

    %% Plugins & Utilities
    subgraph "Plugins & Utilities"
        ExtOps["External Operators & ML bridges"]:::util
        Prec["Preconditioners"]:::util
        CPLog["Checkpointing & Logging"]:::util
        Params["Parameter Management"]:::util
    end
    click ExtOps "https://github.com/firedrakeproject/firedrake/tree/master/firedrake/external_operators/"
    click ExtOps "https://github.com/firedrakeproject/firedrake/tree/master/firedrake/ml/"
    click Prec "https://github.com/firedrakeproject/firedrake/tree/master/firedrake/preconditioners/"
    click CPLog "https://github.com/firedrakeproject/firedrake/blob/master/firedrake/checkpointing.py"
    click CPLog "https://github.com/firedrakeproject/firedrake/blob/master/firedrake/logging.py"
    click Params "https://github.com/firedrakeproject/firedrake/blob/master/firedrake/parameters.py"

    %% User Guidance & CI
    subgraph "User Guidance & CI"
        Docs["Documentation"]:::util2
        Tests["Testing Harness"]:::util2
        CI["Packaging & CI workflows"]:::util2
        Install["Installation & Build"]:::util2
    end
    click Docs "https://github.com/firedrakeproject/firedrake/tree/master/docs/"
    click Docs "https://github.com/firedrakeproject/firedrake/tree/master/docs/source/"
    click Tests "https://github.com/firedrakeproject/firedrake/tree/master/tests/"
    click CI "https://github.com/firedrakeproject/firedrake/tree/master/docker/"
    click CI "https://github.com/firedrakeproject/firedrake/tree/master/.github/workflows/"
    click Install "https://github.com/firedrakeproject/firedrake/blob/master/setup.py"
    click Install "https://github.com/firedrakeproject/firedrake/blob/master/pyproject.toml"
    click Install "https://github.com/firedrakeproject/firedrake/tree/master/Makefile"
    click Install "https://github.com/firedrakeproject/firedrake/tree/master/scripts/"

    %% Main data flow
    User -->|"UFL forms"| API
    API -->|"Form data + mesh"| TSFC
    TSFC -->|"C kernel code"| PyOP2
    PyOP2 -->|"Parallel loops (MPI/OpenMP)"| CY
    CY -->|"Solve & I/O"| Results

    %% Optional paths
    TSFC -.->|"assembly"| TinyASM -.->|"asm output"| PyOP2
    ExtOps -.->|"custom kernels"| PyOP2
    Prec -.->|"preconditioners"| CY
    CPLog -.->|"logging/checkpoint"| CY
    Params -.->|"config"| API

    %% Legend & styles
    classDef user fill:#CCE5FF,stroke:#66A3FF,color:#000;
    classDef frontend fill:#CCE5FF,stroke:#3399FF,color:#000;
    classDef compiler fill:#FFF2CC,stroke:#FFD966,color:#000;
    classDef runtime fill:#D5E8D4,stroke:#82B366,color:#000;
    classDef backend fill:#F8CECC,stroke:#EA9999,color:#000;
    classDef util fill:#EDEDED,stroke:#BFBFBF,color:#000;
    classDef util2 fill:#F2F2F2,stroke:#A6A6A6,color:#000;
```
