# d-li14/mobilenetv2.pytorch architecture

> Architecture diagram of the GitHub repository d-li14/mobilenetv2.pytorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d-li14/mobilenetv2.pytorch
- Repository: https://github.com/d-li14/mobilenetv2.pytorch

## Overview

#### Purpose and Entry Point
This is a PyTorch ImageNet training/evaluation repository centered on MobileNetV2. The CLI entry point is `imagenet.py`, which accepts architecture, ImageNet path, checkpoint, width multiplier, input size, and training/evaluation options. It also supports importing the model directly through `models/imagenet/__init__.py`.

#### Model Definition
MobileNetV2 is implemented in `models/imagenet/mobilenetv2.py` and exported by `models/imagenet/__init__.py`. The model builds the inverted-residual / linear-bottleneck backbone, parameterized for width multipliers and ImageNet classification output. This model boundary is independent of the training driver, enabling direct fine-tuning or inference use.

#### Training Orchestration
`imagenet.py` coordinates argument parsing, model construction, device placement, checkpoint loading/saving, optimizer and learning-rate scheduling, and epoch-level train/validation control. Training is intended for PyTorch `DataParallel` multi-GPU execution rather than distributed training. Evaluation-only mode loads a supplied weight file and runs validation.

#### Dataset and Batch Pipeline
ImageNet directory input enters through `utils/dataloaders.py`, which owns dataset loading, preprocessing/transforms, and PyTorch data-loader construction. Batches flow from this module into the training/evaluation loops in `imagenet.py`; the expected dataset layout includes class-labeled validation subdirectories.

#### Evaluation and Metrics
`utils/eval.py` provides classification evaluation behavior used by the driver, including ImageNet top-1/top-5 accuracy accounting. Validation consumes model logits and labeled batches, then returns aggregate metrics for console/log output and checkpoint selection.

#### Observability and Artifacts
`utils/logger.py` and `utils/visualize.py` support recording and presenting run metrics, while `utils/progress` supports training progress reporting. Checkpoints are written to the CLI-selected checkpoint directory; packaged pretrained weights in `pretrained/mobilenetv2-c5e733a8.pth` and the width/resolution-specific files are loadable PyTorch state dictionaries.

#### Runtime and External Dependencies
The material runtime is Python with PyTorch 1.0+ and CUDA/NVIDIA GPUs for practical ImageNet training. NVIDIA DALI is mentioned as an optional/in-development data pipeline dependency, but the documented standard path uses PyTorch data loaders. External inputs are locally provisioned ILSVRC2012/ImageNet data and local `.pth` model artifacts; this repository does not define a service or web deployment boundary.

