# nvidia/cuda-quantum architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia/cuda-quantum
- Repository: https://github.com/nvidia/cuda-quantum

## Overview

##### Main Components

a) Frontend Layer:
- nvq++ Compiler (tools/nvqpp)
- Language Processing Components (include/cudaq/Frontend)
- Python Bindings (python/)

b) Optimization & IR Layer:
- MLIR-based Optimizer (include/cudaq/Optimizer)
- Quake Dialect (test/Quake)
- Code Generation Components (include/cudaq/Optimizer/CodeGen)

c) Runtime Layer:
- CUDA-Q Runtime (runtime/cudaq)
- Execution Managers (runtime/cudaq/qis/managers)
- Platform Abstractions (runtime/cudaq/platform)

d) Backend Layer:
- Quantum Backends
- QPP Simulator
- CuStateVec
- Hardware Providers (IonQ, Quantinuum, etc.)
- Classical Backends (GPU/CPU)

##### Relationships and Data Flow
Key interactions:

**[Frontend Layer]**
- ↓
**[Optimization & IR Layer]**
- ↓
**[Runtime Layer]**
- ↓
**[Backend Layer]**

##### Specific Elements

a) Frontend Components:
- C++ Compilation Pipeline
- Python Interface Layer
- AST Processing (include/cudaq/Frontend/nvqpp)

b) Core Components:
- Quantum Kernel Processing
- MLIR/Quake Dialect Handling
- Optimization Passes

c) Runtime Features:
- Quantum Platform Management
- Execution Contexts
- Memory Management

d) Backend Integration:
- Simulator Interfaces
- Hardware Provider Connections
- GPU/CPU Integration Points

##### Important Architectural Patterns
- Plugin Architecture (runtime/cudaq/platform)
- Multi-backend Support (runtime/cudaq/platform/*)
- Extensible Optimization Pipeline

##### Key Interfaces
- Quantum Execution Interface
- Backend Provider Interface
- Optimization Pass Interface

##### Deployment Components
- Container Support (docker/)
- Build System Integration (cmake/)
- Platform Configuration

- The modular architecture allowing multiple backends
- The separation between quantum and classical processing
- The optimization pipeline's role
- The plugin-based extension system

- Component types
- Data flow directions
- Interface boundaries
- Extension points

Keep the abstraction level high enough to show the overall architecture while including enough detail to understand the system's key components and their interactions.

This design reflects CUDA-Q's nature as a hybrid quantum-classical platform with emphasis on GPU integration and multiple backend support.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef frontend fill:#a8d1f0,stroke:#000
    classDef optimization fill:#90EE90,stroke:#000
    classDef runtime fill:#FFE5B4,stroke:#000
    classDef backend fill:#DDA0DD,stroke:#000
    classDef infrastructure fill:#FFB6C1,stroke:#000

    subgraph Frontend["Frontend Layer"]
        NVQPP["nvq++ Compiler"]
        LANG["Language Processing"]
        PYIF["Python Interface"]
    end

    subgraph Optimization["Optimization & IR Layer"]
        MLIR["MLIR Optimizer"]
        QUAKE["Quake Dialect"]
        CODEGEN["Code Generation"]
    end

    subgraph Runtime["Runtime Layer"]
        CUDAQRT["CUDA-Q Runtime"]
        EXECMGR["Execution Managers"]
        PLATABS["Platform Abstractions"]
    end

    subgraph Backend["Backend Layer"]
        subgraph Quantum["Quantum Backends"]
            QPP["QPP Simulator"]
            CSV["CuStateVec"]
            HWPROV["Hardware Providers"]
        end
        CGPU["Classical GPU/CPU"]
    end

    subgraph Infrastructure["Core Infrastructure"]
        BUILD["Build System"]
        TEST["Testing Framework"]
        DOCS["Documentation"]
        CONTAINER["Container Support"]
    end

    %% Relationships
    Frontend --> Optimization
    Optimization --> Runtime
    Runtime --> Backend

    %% Apply styles
    class NVQPP,LANG,PYIF frontend
    class MLIR,QUAKE,CODEGEN optimization
    class CUDAQRT,EXECMGR,PLATABS runtime
    class QPP,CSV,HWPROV,CGPU backend
    class BUILD,TEST,DOCS,CONTAINER infrastructure

    %% Click events
    click NVQPP "https://github.com/NVIDIA/cuda-quantum/tree/main/tools/nvqpp"
    click LANG "https://github.com/NVIDIA/cuda-quantum/tree/main/include/cudaq/Frontend"
    click PYIF "https://github.com/NVIDIA/cuda-quantum/tree/main/python/"
    click MLIR "https://github.com/NVIDIA/cuda-quantum/tree/main/include/cudaq/Optimizer"
    click QUAKE "https://github.com/NVIDIA/cuda-quantum/tree/main/include/cudaq/Optimizer/Dialect/Quake"
    click CODEGEN "https://github.com/NVIDIA/cuda-quantum/tree/main/include/cudaq/Optimizer/CodeGen"
    click CUDAQRT "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/cudaq"
    click EXECMGR "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/cudaq/qis/managers"
    click PLATABS "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/cudaq/platform"
    click QPP "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/nvqir/qpp"
    click CSV "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/nvqir/custatevec"
    click HWPROV "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/cudaq/platform/default/rest/helpers"
    click CGPU "https://github.com/NVIDIA/cuda-quantum/tree/main/runtime/cudaq/platform/mqpu/custatevec"
    click BUILD "https://github.com/NVIDIA/cuda-quantum/tree/main/cmake/"
    click TEST "https://github.com/NVIDIA/cuda-quantum/tree/main/test/"
    click DOCS "https://github.com/NVIDIA/cuda-quantum/tree/main/docs/"
    click CONTAINER "https://github.com/NVIDIA/cuda-quantum/tree/main/docker/"
```
