# amshaker/groupmamba architecture

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

- Interactive diagram: https://gitdiagram.com/amshaker/groupmamba
- Repository: https://github.com/amshaker/groupmamba

## Overview

GroupMamba is a visual state-space model project whose primary workflow trains and evaluates image-classification models. Training and evaluation configure the model and data pipeline, then run classification; the model uses grouped directional state-space blocks backed by selective-scan kernels. The README also describes distillation training and reports detection and segmentation results, but this tree exposes classification code only. Links reflect the excerpts, SOURCE INDEX references, and README; unsampled subsystem details are kept at directory level.

Main entry points: [`classification/train.py`](https://github.com/amshaker/groupmamba/blob/main/classification/train.py) (Model training), [`classification/eval.py`](https://github.com/amshaker/groupmamba/blob/main/classification/eval.py) (Model evaluation), [`classification/data/build.py`](https://github.com/amshaker/groupmamba/blob/main/classification/data/build.py) (Loader builder), [`kernels/selective_scan/csrc/selective_scan`](https://github.com/amshaker/groupmamba/tree/main/kernels/selective_scan/csrc/selective_scan) (CUDA scan implementations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Classification workflow"]
  node_config["Run configuration<br/>[config.py]"]
  node_train["Model training<br/>[train.py]"]
  node_evaluate["Model evaluation<br/>[eval.py]"]
end

subgraph group_data["Image data"]
  node_loader["Loader builder<br/>[build.py]"]
  node_folder["Folder and ZIP data"]
  node_zipreader["ZIP reader<br/>[zipreader.py]"]
  node_datasets["Specialized datasets"]
end

subgraph group_model["GroupMamba model"]
  node_modelcore["GroupMamba network<br/>[groupmamba.py]"]
  node_ss2d["SS2D blocks<br/>[ss2d.py]"]
  node_scans["Directional scans<br/>[csms6s.py]"]
end

subgraph group_training["Training support"]
  node_optimizer["Optimizer builder<br/>[optimizer.py]"]
  node_scheduler["LR scheduler<br/>[lr_scheduler.py]"]
  node_cosine["Cosine scheduler<br/>[cosine_lr.py]"]
  node_logger["Logging<br/>[logger.py]"]
  node_utilities["Training utilities<br/>[utils.py]"]
end

subgraph group_kernel["Selective scan kernels"]
  node_scanapi["Scan API<br/>[selective_scan.h]"]
  node_scanimpl["CUDA scan implementations"]
  node_ndstate["ND-state API"]
end

node_user(("Researcher"))

node_user -->|"starts training"| node_train
node_user -->|"starts evaluation"| node_evaluate
node_train -->|"loads settings"| node_config
node_evaluate -->|"loads settings"| node_config
node_train -->|"builds loaders"| node_loader
node_evaluate -->|"builds loaders"| node_loader
node_loader -->|"constructs dataset"| node_folder
node_folder -->|"reads archive images"| node_zipreader
node_loader -->|"selects dataset"| node_datasets
node_train -->|"creates model"| node_modelcore
node_evaluate -->|"creates model"| node_modelcore
node_modelcore -->|"instantiates blocks"| node_ss2d
node_ss2d -->|"uses scan functions"| node_scans
node_scans -->|"dispatches scan operations"| node_scanimpl
node_scanimpl -->|"uses scan parameters"| node_scanapi
node_scanimpl -->|"uses ND-state API"| node_ndstate
node_train -->|"builds optimizer"| node_optimizer
node_train -->|"builds scheduler"| node_scheduler
node_scheduler -->|"uses cosine scheduler"| node_cosine
node_train -->|"logs progress"| node_logger
node_train -->|"uses utilities"| node_utilities
node_evaluate -->|"builds optimizer"| node_optimizer
node_evaluate -->|"logs results"| node_logger

click node_config "https://github.com/amshaker/groupmamba/blob/main/classification/config.py"
click node_train "https://github.com/amshaker/groupmamba/blob/main/classification/train.py"
click node_evaluate "https://github.com/amshaker/groupmamba/blob/main/classification/eval.py"
click node_loader "https://github.com/amshaker/groupmamba/blob/main/classification/data/build.py"
click node_folder "https://github.com/amshaker/groupmamba/blob/main/classification/data/cached_image_folder.py"
click node_zipreader "https://github.com/amshaker/groupmamba/blob/main/classification/data/zipreader.py"
click node_datasets "https://github.com/amshaker/groupmamba/tree/main/classification/data"
click node_modelcore "https://github.com/amshaker/groupmamba/blob/main/classification/models/groupmamba.py"
click node_ss2d "https://github.com/amshaker/groupmamba/blob/main/classification/models/ss2d.py"
click node_scans "https://github.com/amshaker/groupmamba/blob/main/classification/models/csms6s.py"
click node_optimizer "https://github.com/amshaker/groupmamba/blob/main/classification/utils/optimizer.py"
click node_scheduler "https://github.com/amshaker/groupmamba/blob/main/classification/utils/lr_scheduler.py"
click node_cosine "https://github.com/amshaker/groupmamba/blob/main/classification/utils/cosine_lr.py"
click node_logger "https://github.com/amshaker/groupmamba/blob/main/classification/utils/logger.py"
click node_utilities "https://github.com/amshaker/groupmamba/blob/main/classification/utils/utils.py"
click node_scanapi "https://github.com/amshaker/groupmamba/blob/main/kernels/selective_scan/csrc/selective_scan/selective_scan.h"
click node_scanimpl "https://github.com/amshaker/groupmamba/tree/main/kernels/selective_scan/csrc/selective_scan"
click node_ndstate "https://github.com/amshaker/groupmamba/blob/main/kernels/selective_scan/csrc/selective_scan/cusndstate/selective_scan_ndstate.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_train,node_evaluate toneBlue
class node_loader,node_folder,node_zipreader,node_datasets toneAmber
class node_modelcore,node_ss2d,node_scans toneMint
class node_optimizer,node_scheduler,node_cosine,node_logger,node_utilities toneRose
class node_scanapi,node_scanimpl,node_ndstate,node_user toneIndigo
```

## Components

### Classification workflow

- [Run configuration](https://github.com/amshaker/groupmamba/blob/main/classification/config.py): `classification/config.py`
- [Model training](https://github.com/amshaker/groupmamba/blob/main/classification/train.py): `classification/train.py`
- [Model evaluation](https://github.com/amshaker/groupmamba/blob/main/classification/eval.py): `classification/eval.py`

### Image data

- [Loader builder](https://github.com/amshaker/groupmamba/blob/main/classification/data/build.py): `classification/data/build.py`
- [Folder and ZIP data](https://github.com/amshaker/groupmamba/blob/main/classification/data/cached_image_folder.py): `classification/data/cached_image_folder.py`
- [ZIP reader](https://github.com/amshaker/groupmamba/blob/main/classification/data/zipreader.py): `classification/data/zipreader.py`
- [Specialized datasets](https://github.com/amshaker/groupmamba/tree/main/classification/data): `classification/data`

### GroupMamba model

- [GroupMamba network](https://github.com/amshaker/groupmamba/blob/main/classification/models/groupmamba.py): `classification/models/groupmamba.py`
- [SS2D blocks](https://github.com/amshaker/groupmamba/blob/main/classification/models/ss2d.py): `classification/models/ss2d.py`
- [Directional scans](https://github.com/amshaker/groupmamba/blob/main/classification/models/csms6s.py): `classification/models/csms6s.py`

### Training support

- [Optimizer builder](https://github.com/amshaker/groupmamba/blob/main/classification/utils/optimizer.py): `classification/utils/optimizer.py`
- [LR scheduler](https://github.com/amshaker/groupmamba/blob/main/classification/utils/lr_scheduler.py): `classification/utils/lr_scheduler.py`
- [Cosine scheduler](https://github.com/amshaker/groupmamba/blob/main/classification/utils/cosine_lr.py): `classification/utils/cosine_lr.py`
- [Logging](https://github.com/amshaker/groupmamba/blob/main/classification/utils/logger.py): `classification/utils/logger.py`
- [Training utilities](https://github.com/amshaker/groupmamba/blob/main/classification/utils/utils.py): `classification/utils/utils.py`

### Selective scan kernels

- [Scan API](https://github.com/amshaker/groupmamba/blob/main/kernels/selective_scan/csrc/selective_scan/selective_scan.h): `kernels/selective_scan/csrc/selective_scan/selective_scan.h`
- [CUDA scan implementations](https://github.com/amshaker/groupmamba/tree/main/kernels/selective_scan/csrc/selective_scan): `kernels/selective_scan/csrc/selective_scan`
- [ND-state API](https://github.com/amshaker/groupmamba/blob/main/kernels/selective_scan/csrc/selective_scan/cusndstate/selective_scan_ndstate.h): `kernels/selective_scan/csrc/selective_scan/cusndstate/selective_scan_ndstate.h`

### Other components

- **Researcher**

## Connections

- Researcher → Model training: starts training (evidence: `README.md`)
- Researcher → Model evaluation: starts evaluation (evidence: `README.md`)
- Model training → Run configuration: loads settings (evidence: `classification/train.py`)
- Model evaluation → Run configuration: loads settings (evidence: `classification/eval.py`)
- Model training → Loader builder: builds loaders (evidence: `classification/train.py`)
- Model evaluation → Loader builder: builds loaders (evidence: `classification/eval.py`)
- Loader builder → Folder and ZIP data: constructs dataset (evidence: `classification/data/build.py`)
- Folder and ZIP data → ZIP reader: reads archive images (evidence: `classification/data/cached_image_folder.py`)
- Loader builder → Specialized datasets: selects dataset (evidence: `classification/data/__init__.py`)
- Model training → GroupMamba network: creates model (evidence: `classification/train.py`)
- Model evaluation → GroupMamba network: creates model (evidence: `classification/eval.py`)
- GroupMamba network → SS2D blocks: instantiates blocks (evidence: `classification/models/groupmamba.py`)
- SS2D blocks → Directional scans: uses scan functions (evidence: `classification/models/ss2d.py`)
- Directional scans → CUDA scan implementations: dispatches scan operations (evidence: `classification/models/csms6s.py`)
- CUDA scan implementations → Scan API: uses scan parameters (evidence: `kernels/selective_scan/csrc/selective_scan/cus/selective_scan.cpp`)
- CUDA scan implementations → ND-state API: uses ND-state API (evidence: `kernels/selective_scan/csrc/selective_scan/cusndstate/selective_scan_ndstate.cpp`)
- Model training → Optimizer builder: builds optimizer (evidence: `classification/train.py`)
- Model training → LR scheduler: builds scheduler (evidence: `classification/train.py`)
- LR scheduler → Cosine scheduler: uses cosine scheduler (evidence: `classification/utils/lr_scheduler.py`)
- Model training → Logging: logs progress (evidence: `classification/train.py`)
- Model training → Training utilities: uses utilities (evidence: `classification/train.py`)
- Model evaluation → Optimizer builder: builds optimizer (evidence: `classification/eval.py`)
- Model evaluation → Logging: logs results (evidence: `classification/eval.py`)
