# bes-dev/mobilestylegan.pytorch architecture

> Architecture diagram of the GitHub repository bes-dev/mobilestylegan.pytorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bes-dev/mobilestylegan.pytorch
- Repository: https://github.com/bes-dev/mobilestylegan.pytorch

## Overview

##### Project type and purpose
- This is a PyTorch-based machine-learning framework (“MobileStyleGAN”) for training, evaluating, converting, and deploying a lightweight StyleGAN2 variant (MobileStyleGAN) for high-fidelity image synthesis on edge devices.
- Key use cases:
- Train a student GAN via distillation from a teacher StyleGAN2
- Convert existing StyleGAN2 checkpoints into the MobileStyleGAN format
- Generate images, evaluate FID, run demos/comparisons
- Export trained models to ONNX/CoreML and deploy with OpenVINO

##### File structure
- Top-level scripts (entry points):
- train.py (training & export)
- generate.py (batch image generation)
- demo.py / compare.py (visual demos & side-by-side comparisons)
- evaluate_fid.py (FID score evaluation)
- convert_rosinality_ckpt.py (import rosinality StyleGAN2 ckpts)
- configs/ – JSON configuration for model architectures, training hyperparameters, dataset paths, export flags
- core/ – core framework modules:
- dataset.py (data loader & augmentation)
- distiller.py (teacher → student knowledge distillation logic)
- loss/ (GAN, distillation, perceptual, diffaug losses)
- models/ (network definitions)
– mapping_network, mobile_synthesis_network (student), discriminator, inception_v3 (aux for perceptual loss)
– modules/ (building blocks: modulated_conv2d, up/downsampling, wavelets, custom CUDA kernels)
- requirements.txt – external dependencies
- res/ – sample output images
- LICENSE-NVIDIA – CUDA kernel license

##### README for additional insights
- Describes each script’s usage, required GPUs, external library integrations (pytorch-fid, OpenVINO, random_face)
- Explains conversion from rosinality StyleGAN2, exporting to ONNX/CoreML, demo & evaluation workflows

a. Main components
1. Configuration Manager (JSON + argparse)
2. Data Pipeline (Dataset loader + DiffAug)
3. Model Architectures
– Teacher: StyleGAN2 mapping + synthesis networks (rosinality import)
– Student: MobileStyleGAN mapping + mobile synthesis network
– Discriminator
– Auxiliary: InceptionV3 for perceptual loss
4. Training Engine
– Distiller orchestrates forward/backward passes
– Loss Modules (GAN, perceptual, distill, diffaug)
– Optimizer & LR Scheduler
– Checkpoint Manager
5. Inference & Evaluation
– Image Generator (generate.py)
– FID Evaluator (evaluate_fid.py)
– Demo / Compare Visualizer
6. Conversion & Export
– ROS_IMPORT Module (convert_rosinality_ckpt.py)
– ONNX Exporter
– CoreML Exporter
7. Deployment Wrapper
– random_face + OpenVINO integration

b. Relationships and data flows
- User invokes a script → Config Manager parses JSON & CLI →
- train.py → builds Data Pipeline + Model Architectures → passes data through Teacher & Student → computes losses → updates Student → checkpoints
- generate/demo/compare → loads Student ckpt → samples noise → mapping → synthesis → image output
- evaluate_fid → reads generated & reference images → computes FID via pytorch-fid module
- convert_rosinality_ckpt → loads external ckpt → splits into mapping/synthesis ckpts + writes config JSON
- train.py --export-model → uses PyTorch’s exporter APIs to produce ONNX/CoreML files
- Deployment Wrapper loads exported model → runs inference via OpenVINO

c. Architectural patterns & design principles
- Modular separation: dataset, model definitions, losses, scripts
- Teacher–Student (knowledge distillation) pattern
- Plugin-style custom ops (modules/ops) for performance
- Clear config-driven orchestration to decouple code from hyperparameters

