# saeedvdi/golem architecture

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

- Interactive diagram: https://gitdiagram.com/saeedvdi/golem
- Repository: https://github.com/saeedvdi/golem

## Overview

##### Project type and purpose
- GOLEM is a C++ scientific simulation application built on the MOOSE framework. It models coupled Thermo-Hydro-Mechanical (THM) processes in faulted geothermal reservoirs.
- Key indicators:
- “A MOOSE-based application” (README header)
- src/ and include/ hold kernels, boundary conditions (BCs), userobjects, etc.
- Examples/ and test/ directories for input files (.i, .geo, .msh) and regression tests.

##### File structure
- Top-level:
- /: header files organized by component (actions, auxkernels, bcs, controls, dirackernels, functions, kernels, materials, userobjects, utils)
- src/: implementation files in the same sub‐folders as include/ plus main.C
- test/: integration/regression tests (input decks and gold outputs)
- unit/: example unit tests with a minimal test harness
- Examples/: sample input files and meshes
- doc/: documentation content for static site generation via moosedocs.py and configuration
- scripts/: helper scripts (e.g., install format hook)
- Makefile and run_tests: build and test orchestrator
- Architectural patterns:
- Plugin/Factory pattern: MOOSE ObjectFactory registers and instantiates Kernels, BCs, Materials, UserObjects, AuxKernels, Actions, Controls, DiracKernels.
- Monolithic executable (“golem-opt”) that links MOOSE core libs with GOLEM modules.
- Parallel processing via MPI (mpiexec -n <nprocs>).

##### README for additional insights
- Reinforces that GOLEM extends MOOSE, requires a MOOSE installation.
- Usage: CLI → mpiexec → golem-opt with an input file.
- Testing: run_tests script orchestrates the test folder.

