# graphcore/examples architecture

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

- Interactive diagram: https://gitdiagram.com/graphcore/examples
- Repository: https://github.com/graphcore/examples

## Overview

##### Project Overview and High-Level Purpose
- The repository isn’t a monolithic application but rather a catalogue of example applications and reference implementations designed to show how to use Graphcore IPUs via the Poplar SDK. It spans multiple application domains such as Computer Vision, Natural Language Processing, Speech, Multimodal, Graph Neural Networks, and AI for Simulation.
- The aim is to provide reproducible, benchmarked implementations across several frameworks (TensorFlow 2, PyTorch, PopXL, etc.) so that users can see optimized models for training and inference on IPUs.

##### Main Components (High-Level Blocks)
- Domain-Specific Application Examples:
▪ Computer Vision – containing implementations for models like ResNet, EfficientNet, ViT, DINO, Swin, MAE, Yolov4-P5, EfficientDet, UNet, Neural Image Fields.
▪ Natural Language Processing – with models such as BERT, Packed BERT, GPT2, GPTJ, GPT3 variants, RoBERTa, DeBERTa, etc.
▪ Speech – examples include Fastpitch, Conformer, wav2vec2, and Whisper.
▪ Multimodal – covering models like CLIP, miniDALL-E, Frozen in time.
▪ Graph Neural Networks – including MPNN, TGN, NBFNet, ClusterGCN, SchNet, and more.
▪ AI for Simulation – for instance, the ABC COVID-19 example.
- Framework/Implementation Layers:
- Shared Utility Components:
▪ Benchmarking Tools (e.g. examples_utils, benchmarks.yml files) that allow reproducible run/execution.
▪ Common utilities and scripts (in the “utils/” folder) used across many examples.
▪ Testing and configuration components (test folders, requirements, configuration scripts).
- Developer/Documentation Resources:
▪ The README and tutorials subdirectories which provide developer guidance and how-to information.
▪ Infrastructure for running the examples on an IPU system (this includes the Poplar SDK integration).
- External Dependencies:
▪ The Poplar SDK itself and the instructions for the IPU hardware system; these are mandatory and connect to every example.
▪ Links to external resources such as benchmarks pages and model garden.

##### And Illustrate Relationships and Interaction
▪ The common utilities (benchmarks, configuration, and test frameworks) can be shown as supporting layers that are referenced by almost every domain block.
- That the benchmarking tools utilize configuration files (e.g. benchmarks.yml) that come from each application’s subdirectory.
- If needed, indicate how “tutorials” and “examples_tests” provide a developer’s guide overlay.

