# chfeder/turbulence_generator architecture

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

- Interactive diagram: https://gitdiagram.com/chfeder/turbulence_generator
- Repository: https://github.com/chfeder/turbulence_generator

## Overview

##### Project type and purpose
- This is a scientific turbulence-generator library and command-line tool (TurbGen) written in C++ with MPI/HDF5 support.
- It provides a core API (TurbGen.h/C++), a parallel CLI (TurbGen.cpp), demo drivers (TurbGenDemo.cpp), legacy ports in C and Fortran, a Python frontend, and integration “plugins” for hydrodynamics codes (FLASH, AREPO‐style interfaces).

##### File structure
- Top-level:
- Core C++ library and executables: TurbGen.h, TurbGen.cpp, TurbGenDemo.cpp, TurbGen.par, Makefile
- Legacy implementations: legacy_c/ (C), legacy_fortran/ (Fortran)
- Python frontend: python/TurbGen.py
- Plugins for FLASH: plugins/flash/{StirICsMain, StirMain, legacy_fortran} with F90 and C wrappers
- Build system:
- Root Makefile
- Sub-directory Makefiles for legacy and plugins
- Config and parameter files:
- TurbGen.par
- plugin Config subdirectories
- legacy input (.inp)

##### README for additional insights
- Core objective: generate time sequences of random Fourier modes via an OU process, write HDF5 output or return a single realization.
- Supported integrations: AREPO, FLASH, GADGET, PHANTOM, PLUTO.
- Python frontend also computes statistics (PDFs, power spectra).

a. Main components
- Core TurbGen Library (C++)
- Parallel CLI Application (TurbGen.exe)
- Demo CLI (TurbGenDemo)
- Legacy C/Fortran modules
- Python Frontend (python/TurbGen.py)
- Plugin Adapters for Simulation Codes (FLASH StirICsMain, StirMain)
- External Simulation Engines (FLASH, AREPO, GADGET, etc.)
- Data stores: Parameter files (.par, .inp), HDF5 output
b. Relationships and data flows
- Parameter file → CLI/Demo/Python → Core Library → HDF5 output
- Simulation Engine loads Plugin → Plugin Adapter calls Core Library (in‐process) → simulation uses turbulence field
- Python frontend may invoke CLI as subprocess or link against library via C‐API wrapper
- Legacy modules compile separately but follow the same call flow
c. Architectural patterns and design principles
- Layered modular design: Core library at center, adapters around it
- Plugin/Adapter pattern: each simulation code has a thin interface module (Fortran or C wrapper)
- Cross‐language interoperability: C++ core with C and Fortran bindings, plus Python glue
- Parallel computing: MPI in core and CLI
d. Key technologies and frameworks
- C++ (TurbGen.h/.cpp), MPI, HDF5
- Fortran 90 for legacy and plugin modules
- Python for frontend and analysis
- Make (Makefiles) as build orchestrator
- Shell scripts (misc/make_movie.sh) and PowerPoint slides (misc/TurbGen.pptx) for documentation/tools

##### Elements
- Clear labels on each component (e.g., “TurbGen Core Library” vs. “FLASH Plugin Adapter”)
- Core library (e.g., blue rectangle)
- Executables & frontends (green ellipse)
- Plugins/Adapters (orange hexagon)
- External simulation codes (grey rectangle)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data artifacts
    Parameter["Parameter File\n(TurbGen.par)"]:::data
    Output["HDF5 Output"]:::data

    %% Executables & Frontends
    CLI["TurbGen CLI\n(MPI-enabled)"]:::exec
    Demo["TurbGen Demo CLI"]:::exec
    Python["Python Frontend"]:::exec

    %% Core Library
    subgraph "Core Library Layer"
        CoreLib["TurbGen Core Library\n(C++ API)"]:::core
        HDFIO["HDF5 I/O Helper"]:::core
    end

    %% Legacy Modules
    subgraph "Legacy Implementations"
        LegacyC["Legacy C Module"]:::legacy
        LegacyF["Legacy Fortran Module"]:::legacy
    end

    %% Plugin Adapters
    subgraph "FLASH Plugin Adapters"
        StirICs["StirICsMain Adapter"]:::plugin
        StirMain["StirMain Adapter"]:::plugin
        LegacyPlugin["Legacy Fortran Plugin"]:::plugin
    end

    %% External Systems
    ExternalEngine["Simulation Engines\n(FLASH, AREPO, GADGET, etc.)"]:::external

    %% Build System
    Build["Root Build System\n(Makefile)"]:::build

    %% Data flow and invocations
    Parameter -->|reads| CLI
    Parameter -->|reads| Demo
    Parameter -->|reads| Python

    CLI -->|MPI call| CoreLib
    Demo -->|API call| CoreLib
    Python -->|C-API wrapper| CoreLib
    Python -->|subprocess| Demo

    LegacyC -->|calls| CoreLib
    LegacyF -->|calls| CoreLib

    StirICs -->|Fortran/C wrapper call| CoreLib
    StirMain -->|Fortran/C wrapper call| CoreLib
    LegacyPlugin -->|Fortran wrapper call| CoreLib

    CoreLib -->|HDF5 write| Output
    CoreLib -->|provides field| ExternalEngine

    StirICs -->|injects field| ExternalEngine
    StirMain -->|injects field| ExternalEngine
    LegacyPlugin -->|injects field| ExternalEngine

    %% Build dependencies
    Build --> CLI
    Build --> Demo
    Build --> CoreLib
    Build --> LegacyC
    Build --> LegacyF
    Build --> StirICs
    Build --> StirMain
    Build --> LegacyPlugin

    %% Click Events
    click CoreLib "https://github.com/chfeder/turbulence_generator/blob/master/TurbGen.h"
    click CLI "https://github.com/chfeder/turbulence_generator/blob/master/TurbGen.cpp"
    click Demo "https://github.com/chfeder/turbulence_generator/blob/master/TurbGenDemo.cpp"
    click Parameter "https://github.com/chfeder/turbulence_generator/blob/master/TurbGen.par"
    click Build "https://github.com/chfeder/turbulence_generator/tree/master/Makefile"
    click HDFIO "https://github.com/chfeder/turbulence_generator/blob/master/HDFIO.h"
    click LegacyC "https://github.com/chfeder/turbulence_generator/tree/master/legacy_c/"
    click LegacyF "https://github.com/chfeder/turbulence_generator/tree/master/legacy_fortran/"
    click Python "https://github.com/chfeder/turbulence_generator/blob/master/python/TurbGen.py"
    click StirICs "https://github.com/chfeder/turbulence_generator/tree/master/plugins/flash/StirICsMain/"
    click StirMain "https://github.com/chfeder/turbulence_generator/tree/master/plugins/flash/StirMain/"
    click LegacyPlugin "https://github.com/chfeder/turbulence_generator/tree/master/plugins/flash/legacy_fortran/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef exec fill:#d4edda,stroke:#155724,color:#155724
    classDef plugin fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef legacy fill:#f5c6cb,stroke:#721c24,color:#721c24
    classDef build fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
