# vlvovch/thermal-fist architecture

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

- Interactive diagram: https://gitdiagram.com/vlvovch/thermal-fist
- Repository: https://github.com/vlvovch/thermal-fist

## Overview

##### Project Type and Purpose
- Thermal-FIST is a modular C++ scientific package implementing hadron resonance gas (HRG) models, with both command-line/example programs and a Qt GUI frontend for computing thermodynamics, fits, and event generation.

##### Main Components
a. Core Computational Library (src/library & include/)
- Modules:
– HRGBase (ideal and canonical ensembles, thermodynamics routines)
– HRGEV (excluded volume models)
– HRGEventGenerator (Monte Carlo event generators)
– HRGFit, HRGPCE, HRGRealGas, HRGVDW (fits, partial chemical equilibrium, real gas, van der Waals)
– CosmicEos (early-Universe/NS matter)
- Utility submodules (xMath, Broyden solver, spline, integration)
b. Input Data Layer (input/)
- Particle lists, decay tables, interaction parametrizations, lQCD EoS, heavy-ion yield data
c. Third-Party Dependencies (thirdparty/)
- Eigen (linear algebra)
- MINUIT2 (minimization)
- Mersenne Twister (RNG)
- Qt + QCustomPlot (GUI & plotting)
d. Frontends
- CLI / C++ example applications (src/examples/) demonstrating usage (BagModelFit, EoS calculators, NeutronStars, PCE, cpc macros)
- GUI application (src/gui/QtThermalFIST/) for interactive analysis, linking to core library and plotting widgets
- Utility routines (src/routines/EVTablesGenerator/) generating tabulated tables
e. Build & Test Infrastructure
- CMake build definitions (top-level CMakeLists.txt, per-module CMakeLists.txt)
- CI workflows (.github/workflows, Travis CI)
- Unit and regression tests (test/) comparing reference outputs

##### Relationships and Data Flows
- The Frontends (CLI examples, GUI) depend on and link to the Core Library.
- Core Library routines read input data files (particle lists, interactions, lQCD, yield datasets) and use third-party services (Eigen for matrices, MINUIT2 for fits, RNG for event generation).
- EVTablesGenerator links to Core Library to produce precomputed tables stored for reuse.
- Tests invoke library functions or example programs, compare outputs to ReferenceOutput.
- CI system orchestrates build → run tests → report status.

