# qiskit/qiskit-aer architecture

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

- Interactive diagram: https://gitdiagram.com/qiskit/qiskit-aer
- Repository: https://github.com/qiskit/qiskit-aer

## Overview

##### Project Type and Purpose
- This is Qiskit Aer, a high-performance quantum circuit simulator library for Qiskit.
- It provides both a Python API (via pybind11) and a C++ core with multiple simulation methods (statevector, density matrix, stabilizer, MPS, tensor network, etc.), plus realistic noise models and GPU acceleration.

##### File-Tree Analysis & Key Architectural Layers
- Top-level Python package (“qiskit_aer/…”) implements the user-facing API: AerSimulator, backends, noise models, primitives (Estimator, Sampler).
- “src/…” contains the C++ simulation core, subdivided into:
- framework/ – shared data types, JSON parsers, results, linear-algebra abstractions
- simulators/ – concrete simulators (statevector, density matrix, stabilizer, MPS, superoperator, tensor network, unitary)
- noise/ – noise model definitions & passes
- controllers/ – orchestration of shots, chunking, parallel execution
- transpile/ – circuit optimizations (fusion, cache blocking)
- Build and packaging: CMakeLists.txt, cmake/ scripts, conan integration, pyproject.toml / setup.py.
- Third-party libs: BLAS/LAPACK, Thrust, cuStateVec, cuTensorNet for GPUs.
- Tests and CI: Python tests under test/, GitHub workflows for build, tests, docs.

1. Python API Layer
– qiskit_aer package: AerSimulator, backends, primitives, noise-model wrappers.
2. pybind11 Binding Layer
– glue code in qiskit_aer/backends/wrappers & framework/pybind_*.hpp
3. C++ Core
– Framework Module
– Simulator Modules (statevector, density matrix, stabilizer, MPS, superop, tensor network, unitary)
– Noise Module (device models, errors, passes)
– Controller Module (batch executor, parallel executor)
– Transpiler Module (circuit optimizations)
4. External Libraries & Hardware
– BLAS/LAPACK (host CPU)
– CUDA/cuStateVec/cuTensorNet (GPU)
– Thrust (GPU abstractions)
5. Qiskit Terra (upstream circuit & transpile provider)
6. IBM Quantum Backends (for noise-model extraction in runtime)

b. Relationships & Data Flows
- Qiskit Terra → (Circuit) → Qiskit Aer Python API
- Python API → (pybind calls) → C++ Core
- C++ Core → (function calls) → Linear algebra & GPU libraries
- C++ Core → (execute circuits) → Simulator modules produce Results
- Results → (pybind return) → Python API → User
- Python API .from_backend(...) → IBM Quantum → noise model data

c. Architectural Patterns & Principles
- Layered architecture: clear separation of Python API, binding layer, and native core.
- Modular simulator backends: each simulation method is a pluggable component.
- Strategy pattern in controllers: different executors choose shot handling strategy.
- Separation of concerns: framework vs. simulators vs. noise vs. transpile.
- Plugin-style external-library integration (BLAS, CUDA).

