# adeeconometrics/lazymat architecture

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

- Interactive diagram: https://gitdiagram.com/adeeconometrics/lazymat
- Repository: https://github.com/adeeconometrics/lazymat

## Overview

##### Project type and purpose
- This is a C++ library and accompanying executable (“LazyMat”) experimenting with generic lazy evaluation of vector and matrix expressions.
- Its primary goals are to demonstrate deferred execution, expression templates, and measure performance via a set of benchmarks.
- It also contains a small CLI executable (src/main.cpp), unit tests, and documentation pipelines (Doxygen + Sphinx).

##### File structure
- Top-level
- CMakeLists.txt – orchestrates build targets for library, executable, tests, benchmarks, and docs.
- src/main.cpp – entry point for the demo/CLI.
- / – public headers defining core modules: LazyExpr, LazyMatrix, LazyOps, LazyParser, Utils.
- test/unittest.cpp – Google-Test (or custom) unit tests for correctness.
- benchmark/ – separate folder with its own makefile, Python scripts under linalg_libs, utility headers, and profiles for eager vs. lazy implementations.
- docs_doxy/ and docs_sphinx/ – two parallel pipelines: Doxygen for API extraction, Sphinx for rendered HTML docs.
- .github/workflows/conf.yml – CI for building, testing, and possibly deploying docs.
- Patterns and dependencies
- Core library (header-only templates) → built into an object/static library by CMake.
- Clients (main executable, benchmarks, tests) link against the library.
- Documentation generation is a side-car process reading the same headers.
- Benchmarking harness uses both C++ binaries and Python glue scripts to compare against NumPy/PyTorch/TensorFlow.

##### README for additional insights
- Describes motivation (education, performance exploration), usage instructions, and sample benchmark outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build and CI
    subgraph "Build & CI"
        direction TB
        CMake["CMake Build System"]:::build
        CI["GitHub Actions CI"]:::build
    end

    %% Core Library
    subgraph "Core Library (Header-only)" 
        direction TB
        Parser["LazyParser.hpp"]:::core
        Expr["LazyExpr.hpp"]:::core
        Ops["LazyOps.hpp"]:::core
        Matrix["LazyMatrix.hpp"]:::core
        UtilsCore["Utils.hpp"]:::core
    end

    %% Clients
    subgraph "Clients" 
        direction TB
        CLI["CLI Executable<br/>LazyMat"]:::client
        Tests["Unit Test Suite"]:::client
        BenchRunner["Benchmark Runner (C++)"]:::client
        PyScripts["Python Scripts"]:::client
    end

    %% Documentation
    subgraph "Documentation Pipelines"
        direction TB
        Doxy["Doxygen Pipeline"]:::docs
        Sphinx["Sphinx Pipeline"]:::docs
    end

    %% Artifacts
    DocsHTML["HTML Documentation"]:::docs
    XML["Intermediate XML"]:::docs

    %% Build outputs
    CMake -->|"builds"| Parser
    CMake -->|links against| Parser
    CMake -->|"produces"| CLI
    CMake -->|"produces"| Tests
    CMake -->|"produces"| BenchRunner
    CMake -->|"configures"| Doxy
    CMake -->|"configures"| Sphinx

    %% Client dependencies
    CLI -->|"links against"| Parser
    Tests -->|"links against"| Parser
    BenchRunner -->|"links against"| Parser

    PyScripts -->|"invoke"| BenchRunner

    %% Docs flow
    Doxy -->|"generates"| XML
    XML -->|"consumed by"| Sphinx
    Sphinx -->|"outputs"| DocsHTML

    %% CI orchestration
    CI -->|"triggers"| CMake
    CI -->|"runs"| Tests
    CI -->|"runs"| BenchRunner
    CI -->|"generates"| DocsHTML

    %% Click Events
    click Parser "https://github.com/adeeconometrics/lazymat/blob/main/include/LazyParser.hpp"
    click Expr "https://github.com/adeeconometrics/lazymat/blob/main/include/LazyExpr.hpp"
    click Ops "https://github.com/adeeconometrics/lazymat/blob/main/include/LazyOps.hpp"
    click Matrix "https://github.com/adeeconometrics/lazymat/blob/main/include/LazyMatrix.hpp"
    click UtilsCore "https://github.com/adeeconometrics/lazymat/blob/main/include/Utils.hpp"
    click CMake "https://github.com/adeeconometrics/lazymat/blob/main/CMakeLists.txt"
    click CLI "https://github.com/adeeconometrics/lazymat/blob/main/src/main.cpp"
    click Tests "https://github.com/adeeconometrics/lazymat/blob/main/test/unittest.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/baseline.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/eager.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/lazy.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/lazychunked.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/lazypages.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/lazyvector.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/src/nary.cpp"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/include/utils.hpp"
    click PyScripts "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/linalg_libs/gflops.py"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/tree/main/benchmark/makefile"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/profile.sh"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/profile/eager/eager.o"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/profile/eager/gmon.out"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/profile/lazy/lazy2.o"
    click BenchRunner "https://github.com/adeeconometrics/lazymat/blob/main/benchmark/profile/lazy/gmon.out"
    click Doxy "https://github.com/adeeconometrics/lazymat/blob/main/docs_doxy/Doxyfile.in"
    click Sphinx "https://github.com/adeeconometrics/lazymat/tree/main/docs_sphinx/Makefile"
    click Sphinx "https://github.com/adeeconometrics/lazymat/blob/main/docs_sphinx/conf.py"
    click Sphinx "https://github.com/adeeconometrics/lazymat/blob/main/docs_sphinx/api/index.rst"
    click Sphinx "https://github.com/adeeconometrics/lazymat/blob/main/docs_sphinx/api/cpp_doxygen_sphinx.rst"
    click Sphinx "https://github.com/adeeconometrics/lazymat/blob/main/docs_sphinx/index.rst"
    click Sphinx "https://github.com/adeeconometrics/lazymat/blob/main/docs_sphinx/make.bat"
    click CI "https://github.com/adeeconometrics/lazymat/blob/main/.github/workflows/conf.yml"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#2b5797,color:#1f4e79;
    classDef client fill:#d9ead3,stroke:#38761d,color:#274e13;
    classDef build fill:#fce5cd,stroke:#e69138,color:#974f0c;
    classDef docs fill:#e5ccff,stroke:#9370db,color:#4b0082;
```
