# qdevpsi3/quantum-arch-search architecture

> Architecture diagram of the GitHub repository qdevpsi3/quantum-arch-search, 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/qdevpsi3/quantum-arch-search
- Repository: https://github.com/qdevpsi3/quantum-arch-search

## Overview

##### Project Type and Purpose
- The project is a specialized reinforcement learning environment for quantum circuit design. It uses custom Gym environments powered by Google’s Cirq to simulate quantum systems.
- Its main goal is to allow an RL agent (via tools such as Stable-Baselines3) to iteratively build quantum circuits that match a target quantum state, applying actions (gates) and receiving rewards based on fidelity.

##### File Structure
- Top-Level Files: Contains common configuration files like LICENSE, requirements.txt, setup.py, and README.md.
- Notebooks Directory: Holds sample experiments (experiment.ipynb) which serve as an interface for reproducing or testing experiments interactively.
- Render Directory: Contains assets (SVG images) for visually representing quantum gates and observables, which are used for environment rendering.
- src Directory: The heart of the project. Inside src, the qas_gym package contains:
- __init__.py: Initialization for package exposure.
- envs Directory: Contains specific environment definitions:
- basic_envs.py – standard environments (for 2-qubit, 3-qubit, or N-qubit tasks)
- noisy_envs.py – versions of the environments including added noise (introducing measurement and gate errors)
- qas_env.py – likely defines the core quantum architecture search environment abstraction.
- utils.py: Utility functions that support the quantum environments.

a. Main Components:
- Environment Layer:
- Core Environment (qas_env.py) that provides the basic Gym interface.
- Specialized environments (basic_envs.py and noisy_envs.py) which define specific setups (e.g., 2-qubit, 3-qubit circuits) and include parameter configurations such as target states, fidelity thresholds, and reward penalties.
- Rendering and Visualization:
- Uses assets from the render folder and in-environment commands in the Gym API to visually display the quantum circuit actions.
- Experimentation and Evaluation:
- Notebooks provide an interactive layer to train and evaluate RL agents.
- External integration with Stable-Baselines3 for deep reinforcement learning experiments.
- External Dependencies:
- Integration with Google’s Cirq for quantum circuit simulation.
- Usage of Gym and standard deep RL libraries.

b. Relationships and Interactions:
- The RL agent interacts with the Environment (Gym interface) by taking actions (representing quantum gates).
- The Environment (via qas_env and its derivatives) performs state updates based on actions and computes rewards (fidelity calculation, penalties, etc.).
- Utility functions support these computations and operations.
- Rendering components tie back to these environments by using the SVG assets to show gates and observables, supporting both local and interactive (notebook) displays.
- The notebook experiments act as a client that invokes the environments and potentially displays rendered output, creating a feedback loop with the agent.

c. Architectural Patterns/Design Principles:
- Modular design: Clear separation between generic environment functionality (qas_env.py) and specialized implementations (basic_envs.py/noisy_envs.py).
- Use of industry-standard interfaces (OpenAI Gym API) for interoperability with other RL agents and tools.
- Externalization of configuration: Parameters for target states, fidelity thresholds, and error rates are cleanly parameterized for flexibility.
- Visualization and logging are provided externally via notebooks and inline rendering, keeping the core logic isolated and testable.

d. Key Technologies and Libraries:
- Python with packages such as Gym, Cirq (for quantum simulation), and Stable-Baselines3 (for RL training).
- Tools for experiment reproducibility (Jupyter notebooks).
- SVG assets for rendering quantum gate actions and observables.

##### Elements
- Components:
- “Quantum Environment (qas_env)” block as the central component.
- “Basic Environments” and “Noisy Environments” as sub-components branching from the main environment.
- “Utility Functions” module supporting these operations.
- “Rendering Module” that utilizes assets from the render directory.
- “Experiment Notebooks” as an interactive layer.
- “External Libraries” block listing Gym, Cirq, and Stable-Baselines3.
- Interactions:
- Data flow from configuration files (requirements, setup, etc.) into the environment setup process.
- Visual Elements:
- Use clear labels for each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    A("RL Agent"):::agent
    B("Quantum Environment (qas_env)"):::env
    C("Basic Environments"):::envSpec
    D("Noisy Environments"):::envSpec
    E("Utility Functions"):::utils
    F("Rendering Module"):::rendering
    G("Experiment Notebooks"):::notebooks
    H("Requirements.txt"):::config
    I("Setup.py"):::config
    J("External Libraries"):::extLib

    %% Subgraphs
    subgraph "Custom Gym Environment Layer"
        B
        C
        D
        E
    end

    subgraph "Visualization & Experimentation"
        F
        G
    end

    subgraph "Project Configuration"
        H
        I
    end

    %% Interactions
    A -->|"action"| B
    B -->|"extends"| C
    B -->|"extends"| D
    E -->|"supports"| B
    B -->|"renders"| F
    G -->|"triggers"| B
    B -->|"integrates"| J
    H -->|"configures"| B
    I -->|"configures"| B
    B -- "feedback" --> A

    %% Styles
    classDef agent fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef env fill:#d4efdf,stroke:#27ae60,stroke-width:2px;
    classDef envSpec fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef utils fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef rendering fill:#f5eef8,stroke:#9b59b6,stroke-width:2px;
    classDef notebooks fill:#fdebd0,stroke:#e67e22,stroke-width:2px;
    classDef config fill:#fbeee6,stroke:#e74c3c,stroke-width:2px;
    classDef extLib fill:#e8f8f5,stroke:#1abc9c,stroke-width:2px;

    %% Click Events
    click B "https://github.com/qdevpsi3/quantum-arch-search/blob/main/src/qas_gym/envs/qas_env.py"
    click C "https://github.com/qdevpsi3/quantum-arch-search/blob/main/src/qas_gym/envs/basic_envs.py"
    click D "https://github.com/qdevpsi3/quantum-arch-search/blob/main/src/qas_gym/envs/noisy_envs.py"
    click E "https://github.com/qdevpsi3/quantum-arch-search/blob/main/src/qas_gym/utils.py"
    click F "https://github.com/qdevpsi3/quantum-arch-search/tree/main/render"
    click G "https://github.com/qdevpsi3/quantum-arch-search/blob/main/notebooks/experiment.ipynb"
    click H "https://github.com/qdevpsi3/quantum-arch-search/blob/main/requirements.txt"
    click I "https://github.com/qdevpsi3/quantum-arch-search/blob/main/setup.py"
```
