# hubformat/hubsim architecture

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

- Interactive diagram: https://gitdiagram.com/hubformat/hubsim
- Repository: https://github.com/hubformat/hubsim

## Overview

##### Project type and purpose
- From the file tree and README, this is a C++ ​library project​ (“HUB-Float Simulation Library”) that provides a custom floating-point format (HUB) implementation plus a suite of tests.
- It is not a full-stack or microservices app, but an open-source numeric library with build tooling (Makefile), documentation (Doxyfile, doc/nd-config), and multiple test modules.

##### File structure
- Top-level artifacts:
- Makefile, Doxyfile – build and docs
- src/hub_float.cpp & hub_float.hpp – the core library
- doc/nd-config – Doxygen configuration and templates
- test/… – multiple test harnesses split by algorithm (arithmetic, FFT, Horner, neural network, TBLAS/LAPACK)
- Patterns:
- Single-component core ("hub_float") with clearly separated test modules
- Standard C++ build (Makefile) and doc generation
- Tests organized by feature, each with main.cpp and helpers

##### Pull architecture clues from the README
- Core provides configurable exponent/mantissa bits, special-case handling, conversion, and diagnostic functions
- No external runtime dependencies beyond the C++ standard library
- Emphasis on bit-level manipulation and simplified rounding

a. Main components:
1. Core Library Module
– Classes/Types: hub_float, literals, conversion utilities
– Sub-modules: quantize & grid logic, bit-field extractors, arithmetic operators, special-value handlers, string serializers
2. Build & Documentation
– Makefile orchestration
– Doxygen engine + doc/nd-config templates
3. Test Harnesses (5 independent test suites)
– Arithmetic tests
– FFT tests
– Horner polynomial evaluator tests
– Neural network example tests
– TBLAS/LAPACK solver tests
4. External Interfaces
– C++ Standard Library (iostream, math)
– Doxygen toolchain

b. Relationships & interactions:
– The Makefile invokes compilation of src/hub_float into a library or object files.
– The same Makefile triggers Doxygen using Doxyfile and doc/nd-config to generate HTML docs.
– Each test suite links against the compiled hub_float module and exercises API functions.
– Test suites may also share common utilities in test/common.

c. Architectural patterns & design principles:
– Single Responsibility: core logic in src, docs in doc/, tests in test/.
– Layering: low-level bit manipulations → core arithmetic API → test programs.
– Configuration via templates & preprocessor for exponent/mantissa widths.
– Test isolation: each algorithm test lives in its own directory with its own entry point.

d. Key technologies/frameworks:
– C++17 (or later)
– Make (build orchestration)
– Doxygen (documentation)
– Lua (in doc/nd-config converter.lua for template processing)

