# quantumlib/qsim architecture

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

- Interactive diagram: https://gitdiagram.com/quantumlib/qsim
- Repository: https://github.com/quantumlib/qsim

## Overview

##### Project Type and Purpose
- This is a C++ library exposing high-performance simulation engines (CPU, GPU, fused gates, state‐vector).
- It provides a Python interface (pybind11) and a Cirq plugin (`qsimcirq`) to simulate quantum circuits.
- It also includes sample C++ CLI applications, test suites, documentation, CI/CD pipelines, and Docker setups.

- Core C++ Simulation Library (lib/)
– State-vector kernels (basic, SSE, AVX, AVX512, CUDA, Custatevec)
– Gate fusion and circuit parsers
– Utilities (I/O, multithreading via OpenMP, per-backend optimizations)
- Sample Applications (apps/)
– CLI executables linking against the core library for different use cases
- Python Binding Layer (pybind_interface/)
– Per-backend modules (basic, SSE, AVX2, AVX512, CUDA, HIP, Custatevec, Decide)
– Uses CMake + pybind11 to generate `qsim` extension packages
- Cirq Integration (qsimcirq/)
– Python package exposing a `qsim_simulator` and `qsim_circuit` to end users
– Depends on the Python extension module built by pybind_interface
- Circuits Input (circuits/)
– Sample circuits in various formats as test or tutorial inputs
- Tests
– C++ unit tests (tests/) using GoogleTest
– Python tests (qsimcirq_tests/) using pytest
- Third-Party Integrations
– Optional NVIDIA cuQuantum library (third_party/cuquantum/)
- Build & CI/CD
– Bazel (WORKSPACE, BUILD files) + CMakeLists.txt + Makefile
– GitHub workflows (.github/workflows/) for build, tests, formatting, releases
- Containerization
– Dockerfile, docker-compose.yml, Jupyter environment for interactive demos
- Documentation & Tutorials (docs/, jupyter/)
– Sphinx/Book builds, Jupyter notebooks, install instructions

– Cirq or sample apps → feed circuit descriptions → pybind_interface (Python) or direct C++ API
– Python layer (`qsimcirq`) calls into extension modules → C++ core library
– Core library dispatches to the appropriate backend kernel (AVX, GPU, etc.)
– Simulation runs on CPU threads (OpenMP) or GPU streams
– Results returned back through Python or printed by the CLI
– CI pipelines trigger builds/tests across components

##### Architectural Patterns & Principles
– Layered architecture:
- Core simulation engine (performance-critical C++)
- Binding layer (pybind11)
- User-facing API (Python/C++ CLI)
– Plugin/back-end strategy: multiple simulator back ends selected at build/runtime
– Build automation: multi-language tooling (Bazel, CMake, Python packaging)
– Continuous integration: containerized tests and multi-platform coverage

##### Technologies & Frameworks
– C++17, OpenMP, AVX/FMA, CUDA, HIP
– GoogleTest for C++ tests, pytest for Python tests
– pybind11 for Python bindings, setup.py/pyproject.toml for packaging
– Bazel, CMake, Make, Docker, GitHub Actions

