# qiboteam/qibocal architecture

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

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

## Overview

##### Main Components
- CLI & Runcard Parser: Represented in the “src/qibocal/cli” directory that handles runcard inputs and triggers protocol execution.
- Protocol Execution Engine: The core logic that dispatches different quantum protocols. This can be shown as a centralized module that collects sub-components from “src/qibocal/auto”, “src/qibocal/protocols”, and “src/qibocal/fitting” (for analysis and data fitting).
- Reporting & Web Interface: Indicate the reporting module in “src/qibocal/web” and also note the additional “serverscripts/web” that help generate or upload reports to a centralized server.
- External Dependencies: Represent integrations with external projects such as Qibo and Qibolab. Also note that the project uses modern Python tooling (Poetry, pre-commit hooks) and a comprehensive testing suite (“tests”).

##### Relationships and Flows
- The Engine then selects and invokes the appropriate quantum protocol module (from “src/qibocal/protocols”), uses calibration settings (from “src/qibocal/calibration” and platforms configurations under “platforms”), and leverages fitting routines (in “src/qibocal/fitting”) for processing experimental data.

##### Architectural Patterns and Design Principles
- Modules are clearly separated by responsibility (CLI, execution engine, calibration, protocols, reporting). This suggests a layered or modular design, similar to an MVC-type separation (input, processing, output).
- The system uses declarative runcard files, promoting a configuration-driven approach.
- Extensibility: new protocols can be added in the “src/qibocal/protocols” folder and integrated into the execution pipeline.
- The design supports both local execution (by generating a date-stamped directory) and remote reporting (upload feature).

##### Technologies and Tools
- Python as the core language, with Poetry for dependency management and pre-commit for code quality.
- Use of GitHub workflows and tools like Codecov for CI/CD, as seen from the “.github” folder.
- Integration of Qibo and Qibolab as key libraries for execution of quantum experiments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User"):::external

    subgraph "CLI Layer"
        CLI("CLI & Runcard Parser"):::cli
        RC("Runcard Parser"):::cli
        CLI -->|"parses"| RC
    end

    A -->|"initiates"| CLI

    subgraph "Protocol Execution Engine"
        P1("Auto Module"):::engine
        P2("Protocols Module"):::engine
        P3("Fitting Module"):::engine
        P1 -->|"dispatches"| P2
        P2 -->|"analyzes"| P3
    end

    RC -->|"triggers"| P1

    subgraph "Calibration & Platform"
        CAL("Calibration Module"):::calibration
        CS("Calibration Scripts"):::calibration
        PL("Platform Interface"):::platform
        CAL -->|"includes"| CS
    end

    P2 -->|"uses_calibration"| CAL
    P2 -->|"accesses"| PL

    subgraph "Reporting & Upload"
        RPT("Reporting Module"):::reporting
        SU("Server Upload"):::reporting
        RPT -->|"uploads_to"| SU
    end

    P3 -->|"generates_report"| RPT

    TS("Testing Suite"):::testing
    CI("CI/CD"):::testing
    TS -->|"executes_tests"| CI
    TS -->|"validates"| P2

    Qibo("Qibo Library"):::external
    Qibolab("Qibolab Library"):::external
    P1 -->|"integrates"| Qibo
    P1 -->|"integrates"| Qibolab

    %% Click Events
    click CLI "https://github.com/qiboteam/qibocal/tree/main/src/qibocal/cli"
    click RC "https://github.com/qiboteam/qibocal/blob/main/src/qibocal/auto/runcard.py"
    click P1 "https://github.com/qiboteam/qibocal/tree/main/src/qibocal/auto"
    click P2 "https://github.com/qiboteam/qibocal/tree/main/src/qibocal/protocols"
    click P3 "https://github.com/qiboteam/qibocal/tree/main/src/qibocal/fitting"
    click CAL "https://github.com/qiboteam/qibocal/tree/main/src/qibocal/calibration"
    click CS "https://github.com/qiboteam/qibocal/tree/main/calibration_scripts"
    click PL "https://github.com/qiboteam/qibocal/tree/main/platforms"
    click RPT "https://github.com/qiboteam/qibocal/tree/main/src/qibocal/web"
    click SU "https://github.com/qiboteam/qibocal/tree/main/serverscripts/web"
    click TS "https://github.com/qiboteam/qibocal/tree/main/tests"
    click CI "https://github.com/qiboteam/qibocal/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef engine fill:#87cefa,stroke:#000,stroke-width:2px;
    classDef calibration fill:#ffebcd,stroke:#000,stroke-width:2px;
    classDef platform fill:#d3ffd3,stroke:#000,stroke-width:2px;
    classDef reporting fill:#ffd700,stroke:#000,stroke-width:2px;
    classDef testing fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef external fill:#90ee90,stroke:#000,stroke-width:2px;
```
