# pasqal-io/qadence architecture

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

- Interactive diagram: https://gitdiagram.com/pasqal-io/qadence
- Repository: https://github.com/pasqal-io/qadence

## Overview

##### Main Components
- Core Composition & Program Building: Represent the block-based system that lets users compose digital–analog quantum programs. This includes modules like qadence/blocks and the constructors found in qadrence/constructors.
- Backend Management: There are multiple backends for simulation and execution:
– PyQTorch is the default (providing differentiable simulation via PyTorch).
– Additional backends like Pulser (for pulse-sequence-based simulation) and Horqrux (via the JAX engine) are supported.
– The “qadence/backends” directory encapsulates these variants (with submodules for each backend such as horqrux, pulser, pyqtorch).
- Quantum Circuit & Execution Engine: The qadrence/circuit, qadrence/execution, and qadrence/transpile modules are responsible for taking the composed quantum program and preparing or simulating its execution.
- Machine Learning & Differentiation: The qadrence/ml_tools module integrates with PyTorch and provides tools like loss functions, optimizers, and parameter management for automatic differentiation.
- Measurement, Noise, and Error Mitigation: Components for quantum measurements (qadence/measurements), noise handling (qadence/noise), and mitigation (qadence/mitigations) are clearly modularized.
- Supporting Utilities: There are ancillary modules for logging, configuration (log_config.yaml, setup.py, etc.), and exceptions which handle error states, along with a testing framework.

##### Component Relationships and Data Flow
- The “Circuit/Program” is further processed by the “Transpiler” (transforming, flattening circuits, applying noise models) which connects to both simulation backends and the measurement modules.
- The “Machine Learning Tools” and “Differentiation” modules are connected to the simulation backends and to the program builder via parameterized operations. Indicate bi-directional data flow between parameter updates and circuit simulation.
- Integration points for external dependencies (e.g., integration with Sympy for symbolic parameters, Graphviz for visualization, etc.).

##### Architectural Patterns and Design Principles
- Modular Layering: The system is highly modular, separating the quantum program definition (blocks, constructors) from simulation (backends/engines) and differentiation (ml_tools).
- Plugin/Extension Mechanism: Due to its support for multiple backends and extras (visualization, protocols, libs), the design encourages extensibility—illustrate this by grouping backend components as interchangeable plugins.
- Data Flow-Driven Execution: Emphasize the flow from quantum program composition to execution, simulation, evaluation (measurement) and iterative learning, which is crucial for automatic differentiation and optimization.
- Error Handling: Although not as visible as the major functional blocks, note the presence of dedicated exception modules meant to capture any errors across the layers.

##### Relevant Technologies and Frameworks
- Python as the base language.
- PyTorch for differentiable simulation (core to PyQTorch and ml_tools).
- Optional JAX integration for the Horqrux backend.
- Sympy for symbolic parameter definitions.
- Graphviz (in combination with the drawing modules) for circuit visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Program Composition Layer
    subgraph "Program Composition"
        A1["Blocks"]:::composition
        A2["Constructors"]:::composition
    end

    %% Quantum Circuit Creation Layer
    subgraph "Quantum Circuit Creation"
        B1["Circuit Definition"]:::circuit
        B2["Transpiler"]:::circuit
        B3["Execution Engine"]:::circuit
    end

    %% Backend Simulation & ML Integration Layer
    subgraph "Backend Simulation and ML Integration"
        C1["Backend Management"]:::backend
        C2["ML Tools"]:::ml
    end

    %% Evaluation and Visualization Layer
    subgraph "Evaluation and Visualization"
        D1["Measurements"]:::evaluation
        D2["Noise Handling"]:::evaluation
        D3["Mitigations"]:::evaluation
        D4["Visualization & Drawing"]:::visualization
    end

    %% Supporting Utilities Layer
    subgraph "Supporting Utilities"
        E1["Exception Handling"]:::utils
        E2["Logger"]:::utils
        E3["Log Configuration"]:::utils
    end

    %% Data Flow Connections
    A1 --> B1
    A2 --> B1
    B1 --> B2
    B2 --> B3
    B3 -->|"simulate"| C1
    C1 <-->|"update"| C2
    C1 --> D1
    C1 --> D2
    C1 --> D3
    B3 --> D4

    %% Supporting Utilities Integration (dashed error/log feedback)
    B3 -.->|"error_reporting"| E1
    C1 -.->|"error_reporting"| E1
    D4 -.->|"error_reporting"| E1
    B3 -.->|"log"| E2
    B3 -.->|"config"| E3

    %% Click Events
    click A1 "https://github.com/pasqal-io/qadence/tree/main/qadence/blocks/"
    click A2 "https://github.com/pasqal-io/qadence/tree/main/qadence/constructors/"
    click B1 "https://github.com/pasqal-io/qadence/blob/main/qadence/circuit.py"
    click B2 "https://github.com/pasqal-io/qadence/tree/main/qadence/transpile/"
    click B3 "https://github.com/pasqal-io/qadence/blob/main/qadence/execution.py"
    click C1 "https://github.com/pasqal-io/qadence/tree/main/qadence/backends/"
    click C2 "https://github.com/pasqal-io/qadence/tree/main/qadence/ml_tools/"
    click D1 "https://github.com/pasqal-io/qadence/tree/main/qadence/measurements/"
    click D2 "https://github.com/pasqal-io/qadence/tree/main/qadence/noise/"
    click D3 "https://github.com/pasqal-io/qadence/tree/main/qadence/mitigations/"
    click D4 "https://github.com/pasqal-io/qadence/tree/main/qadence/draw/"
    click E1 "https://github.com/pasqal-io/qadence/tree/main/qadence/exceptions/"
    click E2 "https://github.com/pasqal-io/qadence/blob/main/qadence/logger.py"
    click E3 "https://github.com/pasqal-io/qadence/blob/main/qadence/log_config.yaml"

    %% Styles
    classDef composition fill:#E0F7FA,stroke:#00796B,stroke-width:2px;
    classDef circuit fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef backend fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;
    classDef ml fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef evaluation fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef visualization fill:#C5CAE9,stroke:#303F9F,stroke-width:2px;
    classDef utils fill:#CFD8DC,stroke:#607D8B,stroke-width:2px;
```
