# paramind2025/can architecture

> Architecture diagram of the GitHub repository paramind2025/can, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paramind2025/can
- Repository: https://github.com/paramind2025/can

## Overview

##### Project type & purpose (from README + tree)
**Project type:** research-grade **PyTorch vision backbone** implementation (CliffordNet / Clifford Algebra Network) with a **training script** and an **optional compiled CUDA extension** for acceleration.

**Primary purpose:** train/evaluate CliffordNet variants (e.g., Nano/Lite/Deep) on **CIFAR-100** under a “modern recipe”, and benchmark **two execution modes**:
- **Compatibility mode:** pure PyTorch implementation
- **High-performance mode:** custom kernel packaged as `clifford_thrust` wheels (installed via `pip`), enabled via `--enable_cuda`

**Key architectural “twist” worth diagramming:** a **Clifford Interaction layer** that can dispatch to:
- a **custom CUDA path** (when `clifford_thrust` is installed and enabled), or
- a **PyTorch fallback** path

##### File structure into diagrammable components
Top-level files strongly suggest a compact repo organized by “script + model modules + utilities + optional native extension”:

- `train.py`
**Orchestrator / entrypoint**: argument parsing (`--enable_cuda`), dataset setup (CIFAR-100), training loop, evaluation, checkpoint/logging.
- `model.py`
**Top-level model assembly**: `CliffordNet` class, selection of variants via parameters (`patch_size`, `embed_dim`, `depth`, `cli_mode`, `ctx_mode`, etc.).
- `networks.py`
**Network building blocks**: stages/blocks, patch embedding, normalization, classifier head, drop path, etc. (whatever is factored out of `model.py`).
- `gffn.py`
- `utils.py`
Cross-cutting helpers: metrics, LR scheduling, augmentation, checkpointing, device selection, seed, etc.
- `cuda/`
- Prebuilt wheels: `clifford_thrust-...whl`
**Native extension distribution artifact** (binary).
- `cuda/whl.md`
Installation notes / compatibility constraints (RTX 4090, CUDA versions).

##### Extract “architecture requirements” from README (what must be shown)
- **Two execution modes** (accelerated vs pure PyTorch) and the **fallback behavior**
- Hardware/software constraints for accelerated mode (specific CUDA/Python versions; optimized for RTX 4090)
- The training usage path (`python train.py ...`)
- Model configuration knobs that meaningfully change compute graph:
- `cli_mode` (e.g., “full”)
- `ctx_mode` (“diff” vs “full”)
- `shifts`, `depth`, `embed_dim`, `drop_path_rate`

##### Artifacts (checkpoints, logs/metrics)

- User → `train.py` (CLI invocation; flags)
- `train.py` → Dataset loader (download/load/augment)
- `train.py` → Model construction (`CliffordNet(...)`)
- Forward/backward: Model ↔ PyTorch Autograd
- Conditional: Model → `clifford_thrust` (only when enabled/available) → CUDA/GPU
- Outputs: `train.py` → checkpoints/logs

Focus: how `CliffordNet` is built and where the Clifford Interaction sits.

- **Input image** (CIFAR-100)
- **Patch embedding / stem** (because README exposes `patch_size`, `embed_dim`)
- **Backbone blocks × depth**
- **Context builder** (depends on `ctx_mode`: diff/full)
- **Clifford Interaction Layer**
- **Dispatch:**
- PyTorch implementation
- or `clifford_thrust` kernel
- **(Optional) FFN / gFFN** (controlled by “No-FFN” vs baseline/ablation)
- **Residual / norm / drop path** (since `drop_path_rate` is exposed)
- **Pooling / classifier head**

- Dataflow through blocks
- A *branch* inside Clifford Interaction showing the accelerated vs fallback path

Focus: runtime sequencing, not static structure.

- `train.py` orchestration
- Data pipeline
- Model forward
- Loss/metrics
- Optimizer/scheduler
- Checkpoint/logging

Show:
##### Periodic eval and checkpoint

These are the interactions that matter most for accuracy:

##### Mode selection & fallback
- `--enable_cuda` flag (from README)
- runtime check “is clifford_thrust installed?” (README: “code automatically handles fallback”)

##### Python ↔ Native boundary
- That the extension is a *binary wheel* (distribution artifact) loaded by Python.
- That the extension accelerates a specific operation (Clifford Interaction / geometric product).

##### Hardware dependency
- GPU is not just “compute”; it is a **compatibility constraint** (RTX 4090 optimized; compute capability mentioned). Put this as a note callout on the accelerated path.

