# projectq-framework/projectq architecture

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

- Interactive diagram: https://gitdiagram.com/projectq-framework/projectq
- Repository: https://github.com/projectq-framework/projectq

## Overview

##### Main Layers and Components
- Quantum Operations & Libraries: Show a layer representing the operations (gates, commands) and supporting libraries (found in projectq/ops and projectq/libs/ and projectq/meta). This layer underpins how quantum instructions are represented, manipulated, and possibly visualized (as in circuit drawing modules under projectq/backends/_circuits).
- Backends Layer: Create a clear section that shows the multiple backend components residing under projectq/backends (e.g., _sim for simulation, _ibm for IBM Quantum Experience, _aqt, _awsbraket, _azure, _ionq). Each backend often has an associated client (sometimes HTTP-based) for communicating with the corresponding hardware or simulator.

##### Relationships and Data Flow
- That the compiler engines transform the quantum circuit step by step, eventually passing a fully optimized and decomposed series of instructions to a chosen backend.
- That backends not only simulate (via classical simulation modules) but also interface with external quantum hardware (using HTTP client connectors and setup-dependent transformations).
- Optionally, display interactions with the “resource counter” backend or export channels (for drawing circuits with TikZ, as indicated in the documentation).

##### Architectural Patterns and Design Principles
- Modular design: each compiler engine in the pipeline is self-contained and replaceable.
- Separation of concerns: high-level operations (in “ops”), transformation logic (in “cengines”), hardware abstraction (in “backends”), and hardware-specific configuration (in “setups”) are clearly segregated.
- That the backend abstraction enables switching between simulation, emulation, and real hardware execution through the same high-level API.

##### Specific Technologies and Components
- Optionally, mention support for visualizing circuits (with modules like _drawer in projectq/backends/_circuits) and for exporting to LaTeX.

- Don’t hesitate to break down the compiler pipeline into more discrete steps if needed, such as “Optimization & Mapping”, “Command Modification”, and “Decomposition” steps.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        user1["Quantum Application (Examples)"]:::quantum
    end

    subgraph "Core Layer"
        mainEng["MainEngine (Compiler Engine Core)"]:::core
    end

    subgraph "Infrastructure"
        subgraph "Compiler Pipeline (Cengines)"
            comp1["Basic Mapper"]:::pipeline
            comp2["Linear Mapper"]:::pipeline
            comp3["Optimizer"]:::pipeline
            comp4["Cmd Modifier"]:::pipeline
            comp5["Manual Mapper"]:::pipeline
            comp6["Replacer"]:::pipeline
        end

        subgraph "Quantum Operations & Libraries"
            ops1["Operations (Ops)"]:::ops
            ops2["Supporting Libraries"]:::ops
        end

        setup["Setup & Configuration"]:::setup

        subgraph "Backends Layer"
            be1["Simulator (_sim)"]:::backend
            be2["IBM Backend"]:::backend
            be3["AQT Backend"]:::backend
            be4["AWS Braket Backend"]:::backend
            be5["Azure Backend"]:::backend
            be6["IonQ Backend"]:::backend
            be7["Circuit Visualization"]:::backend
        end
    end

    %% Data Flow
    user1 -->|"QuantumCode"| mainEng
    mainEng -->|"CollectsCommands"| comp1
    comp1 -->|"PassesInstruction"| comp2
    comp2 -->|"PassesInstruction"| comp3
    comp3 -->|"PassesInstruction"| comp4
    comp4 -->|"PassesInstruction"| comp5
    comp5 -->|"PassesInstruction"| comp6
    comp6 -->|"OptimizedInstructions"| be1
    comp6 -->|"OptimizedInstructions"| be2
    comp6 -->|"OptimizedInstructions"| be3
    comp6 -->|"OptimizedInstructions"| be4
    comp6 -->|"OptimizedInstructions"| be5
    comp6 -->|"OptimizedInstructions"| be6
    comp6 -->|"OptimizedInstructions"| be7

    ops1 -->|"ProvidesOps"| comp3
    ops2 -->|"ProvidesLibs"| comp3
    setup -->|"ConfiguresPipeline"| comp1

    %% Click Events
    click user1 "https://github.com/projectq-framework/projectq/blob/develop/examples/bellpair_circuit.py"
    click mainEng "https://github.com/projectq-framework/projectq/blob/develop/projectq/cengines/_main.py"
    click comp1 "https://github.com/projectq-framework/projectq/blob/develop/projectq/cengines/_basicmapper.py"
    click comp2 "https://github.com/projectq-framework/projectq/blob/develop/projectq/cengines/_linearmapper.py"
    click comp3 "https://github.com/projectq-framework/projectq/blob/develop/projectq/cengines/_optimize.py"
    click comp4 "https://github.com/projectq-framework/projectq/blob/develop/projectq/cengines/_cmdmodifier.py"
    click comp5 "https://github.com/projectq-framework/projectq/blob/develop/projectq/cengines/_manualmapper.py"
    click comp6 "https://github.com/projectq-framework/projectq/tree/develop/projectq/cengines/_replacer"
    click ops1 "https://github.com/projectq-framework/projectq/blob/develop/projectq/ops/_gates.py"
    click ops2 "https://github.com/projectq-framework/projectq/tree/develop/projectq/libs/"
    click be1 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_sim"
    click be2 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_ibm"
    click be3 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_aqt"
    click be4 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_awsbraket"
    click be5 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_azure"
    click be6 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_ionq"
    click be7 "https://github.com/projectq-framework/projectq/tree/develop/projectq/backends/_circuits"
    click setup "https://github.com/projectq-framework/projectq/tree/develop/projectq/setups/"

    %% Styles
    classDef quantum fill:#f94144,stroke:#000,stroke-width:2px;
    classDef core fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef pipeline fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef ops fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef backend fill:#577590,stroke:#000,stroke-width:2px;
    classDef setup fill:#277da1,stroke:#000,stroke-width:2px;
```