d. Key Technologies & Frameworks
- Python: pybind11, setuptools/CMake integration, Qiskit Terra interoperability.
- C++: CMake, conan, OpenMP, AVX2, Thrust.
- GPU: CUDA/cuStateVec/cuTensorNet.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "External Services" 
        direction TB
        Terra["Qiskit Terra"]:::service
        IBMQ["IBM Quantum Service"]:::service
    end

    subgraph "Python Layer" 
        direction TB
        PythonAPI["Python API Layer\n(qiskit_aer/)"]:::python
    end

    subgraph "Binding Layer" 
        direction TB
        PybindWrappers["pybind11 Wrappers\n(qiskit_aer/backends/wrappers/)"]:::python
        PybindBasics["pybind_basics.hpp"]:::python
        PybindCasts["pybind_casts.hpp"]:::python
        PybindJSON["pybind_json.hpp"]:::python
    end

    subgraph "C++ Core" 
        direction TB
        subgraph "Framework Module" 
            direction TB
            Framework["Framework\n(src/framework/)"]:::cpp
        end

        subgraph "Simulators" 
            direction TB
            SV["Statevector\n(src/simulators/statevector/)"]:::cpp
            DM["Density Matrix\n(src/simulators/density_matrix/)"]:::cpp
            ST["Stabilizer\n(src/simulators/stabilizer/)"]:::cpp
            MPS["MPS\n(src/simulators/matrix_product_state/)"]:::cpp
            SO["Superoperator\n(src/simulators/superoperator/)"]:::cpp
            TN["Tensor Network\n(src/simulators/tensor_network/)"]:::cpp
            UNI["Unitary\n(src/simulators/unitary/)"]:::cpp
            ExecUtils["Executors & Utils\n(batch_shots_executor.hpp\nmulti_state_executor.hpp\nparallel_state_executor.hpp)"]:::cpp
        end

        subgraph "Noise Module" 
            direction TB
            Noise["Noise\n(src/noise/)"]:::cpp
        end

        subgraph "Controller Module" 
            direction TB
            Controllers["Controllers\n(src/controllers/)"]:::cpp
        end

        subgraph "Transpiler Module" 
            direction TB
            Transpile["Transpile\n(src/transpile/)"]:::cpp
        end
    end

    subgraph "External Libraries" 
        direction TB
        BLAS["BLAS/LAPACK\n(cmake/FindBLAS.cmake.fix-static-linking)"]:::external
        PybindFind["FindPybind11\n(cmake/FindPybind11.cmake)"]:::external
        ThrustWrap["Thrust Integration\n(src/misc/wrap_thrust.hpp)"]:::external
        cuSV["cuStateVec\n(src/simulators/statevector/chunk/cuStateVec_chunk_container.hpp)"]:::external
        cuTN["cuTensorNet\n(src/simulators/tensor_network/tensor_net_contractor_cuTensorNet.hpp)"]:::external
    end

    subgraph "Build & Packaging" 
        direction TB
        CMake["CMakeLists.txt"]:::build
        CMakeDir["cmake/"]:::build
        PythonBuild["setup.py\npyproject.toml"]:::build
    end

    User["User"]:::service

    %% Data Flows
    Terra -->|"circuit →"| PythonAPI
    PythonAPI -->|"pybind calls →"| PybindWrappers
    PybindWrappers -->|"binds →"| Framework
    PybindBasics --> Framework
    PybindCasts --> Framework
    PybindJSON --> Framework

    Framework -->|"execute() →"| SV
    Framework -->|"execute() →"| DM
    Framework -->|"execute() →"| ST
    Framework -->|"execute() →"| MPS
    Framework -->|"execute() →"| SO
    Framework -->|"execute() →"| TN
    Framework -->|"execute() →"| UNI
    Framework --> ExecUtils
    ExecUtils --> SV
    ExecUtils --> DM
    ExecUtils --> ST
    ExecUtils --> MPS
    ExecUtils --> SO
    ExecUtils --> TN
    ExecUtils --> UNI

    SV -->|"calls BLAS →"| BLAS
    SV -->|"calls cuStateVec →"| cuSV
    TN -->|"calls cuTensorNet →"| cuTN
    SV -->|"uses Thrust →"| ThrustWrap

    Framework -->|"uses JSON parsers"| Framework
    Noise --> Framework
    Controllers --> ExecUtils
    Transpile --> Framework

    PythonAPI -->|"from_backend() →"| IBMQ
    Framework -->|"results →"| PythonAPI
    PythonAPI -->|"return →"| User

    %% Build Flow
    CMakeDir --> CMake
    CMake -->|"configures →"| Framework
    CMake -->|"configures →"| Simulators
    CMake -->|"configures →"| Noise
    CMake -->|"configures →"| Controllers
    CMake -->|"configures →"| Transpile
    PythonBuild --> PythonAPI

    %% Click Events
    click PythonAPI "https://github.com/qiskit/qiskit-aer/tree/main/qiskit_aer/"
    click PybindWrappers "https://github.com/qiskit/qiskit-aer/tree/main/qiskit_aer/backends/wrappers/"
    click PybindBasics "https://github.com/qiskit/qiskit-aer/blob/main/src/framework/pybind_basics.hpp"
    click PybindCasts "https://github.com/qiskit/qiskit-aer/blob/main/src/framework/pybind_casts.hpp"
    click PybindJSON "https://github.com/qiskit/qiskit-aer/blob/main/src/framework/pybind_json.hpp"
    click Framework "https://github.com/qiskit/qiskit-aer/tree/main/src/framework/"
    click SV "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/statevector/"
    click DM "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/density_matrix/"
    click ST "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/stabilizer/"
    click MPS "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/matrix_product_state/"
    click SO "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/superoperator/"
    click TN "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/tensor_network/"
    click UNI "https://github.com/qiskit/qiskit-aer/tree/main/src/simulators/unitary/"
    click ExecUtils "https://github.com/qiskit/qiskit-aer/blob/main/src/simulators/batch_shots_executor.hpp"
    click ExecUtils "https://github.com/qiskit/qiskit-aer/blob/main/src/simulators/multi_state_executor.hpp"
    click ExecUtils "https://github.com/qiskit/qiskit-aer/blob/main/src/simulators/parallel_state_executor.hpp"
    click Noise "https://github.com/qiskit/qiskit-aer/tree/main/src/noise/"
    click Controllers "https://github.com/qiskit/qiskit-aer/tree/main/src/controllers/"
    click Transpile "https://github.com/qiskit/qiskit-aer/tree/main/src/transpile/"
    click CMake "https://github.com/qiskit/qiskit-aer/blob/main/CMakeLists.txt"
    click CMakeDir "https://github.com/qiskit/qiskit-aer/tree/main/cmake/"
    click PythonBuild "https://github.com/qiskit/qiskit-aer/blob/main/setup.py"
    click PythonBuild "https://github.com/qiskit/qiskit-aer/blob/main/pyproject.toml"
    click BLAS "https://github.com/qiskit/qiskit-aer/blob/main/cmake/FindBLAS.cmake.fix-static-linking"
    click PybindFind "https://github.com/qiskit/qiskit-aer/blob/main/cmake/FindPybind11.cmake"
    click ThrustWrap "https://github.com/qiskit/qiskit-aer/blob/main/src/misc/wrap_thrust.hpp"
    click cuSV "https://github.com/qiskit/qiskit-aer/blob/main/src/simulators/statevector/chunk/cuStateVec_chunk_container.hpp"
    click cuTN "https://github.com/qiskit/qiskit-aer/blob/main/src/simulators/tensor_network/tensor_net_contractor_cuTensorNet.hpp"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef cpp fill:#D6F5D6,stroke:#28A745,color:#28A745;
    classDef external fill:#FFE4B3,stroke:#DE7400,color:#DE7400;
    classDef service fill:#ECECEC,stroke:#6A737D,color:#6A737D;
    classDef build fill:#F5D0E0,stroke:#D73A49,color:#D73A49;
```
