# foamscience/blastamr architecture

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

- Interactive diagram: https://gitdiagram.com/foamscience/blastamr
- Repository: https://github.com/foamscience/blastamr

## Overview

##### Project type and purpose
- This is a C++ library/module for OpenFOAM providing load-balanced adaptive mesh refinement (AMR) on polyhedral meshes, extracted from `blastFoam`.
- It supplies new dynamic-mesh and error-estimator components, solvers, utilities, test cases, and tutorials to integrate with an existing OpenFOAM installation.

##### File structure
- Top-level directories:
- `applications/solvers` – custom solvers (e.g., `reactingDyMFoam`) that link against the AMR library.
- `applications/utilities` – helper utilities (e.g., `reconstructParMesh`, `updateMesh`).
- `src` – core library modules, organized into subfolders:
– `dynamicFvMesh`, `dynamicMesh` (mesh adaptation & balancing)
– `errorEstimators` (various refinement criteria)
- `etc` – code templates for dynamic code generation (e.g., `codedErrorEstimatorTemplate`).
- `tests` – unit/integration tests for mesh adaptivity components and sample test‐cases.
- `tutorials` – end-to-end OpenFOAM case setups demonstrating usage.
- Build files: `Allwmake`, per‐module `Make` directories with `files` and `options` for OpenFOAM’s build system.

##### README for additional insights
- Describes library purpose: load-balanced AMR integration into ESI (openfoam.com) builds.
- Highlights supported features (2D/3D, polyhedral meshes), unimplemented features (particle cloud balancing), and build process via `$FOAM_USER_LIBBIN`.

a. Main components
- OpenFOAM Core (external dependency)
- blastAMR Library
– Dynamic Mesh Manager
· Mesh Refiner & Balancer
· Location Mapper & Mesh Tools
– Error Estimator Suite
· Coded, gradient, delta, etc. selectors
– Code-generation Templates (dynamicCode)
- Applications
– Custom Solvers (link to blastAMR + OpenFOAM)
– Utilities (mesh reconstruction/update)
- Test Harness (foamUT)
- Tutorials (case directories, driven by shell scripts `Allrun`)

b. Relationships & data flow
- Solvers invoke Dynamic Mesh Manager at runtime to refine/coarsen mesh based on error estimators.
- Error Estimators feed refinement criteria into Mesh Refiner.
- Code-generation templates produce custom estimator code compiled into the AMR library.
- Utilities can be run pre-/post-simulation to manipulate partitioned mesh.
- Build system (Allwmake + Makefiles) compiles `src` into shared libs under `$FOAM_USER_LIBBIN`, then links into applications.
- Tests & tutorials consume the library and validate behavior.

c. Architectural patterns & design principles
- Modular C++ library pattern: each capability (mesh adaptivity, error estimation, utilities, solvers) in its own namespace/folder.
- Plugin pattern via Make/options templates—OpenFOAM style dynamic loading of new solvers/utilities.
- Separation of concerns: Static code generation (`etc`), core refinement logic (`src`), user-facing applications (`applications`).
- Test-driven development: dedicated `tests` folder exercising individual modules.

d. Key technologies & frameworks
- C++17 (or as required by OpenFOAM version)
- OpenFOAM build system (Allwmake, custom Make/options files)
- foamUT testing framework
- GitHub Actions for CI (of2006, of2206, of2212 workflows)