##### Detail without over-splitting
- Five test suites as distinct components.
- Sub-modules of the core if space allows (e.g., quantizer vs. arithmetic vs. serializers).
- Don’t forget the doc config folder under the doc generator component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build and Documentation
    subgraph "Build & Documentation"
        Makefile["Makefile"]:::buildDocs
        Doxyfile["Doxyfile"]:::buildDocs
        subgraph "nd-config Templates"
            Comments["Comments.txt"]:::buildDocs
            Languages["Languages.txt"]:::buildDocs
            ProjectT["Project.txt"]:::buildDocs
            Converter["converter.lua"]:::buildDocs
            Template["nd-fragment.template"]:::buildDocs
        end
    end

    %% Core Library Module
    subgraph "Core Library Module"
        HubH["hub_float.hpp"]:::core
        HubCPP["hub_float.cpp"]:::core
    end

    %% Common Test Utilities
    subgraph "Common Test Utilities"
        ErrStats["error_stats.hpp"]:::test
        IOUtils["io_utils.hpp"]:::test
        Matrix["matrix.hpp"]:::test
    end

    %% Test Suites
    subgraph "Arithmetic Test Suite"
        A_main["main.cpp"]:::test
        OpTesterCPP["operation_tester.cpp"]:::test
        OpTesterH["operation_tester.hpp"]:::test
        TestConfig["test_config.hpp"]:::test
        UtilsCPP["utils.cpp"]:::test
        UtilsH["utils.hpp"]:::test
    end

    subgraph "FFT Test Suite"
        FFT_main["main.cpp"]:::test
        FFTCPP["fft.cpp"]:::test
        FFTH["fft.hpp"]:::test
    end

    subgraph "Horner Test Suite"
        Horner_main["main.cpp"]:::test
    end

    subgraph "Neural Network Test Suite"
        Neural_main["main.cpp"]:::test
        NeuralCPP["neural.cpp"]:::test
        NeuralH["neural.h"]:::test
        NeuralImpl["neural_impl.hpp"]:::test
        Half["half.hpp"]:::test
        Mnist["mnist_loader.h"]:::test
    end

    subgraph "TBLAS/LAPACK Test Suite"
        TBLAS_main["main.cpp"]:::test
        LinearSolve["LinearSolve.h"]:::test
        TBLAS["TBLAS.h"]:::test
        TLASupport["TLASupport.h"]:::test
    end

    %% External Tools
    CppStd["C++ Standard Library"]:::external
    DoxygenTool["Doxygen Toolchain"]:::external

    %% Connections
    Makefile -->|compile| HubH
    Makefile -->|compile| HubCPP
    Makefile -->|generate docs| Doxyfile
    Doxyfile -->|uses templates| Comments
    Doxyfile -->|uses templates| Languages
    Doxyfile -->|uses templates| ProjectT
    Doxyfile -->|uses templates| Converter
    Doxyfile -->|uses templates| Template
    DoxygenTool -->|runs| Doxyfile

    HubH -->|API| A_main
    HubCPP -->|API| A_main
    HubH -->|API| FFT_main
    HubCPP -->|API| FFT_main
    HubH -->|API| Horner_main
    HubCPP -->|API| Horner_main
    HubH -->|API| Neural_main
    HubCPP -->|API| Neural_main
    HubH -->|API| TBLAS_main
    HubCPP -->|API| TBLAS_main

    ErrStats -->|shared utils| A_main
    ErrStats -->|shared utils| FFT_main
    ErrStats -->|shared utils| Horner_main
    ErrStats -->|shared utils| Neural_main
    ErrStats -->|shared utils| TBLAS_main
    IOUtils -->|shared utils| A_main
    Matrix -->|shared utils| A_main

    %% Click Events
    click HubH "https://github.com/hubformat/hubsim/blob/main/src/hub_float.hpp"
    click HubCPP "https://github.com/hubformat/hubsim/blob/main/src/hub_float.cpp"
    click Makefile "https://github.com/hubformat/hubsim/tree/main/Makefile"
    click Doxyfile "https://github.com/hubformat/hubsim/tree/main/Doxyfile"
    click Comments "https://github.com/hubformat/hubsim/blob/main/doc/nd-config/Comments.txt"
    click Languages "https://github.com/hubformat/hubsim/blob/main/doc/nd-config/Languages.txt"
    click ProjectT "https://github.com/hubformat/hubsim/blob/main/doc/nd-config/Project.txt"
    click Converter "https://github.com/hubformat/hubsim/blob/main/doc/nd-config/converter.lua"
    click Template "https://github.com/hubformat/hubsim/blob/main/doc/nd-config/nd-fragment.template"
    click ErrStats "https://github.com/hubformat/hubsim/blob/main/test/common/error_stats.hpp"
    click IOUtils "https://github.com/hubformat/hubsim/blob/main/test/common/io_utils.hpp"
    click Matrix "https://github.com/hubformat/hubsim/blob/main/test/common/matrix.hpp"
    click A_main "https://github.com/hubformat/hubsim/blob/main/test/arithmetic_test/main.cpp"
    click OpTesterCPP "https://github.com/hubformat/hubsim/blob/main/test/arithmetic_test/operation_tester.cpp"
    click OpTesterH "https://github.com/hubformat/hubsim/blob/main/test/arithmetic_test/operation_tester.hpp"
    click TestConfig "https://github.com/hubformat/hubsim/blob/main/test/arithmetic_test/test_config.hpp"
    click UtilsCPP "https://github.com/hubformat/hubsim/blob/main/test/arithmetic_test/utils.cpp"
    click UtilsH "https://github.com/hubformat/hubsim/blob/main/test/arithmetic_test/utils.hpp"
    click FFT_main "https://github.com/hubformat/hubsim/blob/main/test/fft/main.cpp"
    click FFTCPP "https://github.com/hubformat/hubsim/blob/main/test/fft/fft.cpp"
    click FFTH "https://github.com/hubformat/hubsim/blob/main/test/fft/fft.hpp"
    click Horner_main "https://github.com/hubformat/hubsim/blob/main/test/horner/main.cpp"
    click Neural_main "https://github.com/hubformat/hubsim/blob/main/test/neural/main.cpp"
    click NeuralCPP "https://github.com/hubformat/hubsim/blob/main/test/neural/neural.cpp"
    click NeuralH "https://github.com/hubformat/hubsim/blob/main/test/neural/neural.h"
    click NeuralImpl "https://github.com/hubformat/hubsim/blob/main/test/neural/neural_impl.hpp"
    click Half "https://github.com/hubformat/hubsim/blob/main/test/neural/half.hpp"
    click Mnist "https://github.com/hubformat/hubsim/blob/main/test/neural/mnist_loader.h"
    click TBLAS_main "https://github.com/hubformat/hubsim/blob/main/test/tblas_lapack/main.cpp"
    click LinearSolve "https://github.com/hubformat/hubsim/blob/main/test/tblas_lapack/LinearSolve.h"
    click TBLAS "https://github.com/hubformat/hubsim/blob/main/test/tblas_lapack/TBLAS.h"
    click TLASupport "https://github.com/hubformat/hubsim/blob/main/test/tblas_lapack/TLASupport.h"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef buildDocs fill:#90EE90,stroke:#000
    classDef test fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
```
