# godrays/aix architecture

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

- Interactive diagram: https://gitdiagram.com/godrays/aix
- Repository: https://github.com/godrays/aix

## Overview

##### Project type and purpose
- This is a C++ machine-learning framework library (AIX) with accompanying CLI tools (benchmarks, tests) and example applications.
- Its primary goal is to provide a highly-readable, single-header API for tensors, dynamic graphs, autodiff, and plug-and-play hardware acceleration.

##### File structure
- Top-level:
- CMakeLists.txt + build.py → Build system orchestrator (configures, compiles, links).
- Externals/Externals.cmake → Third-party dependency hooks (though AIX is header-only).
- Targets/ → All build targets, subdivided into:
– AIXLib → Core library source (aix.hpp, device implementations, floats, version).
– AIXExamples → Example apps demonstrating API usage.
– AIXTests → Unit tests for Tensor, Autograd, Devices, Ops.
– AIXBenchmarks → Benchmark CLI.

##### README insights
- Core classes: Tensor, TensorValue, Device.
- Layers built on core: nn::Sequential, Linear, Activations, Losses, Optimizers.
- Device plugin model: reference device in aix.hpp, Metal device in aixDeviceMetal.cpp, and guidelines for adding more.
- Build flags: AIX_BUILD_STATIC, AIX_BUILD_EXAMPLES, AIX_BUILD_TESTS.

##### Main components
a. AIX Core Library
- Tensor & dynamic computation graph subsystem
- TensorValue for device-side data
- Device abstract base + reference device implementation
b. Hardware Acceleration Layer
- Metal device implementation (aixDeviceMetal.{cpp,hpp})
- DeviceCache, Shaders
- Hook for custom devices
c. Neural-Network API Layer
- nn::Module (Sequential, Linear, Activations, Losses)
- optim::Optimizer subclasses (SGD, Adam)
d. Build System & Packaging
- CMake + Externals.cmake
- build.py script (build targets: library, tests, benchmarks, examples)
e. CLI Tools & Examples
- AIXTests (unit-test runner)
- AIXBenchmarks (benchmarking CLI)
- AIXExamples (XORApp, XORLayerApp, etc.)

##### Relationships and interactions
- Build system compiles AIXLib → static/dynamic library.
- CLI tools and examples link against AIXLib → execute Tensor/Device/nn APIs.
- During runtime: Examples/Benchmarks → call Model.forward/backward → Tensor operations → dispatched to Device implementation → hardware or reference.
- Extensibility: New devices derive from Device base and plug into core via factory (createDevice).

##### Architectural patterns & design principles
- Layered modular design: Core → Device → NN/Optim → Applications
- Plugin pattern for Device implementations
- Single-header façade with optional .cpp for devices
- Separation of compute graph (Tensor) vs. compute backends (Device)

##### Essential details to capture
- All four Targets subfolders as separate components.
- Core classes and the plugin device factory.
- Example apps as clients of the API.
- Build system’s dual role: static vs. examples/tests toggles.

