# mit-mi/smellnet architecture

> Architecture diagram of the GitHub repository mit-mi/smellnet, 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/mit-mi/smellnet
- Repository: https://github.com/mit-mi/smellnet

## Overview

SmellNet is a sensor-based smell-recognition benchmark and research pipeline. Its main workflow runs from MOX sensor recordings through preprocessing and sliding-window preparation into single-substance or mixture modeling, evaluation, and predictions. Separate branches support serial data capture, GC-MS spectrum processing for optional training-time sensor-chemistry alignment, and exploratory analyses. The README documents the overall workflow; source-level evidence is limited to the sampled files and SOURCE INDEX, so uncertain implementation links are omitted.

Main entry points: [`models/run.py`](https://github.com/mit-mi/smellnet/blob/main/models/run.py) (Base experiments), [`models/run_mixture.py`](https://github.com/mit-mi/smellnet/blob/main/models/run_mixture.py) (Mixture experiments), [`models/dataset.py`](https://github.com/mit-mi/smellnet/blob/main/models/dataset.py) (Windowed datasets), [`models/load_data.py`](https://github.com/mit-mi/smellnet/blob/main/models/load_data.py) (Sensor data loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Sensing and acquisition"]
  node_sensor(("MOX sensors"))
  node_sensor_drivers["Sensor drivers<br/>[bme68x.c]"]
  node_serial_capture["Serial capture"]
end

subgraph group_preparation["Data preparation"]
  node_raw_cleanup["Raw-data processing"]
  node_column_correction["Column correction<br/>[correct_column.py]"]
  node_sensor_loader["Sensor data loading<br/>[load_data.py]"]
  node_window_dataset["Windowed datasets<br/>[dataset.py]"]
end

subgraph group_modeling["Modeling and evaluation"]
  node_base_runner["Base experiments<br/>[run.py]"]
  node_mixture_runner["Mixture experiments<br/>[run_mixture.py]"]
  node_architectures["Temporal architectures<br/>[models.py]"]
  node_training["Training and losses<br/>[train.py]"]
  node_evaluation["Evaluation<br/>[evaluate.py]"]
  node_predictions["Recognition results"]
end

subgraph group_chemistry["GC-MS supervision"]
  node_gcms_foods["Food identifiers<br/>[food.py]"]
  node_gcms_processing["GC-MS processing<br/>[gcms_analysis.py]"]
  node_gcms_analysis["GC-MS analysis<br/>[analysis.py]"]
  node_chemistry_vectors["GC-MS vectors"]
end

subgraph group_research["Analysis and figures"]
  node_sensor_analysis["Sensor analyses<br/>[tsne_analysis.py]"]
  node_gcms_figures["GC-MS figures"]
end

node_sensor -.->|"measured by"| node_sensor_drivers
node_sensor -->|"recorded by"| node_serial_capture
node_serial_capture -.->|"supplies recordings"| node_raw_cleanup
node_raw_cleanup -.->|"prepares data"| node_column_correction
node_sensor_loader -->|"segments windows"| node_window_dataset
node_window_dataset -->|"feeds training"| node_base_runner
node_window_dataset -->|"feeds training"| node_mixture_runner
node_base_runner -->|"builds models"| node_architectures
node_mixture_runner -->|"builds models"| node_architectures
node_base_runner -->|"trains"| node_training
node_base_runner -->|"evaluates"| node_evaluation
node_base_runner -->|"produces"| node_predictions
node_mixture_runner -.->|"trains"| node_training
node_mixture_runner -->|"produces ratios"| node_predictions
node_gcms_foods -->|"supplies food IDs"| node_gcms_analysis
node_gcms_foods -->|"supplies food IDs"| node_gcms_processing
node_gcms_processing -->|"generates vectors"| node_chemistry_vectors
node_gcms_analysis -->|"generates vectors"| node_chemistry_vectors
node_chemistry_vectors -.->|"optional supervision"| node_base_runner
node_sensor_loader -.->|"analyzes signals"| node_sensor_analysis
node_chemistry_vectors -.->|"visualized by"| node_gcms_figures

click node_sensor_drivers "https://github.com/mit-mi/smellnet/blob/main/Arduino/libraries/Adafruit_BME680_Library/bme68x.c"
click node_serial_capture "https://github.com/mit-mi/smellnet/blob/main/data_collection/serial-data-collect-csv.py"
click node_raw_cleanup "https://github.com/mit-mi/smellnet/blob/main/preprocessing/process_raw_data.py"
click node_column_correction "https://github.com/mit-mi/smellnet/blob/main/preprocessing/correct_column.py"
click node_sensor_loader "https://github.com/mit-mi/smellnet/blob/main/models/load_data.py"
click node_window_dataset "https://github.com/mit-mi/smellnet/blob/main/models/dataset.py"
click node_base_runner "https://github.com/mit-mi/smellnet/blob/main/models/run.py"
click node_mixture_runner "https://github.com/mit-mi/smellnet/blob/main/models/run_mixture.py"
click node_architectures "https://github.com/mit-mi/smellnet/blob/main/models/models.py"
click node_training "https://github.com/mit-mi/smellnet/blob/main/models/train.py"
click node_evaluation "https://github.com/mit-mi/smellnet/blob/main/models/evaluate.py"
click node_gcms_foods "https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/food.py"
click node_gcms_processing "https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/gcms_analysis.py"
click node_gcms_analysis "https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/analysis.py"
click node_sensor_analysis "https://github.com/mit-mi/smellnet/blob/main/analysis/tsne_analysis.py"
click node_gcms_figures "https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/gcms_paper_figures.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_sensor,node_sensor_drivers,node_serial_capture toneBlue
class node_raw_cleanup,node_column_correction,node_sensor_loader,node_window_dataset toneAmber
class node_base_runner,node_mixture_runner,node_architectures,node_training,node_evaluation,node_predictions toneMint
class node_gcms_foods,node_gcms_processing,node_gcms_analysis,node_chemistry_vectors toneRose
class node_sensor_analysis,node_gcms_figures toneIndigo
```

## Components

### Sensing and acquisition

- **MOX sensors**
- [Sensor drivers](https://github.com/mit-mi/smellnet/blob/main/Arduino/libraries/Adafruit_BME680_Library/bme68x.c): `Arduino/libraries/Adafruit_BME680_Library/bme68x.c`
- [Serial capture](https://github.com/mit-mi/smellnet/blob/main/data_collection/serial-data-collect-csv.py): `data_collection/serial-data-collect-csv.py`

### Data preparation

- [Raw-data processing](https://github.com/mit-mi/smellnet/blob/main/preprocessing/process_raw_data.py): `preprocessing/process_raw_data.py`
- [Column correction](https://github.com/mit-mi/smellnet/blob/main/preprocessing/correct_column.py): `preprocessing/correct_column.py`
- [Sensor data loading](https://github.com/mit-mi/smellnet/blob/main/models/load_data.py): `models/load_data.py`
- [Windowed datasets](https://github.com/mit-mi/smellnet/blob/main/models/dataset.py): `models/dataset.py`

### Modeling and evaluation

- [Base experiments](https://github.com/mit-mi/smellnet/blob/main/models/run.py): `models/run.py`
- [Mixture experiments](https://github.com/mit-mi/smellnet/blob/main/models/run_mixture.py): `models/run_mixture.py`
- [Temporal architectures](https://github.com/mit-mi/smellnet/blob/main/models/models.py): `models/models.py`
- [Training and losses](https://github.com/mit-mi/smellnet/blob/main/models/train.py): `models/train.py`
- [Evaluation](https://github.com/mit-mi/smellnet/blob/main/models/evaluate.py): `models/evaluate.py`
- **Recognition results**

### GC-MS supervision

- [Food identifiers](https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/food.py): `gcms_analysis/food.py`
- [GC-MS processing](https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/gcms_analysis.py): `gcms_analysis/gcms_analysis.py`
- [GC-MS analysis](https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/analysis.py): `gcms_analysis/analysis.py`
- **GC-MS vectors**

### Analysis and figures

- [Sensor analyses](https://github.com/mit-mi/smellnet/blob/main/analysis/tsne_analysis.py): `analysis/tsne_analysis.py`
- [GC-MS figures](https://github.com/mit-mi/smellnet/blob/main/gcms_analysis/gcms_paper_figures.py): `gcms_analysis/gcms_paper_figures.py`

## Connections

- MOX sensors → Sensor drivers: measured by
- MOX sensors → Serial capture: recorded by (evidence: `README.md`)
- Serial capture → Raw-data processing: supplies recordings
- Raw-data processing → Column correction: prepares data
- Sensor data loading → Windowed datasets: segments windows (evidence: `README.md`)
- Windowed datasets → Base experiments: feeds training (evidence: `README.md`)
- Windowed datasets → Mixture experiments: feeds training (evidence: `README.md`)
- Base experiments → Temporal architectures: builds models (evidence: `models/run.py`)
- Mixture experiments → Temporal architectures: builds models (evidence: `models/run_mixture.py`)
- Base experiments → Training and losses: trains (evidence: `models/run.py`)
- Base experiments → Evaluation: evaluates (evidence: `models/run.py`)
- Base experiments → Recognition results: produces (evidence: `README.md`)
- Mixture experiments → Training and losses: trains
- Mixture experiments → Recognition results: produces ratios (evidence: `README.md`)
- Food identifiers → GC-MS analysis: supplies food IDs (evidence: `gcms_analysis/analysis.py`)
- Food identifiers → GC-MS processing: supplies food IDs (evidence: `gcms_analysis/gcms_analysis.py`)
- GC-MS processing → GC-MS vectors: generates vectors (evidence: `README.md`)
- GC-MS analysis → GC-MS vectors: generates vectors (evidence: `README.md`)
- GC-MS vectors → Base experiments: optional supervision (evidence: `README.md`)
- Sensor data loading → Sensor analyses: analyzes signals
- GC-MS vectors → GC-MS figures: visualized by
