# qunasys/quri-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/qunasys/quri-sdk
- Repository: https://github.com/qunasys/quri-sdk

## Overview

##### Main Components
- User-facing Layer
– Jupyter notebooks (notebooks/quri_sdk_notebooks)
– Tutorials & examples
- Meta-Package Layer
– quri_sdk (bundles all sub-packages)
- Core Libraries
– quri-parts: circuit & operator abstractions, transpilers, estimators, samplers
– quri-algo: high-level quantum algorithms, cost functions, problem definitions
– quri-vm: quantum virtual machine for simulation & resource estimation
- Backend & Plugin Layer (quri-parts subpackages)
– Simulators: qulacs, stim, itensor, tensornetwork, rust
– Cloud/Hardware SDKs: braket, cirq, qiskit, ionq, quantinuum, tket
– Chemistry libraries: pyscf, openfermion
– FTQC helpers: qsub
- Infrastructure Layer
– CI/CD: GitHub Actions workflows (lint, test, package)
– Packaging & build tools: Poetry (pyproject.toml), Makefiles, Sphinx docs

##### Relationships and Data Flow
- Notebooks ➔ import quri_sdk API
- quri_sdk ➔ aggregates quri-parts, quri-algo, quri-vm
- quri-algo ➔ calls quri-parts abstractions (circuits, estimators) and can target quri-vm or real devices via backend plugins
- quri-vm ➔ implements Estimator/Sampler interfaces defined by quri-parts for fast simulation and resource analysis
- quri-parts ➔ defines core interfaces; dispatches work to specific backend plugins based on user’s extra-package selection
- Backend plugins ➔ wrap external SDKs or simulators and translate between quri-parts IR and vendor APIs
- CI/CD workflows ➔ run tests, type checks, documentation builds on each component independently

##### Architectural Patterns
- Layered architecture: separation of user interface, orchestration (quri_sdk), core abstractions (quri-parts), algorithm logic (quri-algo), execution engine (quri-vm), and plugin backends
- Plugin/adapter pattern: quri-parts uses adapter subpackages to integrate third-party SDKs and simulators without changing core code
- Meta-package pattern: quri_sdk ensures compatibility and version alignment across quri-parts, quri-algo, and quri-vm
- Modular design: each library (and subpackage) has its own tests, CI, and packaging

