# suferqin/fast-qpu architecture

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

- Interactive diagram: https://gitdiagram.com/suferqin/fast-qpu
- Repository: https://github.com/suferqin/fast-qpu

## Overview

##### Project Type and Purpose
- This project is an experimental research framework focused on learning disentangled representations in SO(3) using fast quaternion product units (QPUs). It implements experiments for both synthetic data (found in the CubeEdge folder) and real-world data. In addition, it includes extensive point cloud experiments by modifying established projects (PointNet++ and RSCNN).
- The README makes clear that the framework supports multiple data modalities: synthetic experiments with CubeEdge, real-world action recognition with datasets like FPHA and NTU RGB+D, and point cloud processing. The custom CUDA modules (in _ext_qpu) further emphasize high-performance calculations.

##### Analysis of the File Structure
- At the top level, there are directories for configuration (configs), data handling (data), experiments and models (CubeEdge, models, utils), and CUDA extensions (_ext_qpu).
- The project also integrates two separate point cloud experiment pipelines grouped under the “pointcloud” directory which is subdivided into the PointNet++ and RSCNN subprojects.
- The presence of typical training scripts (train.py, test.py) and configuration files (YAML files in configs) indicates a clear separation of experiment configuration, model implementation, training, and testing.
- Utility directories (like utils, data/scripts) point to data preprocessing, visualization, and logging capabilities.
- The _ext_qpu folder contains custom C++/CUDA implementations – generally built via setup.py – which are crucial for the performance of the quaternion units.

##### Key Components and Their Relationships
a. Core Experiment Modules:
- CubeEdge: Contains the main experimental notebook (experiments.ipynb), the primary source code (cube_edge.py), and training utilities (train_utils.py).
- Models: The models folder holds implementations of various architectures (e.g., agc_lstm, dgnn, mlp_lstm, etc.) designed for both synthetic and real-world experiments.
- Configs: YAML configuration files dictate experiment parameters; these are read by train.py, test.py, and other control scripts.
- Data: Includes dataset-specific modules (feeder scripts, info files) and scripts for data generation, visualizations, statistics, and edge generation.
- Utilities: Common helper functions (logger, quaternion operations, skeleton utilities) that abstract common logic used across experiments.

b. Custom High-Performance Layers:
- _ext_qpu: This directory includes the C++/CUDA source and header files (bindings, hmd, cuda_utils) – these represent the performance-critical QPU implementations, compiled as extensions.
- Integration: These lower-level modules are likely wrapped and invoked from the high-level Python model implementations (e.g., in utils or models).

c. Point Cloud Experiment Modules:
- PointNet++: Contains its own set of training scripts, model definitions, data loaders, and CUDA-extension source code for point cloud segmentation and classification.
- RSCNN: Similar structure to PointNet++ with specialized setup for point cloud data, including different configuration files, training scripts, and custom operations.
- These subprojects are essentially self-contained but are integrated within the project umbrella for experiments on QPU layers in different modalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Synthetic/Real-World Experiments Block
    subgraph "Synthetic/Real-World Experiments"
        Config["Configuration Files"]:::config
        Data["Data Handling & Preprocessing"]:::data
        CubeEdge["CubeEdge Experiments"]:::experiment
        Models["Model Implementations"]:::models
        Utils["Utility Modules"]:::utils
        Train["Training Script"]:::script
        Test["Testing Script"]:::script
    end

    %% Custom QPU/CUDA Extensions Block
    subgraph "Custom QPU/CUDA Extensions"
        QPU["Custom QPU Extensions"]:::qpu
    end

    %% Point Cloud Experiments Block
    subgraph "Point Cloud Experiments"
        PointNet["PointNet++ Pipeline"]:::pointcloud
        RSCNN["RSCNN Pipeline"]:::pointcloud
    end

    %% Connections for Synthetic/Real-World Experiments
    Config -->|"drives"| Train
    Config -->|"drives"| Test
    Data -->|"feeds"| Train
    Train -->|"triggers"| CubeEdge
    Train -->|"triggers"| Models
    Utils -->|"supports"| CubeEdge
    Utils -->|"supports"| Models
    CubeEdge -->|"integrates_with"| Models
    Models -->|"utilizes"| QPU

    %% Connections for Point Cloud Experiments
    Config -->|"configures"| PointNet
    Config -->|"configures"| RSCNN
    Data -->|"feeds"| PointNet
    Data -->|"feeds"| RSCNN
    Utils -->|"supports"| PointNet
    Utils -->|"supports"| RSCNN
    PointNet -->|"leverages"| QPU
    RSCNN -->|"leverages"| QPU

    %% Styles
    classDef config fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef data fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef experiment fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef models fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef utils fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef script fill:#f4d03f,stroke:#d4ac0d,stroke-width:2px;
    classDef qpu fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef pointcloud fill:#d6eaf8,stroke:#3498db,stroke-width:2px;

    %% Click Events
    click CubeEdge "https://github.com/suferqin/fast-qpu/tree/main/CubeEdge"
    click Models "https://github.com/suferqin/fast-qpu/tree/main/models"
    click Config "https://github.com/suferqin/fast-qpu/tree/main/configs"
    click Data "https://github.com/suferqin/fast-qpu/tree/main/data"
    click Utils "https://github.com/suferqin/fast-qpu/tree/main/utils"
    click QPU "https://github.com/suferqin/fast-qpu/tree/main/_ext_qpu"
    click PointNet "https://github.com/suferqin/fast-qpu/tree/main/pointcloud/PointNet++"
    click RSCNN "https://github.com/suferqin/fast-qpu/tree/main/pointcloud/RSCNN"
    click Train "https://github.com/suferqin/fast-qpu/blob/main/train.py"
    click Test "https://github.com/suferqin/fast-qpu/blob/main/test.py"
```
