# nvlabs/stylegan2 architecture

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

- Interactive diagram: https://gitdiagram.com/nvlabs/stylegan2
- Repository: https://github.com/nvlabs/stylegan2

## Overview

##### Project type and purpose
- This is a research-grade, full-stack machine-learning framework implementing StyleGAN2 in TensorFlow.
- It provides end-to-end tooling: data preparation (TFRecords), model definition (generator/discriminator networks), training loops, evaluation metrics, image projection, generation scripts, and cluster/local submission support.

##### File-structure analysis
- Top-level scripts (dataset_tool.py, run_training.py, run_generator.py, run_metrics.py, run_projector.py) act as CLI entry points.
- `dnnlib/` houses the core library:
- `tflib/` wraps TensorFlow utilities, model I/O, optimizer and custom CUDA ops (compiled via NVCC at runtime).
- `submission/` abstracts job submission to local or cluster environments.
- `util.py` offers miscellaneous helpers.
- `training/` defines the ML pipeline: dataset loader, loss functions, network architectures (StyleGAN & StyleGAN2), and the training loop.
- `metrics/` implements evaluation code (FID, IS, PPL, precision/recall).
- `pretrained_networks.py` and generated `.pkl` files manage model checkpoints.
- Configuration and environment: Dockerfile, NVidia-based build (CUDA, cuDNN), Python 3.6+, TF1.14.

##### Key READM E insights
- The system compiles TensorFlow custom ops (`fused_bias_act`, `upfirdn_2d`) on the fly.
- Users interact via CLI commands that either train, evaluate, project, or sample networks.
- Data flows from raw images → multi-resolution TFRecords (dataset_tool) → training pipeline → saved networks → generator scripts.

- User / CLI layer (run_*.py, dataset_tool.py)
- dnnlib.submission (LocalRunner vs ClusterRunner)
- Core library:
- dnnlib.tflib (TF session init, custom ops loader)
- dnnlib.util
- Training module (`training/`): dataset loader, networks, loss, optimizer, training_loop
- Metrics module (`metrics/`)
- Model checkpoints (`.pkl` files, results/ directory)
- Data storage (TFRecords directory)
- External services: Google Drive for pretrained nets
- Compute resources: NVIDIA GPUs, Docker container
- CLI → submission layer → training job
- Training job → dnnlib.tflib → TensorFlow session → custom ops (NVCC) → GPU kernels
- Training job ← dataset loader ← TFRecords
- Training job → checkpoint files (`.pkl`) and logs
- Generator/metrics/projector CLIs → load checkpoint → dnnlib.tflib → TensorFlow → GPU → images/metrics → results/
- dataset_tool → raw images → TFRecords
- pretrained_networks → Google Drive
c. Architectural patterns & principles:
- Modular Python packages (separation of concerns)
- CLI-driven pipeline orchestration
- Dynamic extension via custom-op compilation
- Environment abstraction for local vs cluster execution
d. Key technologies & frameworks:
- Python 3.6+, TensorFlow 1.14+, NVCC, CUDA 10.0, cuDNN 7.5
- TFRecords for scalable data ingestion
- Docker for reproducible environments

