# ashishgy/footdetec architecture

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

- Interactive diagram: https://gitdiagram.com/ashishgy/footdetec
- Repository: https://github.com/ashishgy/footdetec

## Overview

##### Project Type and Purpose
- This is an open-source Python/C++ mixed library (“ai3”) that extends PyTorch to provide fine-grain, user-selectable DNN algorithm implementations.
- Users call `ai3.swap_operation` or `ai3.convert` at the Python level to swap or convert PyTorch layers to high-performance implementations (cuDNN, SYCL, plain C++, etc.).

##### File Structure Analysis
- Top-level directories:
- src/ai3: Python package + C++ extension source (`csrc`) and custom hook headers.
- bench: Python benchmarking scripts and result data.
- example: Usage scripts demonstrating `swap_operation`, custom operators, training.
- model_zoo: Reference models for testing and demonstration.
- test: Unit, ops, serialization tests validating correctness.
- cmake: Custom CMake modules to find SYCL, configure builds.
- pyproject.toml, CMakeLists.txt: Build and packaging configuration.
- Patterns:
- Layered structure: Python API → C++ extension modules per operator → underlying acceleration backends.
- Plugin/custom directory for user-provided algorithms.
- Benchmarking and example harnesses are decoupled from core library.

##### README Insights
- Two main user entry points: `swap_operation` (in-place swap) and `convert` (full-model conversion).
- Supported operations (conv2d, linear, pooling, ReLU, flatten) with multiple algorithms and backend compatibility tables.
- Emphasis on zero overhead and fine-grain control.

