# tudo-math-ls3/feat3 architecture

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

- Interactive diagram: https://gitdiagram.com/tudo-math-ls3/feat3
- Repository: https://github.com/tudo-math-ls3/feat3

## Overview

Based on our analysis of the file tree and the README file, FEAT3 is a modular, open‐source finite element analysis library written in standard C++17. It is specialized for solving the incompressible Navier–Stokes equations (and related problems) using both conforming and non‐conforming finite element techniques. In addition, the project is designed for parallel execution (using MPI) and for offloading computations to GPUs via CUDA. The system is organized into several key components such as the core “kernel” (which is subdivided into numerous modules like assembly, analytic, geometry, cubature, solver, space, etc.), “control” modules (which include configuration settings, domain and time control, and mesh optimization settings), and numerous “applications” which serve as both demonstration and benchmark codes.

##### Main Components
- Kernel Library (Core Computational Engine):
– This includes submodules for assembly, analytic functions, geometry, cubature, solver routines, finite element spaces, transformation (trafo), mesh optimization, and other utilities.
- Control and Configuration:
– Modules dealing with domain control, time management, solver checkpointing, and various simulation settings.
- Applications & Benchmarks:
– Separate simulation applications (under “applications”, “area51”, “tutorials”) that use the kernel and control modules to set up and run simulations.
- Build System and Third-Party Integration:
– The build configuration (using CMake and custom configure scripts), third-party libraries (MPI, CUDA, MKL, etc.), and integration with external solver packages.
- Tools and Utilities:
– Mesh tools, matrix utilities, and I/O utilities (in the “tools”, “doxy_in”, and “test_system” directories) that support pre- and postprocessing as well as testing.

##### Relationships and Interactions
- The “applications” layer is built on top of the kernel and control libraries. These applications call into various solver routines and mesh handling functions to simulate physical problems.
- The “kernel” is the core where low-level numerical algorithms (assembly, cubature, analytic evaluation, geometry construction, etc.) reside. Internal dependencies exist – for example, the solver often depends on the assembly and geometry modules.
- The “control” module orchestrates simulation aspects like configuring the domain, applying boundary conditions, time stepping, and organizing checkpointing and statistics. It interfaces directly with both the kernel and the application layer.
- The build system and configuration layer integrate external dependencies (MPI, CUDA, third-party libraries) with the compile-time setup of the software. They ensure that the appropriate modules are built with the correct flags.
- Tools and utilities support these components by providing mesh generation, file conversion, visualization (VTK, SVG/EPS export), and additional debugging functions.

##### Important Architectural Patterns and Design Principles
- Modularity: Each major functionality (e.g., geometry, solver, assembly, control) is developed as a separate module; this separation is clearly reflected in the directory structure.
- Layered Architecture: There is a clear layering from the low-level kernel routines to the mid-level control configuration and finally to the high-level simulation applications and tools.
- Extensibility: The design shows the use of “factory” and “assembler” patterns in several subsystems (e.g., in the assembly and solver directories) which facilitate plugging in different algorithms or solver strategies.
- Platform-Specific Optimizations: The system supports MPI for distributed computations and uses CUDA offloading for accelerator-based performance in critical code paths.

##### Relevant Technologies and Frameworks
- C++17 as the programming language.
- CMake for configuring and building the project.
- MPI for parallel scale-out execution.
- CUDA for GPU-based acceleration.
- Integration with third-party libraries such as MKL, Hypre, SuperLU, and Zoltan (conditional on build options).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build System & External Integration Layer
    subgraph "Build System & External Integration"
        BS["Build System & External Integration"]:::build
    end

    %% Kernel Library (Core Computational Engine)
    subgraph "Kernel Library"
        KA["Assembly Module"]:::kernel
        KB["Analytic Module"]:::kernel
        KC["Geometry Module"]:::kernel
        KD["Cubature Module"]:::kernel
        KE["Solver Module"]:::kernel
        KF["Space Module"]:::kernel
        KG["Trafo Module"]:::kernel
        KH["Mesh Optimization Module"]:::kernel
    end

    %% Control and Configuration Layer
    subgraph "Control & Configuration"
        CA["Domain & Time Control"]:::control
        CB["Mesh Optimization Control"]:::control
    end

    %% Applications & Benchmarks Layer
    subgraph "Applications & Benchmarks"
        AA["Applications"]:::applications
        AB["Area51"]:::applications
        AC["Tutorials"]:::applications
    end

    %% Tools and Utilities
    subgraph "Tools & Utilities"
        TA["Tools & Utilities"]:::tools
        TB["Test System"]:::tools
        TC["Doxygen Input"]:::tools
        TD["Benchmark Tools"]:::tools
    end

    %% Relationships
    %% Build System configures Kernel and Control layers
    BS -->|"builds"| KA
    BS -->|"sets_up"| CA

    %% Control orchestrates Kernel computations
    CA -->|"orchestrates"| KA
    CA -->|"orchestrates"| KD
    CA -->|"orchestrates"| KH

    %% Applications use Control for simulation configuration
    AA -->|"calls"| CA
    AB -->|"calls"| CA
    AC -->|"calls"| CA

    %% Tools & Utilities support the Applications layer
    TA -->|"supports"| AA

    %% Additional interaction: Tools aiding Kernel postprocessing
    TA -->|"postprocesses"| KH

    %% Class definitions for styling
    classDef kernel fill:#B3E5FC,stroke:#039BE5,stroke-width:2px;
    classDef control fill:#C5E1A5,stroke:#8BC34A,stroke-width:2px;
    classDef applications fill:#FFF59D,stroke:#FBC02D,stroke-width:2px;
    classDef build fill:#FFCCBC,stroke:#FF5722,stroke-width:2px;
    classDef tools fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;

    %% Click Events for Kernel Library
    click KA "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/assembly"
    click KB "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/analytic"
    click KC "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/geometry"
    click KD "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/cubature"
    click KE "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/solver"
    click KF "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/space"
    click KG "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/trafo"
    click KH "https://github.com/tudo-math-ls3/feat3/tree/master/kernel/meshopt"

    %% Click Events for Control and Configuration
    click CA "https://github.com/tudo-math-ls3/feat3/tree/master/control/domain"
    click CB "https://github.com/tudo-math-ls3/feat3/tree/master/control/meshopt"

    %% Click Events for Applications & Benchmarks
    click AA "https://github.com/tudo-math-ls3/feat3/tree/master/applications/"
    click AB "https://github.com/tudo-math-ls3/feat3/tree/master/area51/"
    click AC "https://github.com/tudo-math-ls3/feat3/tree/master/tutorials/"

    %% Click Event for Build System & External Integration
    click BS "https://github.com/tudo-math-ls3/feat3/tree/master/build_system/"

    %% Click Events for Tools and Utilities
    click TA "https://github.com/tudo-math-ls3/feat3/tree/master/tools/"
    click TB "https://github.com/tudo-math-ls3/feat3/tree/master/test_system/"
    click TC "https://github.com/tudo-math-ls3/feat3/tree/master/doxy_in/"
    click TD "https://github.com/tudo-math-ls3/feat3/tree/master/benchmarks/"
```