d. Key technologies & frameworks
- PyTorch (core DL framework)
- CUDA & custom C++/CUDA kernels (fused activations, upfirdn2d)
- JSON config files + argparse
- ONNX & CoreML export
- External libs: pytorch-fid, OpenVINO, random_face

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        Train["train.py"]:::external
        Generate["generate.py"]:::external
        EvaluateFID["evaluate_fid.py"]:::external
        Demo["demo.py"]:::external
        Compare["compare.py"]:::external
        Convert["convert_rosinality_ckpt.py"]:::external
    end

    %% Configuration Layer
    subgraph "Configuration"
        ConfigManager["Configuration Manager"]:::data
    end

    %% Data Layer
    subgraph "Data Pipeline"
        Dataset["Dataset Loader"]:::data
        DiffAug["Data Augmentation (DiffAug)"]:::data
    end

    %% Model Layer
    subgraph "Model Architectures"
        Mapping["Mapping Network"]:::model
        TeacherSynth["StyleGAN2 Synthesis Network"]:::model
        MobileSynthBlock["Mobile Synthesis Block"]:::model
        MobileSynth["Mobile Synthesis Network"]:::model
        Discriminator["Discriminator"]:::model
        Inception["InceptionV3 (Perceptual)"]:::model
    end

    %% Training Engine
    subgraph "Training Engine"
        Distiller["Distillation Engine"]:::train
        GANLoss["Non-saturating GAN Loss"]:::train
        DistillLoss["Distillation Loss"]:::train
        PercLoss["Perceptual Loss"]:::train
        DiffLoss["DiffAug Loss"]:::train
        Utils["Utility Functions"]:::train
    end

    %% Export & Conversion
    subgraph "Export & Conversion"
        ROSImport["ROS_IMPORT Module"]:::export
        ONNX["ONNX Exporter"]:::export
        CoreML["CoreML Exporter"]:::export
    end

    %% Inference & Evaluation
    subgraph "Inference & Evaluation"
        ImageGen["Image Generator"]:::infer
        FIDEval["FID Evaluator"]:::infer
        VisualDemo["Demo / Compare Visualizer"]:::infer
    end

    %% Deployment
    subgraph "Deployment"
        Deployment["OpenVINO + random_face Wrapper"]:::external
    end

    %% Connections - Training Flow
    Train --> ConfigManager
    ConfigManager --> Dataset
    Dataset --> DiffAug
    DiffAug --> Distiller
    ConfigManager --> Mapping
    Mapping --> TeacherSynth
    Mapping --> MobileSynth
    TeacherSynth --> Distiller
    MobileSynth --> Distiller
    Distiller --> GANLoss
    Distiller --> DistillLoss
    Distiller --> PercLoss
    Distiller --> DiffLoss
    Distiller --> Utils
    Distiller --> Utils
    Distiller --> Utils
    Train --> ONNX
    Train --> CoreML

    %% Inference & Evaluation Flow
    Generate --> ConfigManager
    Demo --> ConfigManager
    Compare --> ConfigManager
    ConfigManager --> MobileSynth
    MobileSynth --> ImageGen
    ImageGen --> VisualDemo
    EvaluateFID --> ConfigManager
    EvaluateFID --> ImageGen
    EvaluateFID --> FIDEval

    %% Conversion Flow
    Convert --> ROSImport

    %% Deployment Flow
    ONNX --> Deployment
    CoreML --> Deployment

    %% Click Events
    click ConfigManager "https://github.com/bes-dev/mobilestylegan.pytorch/tree/develop/configs/"
    click Dataset "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/dataset.py"
    click DiffAug "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/loss/diffaug.py"
    click Mapping "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/models/mapping_network.py"
    click TeacherSynth "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/models/synthesis_network.py"
    click MobileSynth "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/models/mobile_synthesis_network.py"
    click MobileSynthBlock "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/models/modules/mobile_synthesis_block.py"
    click Discriminator "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/models/discriminator.py"
    click Inception "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/models/inception_v3.py"
    click Distiller "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/distiller.py"
    click GANLoss "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/loss/non_saturating_gan_loss.py"
    click DistillLoss "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/loss/distiller_loss.py"
    click PercLoss "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/loss/perceptual_loss.py"
    click DiffLoss "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/loss/diffaug.py"
    click Utils "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/core/utils.py"
    click Train "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/train.py"
    click Generate "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/generate.py"
    click EvaluateFID "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/evaluate_fid.py"
    click Demo "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/demo.py"
    click Compare "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/compare.py"
    click Convert "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/convert_rosinality_ckpt.py"
    click ROSImport "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/convert_rosinality_ckpt.py"
    click ONNX "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/train.py"
    click CoreML "https://github.com/bes-dev/mobilestylegan.pytorch/blob/develop/train.py"
    click Deployment "https://github.com/bes-dev/mobilestylegan.pytorch/tree/develop/core/models/modules/ops/"

    %% Styles
    classDef data fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef model fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef train fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef infer fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef export fill:#ffebcc,stroke:#333,stroke-width:1px
    classDef external fill:#ffe6e6,stroke:#333,stroke-width:1px
```
