# jd26/formopt architecture

> Architecture diagram of the GitHub repository jd26/formopt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jd26/formopt
- Repository: https://github.com/jd26/formopt

## Overview

##### Main components
a. Front-end clients
– Jupyter notebooks (Tutorial.ipynb, Examples.ipynb, Elasticity.ipynb)
– CLI scripts (test.py, load.py, plots.py)
b. Core library
– models.py (problem definitions: elasticity, heat, etc.)
– load.py / plots.py (I/O & post-processing)
c. External engines & services
– FEniCSx (dolfinx) MPI‐based PDE assembly & solver
– pygmsh (mesh generation)
– h5py (HDF5 file I/O)
– PyVista (visualization)
d. Data storage
– File system: results/ (per-test directories with out.txt and ParaView .pvsm files)
– Git repo + docs/ + tex/ for documentation and manuscript sources

##### Relationships & data flows
– Notebooks/scripts invoke the Core library APIs
– Core library requests mesh from pygmsh → hands mesh to FEniCSx
– FEniCSx distributes mesh & fields across MPI ranks (data parallel), or Core spawns tasks (task parallel)
– Intermediate and final results written via h5py + plain text → stored under results/
– load.py & plots.py read these results → generate plots or ParaView state files → saved back to disk

##### Architectural patterns & design principles
– Modular pipeline: geometry → solver → optimization → I/O
– Strategy‐style parallelism: three interchangeable modes (data, task, mixed) controlled by a single entry point in formopt.py
– Separation of concerns: models.py only defines PDE specifications; formopt.py drives optimization; load/plots handle visualization

##### Technologies & frameworks
– Python 3.11, numpy, scipy, matplotlib
– FEniCSx 0.9 (dolfinx) + mpi4py
– pygmsh, h5py, PyVista
– Jupyter, MkDocs for docs, LaTeX for manuscript

## Diagram (Mermaid)

```mermaid
graph TB
    %% Front-End Clients
    subgraph "Front-End Clients"
        direction TB
        NB1["Tutorial.ipynb"]:::frontend
        NB2["Examples.ipynb"]:::frontend
        NB3["Elasticity.ipynb"]:::frontend
        CLI1["test.py"]:::frontend
        CLI2["load.py (post)"]:::frontend
        CLI3["plots.py (post)"]:::frontend
        CLI4["Elasticity.py"]:::frontend
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        OPT["formopt.py"]:::core
        subgraph "Parallel Execution Manager"
            DP["Data Parallel"]:::core
            TP["Task Parallel"]:::core
            MP["Mixed Parallel"]:::core
        end
        MOD["models.py"]:::core
        IO["load.py"]:::io
        PLOT["plots.py"]:::io
    end

    %% External Engines & Services
    subgraph "External Engines & Services"
        direction TB
        MG["Mesh Generator (pygmsh)"]:::external
        SOLV["PDE Solver (FEniCSx)"]:::external
        MPI["MPI / mpi4py"]:::external
        VIS["Visualization (PyVista)"]:::external
        H5EXT["HDF5 I/O (h5py)"]:::external
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        RES["results/"]:::storage
    end

    %% Documentation & Manuscript
    subgraph "Documentation"
        direction TB
        MK["mkdocs.yml & docs/"]:::docs
        LATEX["fead/Manuscript.tex & tex/"]:::docs
    end

    %% Connections
    NB1 -->|"uses"| OPT
    NB2 -->|"uses"| OPT
    NB3 -->|"uses"| OPT
    CLI1 -->|"invokes"| OPT
    CLI4 -->|"invokes"| OPT

    OPT -->|"mesh request"| MG
    MG -->|"mesh"| SOLV
    SOLV -->|"field solutions"| OPT

    OPT -->|"write HDF5"| H5EXT
    H5EXT -->|"store files"| RES
    OPT -->|"write results"| RES

    CLI2 -->|"read/write"| RES
    CLI3 -->|"read/write"| RES

    OPT --> DP
    OPT --> TP
    OPT --> MP

    %% Click Events
    click NB1 "https://github.com/jd26/formopt/blob/main/code/Tutorial.ipynb"
    click NB2 "https://github.com/jd26/formopt/blob/main/code/Examples.ipynb"
    click NB3 "https://github.com/jd26/formopt/blob/main/code/Elasticity.ipynb"
    click CLI1 "https://github.com/jd26/formopt/blob/main/code/test.py"
    click CLI2 "https://github.com/jd26/formopt/blob/main/code/load.py"
    click CLI3 "https://github.com/jd26/formopt/blob/main/code/plots.py"
    click CLI4 "https://github.com/jd26/formopt/blob/main/code/Elasticity.py"
    click OPT "https://github.com/jd26/formopt/blob/main/code/formopt.py"
    click MOD "https://github.com/jd26/formopt/blob/main/code/models.py"
    click IO "https://github.com/jd26/formopt/blob/main/code/load.py"
    click PLOT "https://github.com/jd26/formopt/blob/main/code/plots.py"
    click RES "https://github.com/jd26/formopt/tree/main/results/"
    click MK "https://github.com/jd26/formopt/blob/main/mkdocs.yml"
    click LATEX "https://github.com/jd26/formopt/tree/main/fead/"

    %% Styles
    classDef frontend fill:#ffeb99,stroke:#333,stroke-width:1px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef io fill:#ffd9b3,stroke:#333,stroke-width:1px;
    classDef external fill:#d5f5e3,stroke:#333,stroke-width:1px;
    classDef storage fill:#e6ccff,stroke:#333,stroke-width:1px;
    classDef docs fill:#f2f2f2,stroke:#333,stroke-width:1px;
```
