# soumithbabburi/swapo architecture

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

- Interactive diagram: https://gitdiagram.com/soumithbabburi/swapo
- Repository: https://github.com/soumithbabburi/swapo

## Overview

SWaPO is a genomic-table physical-design adviser: it observes query workloads and table characteristics, recommends storage/layout changes, and estimates their read-cost impact. Its user-facing path is the `swapo advise` command; separate benchmark and paper workflows evaluate the method on simulated and real genomic data. The graph includes core decision, data, pruning, execution, and storage-cost layers. Some subsystem connections rely on the SOURCE INDEX’s import/name references or README descriptions; unsampled internals are not treated as verified call paths.

Main entry points: [`swapo/optimizer.py`](https://github.com/soumithbabburi/swapo/blob/main/swapo/optimizer.py) (Recommendation engine), [`swapo/model.py`](https://github.com/soumithbabburi/swapo/blob/main/swapo/model.py) (Genomic model), [`swapo/cli.py`](https://github.com/soumithbabburi/swapo/blob/main/swapo/cli.py) (CLI), [`swapo/experiments.py`](https://github.com/soumithbabburi/swapo/blob/main/swapo/experiments.py) (Research experiments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_decision["Optimization"]
  node_workload["Workload analysis<br/>[workload.py]"]
  node_optimizer["Recommendation engine<br/>[optimizer.py]"]
  node_cost["Read-cost model<br/>[cost.py]"]
  node_threshold["Split decision<br/>[threshold.py]"]
  node_blocksize["Block-size search<br/>[blocksize.py]"]
  node_rowgroups["Row-group sizing<br/>[rowgroups.py]"]
  node_provenance["Input provenance<br/>[provenance.py]"]
  node_staleness["Freshness costs<br/>[staleness.py]"]
end

subgraph group_data["Genomic data"]
  node_model["Genomic model<br/>[model.py]"]
  node_real["Real-file readers<br/>[real.py]"]
  node_simdata["Data simulator<br/>[data.py]"]
  node_stats["Table statistics<br/>[stats.py]"]
end

subgraph group_runtime["Query runtime"]
  node_layout["Layout writer<br/>[layout.py]"]
  node_zonemap["Interval zone map<br/>[zonemap.py]"]
  node_engine["Query executor<br/>[engine.py]"]
  node_objstore["Object-store costs<br/>[objstore.py]"]
end

subgraph group_evaluation["Measurement"]
  node_experiments["Research experiments<br/>[experiments.py]"]
  node_realbench["Real-data benchmark<br/>[realbench.py]"]
  node_rgbench["Row-group benchmark<br/>[rgbench.py]"]
  node_formatbench["Format benchmark<br/>[formatbench.py]"]
end

node_user(("Analyst"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_optimizer
node_cli -->|"dispatches"| node_experiments
node_cli -->|"uses readers"| node_real
node_cli -->|"uses layouts"| node_layout
node_cli -->|"uses sizing"| node_rowgroups
node_cli -->|"uses costs"| node_objstore
node_optimizer -->|"analyzes"| node_workload
node_optimizer -->|"estimates cost"| node_cost
node_optimizer -->|"chooses size"| node_rowgroups
node_optimizer -->|"evaluates split"| node_threshold
node_optimizer -->|"models storage"| node_objstore
node_optimizer -->|"uses lineage"| node_provenance
node_optimizer -->|"checks freshness"| node_staleness
node_optimizer -->|"uses table data"| node_model
node_optimizer -->|"uses pruning stats"| node_zonemap
node_workload -->|"classifies queries"| node_model
node_cost -->|"costs table"| node_model
node_cost -->|"uses workload"| node_workload
node_cost -->|"models pruning"| node_zonemap
node_threshold -.->|"evaluates intervals"| node_model
node_blocksize -->|"uses threshold"| node_threshold
node_rowgroups -->|"models requests"| node_objstore
node_real -->|"shares data model"| node_simdata
node_real -.->|"builds tables"| node_model
node_simdata -->|"builds tables"| node_model
node_stats -->|"summarizes tables"| node_simdata
node_stats -->|"uses table types"| node_model
node_layout -->|"writes table data"| node_simdata
node_layout -->|"builds blocks"| node_model
node_layout -->|"populates map"| node_zonemap
node_engine -->|"prunes blocks"| node_zonemap
node_engine -->|"runs queries"| node_model
node_experiments -->|"loads data"| node_simdata
node_experiments -->|"loads real data"| node_real
node_experiments -->|"evaluates queries"| node_engine
node_experiments -->|"compares layouts"| node_layout
node_experiments -->|"records statistics"| node_stats
node_experiments -->|"checks split choice"| node_threshold
node_realbench -->|"benchmarks queries"| node_engine
node_realbench -->|"loads real data"| node_real
node_rgbench -->|"measures requests"| node_objstore
node_rgbench -->|"benchmarks sizing"| node_rowgroups
node_formatbench -->|"uses benchmarks"| node_rgbench
node_formatbench -->|"tests row groups"| node_rowgroups

click node_cli "https://github.com/soumithbabburi/swapo/blob/main/swapo/cli.py"
click node_workload "https://github.com/soumithbabburi/swapo/blob/main/swapo/workload.py"
click node_optimizer "https://github.com/soumithbabburi/swapo/blob/main/swapo/optimizer.py"
click node_cost "https://github.com/soumithbabburi/swapo/blob/main/swapo/cost.py"
click node_threshold "https://github.com/soumithbabburi/swapo/blob/main/swapo/threshold.py"
click node_blocksize "https://github.com/soumithbabburi/swapo/blob/main/swapo/blocksize.py"
click node_rowgroups "https://github.com/soumithbabburi/swapo/blob/main/swapo/rowgroups.py"
click node_provenance "https://github.com/soumithbabburi/swapo/blob/main/swapo/provenance.py"
click node_staleness "https://github.com/soumithbabburi/swapo/blob/main/swapo/staleness.py"
click node_model "https://github.com/soumithbabburi/swapo/blob/main/swapo/model.py"
click node_real "https://github.com/soumithbabburi/swapo/blob/main/swapo/real.py"
click node_simdata "https://github.com/soumithbabburi/swapo/blob/main/swapo/data.py"
click node_stats "https://github.com/soumithbabburi/swapo/blob/main/swapo/stats.py"
click node_layout "https://github.com/soumithbabburi/swapo/blob/main/swapo/layout.py"
click node_zonemap "https://github.com/soumithbabburi/swapo/blob/main/swapo/zonemap.py"
click node_engine "https://github.com/soumithbabburi/swapo/blob/main/swapo/engine.py"
click node_objstore "https://github.com/soumithbabburi/swapo/blob/main/swapo/objstore.py"
click node_experiments "https://github.com/soumithbabburi/swapo/blob/main/swapo/experiments.py"
click node_realbench "https://github.com/soumithbabburi/swapo/blob/main/swapo/realbench.py"
click node_rgbench "https://github.com/soumithbabburi/swapo/blob/main/swapo/rgbench.py"
click node_formatbench "https://github.com/soumithbabburi/swapo/blob/main/swapo/formatbench.py"

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_cli toneBlue
class node_workload,node_optimizer,node_cost,node_threshold,node_blocksize,node_rowgroups,node_provenance,node_staleness toneAmber
class node_model,node_real,node_simdata,node_stats toneMint
class node_layout,node_zonemap,node_engine,node_objstore toneRose
class node_experiments,node_realbench,node_rgbench,node_formatbench,node_user toneIndigo
```

## Components

### User interface

- [CLI](https://github.com/soumithbabburi/swapo/blob/main/swapo/cli.py): `swapo/cli.py`

### Optimization

- [Workload analysis](https://github.com/soumithbabburi/swapo/blob/main/swapo/workload.py): `swapo/workload.py`
- [Recommendation engine](https://github.com/soumithbabburi/swapo/blob/main/swapo/optimizer.py): `swapo/optimizer.py`
- [Read-cost model](https://github.com/soumithbabburi/swapo/blob/main/swapo/cost.py): `swapo/cost.py`
- [Split decision](https://github.com/soumithbabburi/swapo/blob/main/swapo/threshold.py): `swapo/threshold.py`
- [Block-size search](https://github.com/soumithbabburi/swapo/blob/main/swapo/blocksize.py): `swapo/blocksize.py`
- [Row-group sizing](https://github.com/soumithbabburi/swapo/blob/main/swapo/rowgroups.py): `swapo/rowgroups.py`
- [Input provenance](https://github.com/soumithbabburi/swapo/blob/main/swapo/provenance.py): `swapo/provenance.py`
- [Freshness costs](https://github.com/soumithbabburi/swapo/blob/main/swapo/staleness.py): `swapo/staleness.py`

### Genomic data

- [Genomic model](https://github.com/soumithbabburi/swapo/blob/main/swapo/model.py): `swapo/model.py`
- [Real-file readers](https://github.com/soumithbabburi/swapo/blob/main/swapo/real.py): `swapo/real.py`
- [Data simulator](https://github.com/soumithbabburi/swapo/blob/main/swapo/data.py): `swapo/data.py`
- [Table statistics](https://github.com/soumithbabburi/swapo/blob/main/swapo/stats.py): `swapo/stats.py`

### Query runtime

- [Layout writer](https://github.com/soumithbabburi/swapo/blob/main/swapo/layout.py): `swapo/layout.py`
- [Interval zone map](https://github.com/soumithbabburi/swapo/blob/main/swapo/zonemap.py): `swapo/zonemap.py`
- [Query executor](https://github.com/soumithbabburi/swapo/blob/main/swapo/engine.py): `swapo/engine.py`
- [Object-store costs](https://github.com/soumithbabburi/swapo/blob/main/swapo/objstore.py): `swapo/objstore.py`

### Measurement

- [Research experiments](https://github.com/soumithbabburi/swapo/blob/main/swapo/experiments.py): `swapo/experiments.py`
- [Real-data benchmark](https://github.com/soumithbabburi/swapo/blob/main/swapo/realbench.py): `swapo/realbench.py`
- [Row-group benchmark](https://github.com/soumithbabburi/swapo/blob/main/swapo/rgbench.py): `swapo/rgbench.py`
- [Format benchmark](https://github.com/soumithbabburi/swapo/blob/main/swapo/formatbench.py): `swapo/formatbench.py`

### Other components

- **Analyst**

## Connections

- Analyst → CLI: invokes (evidence: `README.md`)
- CLI → Recommendation engine: dispatches (evidence: `swapo/cli.py`)
- CLI → Research experiments: dispatches (evidence: `swapo/cli.py`)
- CLI → Real-file readers: uses readers (evidence: `swapo/cli.py`)
- CLI → Layout writer: uses layouts (evidence: `swapo/cli.py`)
- CLI → Row-group sizing: uses sizing (evidence: `swapo/cli.py`)
- CLI → Object-store costs: uses costs (evidence: `swapo/cli.py`)
- Recommendation engine → Workload analysis: analyzes (evidence: `swapo/optimizer.py`)
- Recommendation engine → Read-cost model: estimates cost (evidence: `swapo/optimizer.py`)
- Recommendation engine → Row-group sizing: chooses size (evidence: `swapo/optimizer.py`)
- Recommendation engine → Split decision: evaluates split (evidence: `swapo/optimizer.py`)
- Recommendation engine → Object-store costs: models storage (evidence: `swapo/optimizer.py`)
- Recommendation engine → Input provenance: uses lineage (evidence: `swapo/optimizer.py`)
- Recommendation engine → Freshness costs: checks freshness (evidence: `swapo/optimizer.py`)
- Recommendation engine → Genomic model: uses table data (evidence: `swapo/optimizer.py`)
- Recommendation engine → Interval zone map: uses pruning stats (evidence: `swapo/optimizer.py`)
- Workload analysis → Genomic model: classifies queries (evidence: `swapo/workload.py`)
- Read-cost model → Genomic model: costs table (evidence: `swapo/cost.py`)
- Read-cost model → Workload analysis: uses workload (evidence: `swapo/cost.py`)
- Read-cost model → Interval zone map: models pruning (evidence: `swapo/cost.py`)
- Split decision → Genomic model: evaluates intervals
- Block-size search → Split decision: uses threshold (evidence: `swapo/blocksize.py`)
- Row-group sizing → Object-store costs: models requests (evidence: `swapo/rowgroups.py`)
- Real-file readers → Data simulator: shares data model (evidence: `swapo/real.py`)
- Real-file readers → Genomic model: builds tables
- Data simulator → Genomic model: builds tables (evidence: `swapo/data.py`)
- Table statistics → Data simulator: summarizes tables (evidence: `swapo/stats.py`)
- Table statistics → Genomic model: uses table types (evidence: `swapo/stats.py`)
- Layout writer → Data simulator: writes table data (evidence: `swapo/layout.py`)
- Layout writer → Genomic model: builds blocks (evidence: `swapo/layout.py`)
- Layout writer → Interval zone map: populates map (evidence: `swapo/layout.py`)
- Query executor → Interval zone map: prunes blocks (evidence: `swapo/engine.py`)
- Query executor → Genomic model: runs queries (evidence: `swapo/engine.py`)
- Research experiments → Data simulator: loads data (evidence: `swapo/experiments.py`)
- Research experiments → Real-file readers: loads real data (evidence: `swapo/experiments.py`)
- Research experiments → Query executor: evaluates queries (evidence: `swapo/experiments.py`)
- Research experiments → Layout writer: compares layouts (evidence: `swapo/experiments.py`)
- Research experiments → Table statistics: records statistics (evidence: `swapo/experiments.py`)
- Research experiments → Split decision: checks split choice (evidence: `swapo/experiments.py`)
- Real-data benchmark → Query executor: benchmarks queries (evidence: `swapo/realbench.py`)
- Real-data benchmark → Real-file readers: loads real data (evidence: `swapo/realbench.py`)
- Row-group benchmark → Object-store costs: measures requests (evidence: `swapo/rgbench.py`)
- Row-group benchmark → Row-group sizing: benchmarks sizing (evidence: `swapo/rgbench.py`)
- Format benchmark → Row-group benchmark: uses benchmarks (evidence: `swapo/formatbench.py`)
- Format benchmark → Row-group sizing: tests row groups (evidence: `swapo/formatbench.py`)
