# ginkgo-project/ginkgo architecture

> Architecture diagram of the GitHub repository ginkgo-project/ginkgo, 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/ginkgo-project/ginkgo
- Repository: https://github.com/ginkgo-project/ginkgo

## Overview

##### Project type and purpose
- This is Ginkgo, a high-performance numerical linear-algebra library (C++17) targeting sparse linear‐system solvers on many‐core architectures (CPU, NVIDIA/AMD/Intel GPUs, etc.).
- It provides a unified API (“ginkgo.hpp”) and a set of modular “executors” (Reference, OpenMP, CUDA, HIP, DPC++/SYCL) that dispatch core algorithms to hardware-specific kernels.

##### File structure
- Top‐level build/config: CMakeLists.txt, cmake/ modules, .github & .gitlab CI workflows, codecov.yml.
- Public headers: include/ginkgo/core/... define the API (LinOps, executors, matrix formats, solvers, preconditioners, distributed).
- Core library: core/ (base types & dispatch helpers, core algorithms, distributed support).
- Backends:
- reference/ – generic CPU kernels
- omp/ – OpenMP parallel kernels
- cuda/ + common/cuda_hip/ – NVIDIA GPU kernels & shared CUDA/HIP helpers
- hip/ – AMD GPU kernels
- dpcpp/ – Intel oneAPI (SYCL) kernels
- devices/ – executor abstractions & machine topology
- Tests: test/, core/test/, cuda/test/, hip/test/, dpcpp/test/, reference/test/, extensions/test/
- Examples & benchmarks: examples/, benchmark/
- Third-party: third_party/ (SuiteSparse, gflags, gtest, nlohmann_json, helper tools)

##### README for additional insights
- API usage via find_package(Ginkgo) → target Ginkgo::ginkgo
- CMake options toggle modules (–DGINKGO_WITH_CUDA=ON, etc.)
- Emphasis on unit tests (Google Test), examples, benchmarks & Ginkgo Performance Explorer (GPE).

##### Elements
- Blue for library layers (API, Core, Executors)
- Green for backends & hardware
- Orange for third-party dependencies
- Grey for build system (CMake)
- Rectangles for components
- Diamonds for factory/registry

Capture all essential modules rather than every single directory; grouping directories by logical layer (core, backends, API, tooling) ensures clarity without clutter.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application / Client Code"
        direction TB
        Examples["Examples"]:::lib
        Benchmarks["Benchmarks"]:::lib
    end

    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        API["ginkgo.hpp & core headers"]:::lib
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Core["core/ (base, components, solver, preconditioner, distributed, etc.)"]:::lib
    end

    %% Executor Abstraction
    Factory{"Executor Factory / Registry"}:::lib
    
    %% Backend Modules
    subgraph "Executor Backends"
        direction TB
        RefExec["Reference Executor"]:::backend
        OmpExec["OpenMP Executor"]:::backend
        CudaExec["CUDA Executor"]:::backend
        HipExec["HIP Executor"]:::backend
        DpcppExec["DPC++ Executor"]:::backend
    end

    %% Hardware Targets
    subgraph "Hardware Targets"
        direction TB
        CPU["CPU Cores"]:::hw
        NvidiaGPU["NVIDIA GPU"]:::hw
        AMDGPU["AMD GPU"]:::hw
        IntelGPU["Intel GPU"]:::hw
    end

    %% Build System and Third-party
    CMake["CMake Build System"]:::build
    ThirdParty["Third-party Dependencies"]:::third

    %% Connections
    Examples -->|uses| API
    Benchmarks -->|uses| API
    API -->|calls| Core
    Core -->|dispatches to| Factory
    Factory -->|selects| RefExec
    Factory -->|selects| OmpExec
    Factory -->|selects| CudaExec
    Factory -->|selects| HipExec
    Factory -->|selects| DpcppExec

    RefExec -->|runs on| CPU
    OmpExec -->|runs on| CPU
    CudaExec -->|runs on| NvidiaGPU
    HipExec -->|runs on| AMDGPU
    DpcppExec -->|runs on| IntelGPU

    CMake -->|builds/enables| RefExec
    CMake -->|builds/enables| OmpExec
    CMake -->|builds/enables| CudaExec
    CMake -->|builds/enables| HipExec
    CMake -->|builds/enables| DpcppExec
    CMake -->|links| ThirdParty

    Core <-->|"MPI for distributed"| ThirdParty

    %% Click Events
    click Examples "https://github.com/ginkgo-project/ginkgo/tree/develop/examples/"
    click Benchmarks "https://github.com/ginkgo-project/ginkgo/tree/develop/benchmark/"
    click API "https://github.com/ginkgo-project/ginkgo/blob/develop/include/ginkgo/ginkgo.hpp"
    click API "https://github.com/ginkgo-project/ginkgo/tree/develop/include/ginkgo/core/"
    click Core "https://github.com/ginkgo-project/ginkgo/tree/develop/core/"
    click Factory "https://github.com/ginkgo-project/ginkgo/blob/develop/devices/device.cpp"
    click Factory "https://github.com/ginkgo-project/ginkgo/blob/develop/devices/machine_topology.cpp"
    click RefExec "https://github.com/ginkgo-project/ginkgo/tree/develop/reference/"
    click OmpExec "https://github.com/ginkgo-project/ginkgo/tree/develop/omp/"
    click CudaExec "https://github.com/ginkgo-project/ginkgo/tree/develop/cuda/"
    click CudaExec "https://github.com/ginkgo-project/ginkgo/tree/develop/common/cuda_hip/"
    click HipExec "https://github.com/ginkgo-project/ginkgo/tree/develop/hip/"
    click DpcppExec "https://github.com/ginkgo-project/ginkgo/tree/develop/dpcpp/"
    click CMake "https://github.com/ginkgo-project/ginkgo/blob/develop/CMakeLists.txt"
    click CMake "https://github.com/ginkgo-project/ginkgo/tree/develop/cmake/"
    click ThirdParty "https://github.com/ginkgo-project/ginkgo/tree/develop/third_party/"

    %% Styles
    classDef lib fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef hw fill:#90EE90,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef third fill:#FFA500,stroke:#000,stroke-width:1px
    class Factory lib
```
