# woongineer/qcds architecture

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

- Interactive diagram: https://gitdiagram.com/woongineer/qcds
- Repository: https://github.com/woongineer/qcds

## Overview

##### Project Type and Purpose
- This project implements a reinforcement learning (RL) search strategy to design parameterized quantum circuits (PQC).
- It supports both a classical controller (neural network-based) and an optional hybrid quantum-classical controller.
- It is an experimental / research codebase centered on quantum circuit search strategies, with special support for testing on datasets (e.g., the Glass dataset).

##### Main Components
a. Entry Points and Controllers:
- main.py – The main entry point for starting experiments with default or custom parameters. It instantiates the controller that performs the search.
- runner.py (mentioned in the README) – A module for running tests on fixed or benchmark designs using pre-saved quantum weights.
b. Neural Network Components:
- ControllerNetwork.py – Implements the classical RL controller responsible for the search process.
- QuantumNetwork.py – Implements the potential quantum or hybrid controller for designing parts of the PQC.
c. Data and Schemes:
- data.py – Responsible for handling data, likely including preprocessing and interfacing with the Glass dataset.
- schemes.py – Defines the quantum circuit schemes or possibly the templates for circuit designs.
d. Saved Designs and Weights:
- The designs/ directory – Contains subdirectories with benchmark designs ("BenchMarkDesigns", "SelectedDesigns", "Top1000DesignsRandomSearch") that represent various candidate circuit structures.
- quantumWeights/ – Stores pre-trained or default weights for various designs (differentiated by numeric folders and special ones like "CNOT").
f. External Dependencies/Technologies:
- PyTorch (for neural network operations)
- PennyLane (for quantum operations simulation)
- The README clearly specifies these versions as requirements.

##### Relationships and Data Flow
- The execution starts with main.py, which reads command-line arguments to determine whether to run the full circuit design search, a small (layer-specific) design, or a hybrid mode.
- main.py initializes the ControllerNetwork (and possibly QuantumNetwork if the hybrid mode is enabled).
- The controller module interacts with the data handling routines (in data.py) and scheme definitions (from schemes.py) to generate a PQC.
- Depending on the operation mode:
- When training from scratch, the system loops through the RL process to update the network weights.
- When using a pre-trained design, runner.py loads the appropriate weights from quantumWeights/.
- The designs folder provides different circuit templates that might be selected either manually (via design_identifier flag) or produced by the RL search.
- There is a clear flow of inputs (data from dataset, design parameters from command-line arguments) through the controller to generating a quantum circuit design, which then loops back to testing performance on the Glass dataset.

##### Architectural Patterns and Design Principles
- Modularity – Each component is separated into distinct files (controllers, network models, data, schemes, and design storage).
- Configurability – Command-line arguments determine what controller is used and whether the training is initialized from scratch or loads pre-saved weights.
- Extensibility – The structured designs and weight directories allow for extension, supporting new quantum circuit designs or experiments.
- Separation of Concerns – There is a clear division between learning (RL via ControllerNetwork and QuantumNetwork), data management (data.py), circuit scheme definition (schemes.py), and experiment orchestration (main.py and runner.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Execution Layer
    subgraph "Execution Layer"
        M("main.py"):::execution
        R("runner.py"):::execution
    end

    %% Controller Layer
    subgraph "Controller Layer"
        CN("ControllerNetwork.py"):::neural
        QN("QuantumNetwork.py"):::neural
    end

    %% Data & Schemes
    subgraph "Data & Schemes"
        D("data.py"):::data
        S("schemes.py"):::scheme
    end

    %% Design Repositories
    subgraph "Design Repositories"
        DS("designs/"):::repo
        QW("quantumWeights/"):::repo
    end

    %% Supporting Diagrams
    subgraph "Supporting Diagrams"
        DI("diagrams/"):::diagram
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PT("PyTorch"):::external
        PL("PennyLane"):::external
    end

    %% Connections
    M -->|"initializes"| CN
    M -->|"optionally initializes"| QN
    M -->|"processes"| D
    M -->|"defines"| S
    CN -->|"generates design"| DS
    QN -->|"generates design"| DS
    R -->|"loads design"| DS
    R -->|"loads weights"| QW
    D -->|"supplies data to"| CN
    S -->|"guides"| CN
    CN -->|"trained by"| PT
    QN -->|"uses"| PL
    DI -->|"provides visual guides to"| M

    %% Click Events
    click M "https://github.com/woongineer/qcds/blob/main/main.py"
    click CN "https://github.com/woongineer/qcds/blob/main/ControllerNetwork.py"
    click QN "https://github.com/woongineer/qcds/blob/main/QuantumNetwork.py"
    click D "https://github.com/woongineer/qcds/blob/main/data.py"
    click S "https://github.com/woongineer/qcds/blob/main/schemes.py"
    click DS "https://github.com/woongineer/qcds/tree/main/designs/"
    click QW "https://github.com/woongineer/qcds/tree/main/quantumWeights/"
    click DI "https://github.com/woongineer/qcds/tree/main/diagrams/"

    %% Styles
    classDef execution fill:#ffefc5,stroke:#333,stroke-width:2px;
    classDef neural fill:#c1f2c1,stroke:#333,stroke-width:2px;
    classDef data fill:#f2f2c1,stroke:#333,stroke-width:2px;
    classDef scheme fill:#c1dff2,stroke:#333,stroke-width:2px;
    classDef repo fill:#f2d1d1,stroke:#333,stroke-width:2px;
    classDef diagram fill:#d1f2f8,stroke:#333,stroke-width:2px;
    classDef external fill:#f8d1f2,stroke:#333,stroke-width:2px;
```
