# danielleodigie/red-queen architecture

> Architecture diagram of the GitHub repository danielleodigie/red-queen, 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/danielleodigie/red-queen
- Repository: https://github.com/danielleodigie/red-queen

## Overview

##### Main Components
- Benchmark Runner & Integration Layer – Note that pytest forms the core test runner. This layer includes:
– The pytest entry point along with configuration files (pyproject.toml, pytest.ini, conftest.py).
– Integration with pytest plugins (pytest-xdist and pytest-benchmark) as inspirations.
- Benchmark Definitions – These are the “bench_*” functions mostly located in red_queen/games/mapping/map_queko.py along with similar modules in red_queen/games/applications.
- Quantum Assembly Data and Benchmarks – The repository contains hundreds of .qasm files within structured subdirectories (e.g., red_queen/games/applications/qasm and red_queen/games/mapping/benchmarks) that represent the input circuits for the benchmarking algorithms.
- Core Framework Modules – In the red_queen directory you see modules like bishop.py, knight.py, pawn.py, queen.py, and rook.py. These encapsulate core functionality and abstract pieces of the quantum compilation process.
- Reporting & Result Storage – A separate “report” module (with console_tables and loader) handles processing of benchmark results stored as JSON (invoked via the “--store” option). This component takes the stored results, formats the data, and displays tabular results in a console application.
- Utility and Test Support – Files like fixtures.py, test configurations (pytest.ini, tox.ini) and continuous integration workflows (under .github) support quality checks and automated testing.

##### Relationships and Data Flow
- From pytest, the execution flows into the Benchmark Definitions which call core modules (chess piece modules) and the mapping / application algorithms.
- In the course of execution, the framework processes quantum assembly (.qasm) files as input data for benchmarking.
- A “Results Handler” component then collects outcomes and, if “--store” is used, stores them as JSON in a designated results directory.
- Finally, a reporting tool (from the “report” module) reads these JSON result files and presents them in table format, returning the output to the user.

##### Architectural Patterns and Technologies
- Layering: Clear separation between the test/benchmark definitions, core compilation components, data (qasm benchmarks), and the presentation/reporting layer.
- Integration with external testing frameworks: Leveraging pytest and markers to filter tests.
- Extensibility: The folder structure under “games” (with subdivisions for mapping benchmarks and applications) indicates that additional benchmark types can be added easily.
- Use of configuration and CI/CD (via .github/workflows) to maintain quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Invoker (User/CI)"]:::invoker

    subgraph "Test & Integration Layer"
        PI["Pytest Integration"]:::integration
        CT["conftest.py"]:::integration
        PYT["pyproject.toml"]:::integration
        PINI["pytest.ini"]:::integration
    end

    subgraph "Benchmark Definitions"
        MB["Mapping: map_queko.py"]:::benchmark
        AB["Applications: run_bv.py & run_ft.py"]:::benchmark
    end

    subgraph "Quantum Assembly Data"
        QA1["Applications QASM (folder)"]:::qasm
        QA2["Mapping Benchmarks QASM (folder)"]:::qasm
    end

    subgraph "Core Quantum Compilation Modules"
        BH["bishop.py"]:::core
        KN["knight.py"]:::core
        PN["pawn.py"]:::core
        QN["queen.py"]:::core
        RK["rook.py"]:::core
    end

    subgraph "Result Handling"
        JS["JSON Store"]:::report
        RT["Reporting Module (console_tables & loader)"]:::report
    end

    subgraph "Utility & Test Support"
        FIX["fixtures.py"]:::utility
        TOX["tox.ini"]:::utility
        CI["CI Workflows (.github)"]:::utility
    end

    %% Flow connections
    A -->|"runs"| PI

    %% Integration layer components (files are part of the integration)
    PI --> CT
    PI --> PYT
    PI --> PINI

    %% Utility supports integration
    FIX -->|"supports"| PI
    TOX -->|"supports"| PI
    CI -->|"supports"| PI

    %% Pytest discovers benchmark definitions
    PI -->|"discovers"| MB
    PI -->|"discovers"| AB

    %% Benchmark Definitions use Quantum Assembly Data as input
    QA2 -- "input_circuits" --> MB
    QA1 -- "input_circuits" --> AB

    %% Benchmark Definitions invoke Core Modules
    MB -->|"invokes"| BH
    MB -->|"invokes"| KN
    MB -->|"invokes"| PN
    MB -->|"invokes"| QN
    MB -->|"invokes"| RK

    AB -->|"invokes"| BH
    AB -->|"invokes"| KN
    AB -->|"invokes"| PN
    AB -->|"invokes"| QN
    AB -->|"invokes"| RK

    %% Benchmark Definitions store results
    MB -->|"stores_results"| JS
    AB -->|"stores_results"| JS

    %% Reporting reads stored JSON and displays results back to user
    JS -->|"reads_results"| RT
    RT -->|"outputs"| A

    %% Click Events for Test & Integration Layer
    click CT "https://github.com/danielleodigie/red-queen/blob/main/conftest.py"
    click PYT "https://github.com/danielleodigie/red-queen/blob/main/pyproject.toml"
    click PINI "https://github.com/danielleodigie/red-queen/blob/main/pytest.ini"

    %% Click Events for Benchmark Definitions
    click MB "https://github.com/danielleodigie/red-queen/blob/main/red_queen/games/mapping/map_queko.py"
    click AB "https://github.com/danielleodigie/red-queen/blob/main/red_queen/games/applications/run_bv.py"

    %% Click Events for Quantum Assembly Data
    click QA1 "https://github.com/danielleodigie/red-queen/tree/main/red_queen/games/applications/qasm"
    click QA2 "https://github.com/danielleodigie/red-queen/tree/main/red_queen/games/mapping/benchmarks"

    %% Click Events for Core Quantum Compilation Modules
    click BH "https://github.com/danielleodigie/red-queen/blob/main/red_queen/bishop.py"
    click KN "https://github.com/danielleodigie/red-queen/blob/main/red_queen/knight.py"
    click PN "https://github.com/danielleodigie/red-queen/blob/main/red_queen/pawn.py"
    click QN "https://github.com/danielleodigie/red-queen/blob/main/red_queen/queen.py"
    click RK "https://github.com/danielleodigie/red-queen/blob/main/red_queen/rook.py"

    %% Click Events for Reporting & Result Storage
    click RT "https://github.com/danielleodigie/red-queen/blob/main/report/console_tables.py"

    %% Click Events for Utility & Test Support
    click FIX "https://github.com/danielleodigie/red-queen/blob/main/red_queen/fixtures.py"
    click TOX "https://github.com/danielleodigie/red-queen/blob/main/tox.ini"
    click CI "https://github.com/danielleodigie/red-queen/blob/main/.github/workflows/main.yml"

    %% Classes for styling
    classDef invoker fill:#ffcc80,stroke:#000,stroke-width:2px;
    classDef integration fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef benchmark fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef qasm fill:#ffffe0,stroke:#000,stroke-width:2px;
    classDef core fill:#f08080,stroke:#000,stroke-width:2px;
    classDef report fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef utility fill:#dda0dd,stroke:#000,stroke-width:2px;
```