##### Final advice
- How CLI scripts reuse the same core library—so the viewer sees the unified architecture underlying all surface tools.
- Be exhaustive: it’s better to show too many components than too few.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        DT["Data Prep CLI\n(dataset_tool.py)"]:::cli
        RT["Training CLI\n(run_training.py)"]:::cli
        RG["Generator CLI\n(run_generator.py)"]:::cli
        RM["Metrics CLI\n(run_metrics.py)"]:::cli
        RP["Projection CLI\n(run_projector.py)"]:::cli
        PJ["Projector Module\n(projector.py)"]:::cli
    end

    %% Submission Abstraction
    subgraph "Submission Abstraction"
        LR["LocalRunner"]:::submission
        CR["ClusterRunner"]:::submission
        RC["RunContext"]:::submission
        SB["Submit"]:::submission
    end

    %% Core Library
    subgraph "Core Library (dnnlib)"
        subgraph "dnnlib.tflib"
            TI["__init__.py"]:::core
            AS["autosummary.py"]:::core
            CO["custom_ops.py"]:::core
            NT["network.py"]:::core
            OP["optimizer.py"]:::core
            TFU["tfutil.py"]:::core
        end
        UT["util.py"]:::core

        subgraph "Custom CUDA Ops"
            FBCU["fused_bias_act.cu"]:::core
            FBPY["fused_bias_act.py"]:::core
            UDCU["upfirdn_2d.cu"]:::core
            UDPY["upfirdn_2d.py"]:::core
        end
    end

    %% Training Module
    subgraph "Training Module"
        DS["dataset.py"]:::training
        LS["loss.py"]:::training
        MS["misc.py"]:::training
        NS1["networks_stylegan.py"]:::training
        NS2["networks_stylegan2.py"]:::training
        TL["training_loop.py"]:::training
    end

    %% Metrics Module
    subgraph "Metrics Module"
        FID["frechet_inception_distance.py"]:::metric
        IS["inception_score.py"]:::metric
        LSep["linear_separability.py"]:::metric
        MB["metric_base.py"]:::metric
        MD["metric_defaults.py"]:::metric
        PPL["perceptual_path_length.py"]:::metric
        PR["precision_recall.py"]:::metric
    end

    %% Utilities and Environment
    PN["Pretrained Network Loader\n(pretrained_networks.py)"]:::core
    NVCC["NVCC Compilation Test\n(test_nvcc.cu)"]:::compute
    DF["Dockerfile"]:::compute

    %% Data Stores
    TFREC["TFRecords (Data Store)"]:::data
    CKPT["Checkpoints (.pkl)"]:::data

    %% Compute Resources & External
    GPU["NVIDIA GPUs"]:::compute
    DC["Docker Container"]:::compute
    GD["Google Drive"]:::external

    %% Relationships
    DT -->|"creates TFRecords"| TFREC
    RT -->|"submits job"| LR
    RT -->|"submits job"| CR
    LR --> RC
    CR --> RC
    RC --> SB
    SB --> TL
    TL --> DS
    TL --> NT
    TL --> LS
    TL --> OP
    TL --> CO
    TL --> TFU
    TL -->|"loads session"| TI
    TL -->|"compiles ops"| NVCC
    NVCC --> FBCU
    NVCC --> UDCU
    FBCU --> CO
    UDCU --> CO
    CO --> GPU
    TL -->|"writes checkpoints"| CKPT

    RG --> PN
    RM --> PN
    RP --> PN
    PJ --> PN
    PN --> GD

    RG --> TI
    RM --> TI
    RP --> TI
    PJ --> TI

    RG --> GPU
    RM --> GPU
    RP --> GPU

    RG -->|"outputs images"| CKPT
    RM -->|"outputs metrics"| CKPT

    %% Submission reuse core
    RT --> TI

    %% Docker environment
    DF --> DC
    DC --> GPU

    %% Classes
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef submission fill:#90EE90,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef training fill:#98FB98,stroke:#333,stroke-width:1px
    classDef metric fill:#98FB98,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef compute fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px

    %% Click Events
    click DT "https://github.com/nvlabs/stylegan2/blob/master/dataset_tool.py"
    click RT "https://github.com/nvlabs/stylegan2/blob/master/run_training.py"
    click RG "https://github.com/nvlabs/stylegan2/blob/master/run_generator.py"
    click RM "https://github.com/nvlabs/stylegan2/blob/master/run_metrics.py"
    click RP "https://github.com/nvlabs/stylegan2/blob/master/run_projector.py"
    click PJ "https://github.com/nvlabs/stylegan2/blob/master/projector.py"
    click PN "https://github.com/nvlabs/stylegan2/blob/master/pretrained_networks.py"
    click LR "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/submission/internal/local.py"
    click RC "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/submission/run_context.py"
    click SB "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/submission/submit.py"
    click TI "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/__init__.py"
    click AS "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/autosummary.py"
    click CO "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/custom_ops.py"
    click NT "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/network.py"
    click OP "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/optimizer.py"
    click TFU "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/tfutil.py"
    click FBCU "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/ops/fused_bias_act.cu"
    click FBPY "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/ops/fused_bias_act.py"
    click UDCU "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/ops/upfirdn_2d.cu"
    click UDPY "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/tflib/ops/upfirdn_2d.py"
    click UT "https://github.com/nvlabs/stylegan2/blob/master/dnnlib/util.py"
    click DS "https://github.com/nvlabs/stylegan2/blob/master/training/dataset.py"
    click LS "https://github.com/nvlabs/stylegan2/blob/master/training/loss.py"
    click MS "https://github.com/nvlabs/stylegan2/blob/master/training/misc.py"
    click NS1 "https://github.com/nvlabs/stylegan2/blob/master/training/networks_stylegan.py"
    click NS2 "https://github.com/nvlabs/stylegan2/blob/master/training/networks_stylegan2.py"
    click TL "https://github.com/nvlabs/stylegan2/blob/master/training/training_loop.py"
    click FID "https://github.com/nvlabs/stylegan2/blob/master/metrics/frechet_inception_distance.py"
    click IS "https://github.com/nvlabs/stylegan2/blob/master/metrics/inception_score.py"
    click LSep "https://github.com/nvlabs/stylegan2/blob/master/metrics/linear_separability.py"
    click MB "https://github.com/nvlabs/stylegan2/blob/master/metrics/metric_base.py"
    click MD "https://github.com/nvlabs/stylegan2/blob/master/metrics/metric_defaults.py"
    click PPL "https://github.com/nvlabs/stylegan2/blob/master/metrics/perceptual_path_length.py"
    click PR "https://github.com/nvlabs/stylegan2/blob/master/metrics/precision_recall.py"
    click DF "https://github.com/nvlabs/stylegan2/tree/master/Dockerfile"
    click NVCC "https://github.com/nvlabs/stylegan2/blob/master/test_nvcc.cu"
```
