# nvidia/numba-cuda architecture

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

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

## Overview

##### Main Components
- Core Library Components:
- API Interface: Represented by files like “numba_cuda/numba/cuda/api.py” which serve as the entry points for users.
- Code Generation & Compilation: Modules such as “numba_cuda/numba/cuda/codegen.py” and “compiler.py” which translate Python code into CUDA kernels.
- CUDA Driver and Runtime Wrappers: The “cudadrv” directory contains multiple scripts (driver.py, nvrtc.py, nvvm.py, etc.) that abstract the CUDA driver and runtime interactions.
- Simulation: The “simulator” subdirectory encapsulates CUDA simulation capabilities for testing and prototyping.
- Utility and Support Modules: Including error handling, decorators, caching, and helper functions (e.g., “errors.py”, “device_init.py”, “utils.py”).
- Testing & Examples:
- Extensive tests under “numba_cuda/numba/cuda/tests” demonstrate how each module is verified. This includes unit tests for the driver, simulator, and code generation.
- Documentation examples in “docs/source/user” guide how the features can be used.
- Build and Deployment Infrastructure:
- CI/CD pipelines (GitHub workflows in “.github/workflows” & “ci” scripts) for building conda packages, wheels, testing, and documentation.
- Packaging tools (setup.py, pyproject.toml, and conda recipe directories) that manage distribution.
- Documentation:
- The “docs” directory includes Sphinx-based documentation for both user and reference guides.

##### Relationships and Interactions
- The user-facing API layer interacts with the internal modules. For instance, a call to a CUDA kernel from the API contacts the code generation module, which in turn links with the driver and runtime wrappers.
- The “cudadrv” modules form a cohesive layer that abstracts almost all low-level CUDA driver functionalities. Data and control flow here are critical and should be clearly shown.
- The simulation components mirror much of the “cudadrv” APIs but allow for a controlled, testing-friendly environment, so indicate how simulation can replace actual CUDA driver calls when necessary.
- CI/CD and build scripts interface with the library components to automate testing, building, and deployment.

##### Architectural Patterns and Important Design Principles
- Layered Architecture: Organize components in layers where the top layer is the user API and documentation, followed by the intermediate processing (codegen and simulation), then the driver and runtime abstraction.
- Extensibility and Integration: The project is designed to be integrated with Numba and extended using both pip and conda builds. Show integration points for external systems (e.g., CI systems, distribution channels, and external content such as the Numba Discourse for support).

##### Detail and Clarity
- Integration with external systems like conda-forge and GitHub Actions as part of the deployment pipeline.

## Diagram (Mermaid)

```mermaid
graph TD

  %% User Interface Layer
  subgraph "User Interface Layer"
    A["CUDA API Interface"]:::apiLayer
    D["Documentation & Examples"]:::apiLayer
  end
  
  %% Processing Layer
  subgraph "Processing Layer"
    B["Code Generation (codegen.py)"]:::processLayer
    C["Compiler (compiler.py)"]:::processLayer
    S["Simulation Environment"]:::processLayer
  end
  
  %% Driver Layer
  subgraph "Driver & Runtime Layer"
    DR["CUDA Driver & Runtime (cudadrv)"]:::driverLayer
  end
  
  %% Utility & Support Layer
  subgraph "Utility & Support Modules"
    E["Error Handling (errors.py)"]:::supportLayer
    DI["Device Initialization (device_init.py)"]:::supportLayer
    U["Utilities (utils.py)"]:::supportLayer
  end
  
  %% Testing & Deployment Infrastructure
  subgraph "Testing & Deployment"
    T["Testing Suite"]:::infraLayer
    CI["CI/CD Pipelines"]:::infraLayer
    PD["Packaging & Deployment"]:::infraLayer
  end

  %% Relationships
  A -->|"calls"| B
  A -->|"calls"| C
  B -->|"compiles_to"| DR
  C -->|"compiles_to"| DR
  A -->|"simulates"| S
  S -->|"simulates"| DR
  A ---|"guided_by"| D

  %% Support Relationships (dashed lines)
  B -.-> U
  C -.-> U
  DR -.-> U
  S -.-> U
  B -.-> E
  C -.-> E
  DR -.-> E
  S -.-> E
  B -.-> DI
  C -.-> DI
  DR -.-> DI
  S -.-> DI

  %% Testing & Deployment Relationships
  T -->|"tests"| A
  T -->|"tests"| B
  T -->|"tests"| C
  T -->|"tests"| DR
  T -->|"tests"| S
  CI -->|"automates"| T
  PD -->|"packages"| T

  %% Styles
  classDef apiLayer fill:#ffecb3,stroke:#f39c12,stroke-width:2px;
  classDef processLayer fill:#d0e9ff,stroke:#3498db,stroke-width:2px;
  classDef driverLayer fill:#d4efdf,stroke:#27ae60,stroke-width:2px;
  classDef supportLayer fill:#f2d7d5,stroke:#c0392b,stroke-width:2px;
  classDef infraLayer fill:#fdebd0,stroke:#e67e22,stroke-width:2px;

  %% Click Events
  click A "https://github.com/nvidia/numba-cuda/blob/main/numba_cuda/numba/cuda/api.py"
  click B "https://github.com/nvidia/numba-cuda/blob/main/numba_cuda/numba/cuda/codegen.py"
  click C "https://github.com/nvidia/numba-cuda/blob/main/numba_cuda/numba/cuda/compiler.py"
  click DR "https://github.com/nvidia/numba-cuda/tree/main/numba_cuda/numba/cuda/cudadrv"
  click S "https://github.com/nvidia/numba-cuda/tree/main/numba_cuda/numba/cuda/simulator"
  click E "https://github.com/nvidia/numba-cuda/blob/main/numba_cuda/numba/cuda/errors.py"
  click DI "https://github.com/nvidia/numba-cuda/blob/main/numba_cuda/numba/cuda/device_init.py"
  click U "https://github.com/nvidia/numba-cuda/blob/main/numba_cuda/numba/cuda/utils.py"
  click T "https://github.com/nvidia/numba-cuda/tree/main/numba_cuda/numba/cuda/tests"
  click D "https://github.com/nvidia/numba-cuda/tree/main/docs/source/user"
  click CI "https://github.com/nvidia/numba-cuda/tree/main/.github/workflows"
  click PD "https://github.com/nvidia/numba-cuda/tree/main/ci"
```