##### Final advice
- Every folder’s role: Modules (`src`), user‐facing binaries (`applications`), support scripts (`etc`), validation layers (`tests`, `tutorials`).
- Keep labels concise but precise; avoid listing every file—group by functionality.
- Data/control flow at runtime (mesh → estimator → refiner → updated mesh) and build‐time dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    OFCore["OpenFOAM Core"]:::external

    subgraph "blastAMR Library"
        subgraph "Dynamic Mesh Manager"
            DM1["dynamicFvMesh"]:::core
            subgraph "Mesh Adaptation & Balancing"
                DM2["dynamicMesh"]:::core
                subgraph "Mesh Refiner & Balancer"
                    MR1["fvMeshRefiner"]:::core
                    MR2["fvMeshBalance"]:::core
                    MR3["RefineBalanceMeshObject"]:::core
                end
                subgraph "Location Mapper & Mesh Tools"
                    LM["locationMapper"]:::core
                    MT["meshTools"]:::core
                end
            end
        end
        subgraph "Error Estimator Suite"
            EE["errorEstimators"]:::core
        end
        subgraph "Code-generation Templates"
            CGC["codedErrorEstimatorTemplate.C"]:::core
            CGH["codedErrorEstimatorTemplate.H"]:::core
        end
    end

    subgraph "Applications"
        SOL["reactingDyMFoam"]:::applications
        UTIL1["reconstructParMesh"]:::applications
        UTIL2["updateMesh"]:::applications
    end

    subgraph "Tests & Tutorials"
        TH["foamUT Tests"]:::tests
        TC["Test Cases"]:::tests
        TU["Tutorials"]:::tests
    end

    BS["Build System"]:::build

    OFCore -->|"API usage"| DM1
    OFCore -->|"API usage"| EE
    BS -->|"compiles"| DM1
    BS -->|"compiles"| DM2
    BS -->|"compiles"| EE
    BS -->|"builds"| SOL
    BS -->|"builds"| UTIL1
    BS -->|"builds"| UTIL2
    BS -->|"builds"| TH
    BS -->|"builds"| TU

    DM1 -->|"runtime call"| MR1
    DM1 -->|"runtime call"| MR2
    DM1 -->|"runtime call"| MR3
    DM1 -->|"runtime call"| LM
    DM1 -->|"runtime call"| MT

    EE -->|"refinement criteria"| DM1
    CGC -->|"code generation"| EE
    CGH -->|"code generation"| EE

    SOL -->|"link-time"| DM1
    UTIL1 -->|"runtime"| DM1
    UTIL2 -->|"runtime"| DM1
    TH -->|"test execution"| DM1
    TU -->|"script run"| SOL

    click DM1 "https://github.com/foamscience/blastamr/tree/master/src/dynamicFvMesh"
    click DM2 "https://github.com/foamscience/blastamr/tree/master/src/dynamicMesh"
    click MR1 "https://github.com/foamscience/blastamr/tree/master/src/dynamicMesh/fvMeshRefiner"
    click MR2 "https://github.com/foamscience/blastamr/tree/master/src/dynamicMesh/fvMeshBalance"
    click MR3 "https://github.com/foamscience/blastamr/tree/master/src/dynamicMesh/RefineBalanceMeshObject"
    click LM "https://github.com/foamscience/blastamr/tree/master/src/dynamicMesh/locationMapper"
    click MT "https://github.com/foamscience/blastamr/tree/master/src/dynamicMesh/meshTools"
    click EE "https://github.com/foamscience/blastamr/tree/master/src/errorEstimators"
    click CGC "https://github.com/foamscience/blastamr/blob/master/etc/codeTemplates/dynamicCode/codedErrorEstimatorTemplate.C"
    click CGH "https://github.com/foamscience/blastamr/blob/master/etc/codeTemplates/dynamicCode/codedErrorEstimatorTemplate.H"
    click SOL "https://github.com/foamscience/blastamr/tree/master/applications/solvers/combustion/reactingDyMFoam"
    click UTIL1 "https://github.com/foamscience/blastamr/tree/master/applications/utilities/reconstructParMesh"
    click UTIL2 "https://github.com/foamscience/blastamr/tree/master/applications/utilities/updateMesh"
    click TH "https://github.com/foamscience/blastamr/tree/master/tests/adaptiveFvMeshTests"
    click TC "https://github.com/foamscience/blastamr/tree/master/tests/testCases"
    click TU "https://github.com/foamscience/blastamr/tree/master/tutorials/"
    click BS "https://github.com/foamscience/blastamr/tree/master/Allwmake"

    classDef external fill:#dddddd,stroke:#333333,color:#333333
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef applications fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef tests fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef build fill:#e1bee7,stroke:#8e24aa,color:#4a148c
```
