# newton-raphson/spm2025 architecture

> Architecture diagram of the GitHub repository newton-raphson/spm2025, 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/newton-raphson/spm2025
- Repository: https://github.com/newton-raphson/spm2025

## Overview

This project is a high‐performance simulation framework (dendrite-kt) built in C++ that targets multi-dimensional computations (2D, 3D, 4D and experimental IBM modes) for solving partial differential equations via finite element methods in parallel. It tightly couples various external scientific libraries (PETSc for solving sparse linear systems via MPI, BLAS/LAPACK for linear algebra, libconfig for reading simulation parameters, etc.), and its internal structure is organized into multiple submodules covering geometry, mesh management, boundary handling, traversal algorithms, and checkpointing.

##### Main Components
- Build and Configuration Layer:
– CMake build scripts, toolchain configuration (using mpicc and mpicxx), and custom CMake modules (in the “cmake-modules” folder).
– Support for conditional builds (e.g. ENABLE_2D, ENABLE_3D, ENABLE_4D, IBM mode, TENSOR assembly) that indicate how the build is tuned.

- External Dependencies:
– PETSc (with inherent MPI support and an integrated build process) that is the backbone for parallel sparse solver routines.
– libconfig (for parsing configuration files with simulation parameters).
– BLAS, LAPACK, LAPACKE (for optimized linear algebra operations).
– Other external libraries (e.g., Dendro-KT, talylite, ray_tracing) that supplement or extend functionality via external modules in “external/”.

- Core Internal Modules:
– Core Simulation and Numerical Kernels: modules in “src” and “include” follow a modular design with directories for Boundary, Checkpoint, Geometry, Mesh, PETSc interfacing, SubDA (domain decomposition), and Traversal algorithms.
– These modules coordinate to set up the simulation domain, load parameters, construct the finite element mesh, apply boundary conditions, and carry out the solve (using PETSc’s solvers internally).
– Data structure headers (as seen under “include/”) define common types (e.g. Node and Mesh data, equations, vector/matrix operations) that are used across modules.

- Example and Testing Suites:
– A large “examples” directory with multiple simulation cases and regression tests (for SSHT, transient heat, various benchmarks, etc.) that demonstrate the functionality and help ensure the system remains stable.
– The “test” directory contains unit/regression tests (with CMakeLists.txt and dedicated source files) which validate simulation correctness.

- Projects and Specialized Applications:
– The “projects” directory hosts derivative projects (DeepTrace, Elasticity-SBM, variants of Navier-Stokes solvers, etc.) that build on the dendrite-kt framework.
– These projects show how the core modules can be extended or combined to tackle different simulation and analysis tasks.

- Supporting Scripts and Tools:

##### Lay Out Interactions and Data Flow
- At initialization, configuration files (processed via libconfig) supply simulation parameters that drive the setup.
- The build layer (CMake) organizes conditional compilation, linking the various modules and specifying external dependency paths.
- The core simulation modules (Mesh, Geometry, Boundary, and Traversal) ingest the simulation parameters to build the computational domain.
- When the simulation runs, PETSc (leveraging MPI) orchestrates the solution of sparse systems generated by the finite element discretization.
- Input/output functionalities (under IO/VTU, PETSc/IO, etc.) package simulation results for visualization or further post-processing.
- Regression tests (in examples and test directories) automatically invoke simulation runs and compare outputs against reference data.

