# microsoft/directml architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/directml
- Repository: https://github.com/microsoft/directml

## Overview

##### Project’s Purpose and High-Level Components
- The repository centers on DirectML, a DirectX 12–based, high-performance machine learning API that works both as a standalone native library and as the GPU backend for several higher-level ML frameworks.
- The README explains that DirectML is used to accelerate ML workloads (e.g., real‑time inference in games, high-performance ML frameworks) and that it integrates with Windows ML, ONNX Runtime, PyTorch, and TensorFlow.
- The project also includes a command-line tool (“DxDispatch”) for launching DirectX 12 compute programs and a large suite of samples (in C++ and Python) that demonstrate how to use DirectML.

##### File Structure and Key Modules
- DxDispatch – This is a CMake–based C++ project (found under the “DxDispatch” directory) that likely encapsulates the boilerplate for interfacing with DirectML API calls. Notice the extensive “src” folder with modules like “Adapter.cpp/h,” “Device.cpp/h,” “DirectMLHelpers,” etc. These components are the building blocks that wrap DirectX 12 and DirectML calls.
- Libraries – A small directory (e.g. DirectMLX.h) that might provide utility wrappers or extensions.
- Samples – There are multiple samples across directories:
– Samples/HelloDirectML, DirectMLNpuInference, DirectMLSuperResolution, yolov4, etc. This folder clearly serves as demonstration applications that plug into the DirectML core.
– Python – Contains a “samples” subdirectory where there are Python applications (mobilenet, mnist, squeezenet, candy style transfer, etc.) built on top of a Python wrapper (PyDirectML) that is implemented in the “Python/src” directory.
– PyTorch, TensorFlow – These directories contain integration examples (and in some cases build files or extra documentation) that show how DirectML is integrated as the backend for these frameworks.
- TensorFlow – Contains both TF1 and TF2 variants and various supporting scripts.
- Additionally, there are configuration files (like CMakeLists.txt, cmake scripts, and cmake modules for dependencies) that indicate the project is built with modularity and allows for separate builds of various components.

##### Establish Key Relationships and Data Flow
- At the bottom layer, you have the hardware: DirectX 12–capable GPUs with vendor drivers (AMD, Intel, NVIDIA, etc.). They provide the essential GPU compute capabilities.
- Immediately above this is the DirectX 12 runtime, which supports DirectML. DirectML is a library that builds on top of DirectX 12 and abstracts many low-level details.
- The DirectML core library (either as a system component or a redistributable package) is what the DxDispatch tool and other native C++ applications call.
- The DxDispatch component is a “dispatch” or launcher tool that encapsulates DirectML operators and sets up the pipeline to run them.
- On the integration side, various higher-level frameworks (Windows ML, ONNX Runtime, PyTorch with DirectML, TensorFlow with DirectML) use DirectML as their execution provider. These frameworks are integrated through separate submodules/samples (see directories “PyTorch” and “TensorFlow”).
- Python samples and libraries (via PyDirectML) act as a thin wrapper for developers to experiment with DirectML via Python interfaces, while still calling into the native DirectML library.
- The samples in the “Samples” folder demonstrate end-to-end use cases by connecting application layer code (e.g., object detection in yolov4 or image upscaling in SuperResolution) with the DirectML backend.

##### Additional Details
- Build system (CMake) which is used for compiling the C++ components.
- Configuration/dependency management files (e.g., cmake modules for third-party libraries like fmt, gsl, onnxruntime, etc.) to show the external dependencies.
- An annotation about the interoperability of DirectML across different vendors, emphasizing hardware agnosticism.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        Hardware["GPU/DirectX Hardware"]:::external
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        DXRuntime["DirectX 12 Runtime"]:::external
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        DMCore["DirectML Core Library"]:::core
        DxDispatchCore["DxDispatch Core (C++ Wrappers)"]:::core
        DirectMLHelpers["DirectML Helpers"]:::core
        DirectMLXLib["DirectMLX Utility Library"]:::core
        CMakeBuild["CMake Build System"]:::build
    end

    %% Integration Layer
    subgraph "Integration Layer"
        DxDispatchTool["DxDispatch Command-Line Tool"]:::integration
        PyDirectML["PyDirectML & Python Samples"]:::integration
        PyTorchInt["PyTorch Integration"]:::integration
        TensorFlowInt["TensorFlow Integration"]:::integration
    end

    %% Application Layer
    subgraph "Application Layer"
        DirectMLSamples["DirectML Sample Applications"]:::app
    end

    %% Connections from Hardware upward
    Hardware -->|"triggers"| DXRuntime
    DXRuntime -->|"supports"| DMCore
    DMCore -->|"interfaces with"| DxDispatchCore
    DxDispatchCore -->|"utilizes"| DirectMLHelpers
    DMCore -->|"leverages"| DirectMLXLib
    DMCore -->|"built via"| CMakeBuild

    %% Integration connections
    DMCore -->|"accessed-by"| DxDispatchTool
    DMCore -->|"accessed-by"| PyDirectML
    DMCore -->|"accessed-by"| PyTorchInt
    DMCore -->|"accessed-by"| TensorFlowInt

    %% Connections to Application Layer
    DxDispatchTool -->|"executes"| DirectMLSamples
    PyDirectML -->|"demonstrates"| DirectMLSamples
    PyTorchInt -->|"integrates with"| DirectMLSamples
    TensorFlowInt -->|"integrates with"| DirectMLSamples
    DMCore -->|"used in"| DirectMLSamples

    %% Click Events
    click DxDispatchCore "https://github.com/microsoft/directml/tree/master/DxDispatch/src/dxdispatch"
    click DxDispatchTool "https://github.com/microsoft/directml/tree/master/DxDispatch/src/exe"
    click DirectMLHelpers "https://github.com/microsoft/directml/tree/master/DxDispatch/src/dxdispatch/DirectMLHelpers"
    click DirectMLXLib "https://github.com/microsoft/directml/blob/master/Libraries/DirectMLX.h"
    click PyDirectML "https://github.com/microsoft/directml/tree/master/Python/src"
    click PyTorchInt "https://github.com/microsoft/directml/tree/master/PyTorch"
    click TensorFlowInt "https://github.com/microsoft/directml/tree/master/TensorFlow"
    click DirectMLSamples "https://github.com/microsoft/directml/tree/master/Samples"

    %% Styles
    classDef external fill:#ffcc00,stroke:#cc9900,stroke-width:2px;
    classDef core fill:#bbdefb,stroke:#0b5394,stroke-width:2px;
    classDef integration fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef app fill:#ffccbc,stroke:#d84315,stroke-width:2px;
    classDef build fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
```
