# munich-quantum-software-stack/qdmi architecture

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

- Interactive diagram: https://gitdiagram.com/munich-quantum-software-stack/qdmi
- Repository: https://github.com/munich-quantum-software-stack/qdmi

## Overview

##### Project Overview and Type
- QDMI is a C-based library that provides a standardized interface for communicating with quantum hardware.
- It is one of the core components of the Munich Quantum Software Stack (MQSS), designed to allow seamless integration between software tools and quantum devices.
- The project is not a full-stack application but a hardware interface library accompanied by examples, tests, and extensive documentation.

##### Analyzing the File Structure
- Core API – The “include/qdmi” directory contains the main C header files (client.h, device.h, constants.h, types.h) that define the interface.
- Build System – Files like “CMakeLists.txt” at the top level and the “cmake” directory indicate that CMake is used to manage builds, external dependencies, and compiler configurations.
- Examples – The “examples” folder is subdivided into various implementation scenarios like ‘device’, ‘driver’, ‘fomac’, and ‘tool’. These serve as real-world usage demos of the QDMI API.
- Templates – The “templates” directory provides scaffolding (including device-specific CMake setups and source files) for developing new devices or integrations.
- Testing – The “test” directory, together with “test/utils”, hosts unit tests and integration testing code to ensure the API functions as expected.
- Documentation – The “docs” folder contains Markdown and Doxygen configuration files, CSS, and supporting assets for generating project documentation.
- CI/CD – The presence of GitHub Actions workflows under “.github/workflows” shows automated testing, documentation, and release management processes.

##### Main Components
- QDMI Core Library:
– Represent the core C header files (API) in a clearly marked block.
- Build & Configuration:
– A block representing the CMake build system (CMakeLists.txt, cmake/ modules) used to compile the core library, examples, tests, and templates.
- Examples & Integration:
– Separate blocks for different example scenarios (device, driver, etc.) to illustrate how the QDMI core is used.
- Testing Framework:
– A block for the unit/integration tests that ensures the interface meets performance and reliability requirements.
- Documentation:
– A module that covers the auto-generated documentation (via Doxygen and Markdown files).
- CI/CD Pipeline:
– A component outlining how GitHub workflows (CI, test automation, release drafts) integrate and support the development process.
- Templates:
– A module for developer templates that assists in creating new device instances or integrating QDMI into other systems.
- External Interactions:
– Optionally, add a block for the MQSS ecosystem to show QDMI’s role in the overall quantum software stack, emphasizing its integration into HPC environments and as an interface for various quantum platforms.

##### Relationships and Data Flow
- The QDMI Core Library is central and provides the API that several other components interact with.
- The build system (CMake) is connected to every component since it manages compilation and dependency resolution.
- Documentation generation sources from the whole codebase (especially the core API and examples) and should have bi-directional relationships with both code and tests.
- CI/CD is linked to the build system, tests, and documentation components, automating their processes.

##### Important Architectural Patterns and Design Principles
- Modularity – The separation between the API, examples, tests, and documentation emphasizes a modular design.
- Layered Approach – Think of QDMI as having a “core” layer that provides low-level C interfaces and multiple “usage layers” (examples, integrations, tests).
- Separation of Concerns – The build system, testing framework, and documentation are distinct components that support and interact with the core libraries but remain decoupled.
- Continuous Integration/Delivery – GitHub workflows and CI pipelines ensure code quality and systematic deployment routines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs for grouping components
    subgraph "Infrastructure"
        CMS("CMake Build System"):::infra
        CID("CI/CD Pipeline"):::infra
        DOC("Documentation (Doxygen/Markdown)"):::infra
    end

    subgraph "Usage"
        EX("Examples & Integration"):::peripheral
        TMP("Templates"):::peripheral
        TEST("Testing Framework"):::peripheral
    end

    subgraph "Core Components"
        CORE("QDMI Core Library"):::core
    end

    subgraph "External"
        MQSS("MQSS Ecosystem"):::external
    end

    %% Connections from Infrastructure to Core and others
    CMS --> CORE
    CMS --> EX
    CMS --> TMP
    CMS --> TEST
    CMS --> DOC
    CMS --> CID

    %% Connections from Usage components to Core
    EX --> CORE
    TMP --> CORE
    TEST --> CORE

    %% Documentation bi-directional with Core and Testing
    DOC <--> CORE
    DOC <--> TEST

    %% CI/CD Pipeline links to Infrastructure and Testing
    CID --> CMS
    CID --> TEST
    CID --> DOC

    %% External integration from Core to MQSS Ecosystem
    CORE --> MQSS

    %% Styles for color coding
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef peripheral fill:#C1FFC1,stroke:#000,stroke-width:2px;
    classDef infra fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;

    %% Click Events (paths are for click events only)
    click CORE "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/include/qdmi"
    click CMS "https://github.com/munich-quantum-software-stack/qdmi/blob/develop/CMakeLists.txt"
    click CMS "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/cmake/"
    click EX "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/examples/"
    click TEST "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/test/"
    click DOC "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/docs/"
    click CID "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/.github/workflows/"
    click TMP "https://github.com/munich-quantum-software-stack/qdmi/tree/develop/templates/"
```