##### Artifacts
- Checkpoints and logs are outputs; include filesystem as a node (even if not shown in tree).

##### Open each file and confirm the real boundaries
- Where is CIFAR-100 loaded? (in `train.py` or `utils.py`)
- Where is the CUDA extension imported? (likely in `networks.py` or a dedicated op wrapper)
- What is the exact class/function name for the interaction layer?
##### Reflect reality, not intention
- If `gffn.py` is unused in current CIFAR experiments, mark it “optional/ablation”.
##### Annotate key configuration parameters at the component they affect
- `ctx_mode` next to Context Builder
- `cli_mode` next to Clifford Interaction
- `drop_path_rate` next to residual/drop path
##### Make the accelerated path unmissable
- conditional edge + hardware note + wheel artifact node.
- Iterative loop and the artifact outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ============================================================
  %% Diagram A: Container-level (system context / runtime containers)
  %% ============================================================
  subgraph A["A) Container-level: training runtime & optional acceleration"]
    direction TB

    U["User / Researcher"]:::external
    R["Project Documentation\n(usage, modes, knobs)"]:::doc
    T["Training Entrypoint\ntrain.py"]:::python

    DS[("CIFAR-100 Dataset\n(download/load/augment)")]:::data
    UT["Utilities\n(utils.py)"]:::python
    MP["Model Package\n(CliffordNet + blocks)"]:::python

    M["CliffordNet Assembly\n(model.py)"]:::python
    N["Backbone Components\n(networks.py)"]:::python
    G["Optional FFN / gFFN\n(gffn.py)"]:::python

    PT(["PyTorch Runtime\n(autograd, ops)"]):::runtime
    DEV["Device Selector\n(CPU/GPU)"]:::runtime

    DEC{"Dispatch?\n--enable_cuda\n& wheel installed"}:::decision
    EXT["Native Extension\nclifford_thrust (wheel)"]:::native
    CUDA(["CUDA Runtime"]):::runtime
    GPU["NVIDIA GPU\n(optimized for RTX 4090)"]:::gpu

    ART[("Artifacts\n(checkpoints, logs, metrics)")]:::artifact

    %% Flows (vertical)
    U -->|"reads"| R
    U -->|"runs CLI"| T

    T -->|"parses args\n(--enable_cuda, depth, embed_dim, ctx_mode, cli_mode)"| UT
    T -->|"loads/augments"| DS
    T -->|"selects device"| DEV

    T -->|"constructs model"| M
    M -->|"composes"| N
    N -.->|"optional/ablation"| G
    M -->|"uses ops"| PT

    T -->|"train/eval loop\n(fwd/bwd)"| PT

    %% Explicit conditional boundary
    M -->|"invokes Clifford Interaction"| DEC
    DEC -->|"fallback (pure PyTorch)"| PT
    DEC -.->|"accelerated path"| EXT
    EXT -->|"launches kernels"| CUDA
    CUDA -->|"executes on"| GPU
    PT -->|"tensor ops on"| GPU

    T -->|"writes"| ART

    %% Notes / constraints (kept vertical)
    NOTE1["Accelerated mode constraints:\nCUDA/Python/arch compatibility\n(see wheel notes)"]:::note
    EXT -.->|"requires"| NOTE1
  end

  %% ============================================================
  %% Diagram B: Component-level (inside CliffordNet)
  %% ============================================================
  subgraph B["B) Component-level: CliffordNet internal dataflow"]
    direction TB

    IN["Input Image\n(CIFAR-100 32x32)"]:::data
    STEM["Patch Embedding / Stem\n(patch_size, embed_dim)"]:::component
    STAGES["Backbone Stages\n(depth blocks)"]:::component
    BLK["Block (repeated)"]:::component

    NORM1["Norm"]:::component
    RES["Residual Path"]:::component
    DP["DropPath\n(drop_path_rate)"]:::component

    CTX["Context Builder\n(ctx_mode = diff | full)"]:::component
    CLI["Clifford Interaction Layer\n(cli_mode, shifts)"]:::hot

    DISPATCH{"Interaction Dispatch"}:::decision
    PTOPS["PyTorch Implementation\n(compatibility mode)"]:::pytorch
    KERN["clifford_thrust Kernel\n(high-performance mode)"]:::native
    CUDA2(["CUDA Runtime"]):::runtime
    GPU2["GPU"]:::gpu

    OPTFFN["Optional (g)FFN\n(ablation/baseline)"]:::optional
    HEAD["Pooling / Classifier Head"]:::component
    OUT["Logits"]:::component

    IN --> STEM --> STAGES --> BLK

    %% block internals
    BLK --> NORM1 --> CTX --> CLI --> DISPATCH
    DISPATCH -->|"fallback"| PTOPS
    DISPATCH -.->|"if enabled & installed"| KERN
    KERN --> CUDA2 --> GPU2
    PTOPS --> GPU2

    %% post-interaction
    PTOPS --> RES
    KERN --> RES
    RES --> DP --> OPTFFN --> HEAD --> OUT

    %% make optional explicit
    OPTFFN -.->|"can be removed\n(No-FFN setting)"| HEAD
  end

  %% ============================================================
  %% Diagram C: Training dataflow (per-iteration runtime)
  %% ============================================================
  subgraph C["C) Training dataflow: per-iteration sequence (runtime)"]
    direction TB

    TR["train.py\n(loop/orchestration)"]:::python
    PIPE["Data Pipeline\n(load -> augment -> batch)"]:::component
    MOVE["Move Batch to Device"]:::runtime
    FWD["Model Forward\n(CliffordNet)"]:::component
    LOSS["Loss Computation\n(criterion)"]:::component
    BWD["Backward Pass\n(autograd)"]:::runtime
    OPT["Optimizer Step\n(AdamW)"]:::component
    SCHED["LR Scheduler Step"]:::component
    MET["Metrics / Eval\n(top-1, etc.)"]:::component
    CKPT[("Checkpoint / Logs\n(filesystem)")]:::artifact

    TR --> PIPE --> MOVE --> FWD --> LOSS --> BWD --> OPT --> SCHED --> MET --> CKPT
    TR -.->|"periodic validation"| MET
    TR -.->|"save best/last"| CKPT
  end

  %% ============================================================
  %% Cross-diagram links (light)
  %% ============================================================
  T -->|"builds"| M
  T -->|"drives"| TR
  M -->|"implements"| FWD

  %% ============================================================
  %% Click Events (from component_mapping)
  %% ============================================================
  click T "https://github.com/paramind2025/can/blob/main/train.py"
  click TR "https://github.com/paramind2025/can/blob/main/train.py"
  click M "https://github.com/paramind2025/can/blob/main/model.py"
  click N "https://github.com/paramind2025/can/blob/main/networks.py"
  click G "https://github.com/paramind2025/can/blob/main/gffn.py"
  click UT "https://github.com/paramind2025/can/blob/main/utils.py"
  click EXT "https://github.com/paramind2025/can/blob/main/cuda/clifford_thrust-0.0.1-cp310-cp310-linux_x86_64.whl"
  click KERN "https://github.com/paramind2025/can/blob/main/cuda/clifford_thrust-0.0.1-cp312-cp312-linux_x86_64.whl"
  click NOTE1 "https://github.com/paramind2025/can/blob/main/cuda/whl.md"
  click R "https://github.com/paramind2025/can/blob/main/README.md"

  %% ============================================================
  %% Styles (color is critical)
  %% ============================================================
  classDef external fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px
  classDef doc fill:#fff7ed,stroke:#ea580c,color:#111827,stroke-width:1px
  classDef python fill:#ecfeff,stroke:#0891b2,color:#0f172a,stroke-width:1px
  classDef runtime fill:#eef2ff,stroke:#4f46e5,color:#0f172a,stroke-width:1px
  classDef data fill:#f0fdf4,stroke:#16a34a,color:#0f172a,stroke-width:1px
  classDef artifact fill:#fdf4ff,stroke:#a21caf,color:#0f172a,stroke-width:1px
  classDef component fill:#eff6ff,stroke:#2563eb,color:#0f172a,stroke-width:1px
  classDef pytorch fill:#dbeafe,stroke:#1d4ed8,color:#0f172a,stroke-width:2px
  classDef hot fill:#dbeafe,stroke:#0b5bd3,color:#0f172a,stroke-width:2px
  classDef native fill:#fee2e2,stroke:#dc2626,color:#0f172a,stroke-width:2px
  classDef gpu fill:#ffedd5,stroke:#f97316,color:#0f172a,stroke-width:2px
  classDef decision fill:#fef3c7,stroke:#d97706,color:#0f172a,stroke-width:2px
  classDef optional fill:#f5f5f5,stroke:#9ca3af,color:#111827,stroke-width:1px,stroke-dasharray: 4 4
  classDef note fill:#fff1f2,stroke:#e11d48,color:#0f172a,stroke-width:1px,stroke-dasharray: 3 3
```