##### Capturing Essential Elements
– Don’t omit the build system: Bazel/CMake orchestrates C++ and Python builds across platforms.
– Include CI workflows to show how quality gates (format checks, sanitizer tests, wheel releases) fit into the pipeline.
– Represent Docker and Jupyter environments for reproducible demos and tests.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Users & Tools
    subgraph "User & External Tools" 
        direction TB
        Cirq["Google Cirq"]:::external
        CLIAppUser["CLI Applications"]:::external
    end

    %% Python Binding & API Layer
    subgraph "Python Binding & API (green)" 
        direction TB
        PybindMain["pybind_interface/pybind_main.cpp"]:::python
        PB_Basic["basic module"]:::python
        PB_SSE["sse module"]:::python
        PB_AVX2["avx2 module"]:::python
        PB_AVX512["avx512 module"]:::python
        PB_CUDA["cuda module"]:::python
        PB_HIP["hip module"]:::python
        PB_Custatevec["custatevec module"]:::python
        PB_Decide["decide module"]:::python
    end

    %% Cirq Integration Layer
    subgraph "Cirq Integration (green)"
        direction TB
        QSimCirqSim["qsimcirq/qsim_simulator.py"]:::python
        QSimCirqCirc["qsimcirq/qsim_circuit.py"]:::python
        QSimCirqH["qsimcirq/qsimh_simulator.py"]:::python
    end

    %% Sample Applications Layer
    subgraph "Sample C++ Applications (green)"
        direction TB
        App_Base["apps/qsim_base.cc"]:::python
        App_Base_CUDA["apps/qsim_base_cuda.cu"]:::python
        App_Base_CV["apps/qsim_base_custatevec.cu"]:::python
        App_Amps["apps/qsim_amplitudes.cc"]:::python
        App_VN["apps/qsim_von_neumann.cc"]:::python
        App_QTraj["apps/qsim_qtrajectory_cuda.cu"]:::python
    end

    %% Core C++ Simulation Library
    subgraph "Core C++ Simulation Library (blue)"
        direction TB
        CoreLib["lib/"]:::core

        subgraph "State-vector Kernels"
            direction TB
            Basic["statespace_basic.h\nsimulator_basic.h"]:::core
            SSE["statespace_sse.h\nsimulator_sse.h"]:::core
            AVX["statespace_avx.h\nsimulator_avx.h"]:::core
            AVX512["statespace_avx512.h\nsimulator_avx512.h"]:::core
            CUDA["statespace_cuda.h\nsimulator_cuda.h"]:::core
            Custatevec["statespace_custatevec.h\nsimulator_custatevec.h"]:::core
        end

        subgraph "Gate Fusion & Parsers"
            direction TB
            Fuser["fuser.h\nfuser_basic.h\nfuser_mqubit.h"]:::core
            Parser["circuit.h\ncircuit_qsim_parser.h"]:::core
        end

        subgraph "Utilities"
            direction TB
            IO["io.h\nio_file.h"]:::core
            ParFor["parfor.h"]:::core
            SeqFor["seqfor.h"]:::core
            Util["util.h\nutil_cpu.h\nutil_cuda.h\nutil_custatevec.h"]:::core
        end
    end

    %% Third-Party Integration
    ThirdParty["third_party/cuquantum/"]:::external

    %% Circuits Inputs
    subgraph "Circuits Input"
        direction TB
        Circuit_q24["circuits/circuit_q24"]:::core
        Circuit_q30["circuits/circuit_q30"]:::core
        Circuit_q40["circuits/circuit_q40"]:::core
        Bit_q24_s1["circuits/bitstrings_q24_s1"]:::core
        Bit_q24_s2["circuits/bitstrings_q24_s2"]:::core
        Bit_q40_s1["circuits/bitstrings_q40_s1"]:::core
    end

    %% Testing
    subgraph "Testing & Validation"
        direction TB
        CppTests["tests/"]:::core
        PyTests["qsimcirq_tests/"]:::python
    end

    %% Build & CI/CD
    subgraph "Build & CI/CD (orange)"
        direction TB
        Bazel["Bazel BUILD Files"]:::ci
        CMakeMake["CMakeLists.txt & Makefiles"]:::ci
        CIWorkflows[".github/workflows/"]:::ci
        DockerCompose["Dockerfile & docker-compose.yml"]:::ci
    end

    %% Documentation & Tutorials
    subgraph "Documentation & Tutorials"
        direction TB
        Docs["docs/"]:::external
        Jupyter["jupyter/"]:::external
    end

    %% Data & Control Flow
    Cirq -->|invokes| QSimCirqSim
    QSimCirqSim -->|uses| PybindMain
    CLIAppUser -->|calls| App_Base
    CLIAppUser --> App_Base_CUDA
    CLIAppUser --> App_Base_CV
    App_Base -->|links| CoreLib
    PybindMain -->|binds| CoreLib
    CoreLib --> Basic
    CoreLib --> SSE
    CoreLib --> AVX
    CoreLib --> AVX512
    CoreLib --> CUDA
    CoreLib --> Custatevec
    CoreLib --> Fuser
    CoreLib --> Parser
    CoreLib --> IO
    CoreLib --> ParFor
    CoreLib --> SeqFor
    CoreLib --> Util
    CoreLib --> ThirdParty
    Circuit_q24 -->|input| CoreLib
    Circuit_q30 --> CoreLib
    Circuit_q40 --> CoreLib
    CoreLib -->|outputs| CLIAppUser
    CoreLib -->|returns results| PybindMain
    CoreLib -->|tested by| CppTests
    PybindMain -->|tested by| PyTests

    %% Build & CI connections
    Bazel --> CoreLib
    CMakeMake --> CoreLib
    Bazel --> PybindMain
    CMakeMake --> PybindMain
    CIWorkflows --> Bazel
    CIWorkflows --> CMakeMake
    CIWorkflows --> CppTests
    CIWorkflows --> PyTests
    DockerCompose --> CIWorkflows
    DockerCompose --> Jupyter
    Docs --> CIWorkflows

    %% Click Events
    click CoreLib "https://github.com/quantumlib/qsim/tree/master/lib/"
    click Basic "https://github.com/quantumlib/qsim/blob/master/lib/statespace_basic.h"
    click SSE "https://github.com/quantumlib/qsim/blob/master/lib/statespace_sse.h"
    click AVX "https://github.com/quantumlib/qsim/blob/master/lib/statespace_avx.h"
    click AVX512 "https://github.com/quantumlib/qsim/blob/master/lib/statespace_avx512.h"
    click CUDA "https://github.com/quantumlib/qsim/blob/master/lib/statespace_cuda.h"
    click Custatevec "https://github.com/quantumlib/qsim/blob/master/lib/statespace_custatevec.h"
    click Fuser "https://github.com/quantumlib/qsim/blob/master/lib/fuser.h"
    click Parser "https://github.com/quantumlib/qsim/blob/master/lib/circuit.h"
    click IO "https://github.com/quantumlib/qsim/blob/master/lib/io.h"
    click ParFor "https://github.com/quantumlib/qsim/blob/master/lib/parfor.h"
    click SeqFor "https://github.com/quantumlib/qsim/blob/master/lib/seqfor.h"
    click Util "https://github.com/quantumlib/qsim/blob/master/lib/util.h"
    click App_Base "https://github.com/quantumlib/qsim/blob/master/apps/qsim_base.cc"
    click App_Base_CUDA "https://github.com/quantumlib/qsim/blob/master/apps/qsim_base_cuda.cu"
    click App_Base_CV "https://github.com/quantumlib/qsim/blob/master/apps/qsim_base_custatevec.cu"
    click PybindMain "https://github.com/quantumlib/qsim/blob/master/pybind_interface/pybind_main.cpp"
    click PB_Basic "https://github.com/quantumlib/qsim/blob/master/pybind_interface/basic/pybind_main_basic.cpp"
    click PB_SSE "https://github.com/quantumlib/qsim/blob/master/pybind_interface/sse/pybind_main_sse.cpp"
    click PB_AVX2 "https://github.com/quantumlib/qsim/blob/master/pybind_interface/avx2/pybind_main_avx2.cpp"
    click PB_AVX512 "https://github.com/quantumlib/qsim/blob/master/pybind_interface/avx512/pybind_main_avx512.cpp"
    click PB_CUDA "https://github.com/quantumlib/qsim/blob/master/pybind_interface/cuda/pybind_main_cuda.cpp"
    click PB_HIP "https://github.com/quantumlib/qsim/blob/master/pybind_interface/hip/pybind_main_hip.cpp"
    click PB_Custatevec "https://github.com/quantumlib/qsim/blob/master/pybind_interface/custatevec/pybind_main_custatevec.cpp"
    click PB_Decide "https://github.com/quantumlib/qsim/blob/master/pybind_interface/decide/decide.cpp"
    click QSimCirqSim "https://github.com/quantumlib/qsim/blob/master/qsimcirq/qsim_simulator.py"
    click QSimCirqCirc "https://github.com/quantumlib/qsim/blob/master/qsimcirq/qsim_circuit.py"
    click QSimCirqH "https://github.com/quantumlib/qsim/blob/master/qsimcirq/qsimh_simulator.py"
    click ThirdParty "https://github.com/quantumlib/qsim/tree/master/third_party/cuquantum/"
    click Bazel "https://github.com/quantumlib/qsim/tree/master/WORKSPACE"
    click CMakeMake "https://github.com/quantumlib/qsim/blob/master/CMakeLists.txt"
    click CIWorkflows "https://github.com/quantumlib/qsim/tree/master/.github/workflows/"
    click DockerCompose "https://github.com/quantumlib/qsim/blob/master/docker-compose.yml"
    click Docs "https://github.com/quantumlib/qsim/tree/master/docs/"
    click Jupyter "https://github.com/quantumlib/qsim/blob/master/jupyter/README.md"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#6c8ebf,color:#000;
    classDef python fill:#d9ead3,stroke:#6aa84f,color:#000;
    classDef ci fill:#fce5cd,stroke:#f6b26b,color:#000;
    classDef external fill:#eeeeee,stroke:#999999,color:#333;
    classDef green fill:#d9ead3,stroke:#6aa84f;
    classDef blue fill:#cfe2f3,stroke:#6c8ebf;
    classDef orange fill:#fce5cd,stroke:#f6b26b;
```