##### Architectural Patterns and Design Principles
- “Separation of Concerns” – Although the repository is unified, each folder clearly separates model implementations, utilities, and benchmarks. Highlight this separation.
- “Reusability” – The shared utility components (e.g., in the utils folder) underscore code reuse across different domains. Represent this as a shared block linking to multiple sections.
- “Configurability” – The presence of configuration files, benchmarks and tests indicates an emphasis on parameterized, reproducible experiments. Mark the configuration pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level container
    subgraph "Graphcore Applications Repository"
        %% Domain Applications Subgraph
        subgraph "Domain Applications"
            CV["Computer Vision"]:::domain
            NLP["Natural Language Processing"]:::domain
            Speech["Speech"]:::domain
            GNN["Graph Neural Networks"]:::domain
            Multi["Multimodal"]:::domain
            AFS["AI for Simulation"]:::domain
        end

        %% Framework Implementations Subgraph
        subgraph "Framework Implementations"
            CV_PT["CV: PyTorch"]:::framework
            CV_TF["CV: TensorFlow 2"]:::framework
            CV_PopXL["CV: PopXL"]:::framework

            NLP_PT["NLP: PyTorch"]:::framework
            NLP_TF["NLP: TensorFlow 2"]:::framework
            NLP_PopXL["NLP: PopXL"]:::framework

            Speech_PT["Speech: PyTorch"]:::framework
            Speech_TF["Speech: TensorFlow 2"]:::framework
            Speech_PopXL["Speech: PopXL"]:::framework

            GNN_PT["GNN: PyTorch"]:::framework
            GNN_TF["GNN: TensorFlow 2"]:::framework
            GNN_PopXL["GNN: PopXL"]:::framework

            Multi_PT["Multimodal: PyTorch"]:::framework
            Multi_TF["Multimodal: TensorFlow 2"]:::framework
            Multi_PopXL["Multimodal: PopXL"]:::framework

            AFS_PT["AI Simulation: PyTorch"]:::framework
            AFS_TF["AI Simulation: TensorFlow 2"]:::framework
            AFS_PopXL["AI Simulation: PopXL"]:::framework
        end

        %% Shared Utilities and Developer Resources
        UTIL["Shared Utilities & Benchmarking"]:::utility
        DOC_R["README.md"]:::doc
        DOC_T["Tutorials"]:::doc

        %% IPU Integration
        IPU["IPU System / Poplar SDK"]:::ipu
    end

    %% Connections from Domain Applications to their Framework Implementations
    CV --> CV_PT
    CV --> CV_TF
    CV --> CV_PopXL

    NLP --> NLP_PT
    NLP --> NLP_TF
    NLP --> NLP_PopXL

    Speech --> Speech_PT
    Speech --> Speech_TF
    Speech --> Speech_PopXL

    GNN --> GNN_PT
    GNN --> GNN_TF
    GNN --> GNN_PopXL

    Multi --> Multi_PT
    Multi --> Multi_TF
    Multi --> Multi_PopXL

    AFS --> AFS_PT
    AFS --> AFS_TF
    AFS --> AFS_PopXL

    %% Domain Applications use Shared Utilities
    CV -->|"benchmarks"| UTIL
    NLP -->|"benchmarks"| UTIL
    Speech -->|"benchmarks"| UTIL
    GNN -->|"benchmarks"| UTIL
    Multi -->|"benchmarks"| UTIL
    AFS -->|"benchmarks"| UTIL

    %% Framework Implementations execute on IPU System
    CV_PT -->|"runs_on"| IPU
    CV_TF -->|"runs_on"| IPU
    CV_PopXL -->|"runs_on"| IPU

    NLP_PT -->|"runs_on"| IPU
    NLP_TF -->|"runs_on"| IPU
    NLP_PopXL -->|"runs_on"| IPU

    Speech_PT -->|"runs_on"| IPU
    Speech_TF -->|"runs_on"| IPU
    Speech_PopXL -->|"runs_on"| IPU

    GNN_PT -->|"runs_on"| IPU
    GNN_TF -->|"runs_on"| IPU
    GNN_PopXL -->|"runs_on"| IPU

    Multi_PT -->|"runs_on"| IPU
    Multi_TF -->|"runs_on"| IPU
    Multi_PopXL -->|"runs_on"| IPU

    AFS_PT -->|"runs_on"| IPU
    AFS_TF -->|"runs_on"| IPU
    AFS_PopXL -->|"runs_on"| IPU

    %% Shared Utilities include documentation guides
    UTIL -->|"includes_guides"| DOC_R
    UTIL -->|"includes_guides"| DOC_T

    %% Click Events
    click CV "https://github.com/graphcore/examples/tree/master/vision/"
    click NLP "https://github.com/graphcore/examples/tree/master/nlp/"
    click Speech "https://github.com/graphcore/examples/tree/master/speech/"
    click GNN "https://github.com/graphcore/examples/tree/master/gnn/"
    click Multi "https://github.com/graphcore/examples/tree/master/multimodal/"
    click AFS "https://github.com/graphcore/examples/tree/master/ai_for_simulation/"
    click UTIL "https://github.com/graphcore/examples/tree/master/utils/"
    click DOC_R "https://github.com/graphcore/examples/blob/master/README.md"
    click DOC_T "https://github.com/graphcore/examples/tree/master/tutorials/"

    %% Style Classes
    classDef domain fill:#A3BE8C,stroke:#2E3440,stroke-width:2px;
    classDef framework fill:#88C0D0,stroke:#2E3440,stroke-width:2px;
    classDef utility fill:#EBCB8B,stroke:#2E3440,stroke-width:2px;
    classDef doc fill:#D08770,stroke:#2E3440,stroke-width:2px;
    classDef ipu fill:#B48EAD,stroke:#2E3440,stroke-width:2px;
```
