# qiboteam/qiboml architecture

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

- Interactive diagram: https://gitdiagram.com/qiboteam/qiboml
- Repository: https://github.com/qiboteam/qiboml

## Overview

##### Project type and purpose
- Qiboml is an open-source Python library for Quantum Machine Learning built on top of the Qibo full-stack quantum computing framework.
- It exposes easy-to-use machine-learning interfaces (e.g., Keras, PyTorch) and plugs in quantum differentiable models, backends, and operations.

##### File structure
- src/qiboml/
- backends/: adapters for execution engines (jax, pytorch, tensorflow)
- interfaces/: wrappers exposing standard ML APIs (keras.py, pytorch.py)
- models/: quantum ansätze, encoding/decoding strategies
- operations/: differentiation rules
- tests/: unit tests for each package
- tutorials/ & doc/source/: user guides, API reference, and examples
- CI/config (GitHub workflows), packaging (pyproject.toml, flake.nix), docs build (Sphinx)

##### README for additional insights
- Confirms Qiboml’s role: integrate ML interfaces with Qibo’s quantum utilities
- Shows the “qiboml_triad” emblem hinting at three pillars: Interfaces, Models, Backends

a. Components
1. Client/User Code
2. qiboml.interfaces (Keras, PyTorch frontends)
3. qiboml.models (Ansatze, Encoding, Decoding)
4. qiboml.operations (Differentiation rules)
5. qiboml.backends (JAX, PyTorch, TensorFlow engines)
6. External Core: Qibo quantum simulator/hardware API
7. Optional: Standard ML libs (TensorFlow, PyTorch)

b. Relationships / Data flow
- Client → interfaces: user constructs quantum ML models or training loops
- interfaces → models: fetch quantum circuit definitions (ansatz, encode/decode)
- models → operations: attach differentiation rules to the circuits
- interfaces & models → backends: compile circuits + compute gradients
- backends → Qibo core: execute on simulator or hardware
- Qibo returns results → backends → interfaces → Client

c. Architectural patterns / principles
- Layered modular design:
- Interfaces layer abstracts away quantum details
- Models layer encapsulates quantum circuit design
- Operations layer provides pluggable differentiation strategies
- Backends layer decouples execution engine providers
- Dependency inversion: interfaces and models depend on abstract backends, not concrete engines
- Extensibility: new backends or interfaces can be added by implementing the prescribed APIs

d. Technologies / libraries
- Python 3, Qibo
- JAX, PyTorch, TensorFlow (for differentiable backend support)
- Sphinx for docs, pytest for testing, GitHub Actions for CI

##### Important details to capture
- Package boundaries and responsibilities
- Dataflow: high-level (user code → backend → quantum hardware/simulator)
- Extensibility: clear markers on where new interfaces/backends hook in
- External dependencies and how they integrate

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client/User Code"]:::client

    %% Interfaces Layer
    subgraph "Interfaces Layer"
        IK["keras.py"]:::core
        IP["pytorch.py"]:::core
    end

    %% Models Layer
    subgraph "Models Layer"
        AM["ansatze.py"]:::core
        EM["encoding.py"]:::core
        DM["decoding.py"]:::core
    end

    %% Operations Layer
    subgraph "Operations Layer"
        OP["differentiation.py"]:::core
    end

    %% Backends Layer
    subgraph "Backends Layer"
        BJ["jax.py"]:::core
        BP["pytorch.py"]:::core
        BT["tensorflow.py"]:::core
    end

    %% External Core & Dependencies
    Qibo["Qibo Core"]:::external
    subgraph "External ML Frameworks"
        TF["TensorFlow"]:::external
        PT["PyTorch"]:::external
    end

    %% Data Flow
    Client -->|"construct model"| IK
    Client -->|"construct model"| IP

    IK -->|"circuit definition"| AM
    IK -->|"circuit definition"| EM
    IK -->|"circuit definition"| DM
    IP -->|"circuit definition"| AM
    IP -->|"circuit definition"| EM
    IP -->|"circuit definition"| DM

    AM -->|"attach rules"| OP
    EM -->|"attach rules"| OP
    DM -->|"attach rules"| OP

    OP -->|"compile & compute gradients"| BJ
    OP -->|"compile & compute gradients"| BP
    OP -->|"compile & compute gradients"| BT

    BJ -->|"execute circuit"| Qibo
    BP -->|"execute circuit"| Qibo
    BT -->|"execute circuit"| Qibo

    Qibo -->|"execution result"| BJ
    Qibo -->|"execution result"| BP
    Qibo -->|"execution result"| BT

    BJ -->|"result data"| IK
    BP -->|"result data"| IK
    BT -->|"result data"| IK

    IK -->|"training result"| Client
    IP -->|"training result"| Client

    IK -.->|"optional use"| TF
    IP -.->|"optional use"| PT

    %% Click Events
    click Client "https://github.com/qiboteam/qiboml/tree/main/tutorials/"
    click IK "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/interfaces/keras.py"
    click IP "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/interfaces/pytorch.py"
    click AM "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/models/ansatze.py"
    click EM "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/models/encoding.py"
    click DM "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/models/decoding.py"
    click OP "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/operations/differentiation.py"
    click BJ "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/backends/jax.py"
    click BP "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/backends/pytorch.py"
    click BT "https://github.com/qiboteam/qiboml/blob/main/src/qiboml/backends/tensorflow.py"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef client fill:#D3D3D3,stroke:#000,stroke-width:1px
```