##### Elements
- GOLEM modules in another (blue)
- External libraries/solvers in a third (green)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Execution
    User["User CLI"]:::external
    MPI["MPI Runtime"]:::external
    Exec["golem-opt Executable"]:::golem
    User -->|"mpiexec -n <n> golem-opt -i input.i"| MPI --> Exec

    %% Application Setup
    Exec --> AppSetup["GolemApp (Application Setup)"]:::golem
    click AppSetup "https://github.com/saeedvdi/golem/blob/master/include/base/GolemApp.h"
    click AppSetup "https://github.com/saeedvdi/golem/blob/master/src/base/GolemApp.C"

    %% MOOSE Core Libraries
    subgraph "MOOSE Core Libraries"
        MC1["libmoose"]:::framework
        MC2["libmesh"]:::framework
        MC3["libstdc++"]:::framework
    end
    AppSetup --> MC1
    AppSetup --> MC2
    Exec --> MC3

    %% GOLEM Modules via Factory
    AppSetup --> Factory["Kernel Factory (ObjectFactory)"]:::golem
    subgraph "GOLEM Modules"
        Kernels["Kernels"]:::golem
        AuxKernels["AuxKernels"]:::golem
        BCs["Boundary Conditions"]:::golem
        Materials["Materials"]:::golem
        UserObjs["UserObjects"]:::golem
        Actions["Actions"]:::golem
        Controls["Controls"]:::golem
        DiracKernels["DiracKernels"]:::golem
        Utils["Utility Functions"]:::golem
    end
    click Kernels "https://github.com/saeedvdi/golem/tree/master/include/kernels/"
    click Kernels "https://github.com/saeedvdi/golem/tree/master/src/kernels/"
    click AuxKernels "https://github.com/saeedvdi/golem/tree/master/include/auxkernels/"
    click AuxKernels "https://github.com/saeedvdi/golem/tree/master/src/auxkernels/"
    click BCs "https://github.com/saeedvdi/golem/tree/master/include/bcs/"
    click BCs "https://github.com/saeedvdi/golem/tree/master/src/bcs/"
    click Materials "https://github.com/saeedvdi/golem/tree/master/include/materials/"
    click Materials "https://github.com/saeedvdi/golem/tree/master/src/materials/"
    click UserObjs "https://github.com/saeedvdi/golem/tree/master/include/userobjects/"
    click UserObjs "https://github.com/saeedvdi/golem/tree/master/src/userobjects/"
    click Actions "https://github.com/saeedvdi/golem/tree/master/include/actions/"
    click Actions "https://github.com/saeedvdi/golem/tree/master/src/actions/"
    click Controls "https://github.com/saeedvdi/golem/tree/master/include/controls/"
    click Controls "https://github.com/saeedvdi/golem/tree/master/src/controls/"
    click DiracKernels "https://github.com/saeedvdi/golem/tree/master/include/dirackernels/"
    click DiracKernels "https://github.com/saeedvdi/golem/tree/master/src/dirackernels/"
    click Utils "https://github.com/saeedvdi/golem/tree/master/include/utils/"
    click Utils "https://github.com/saeedvdi/golem/tree/master/src/utils/"

    Factory --> Kernels
    Factory --> AuxKernels
    Factory --> BCs
    Factory --> Materials
    Factory --> UserObjs
    Factory --> Actions
    Factory --> Controls
    Factory --> DiracKernels
    Factory --> Utils

    %% Input and Mesh
    InputParser["Input Parser"]:::golem
    Exec --> InputParser
    click Exec "https://github.com/saeedvdi/golem/blob/master/src/main.C"

    InputParser -->|"reads .i files"| MeshLoad["Mesh Loader"]:::framework
    MeshLoad --> MC2

    %% Assembly and Solve
    subgraph "Compute Loop"
        Assembly["FEM Assembly"]:::framework
        Solver["Linear/Nonlinear Solver"]:::external
        Assembly --> Solver
    end
    MeshLoad --> Assembly
    Kernels --> Assembly
    AuxKernels --> Assembly
    BCs --> Assembly
    DiracKernels --> Assembly
    Materials --> Assembly
    UserObjs --> Assembly
    Controls --> Assembly
    Solver -->|"PETSc/Trilinos"| MC1

    %% Actions and Outputs
    Assembly --> Actions
    Actions --> Output["Output Handler (VTK/Exodus)"]:::external

    %% Build Orchestrator
    Make["Build Orchestrator (Makefile)"]:::external
    click Make "https://github.com/saeedvdi/golem/tree/master/Makefile"
    Make --> Exec

    %% Tests and Examples
    subgraph "Testing & Examples"
        Examples["Input Examples & Meshes"]:::tests
        IntegrationTests["Regression & Integration Tests"]:::tests
        UnitTests["Unit Tests Harness"]:::tests
    end
    click Examples "https://github.com/saeedvdi/golem/tree/master/Examples/"
    click IntegrationTests "https://github.com/saeedvdi/golem/tree/master/test/"
    click UnitTests "https://github.com/saeedvdi/golem/tree/master/unit/"
    IntegrationTests --> Exec
    UnitTests --> Exec
    Examples --> InputParser

    %% Documentation
    subgraph "Documentation"
        DocGen["moosedocs.py"]:::docs
        DocContent["Documentation Content"]:::docs
    end
    click DocGen "https://github.com/saeedvdi/golem/blob/master/doc/moosedocs.py"
    click DocContent "https://github.com/saeedvdi/golem/tree/master/doc/content/"
    DocGen --> DocContent

    %% Helper Scripts
    Scripts["Helper Scripts"]:::external
    click Scripts "https://github.com/saeedvdi/golem/blob/master/scripts/install-format-hook.sh"
    Scripts --> Make

    %% Styles
    classDef framework fill:#cccccc,stroke:#333,stroke-width:1px
    classDef golem fill:#88ccff,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef tests fill:#ffccdd,stroke:#333,stroke-width:1px
    classDef docs fill:#ffdd99,stroke:#333,stroke-width:1px
```