##### Relevant Technologies
- Python 3.10+
- Packaging: Poetry (pyproject.toml)
- CI/CD: GitHub Actions (.github/workflows/*.yml)
- Documentation: Sphinx (quri-parts/docs), Jupyter notebooks
- Quantum frameworks: Qulacs, Stim, ITensor, TensorNetwork, OpenQASM, Braket, Cirq, Qiskit, IonQ, Quantinuum, PySCF, OpenFermion, TKET
- FTQC circuit synthesis: qsub

##### Essential Elements
- Interface labels on connections (e.g., “Circuit → Transpiler,” “Algorithm → Estimator”)
- CI/CD pipeline as a side flow feeding into each component’s build/test stage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        direction TB
        Notebooks["Jupyter Notebooks"]:::user
        Tutorials["Tutorials & Examples"]:::user
    end

    %% Meta-Package Layer
    subgraph "Meta-Package Layer"
        direction TB
        Meta["quri_sdk Meta-Package"]:::meta
    end

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        Parts["quri-parts"]:::core
        Algo["quri-algo"]:::core
        VM["quri-vm"]:::core
    end

    %% Backend & Plugin Layer
    subgraph "Backend & Plugin Layer"
        direction TB
        Qulacs["Qulacs Simulator"]:::plugin
        Stim["Stim Simulator"]:::plugin
        ITensor["ITensor Simulator"]:::plugin
        TensorNetwork["TensorNetwork Simulator"]:::plugin
        RustSim["Rust-based Simulator"]:::plugin
        Braket["Amazon Braket"]:::plugin
        Cirq["Google Cirq"]:::plugin
        Qiskit["IBM Qiskit"]:::plugin
        IonQ["IonQ Hardware"]:::plugin
        Quantinuum["Quantinuum Hardware"]:::plugin
        TKET["TKET Hardware"]:::plugin
        PySCF["PySCF Integration"]:::plugin
        OpenFermion["OpenFermion Integration"]:::plugin
        Qsub["Qsub FTQC Helper"]:::plugin
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        CI["CI/CD Workflows"]:::infra
        Packaging["Packaging & Build Tools"]:::infra
        Docs["Sphinx Documentation"]:::infra
        SetupNotebooks["Notebook Env Setup Action"]:::infra
        PoetryInstall["Poetry Install Action"]:::infra
    end

    %% Connections
    Notebooks -->|"import API"| Meta
    Tutorials -->|"import API"| Meta

    Meta -->|"aggregates"| Parts
    Meta -->|"aggregates"| Algo
    Meta -->|"aggregates"| VM

    Algo -->|"uses Abstractions"| Parts
    Algo -->|"targets Simulation"| VM
    Algo -->|"targets Real Devices"| Braket
    Algo -->|"targets Real Devices"| Cirq
    Algo -->|"targets Real Devices"| Qiskit
    Algo -->|"targets Real Devices"| IonQ
    Algo -->|"targets Real Devices"| Quantinuum
    Algo -->|"targets Real Devices"| TKET

    VM -->|"implements Estimator/Sampler"| Parts

    Parts -->|"dispatch to Plugin"| Qulacs
    Parts -->|"dispatch to Plugin"| Stim
    Parts -->|"dispatch to Plugin"| ITensor
    Parts -->|"dispatch to Plugin"| TensorNetwork
    Parts -->|"dispatch to Plugin"| RustSim
    Parts -->|"dispatch to Plugin"| Braket
    Parts -->|"dispatch to Plugin"| Cirq
    Parts -->|"dispatch to Plugin"| Qiskit
    Parts -->|"dispatch to Plugin"| IonQ
    Parts -->|"dispatch to Plugin"| Quantinuum
    Parts -->|"dispatch to Plugin"| TKET
    Parts -->|"dispatch to Plugin"| PySCF
    Parts -->|"dispatch to Plugin"| OpenFermion
    Parts -->|"dispatch to Plugin"| Qsub

    CI -->|runs tests/docs| Meta
    CI -->|runs tests/docs| Parts
    CI -->|runs tests/docs| Algo
    CI -->|runs tests/docs| VM
    CI -->|runs tests/docs| Docs

    Packaging -->|defines| Meta
    Packaging -->|defines| Parts
    Packaging -->|defines| Algo
    Packaging -->|defines| VM

    Docs -->|build docs| Parts

    SetupNotebooks -->|setup env for| Notebooks
    PoetryInstall -->|install dependencies| Meta
    PoetryInstall -->|install dependencies| Parts
    PoetryInstall -->|install dependencies| Algo
    PoetryInstall -->|install dependencies| VM

    %% Click Events
    click Notebooks "https://github.com/qunasys/quri-sdk/tree/main/notebooks/quri_sdk_notebooks"
    click Meta "https://github.com/qunasys/quri-sdk/blob/main/quri_sdk/_quri_sdk_meta.py"
    click Parts "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/quri_parts"
    click Algo "https://github.com/qunasys/quri-sdk/tree/main/quri-algo/quri_algo"
    click VM "https://github.com/qunasys/quri-sdk/tree/main/quri-vm/quri_vm"
    click Qulacs "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/qulacs/quri_parts/qulacs"
    click Stim "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/stim/quri_parts/stim"
    click ITensor "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/itensor/quri_parts/itensor"
    click TensorNetwork "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/tensornetwork/quri_parts/tensornetwork"
    click RustSim "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/rust/quri_parts/rust"
    click RustSim "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/rust/src"
    click Braket "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/braket/quri_parts/braket"
    click Cirq "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/cirq/quri_parts/cirq"
    click Qiskit "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/qiskit/quri_parts/qiskit"
    click IonQ "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/ionq/quri_parts/ionq"
    click Quantinuum "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/quantinuum/quri_parts/quantinuum"
    click TKET "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/tket/quri_parts/tket"
    click PySCF "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/pyscf/quri_parts/pyscf"
    click OpenFermion "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/openfermion/quri_parts/openfermion"
    click Qsub "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/packages/qsub/quri_parts/qsub"
    click CI "https://github.com/qunasys/quri-sdk/blob/main/.github/workflows/*.yml"
    click CI "https://github.com/qunasys/quri-sdk/tree/main/.github/actions"
    click Packaging "https://github.com/qunasys/quri-sdk/blob/main/pyproject.toml"
    click Docs "https://github.com/qunasys/quri-sdk/tree/main/quri-parts/docs"
    click SetupNotebooks "https://github.com/qunasys/quri-sdk/blob/main/.github/actions/notebooks/setup/action.yml"
    click PoetryInstall "https://github.com/qunasys/quri-sdk/blob/main/.github/actions/python-poetry-install/action.yml"

    %% Styles
    classDef user fill:#a8e6cf,stroke:#379683,color:#05386b
    classDef meta fill:#d0e1f9,stroke:#3b5998,color:#102a43
    classDef core fill:#ffd3b6,stroke:#ff8b94,color:#66332f
    classDef plugin fill:#e0bbE4,stroke:#8e44ad,color:#4f0125
    classDef infra fill:#eeeeee,stroke:#cccccc,color:#333333
```