- Clearly labels each module, target, and script.
- Captures the plug-and-play nature of devices and the layering from Tensor → Device → Application.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build System & Packaging"
        direction TB
        CMake["CMakeLists.txt"]:::config
        Externals["Externals/Externals.cmake"]:::config
        BuildPy["build.py"]:::config
    end

    subgraph "Targets/AIXLib (AIX Core Library)"
        direction TB
        AIXCore["aix.hpp"]:::core
        AIXDevicesH["aixDevices.hpp"]:::device
        AIXDevicesCpp["aixDevices.cpp"]:::device
        AIXFloat16["aixFloat16.hpp"]:::core
        AIXVersion["aixVersion.hpp"]:::core

        subgraph "Hardware Acceleration Layer"
            direction TB
            MetalH["aixDeviceMetal.hpp"]:::deviceImp
            MetalCpp["aixDeviceMetal.cpp"]:::deviceImp
            MetalCache["aixDeviceMetalCache.hpp"]:::deviceImp
            MetalShaders["aixDeviceMetalShaders.hpp"]:::deviceImp
        end
    end

    subgraph "Executable Outputs"
        direction TB
        AIXLibBin["AIXLib (library)"]:::core
        BenchExe["AIXBenchmarks (CLI)"]:::app
        TestExe["AIXTests (runner)"]:::app
        ExampleExe["AIXExamples (apps)"]:::app
    end

    subgraph "Targets/AIXBenchmarks"
        direction TB
        BenchMain["Main.cpp"]:::app
        BenchDevice["Device.cpp"]:::app
        BenchModel["Model.cpp"]:::app
        BenchTensor["Tensor.cpp"]:::app
        BenchCommon["Common.hpp"]:::app
        BenchCMake["CMakeLists.txt"]:::config
    end

    subgraph "Targets/AIXTests"
        direction TB
        TestMain["Main.cpp"]:::app
        TestActivation["ActivationTests.cpp"]:::app
        TestAutoGrad["AutoGradTests.cpp"]:::app
        TestDevice["DeviceTests.cpp"]:::app
        TestFloat16["Float16Tests.cpp"]:::app
        TestFunctional["FunctionalTests.cpp"]:::app
        TestLoss["LossTests.cpp"]:::app
        TestOptimizer["OptimizerTests.cpp"]:::app
        TestTensor["TensorTests.cpp"]:::app
        TestTensorValue["TensorValueTests.cpp"]:::app
        TestUtils["Utils.hpp"]:::app
        TestCMake["CMakeLists.txt"]:::config
    end

    subgraph "Targets/AIXExamples"
        direction TB
        XORApp["XORApp/Main.cpp"]:::app
        XORLayerApp["XORLayerApp/Main.cpp"]:::app
        XORMetalApp["XORMetalApp/Main.cpp"]:::app
        XORSequentialApp["XORSequentialApp/Main.cpp"]:::app
    end

    %% Build-time relationships
    CMake -->|"configure"| AIXLibBin
    BuildPy -->|"build"| AIXLibBin
    CMake -->|"configure"| BenchExe
    BuildPy -->|"build"| BenchExe
    CMake -->|"configure"| TestExe
    BuildPy -->|"build"| TestExe
    CMake -->|"configure"| ExampleExe
    BuildPy -->|"build"| ExampleExe

    AIXLibBin -->|"link"| BenchExe
    AIXLibBin -->|"link"| TestExe
    AIXLibBin -->|"link"| ExampleExe

    BenchExe --> BenchMain
    BenchExe --> BenchDevice
    BenchExe --> BenchModel
    BenchExe --> BenchTensor
    BenchExe --> BenchCommon

    TestExe --> TestMain
    TestExe --> TestActivation
    TestExe --> TestAutoGrad
    TestExe --> TestDevice
    TestExe --> TestFloat16
    TestExe --> TestFunctional
    TestExe --> TestLoss
    TestExe --> TestOptimizer
    TestExe --> TestTensor
    TestExe --> TestTensorValue
    TestExe --> TestUtils

    ExampleExe --> XORApp
    ExampleExe --> XORLayerApp
    ExampleExe --> XORMetalApp
    ExampleExe --> XORSequentialApp

    %% Runtime relationships
    BenchExe -.->|"runtime calls"| AIXCore
    TestExe -.->|"runtime tests"| AIXCore
    XORApp -.->|"runtime calls"| AIXCore
    XORLayerApp -.->|"runtime calls"| AIXCore
    XORMetalApp -.->|"runtime calls"| AIXCore
    XORSequentialApp -.->|"runtime calls"| AIXCore

    %% Plugin Extensibility
    CustomSDKs["Custom Device SDKs"]:::deviceImp
    CustomSDKs -->|"implements"| MetalH

    %% Click Events
    click CMake "https://github.com/godrays/aix/blob/main/CMakeLists.txt"
    click Externals "https://github.com/godrays/aix/blob/main/Externals/Externals.cmake"
    click BuildPy "https://github.com/godrays/aix/blob/main/build.py"
    click AIXCore "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aix.hpp"
    click AIXDevicesH "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixDevices.hpp"
    click AIXDevicesCpp "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixDevices.cpp"
    click AIXFloat16 "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixFloat16.hpp"
    click AIXVersion "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixVersion.hpp"
    click MetalH "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixDeviceMetal.hpp"
    click MetalCpp "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixDeviceMetal.cpp"
    click MetalCache "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixDeviceMetalCache.hpp"
    click MetalShaders "https://github.com/godrays/aix/blob/main/Targets/AIXLib/aixDeviceMetalShaders.hpp"
    click BenchMain "https://github.com/godrays/aix/blob/main/Targets/AIXBenchmarks/Main.cpp"
    click BenchDevice "https://github.com/godrays/aix/blob/main/Targets/AIXBenchmarks/Device.cpp"
    click BenchModel "https://github.com/godrays/aix/blob/main/Targets/AIXBenchmarks/Model.cpp"
    click BenchTensor "https://github.com/godrays/aix/blob/main/Targets/AIXBenchmarks/Tensor.cpp"
    click BenchCommon "https://github.com/godrays/aix/blob/main/Targets/AIXBenchmarks/Common.hpp"
    click BenchCMake "https://github.com/godrays/aix/blob/main/Targets/AIXBenchmarks/CMakeLists.txt"
    click TestMain "https://github.com/godrays/aix/blob/main/Targets/AIXTests/Main.cpp"
    click TestActivation "https://github.com/godrays/aix/blob/main/Targets/AIXTests/ActivationTests.cpp"
    click TestAutoGrad "https://github.com/godrays/aix/blob/main/Targets/AIXTests/AutoGradTests.cpp"
    click TestDevice "https://github.com/godrays/aix/blob/main/Targets/AIXTests/DeviceTests.cpp"
    click TestFloat16 "https://github.com/godrays/aix/blob/main/Targets/AIXTests/Float16Tests.cpp"
    click TestFunctional "https://github.com/godrays/aix/blob/main/Targets/AIXTests/FunctionalTests.cpp"
    click TestLoss "https://github.com/godrays/aix/blob/main/Targets/AIXTests/LossTests.cpp"
    click TestOptimizer "https://github.com/godrays/aix/blob/main/Targets/AIXTests/OptimizerTests.cpp"
    click TestTensor "https://github.com/godrays/aix/blob/main/Targets/AIXTests/TensorTests.cpp"
    click TestTensorValue "https://github.com/godrays/aix/blob/main/Targets/AIXTests/TensorValueTests.cpp"
    click TestUtils "https://github.com/godrays/aix/blob/main/Targets/AIXTests/Utils.hpp"
    click TestCMake "https://github.com/godrays/aix/blob/main/Targets/AIXTests/CMakeLists.txt"
    click XORApp "https://github.com/godrays/aix/blob/main/Targets/AIXExamples/XORApp/Main.cpp"
    click XORLayerApp "https://github.com/godrays/aix/blob/main/Targets/AIXExamples/XORLayerApp/Main.cpp"
    click XORMetalApp "https://github.com/godrays/aix/blob/main/Targets/AIXExamples/XORMetalApp/Main.cpp"
    click XORSequentialApp "https://github.com/godrays/aix/blob/main/Targets/AIXExamples/XORSequentialApp/Main.cpp"

    classDef config fill:#ccc,stroke:#333;
    classDef core fill:#bbf,stroke:#00f;
    classDef device fill:#bfb,stroke:#0a0;
    classDef deviceImp fill:#8f8,stroke:#070;
    classDef app fill:#feb,stroke:#fa0;
```
