# fenics/dolfinx architecture

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

- Interactive diagram: https://gitdiagram.com/fenics/dolfinx
- Repository: https://github.com/fenics/dolfinx

## Overview

The DOLFINx project is a full-featured computational environment for solving finite element problems, split into a high-performance C++ core and a Python interface. The README alongside the detailed file tree clearly shows that the system’s purpose is to provide a modular and extensible problem‐solving environment (as part of FEniCSx) that integrates finite element method (FEM) capabilities with mesh handling, solver infrastructure, and advanced input/output facilities.

##### Main Components
- C++ Core: Represented by the “cpp” directory, which includes major submodules such as:
– dolfinx/common (logging, timing, utilities)
– dolfinx/fem (finite element method implementation, function spaces, assembly routines, solvers, boundary conditions)
– dolfinx/geometry (mesh generation and geometry utilities)
– dolfinx/graph (graph algorithms for mesh partitions)
– dolfinx/io (input/output for different file formats like XDMF, VTK, HDF5, ADIOS2)
– dolfinx/la (linear algebra modules interfacing with PETSc/SLEPc)
– dolfinx/mesh (mesh data structures and processing)
– dolfinx/nls (nonlinear solvers)
– dolfinx/refinement (mesh refinement capabilities)

- Python Interface: Found in the “python” directory. This part wraps the C++ core functionalities and exposes them in Python. It includes:
– The Python package (python/dolfinx) for user-facing APIs.
– Python wrappers (python/dolfinx/wrappers) that bridge C++ functions to Python.
– Demo scripts and tests that show how the interface is used.

- Build and Configuration Infrastructure:
– The provided CMakeLists.txt files, cmake modules, and vcpkg overlays in the “cpp” and “python” directories indicate a robust build system using CMake.
– CI/CD integration (files in .github/workflows and related docker configurations) that ensure cross-platform builds and tests.

- Docker and Deployment: The “docker” directory contains Dockerfiles and related configuration files to create end-user images, testing environments, and specialized build modes (real/complex builds).

##### Relationships and Interactions
- The Python interface is tightly coupled with the C++ core via a wrapper layer that exposes internal C++ functionalities to Python users.
- The various C++ modules interact internally. For example:
- FEM modules use mesh and geometry data structures.
- IO modules fetch mesh and function data from both FEM and mesh modules.
- Linear algebra modules interact with FEM and non-linear solvers; these in turn use PETSc/SLEPc as external dependencies.
- The build system (CMake) orchestrates compilation and integration of these modules, ensuring that dependencies between modules are resolved.
- CI workflows and Docker images provide automated testing, packaging, and deployment pipelines.

##### Architectural Patterns & Design Principles
- Modular Design: Both the C++ and Python parts are divided into clear modules (common, fem, geometry, graph, io, la, mesh, nls, refinement) that can be developed and maintained independently.
- Layered Architecture: There is a clear separation between the computational core (C++), the interface layer (Python wrappers), and the deployment/testing infrastructure (Docker, CI workflows).
- Separation of Concerns: Numerical methods, mesh handling, input/output, and linear algebra are dealt with in distinct parts of the repository.
- Extensibility: The well-structured directories (e.g., additional demos, tests, and documentation subdirectories) hint at a design that is intended to be extended, both by core developers and by external contributors.

##### Relevant Technologies, Frameworks, or Libraries
- Core dependencies include PETSc and SLEPc for solver operations and linear algebra.
- For IO, external libraries such as HDF5, ADIOS2, and VTK are likely involved.
- Development tools include CMake, vcpkg (for package management), and GitHub Actions for CI.
- The Python ecosystem: pip, conda (for build and installation), and pyvista for visualization.

## Diagram (Mermaid)

```mermaid
graph TD

  %% DOLFINx System high-level grouping
  subgraph "C++ Core"
    CppCommon["Common Module"]:::core
    CppFEM["FEM Module"]:::core
    CppGeometry["Geometry Module"]:::core
    CppGraph["Graph Module"]:::core
    CppIO["IO Module"]:::core
    CppLA["Linear Algebra Module"]:::core
    CppMesh["Mesh Module"]:::core
    CppNLS["Nonlinear Solvers Module"]:::core
    CppRefinement["Refinement Module"]:::core
  end

  subgraph "Python Interface"
    PyCore["Core Package"]:::interface
    PyWrapper["Wrapper Layer"]:::interface
  end

  subgraph "Build and Deployment"
    CppBuild["C++ Build System"]:::build
    PyBuild["Python Build System"]:::build
    CICD["CI/CD Infrastructure"]:::build
    Docker["Docker and Deployment"]:::build
  end

  %% Internal C++ Core interactions
  CppMesh -->|"provides_mesh"| CppFEM
  CppGeometry -->|"supplies_geometry"| CppFEM
  CppFEM -->|"assembles_using"| CppLA
  CppFEM -->|"requires_mesh"| CppMesh
  CppIO -->|"reads/writes"| CppFEM
  CppIO -->|"handles_mesh"| CppMesh
  CppNLS -->|"optimizes_using"| CppLA

  %% Python Interface to C++ Core connections
  PyWrapper -->|"wraps"| CppFEM
  PyCore -->|"interfaces_with"| PyWrapper

  %% Build and Deployment relationships
  CppBuild -->|"builds"| CppCommon
  PyBuild -->|"builds"| PyCore
  CICD -->|"triggers_build"| CppBuild
  CICD -->|"triggers_build"| PyBuild
  Docker -->|"deploys_through"| CICD

  %% Styling classes
  classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
  classDef interface fill:#ccffcc,stroke:#006600,stroke-width:2px;
  classDef build fill:#ccccff,stroke:#000099,stroke-width:2px;

  %% Click Events
  click CppCommon "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/common"
  click CppFEM "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/fem"
  click CppGeometry "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/geometry"
  click CppGraph "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/graph"
  click CppIO "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/io"
  click CppLA "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/la"
  click CppMesh "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/mesh"
  click CppNLS "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/nls"
  click CppRefinement "https://github.com/fenics/dolfinx/tree/main/cpp/dolfinx/refinement"
  click PyCore "https://github.com/fenics/dolfinx/tree/main/python/dolfinx"
  click PyWrapper "https://github.com/fenics/dolfinx/tree/main/python/dolfinx/wrappers"
  click CppBuild "https://github.com/fenics/dolfinx/blob/main/cpp/CMakeLists.txt"
  click PyBuild "https://github.com/fenics/dolfinx/blob/main/python/CMakeLists.txt"
  click CICD "https://github.com/fenics/dolfinx/tree/main/.github/workflows"
  click Docker "https://github.com/fenics/dolfinx/tree/main/docker"
```