Main entry points: [`imagenet.py`](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/imagenet.py) (ImageNet CLI driver), [`models/imagenet/mobilenetv2.py`](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/models/imagenet/mobilenetv2.py) (MobileNetV2 backbone), [`utils/dataloaders.py`](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/dataloaders.py) (Dataset and loaders), [`utils/eval.py`](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/eval.py) (ImageNet evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model"]
  node_model_api["Model import API<br/>model exports<br/>[__init__.py]"]
  node_mobilenetv2["MobileNetV2 backbone<br/>PyTorch classifier<br/>[mobilenetv2.py]"]
end

subgraph group_data["Data pipeline"]
  node_imagenet_data[("ImageNet directories<br/>local dataset")]
  node_dataloaders["Dataset and loaders<br/>batch pipeline<br/>[dataloaders.py]"]
  node_batches["Labeled batches<br/>tensor stream"]
end

subgraph group_run["Training runtime"]
  node_driver["ImageNet CLI driver<br/>training entry point<br/>[imagenet.py]"]
  node_train_loop["Train and validation loops<br/>epoch execution<br/>[imagenet.py]"]
  node_evaluator["ImageNet evaluation<br/>metrics<br/>[eval.py]"]
  node_observability["Run reporting<br/>logging and progress<br/>[logger.py]"]
  node_torch_runtime{{"PyTorch + CUDA GPUs<br/>execution runtime"}}
end

subgraph group_artifacts["Artifacts"]
  node_checkpoints["Run checkpoints<br/>state dictionaries"]
  node_pretrained["Packaged pretrained weights<br/>state dictionaries"]
end

node_model_api -->|"exports"| node_mobilenetv2
node_driver -->|"constructs"| node_mobilenetv2
node_imagenet_data -->|"images and labels"| node_dataloaders
node_dataloaders -->|"loads and transforms"| node_batches
node_driver -->|"controls epochs"| node_train_loop
node_batches -->|"feeds"| node_train_loop
node_train_loop -->|"forward and backward"| node_mobilenetv2
node_train_loop -->|"validation logits and labels"| node_evaluator
node_evaluator -->|"aggregate metrics"| node_driver
node_driver -->|"reports metrics"| node_observability
node_driver -->|"saves and resumes"| node_checkpoints
node_pretrained -->|"loads weights"| node_driver
node_torch_runtime -->|"executes on devices"| node_driver
node_torch_runtime -->|"DataParallel execution"| node_train_loop

click node_driver "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/imagenet.py"
click node_model_api "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/models/imagenet/__init__.py"
click node_mobilenetv2 "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/models/imagenet/mobilenetv2.py"
click node_dataloaders "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/dataloaders.py"
click node_train_loop "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/imagenet.py"
click node_evaluator "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/eval.py"
click node_observability "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/logger.py"
click node_pretrained "https://github.com/d-li14/mobilenetv2.pytorch/blob/master/pretrained/mobilenetv2-c5e733a8.pth"

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_model_api,node_mobilenetv2 toneBlue
class node_imagenet_data,node_dataloaders,node_batches toneAmber
class node_driver,node_train_loop,node_evaluator,node_observability,node_torch_runtime toneMint
class node_checkpoints,node_pretrained toneRose
```

## Components

### Model

- [Model import API](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/models/imagenet/__init__.py): model exports · Allows MobileNetV2 to be imported independently of the CLI. · `models/imagenet/__init__.py`
- [MobileNetV2 backbone](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/models/imagenet/mobilenetv2.py): PyTorch classifier · Inverted-residual ImageNet classifier parameterized by width and input size. · `models/imagenet/mobilenetv2.py`

### Data pipeline

- **ImageNet directories**: local dataset · ILSVRC2012 class-labeled training and validation images.
- [Dataset and loaders](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/dataloaders.py): batch pipeline · Builds datasets, transforms, and PyTorch data loaders. · `utils/dataloaders.py`
- **Labeled batches**: tensor stream

### Training runtime

- [ImageNet CLI driver](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/imagenet.py): training entry point · Parses options and controls train, validation, resume, and evaluation-only runs. · `imagenet.py`
- [Train and validation loops](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/imagenet.py): epoch execution · Runs forward/backward optimization and validation over batches. · `imagenet.py`
- [ImageNet evaluation](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/eval.py): metrics · Computes aggregate top-1 and top-5 accuracy from logits and labels. · `utils/eval.py`
- [Run reporting](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/utils/logger.py): logging and progress · Records, presents, and reports training metrics. · `utils/logger.py`
- **PyTorch + CUDA GPUs**: execution runtime · Uses PyTorch DataParallel for multi-GPU training.

### Artifacts

- **Run checkpoints**: state dictionaries · CLI-selected directory for saved and resumed training state.
- [Packaged pretrained weights](https://github.com/d-li14/mobilenetv2.pytorch/blob/master/pretrained/mobilenetv2-c5e733a8.pth): state dictionaries · Loadable MobileNetV2 .pth weights, including width/resolution variants. · `pretrained/mobilenetv2-c5e733a8.pth`

## Connections

- Model import API → MobileNetV2 backbone: exports
- ImageNet CLI driver → MobileNetV2 backbone: constructs
- ImageNet directories → Dataset and loaders: images and labels
- Dataset and loaders → Labeled batches: loads and transforms
- ImageNet CLI driver → Train and validation loops: controls epochs
- Labeled batches → Train and validation loops: feeds
- Train and validation loops → MobileNetV2 backbone: forward and backward
- Train and validation loops → ImageNet evaluation: validation logits and labels
- ImageNet evaluation → ImageNet CLI driver: aggregate metrics
- ImageNet CLI driver → Run reporting: reports metrics
- ImageNet CLI driver → Run checkpoints: saves and resumes
- Packaged pretrained weights → ImageNet CLI driver: loads weights
- PyTorch + CUDA GPUs → ImageNet CLI driver: executes on devices
- PyTorch + CUDA GPUs → Train and validation loops: DataParallel execution