##### Final Checklist
- Clearly labelled components for:
– Build/Configuration (CMake, toolchain, environment variables like PETSC_DIR, PETSC_ARCH, LIBCONFIG_DIR)
– External dependencies: PETSc with MPI, libconfig, BLAS, LAPACK, and any other external libraries.
– Core simulation modules (e.g., Geometry, Mesh, Boundary, Checkpoint, SubDA, Traversal).
– Examples/Regression Tests.
– Specialized projects/applications.
- Details like compile flags (e.g., ENABLE_2D/3D/4D switches) are captured as annotations that explain optional features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration
    subgraph "Build & Configuration"
        CB["CMake Build Scripts"]:::build
        TC["Toolchain & CMake Modules"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PETSC["PETSc (MPI)"]:::external
        LIBCONFIG["libconfig"]:::external
        BLAS["BLAS/LAPACK"]:::external
        EXT_LIB["Other External Libraries"]:::external
    end

    %% Core Simulation Framework
    subgraph "Core Simulation Framework"
        CONFIG["Configuration Parsing (libconfig)"]:::core
        GEOM["Geometry Module"]:::core
        MESH["Mesh Management"]:::core
        BOUND["Boundary Handling"]:::core
        CHECK["Checkpointing"]:::core
        TRAV["Traversal Algorithms"]:::core
        SUBDA["Subdomain Decomposition"]:::core
        DATA["Common Data Structures"]:::core
    end

    %% Example & Test Harness
    subgraph "Example & Test Harness"
        EXAMPLES["Examples Suite"]:::test
        TESTS["Testing Suite"]:::test
    end

    %% Projects & Specialized Applications
    subgraph "Projects & Specialized Applications"
        PROJECTS["Specialized Projects"]:::project
    end

    %% Supporting Scripts & Tools
    subgraph "Supporting Scripts & Tools"
        SCRIPTS["Utility Scripts"]:::scripts
    end

    %% Relationships - Build System influences Core Simulation and External Dependencies
    CB -->|"build"| GEOM
    CB -->|"build"| PETSC
    TC -->|"build"| GEOM
    TC -->|"build"| PETSC

    %% External Dependencies interaction
    LIBCONFIG -->|"provides"| CONFIG
    BLAS -->|"supplies"| PETSC
    EXT_LIB -->|"supplements"| PETSC

    %% Core Simulation Data Flow
    CONFIG -->|"init"| GEOM
    GEOM -->|"generates mesh"| MESH
    MESH -->|"defines"| BOUND
    MESH -->|"decomposes"| SUBDA
    BOUND -->|"guides"| TRAV

    %% Common Data Structures integration
    GEOM --> DATA
    MESH --> DATA
    BOUND --> DATA
    CHECK --> DATA
    TRAV --> DATA
    SUBDA --> DATA

    %% Core Simulation to External Solver
    TRAV -->|"solves via"| PETSC

    %% Simulation output directed to Examples and Testing
    PETSC -->|"outputs"| EXAMPLES
    PETSC -->|"outputs"| TESTS

    %% Data sharing to Specialized Projects
    DATA -->|"feeds"| PROJECTS

    %% Supporting Scripts influence on Example and Test harness
    SCRIPTS -->|"assists"| EXAMPLES
    SCRIPTS -->|"assists"| TESTS

    %% Styling classes
    classDef build fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef external fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef core fill:#ccccff,stroke:#000,stroke-width:2px;
    classDef test fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef project fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef scripts fill:#ccffff,stroke:#000,stroke-width:2px;

    %% Click Events
    click CB "https://github.com/newton-raphson/spm2025/blob/master/CMakeLists.txt"
    click TC "https://github.com/newton-raphson/spm2025/tree/master/cmake-modules"
    click PETSC "https://github.com/newton-raphson/spm2025/blob/master/include/PETSc/BoundaryConditions.h"
    click EXT_LIB "https://github.com/newton-raphson/spm2025/tree/master/external/"
    click GEOM "https://github.com/newton-raphson/spm2025/blob/master/include/Geometry/Geometry.h"
    click MESH "https://github.com/newton-raphson/spm2025/blob/master/include/Mesh/Mesh2D.h"
    click BOUND "https://github.com/newton-raphson/spm2025/blob/master/include/Boundary/DomainBoundary.h"
    click CHECK "https://github.com/newton-raphson/spm2025/blob/master/include/Checkpoint/Checkpointer.h"
    click TRAV "https://github.com/newton-raphson/spm2025/blob/master/include/Traversal/Traversal.h"
    click SUBDA "https://github.com/newton-raphson/spm2025/blob/master/include/SubDA/SubDomain.h"
    click DATA "https://github.com/newton-raphson/spm2025/blob/master/include/DataTypes.h"
    click EXAMPLES "https://github.com/newton-raphson/spm2025/tree/master/examples/"
    click TESTS "https://github.com/newton-raphson/spm2025/tree/master/test/"
    click PROJECTS "https://github.com/newton-raphson/spm2025/tree/master/projects/"
    click SCRIPTS "https://github.com/newton-raphson/spm2025/tree/master/scripts/"
```