##### Architectural Patterns & Principles
- Layered architecture:
1. Data Layer (input/)
2. Core Library (computation engine)
3. Service Layer (fit & event-gen modules)
4. Presentation Layer (CLI, GUI)
- Modular design: each physics extension in its own namespace/submodule
- Separation of concerns: numerical routines vs. I/O vs. user interface
- Dependency injection via CMake targets for easy submodule composition

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Input Data Layer"
        direction TB
        ParticleLists(["Particle Lists"]):::data
        DecayTables(["Decay Tables & Interactions"]):::data
        YieldData(["Experimental Yield Data"]):::data
        LatticeEoS(["Lattice QCD EoS"]):::data
    end

    %% Core Computational Library
    subgraph "Core Computational Library" 
        direction TB
        HRGBase(["HRGBase Module"]):::module
        HRGEV(["HRGEV Module"]):::module
        HRGEventGen(["HRGEventGenerator Module"]):::module
        HRGFit(["HRGFit Module"]):::module
        HRGPCE(["HRGPCE Module"]):::module
        HRGRealGas(["HRGRealGas Module"]):::module
        HRGVDW(["HRGVDW Module"]):::module
        CosmicEos(["CosmicEos Module"]):::module
        Utilities(["Utility Submodules"]):::module
    end

    %% Third-Party Dependencies
    subgraph "Third-Party Dependencies"
        direction TB
        Eigen(["Eigen"]):::external
        Minuit2(["MINUIT2"]):::external
        RNG(["Mersenne Twister (RNG)"]):::external
        QCustomPlot(["QCustomPlot"]):::external
    end

    %% Frontends and Routines
    subgraph "Frontends & Utilities"
        direction TB
        CLI(["CLI Examples"]):::frontend
        GUI(["Qt GUI (QtThermalFIST)"]):::frontend
        EVGen(["EVTablesGenerator Utility"]):::frontend
    end

    %% Build & Test Infrastructure
    subgraph "Build & Test Infrastructure"
        direction TB
        CMake(["CMake Build System"]):::infra
        CI(["CI Workflows"]):::infra
        Tests(["Unit & Regression Tests"]):::infra
        Reports(["Test Reports"]):::infra
    end

    %% Data flows
    ParticleLists -->|reads data| HRGBase
    DecayTables -->|reads data| HRGBase
    YieldData -->|reads data| HRGBase
    LatticeEoS -->|reads data| HRGBase

    %% Core to Third-Party
    HRGBase -->|uses| Eigen
    HRGBase -->|uses| Minuit2
    HRGEventGen -->|uses| RNG
    GUI -->|uses| QCustomPlot

    %% Core to Frontends
    HRGBase -->|links to| CLI
    HRGEV -->|links to| CLI
    HRGEventGen -->|links to| CLI
    HRGFit -->|links to| CLI
    HRGPCE -->|links to| CLI
    HRGRealGas -->|links to| CLI
    HRGVDW -->|links to| CLI
    CosmicEos -->|links to| CLI

    HRGBase -->|links to| GUI
    Utilities -->|links to| GUI

    HRGBase -->|produces tables| EVGen
    Utilities -->|supports| EVGen

    %% Build/Test Workflow
    CLI -->|built by| CMake
    GUI -->|built by| CMake
    EVGen -->|built by| CMake
    CMake -->|triggered by| CI
    CI -->|runs| Tests
    Tests -->|reports to| Reports

    %% Click Events for component mapping
    click HRGBase "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGBase/"
    click HRGBase "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGBase/"
    click HRGEV "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGEV/"
    click HRGEV "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGEV/"
    click HRGEventGen "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGEventGenerator/"
    click HRGEventGen "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGEventGenerator/"
    click HRGFit "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGFit/"
    click HRGFit "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGFit/"
    click HRGPCE "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGPCE/"
    click HRGPCE "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGPCE/"
    click HRGRealGas "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGRealGas/"
    click HRGRealGas "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGRealGas/"
    click HRGVDW "https://github.com/vlvovch/thermal-fist/tree/master/include/HRGVDW/"
    click HRGVDW "https://github.com/vlvovch/thermal-fist/tree/master/src/library/HRGVDW/"
    click CosmicEos "https://github.com/vlvovch/thermal-fist/tree/master/include/CosmicEos/"
    click CosmicEos "https://github.com/vlvovch/thermal-fist/tree/master/src/library/CosmicEos/"
    click Utilities "https://github.com/vlvovch/thermal-fist/blob/master/include/HRGBase/xMath.*"
    click HRGBase "https://github.com/vlvovch/thermal-fist/blob/master/src/library/CMakeLists.txt"
    click ParticleLists "https://github.com/vlvovch/thermal-fist/tree/master/input/list/"
    click DecayTables "https://github.com/vlvovch/thermal-fist/tree/master/input/interaction/"
    click YieldData "https://github.com/vlvovch/thermal-fist/tree/master/input/data/"
    click LatticeEoS "https://github.com/vlvovch/thermal-fist/tree/master/input/lqcd/"
    click Eigen "https://github.com/vlvovch/thermal-fist/tree/master/thirdparty/Eigen3/"
    click Minuit2 "https://github.com/vlvovch/thermal-fist/tree/master/thirdparty/Minuit2/"
    click RNG "https://github.com/vlvovch/thermal-fist/tree/master/thirdparty/MersenneTwister/"
    click QCustomPlot "https://github.com/vlvovch/thermal-fist/tree/master/thirdparty/QCustomPlot/"
    click CLI "https://github.com/vlvovch/thermal-fist/tree/master/src/examples/"
    click GUI "https://github.com/vlvovch/thermal-fist/tree/master/src/gui/QtThermalFIST/"
    click EVGen "https://github.com/vlvovch/thermal-fist/blob/master/src/routines/EVTablesGenerator/EVTablesGenerator.cpp"
    click CMake "https://github.com/vlvovch/thermal-fist/blob/master/CMakeLists.txt"
    click CI "https://github.com/vlvovch/thermal-fist/tree/master/.github/workflows/"
    click CI "https://github.com/vlvovch/thermal-fist/blob/master/.travis.yml"
    click Tests "https://github.com/vlvovch/thermal-fist/tree/master/test/"

    %% Styles
    classDef module fill:#D0E6FF,stroke:#000,stroke-width:1px;
    classDef data fill:#FFE4B2,stroke:#000,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px;
    classDef frontend fill:#B2FFD8,stroke:#000,stroke-width:1px;
    classDef infra fill:#DFF2BF,stroke:#000,stroke-width:1px;
```