##### Components
a. Main Components
- User Applications: PyTorch models, example scripts, custom operators.
- Python API Layer: `src/ai3/__init__.py`, `layers.py`, `tensor.py`, `swap_torch.py`.
- Dispatcher/Selector: AlgorithmicSelector logic in Python that chooses which C++ kernel to call.
- C++ Extension Modules: `src/ai3/csrc/*` (conv2d, linear, pooling, relu, flatten).
- Acceleration Backends: cuDNN, SYCL, CUBLAS, MPS, Metal, or plain C++ direct implementations.
- Build System: CMake (custom.cmake, FindSYCL), Python packaging (pyproject.toml).
- Auxiliary Components: Bench scripts (`bench/`), examples (`example/`), tests (`test/`), documentation (`docs/`).
b. Relationships and Interactions
- User code imports `aithree` Python package ⇒ calls `swap_operation`/`convert`.
- Python API constructs an internal `Model` object, walks the PyTorch graph, and dispatches each op to the selected C++ kernel via PyBind11 or similar binding.
- At build time, CMake compiles the C++ sources (`csrc`) into shared libraries, linking to chosen backends (cuDNN, SYCL).
- Bench scripts invoke both PyTorch and ai3 implementations to gather performance data.
c. Architectural Patterns
- Layered modular design separating API, dispatch logic, and compute kernels.
- Strategy pattern in Python: pluggable algorithms per operation.
- Extension/plugin architecture: `src/ai3/custom` for user-provided kernels.
d. Key Technologies
- Python (user API, benchmarks, tests, examples).
- C++ (compute kernels in `src/ai3/csrc`).
- Build: CMake + custom modules, pyproject.toml for pip distribution.
- Backends: NVIDIA cuDNN/cuBLAS, SYCL, Metal, MPS, plain C++.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Applications
    subgraph "User Applications"
        UA1["Example Scripts"]:::aux
        UA2["FinalProgram.py"]:::aux
        UA3["main_debug.py"]:::aux
        UA4["run.py"]:::aux
    end

    %% Python API Layer
    subgraph "Python API Layer"
        PY1["__init__.py"]:::python
        PY2["layers.py"]:::python
        PY3["tensor.py"]:::python
        PY4["swap_torch.py"]:::python
        PY5["utils.py"]:::python
        PY6["errors.py"]:::python
    end

    %% Dispatcher/Selector
    subgraph "Dispatcher / Selector"
        DS1["swap_torch.py"]:::python
        DS2["utils.py"]:::python
    end

    %% C++ Extension Modules
    subgraph "C++ Extension Modules"
        CC1["ai3.cpp"]:::cpp
        CC2["ai3.hpp"]:::cpp
        CC3["algos.hpp"]:::cpp
        CC4["context.hpp"]:::cpp
        CC5["tensor.hpp"]:::cpp
        CC6["utils.hpp"]:::cpp
        CC7["adaptiveavgpool2d/plain.cpp"]:::cpp
        CC8["avgpool2d/plain.cpp"]:::cpp
        CC9["flatten/plain.cpp"]:::cpp
        CC10["linear/gemm_plain.cpp"]:::cpp
        CC11["linear/gemm_cublas.cpp"]:::cpp
        CC12["linear/gemm_sycl.cpp"]:::cpp
        CC13["maxpool2d/plain.cpp"]:::cpp
        CC14["relu/plain.cpp"]:::cpp
        subgraph "conv2d Modules"
            CC15["conv2d/*"]:::cpp
        end
    end

    %% Acceleration Backends
    subgraph "Acceleration Backends"
        AB1["CUDA/cuDNN"]:::backend
        AB2["CUBLAS"]:::backend
        AB3["SYCL"]:::backend
        AB4["Metal/MPS"]:::backend
        AB5["Plain C++"]:::backend
    end

    %% Build System
    subgraph "Build System"
        BS1["CMakeLists.txt"]:::build
        BS2["cmake/custom.cmake"]:::build
        BS3["cmake/FindSYCL.cmake"]:::build
        BS4["pyproject.toml"]:::build
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        AUX1["bench/"]:::aux
        AUX2["test/"]:::aux
        AUX3["docs/"]:::aux
        AUX4["model_zoo/"]:::aux
    end

    %% Relationships
    UA1 -->|imports| PY1
    UA1 -->|imports| PY2
    UA2 -->|calls| PY4
    UA3 -->|calls| PY4
    UA4 -->|calls| PY4

    PY1 -->|"defines API"| DS1
    PY2 -->|"defines layers"| DS1
    PY3 -->|"tensor ops"| DS1
    PY4 -->|"swap/convert"| DS1
    PY5 -->|"helpers"| DS2
    PY6 -->|"error handling"| DS1

    DS1 -->|"PyBind11 call"| CC1
    DS2 -->|"algorithm selection"| CC3

    CC1 -->|"link"| AB1
    CC1 -->|"link"| AB2
    CC1 -->|"link"| AB3
    CC1 -->|"link"| AB4
    CC1 -->|"link"| AB5

    BS1 -->|"CMake config"| CC1
    BS2 -->|"includes"| BS1
    BS3 -->|"Find SYCL"| BS1
    BS4 -->|"Python packaging"| PY1

    AUX1 -.->|"benchmarks"| PY1
    AUX1 -.->|"benchmarks"| CC1
    AUX2 -.->|"tests"| PY1
    AUX2 -.->|"tests"| CC1
    AUX3 -.->|"docs|overview"| PY1
    AUX4 -.->|"models"| UA1

    %% Click Events
    click UA1 "https://github.com/ashishgy/footdetec/tree/main/example/"
    click UA2 "https://github.com/ashishgy/footdetec/blob/main/example/FinalProgram.py"
    click UA3 "https://github.com/ashishgy/footdetec/blob/main/example/main_debug.py"
    click UA4 "https://github.com/ashishgy/footdetec/blob/main/example/run.py"
    click PY1 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/__init__.py"
    click PY2 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/layers.py"
    click PY3 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/tensor.py"
    click PY4 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/swap_torch.py"
    click PY5 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/utils.py"
    click PY6 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/errors.py"
    click DS1 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/swap_torch.py"
    click DS2 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/utils.py"
    click CC1 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/ai3.cpp"
    click CC2 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/ai3.hpp"
    click CC3 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/algos.hpp"
    click CC4 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/context.hpp"
    click CC5 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/tensor.hpp"
    click CC6 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/utils.hpp"
    click CC7 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/adaptiveavgpool2d/direct_plain.cpp"
    click CC8 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/avgpool2d/direct_plain.cpp"
    click CC9 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/flatten/direct_plain.cpp"
    click CC10 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/linear/gemm_plain.cpp"
    click CC11 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/linear/gemm_cublas.cpp"
    click CC12 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/linear/gemm_sycl.cpp"
    click CC13 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/maxpool2d/direct_plain.cpp"
    click CC14 "https://github.com/ashishgy/footdetec/blob/main/src/ai3/csrc/relu/direct_plain.cpp"
    click CC15 "https://github.com/ashishgy/footdetec/tree/main/src/ai3/csrc/conv2d/"
    click BS1 "https://github.com/ashishgy/footdetec/blob/main/CMakeLists.txt"
    click BS2 "https://github.com/ashishgy/footdetec/blob/main/cmake/custom.cmake"
    click BS3 "https://github.com/ashishgy/footdetec/blob/main/cmake/FindSYCL.cmake"
    click BS4 "https://github.com/ashishgy/footdetec/blob/main/pyproject.toml"
    click AUX1 "https://github.com/ashishgy/footdetec/tree/main/bench/"
    click AUX2 "https://github.com/ashishgy/footdetec/tree/main/test/"
    click AUX3 "https://github.com/ashishgy/footdetec/tree/main/docs/"
    click AUX4 "https://github.com/ashishgy/footdetec/tree/main/model_zoo/"

    %% Styles
    classDef python fill:#D0E7FF,stroke:#0366D6,color:#0366D6
    classDef cpp fill:#E6FFDA,stroke:#2F9E44,color:#2F9E44
    classDef backend fill:#FFE8CC,stroke:#F76707,color:#F76707
    classDef build fill:#E2E3E5,stroke:#6C757D,color:#6C757D
    classDef aux fill:#F0F0FF,stroke:#6F42C1,color:#6F42C1
```
