# aqasch/gadget_rl architecture

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

- Interactive diagram: https://gitdiagram.com/aqasch/gadget_rl
- Repository: https://github.com/aqasch/gadget_rl

## Overview

##### Project type and purpose
- This is a research-oriented Python project that implements two tightly coupled pipelines:
a. A “Gadget Discovery” pipeline (`discover_gadgets/`) that uses program synthesis (DreamCoder) and decomposition scripts to extract reusable quantum‐circuit gadgets.
b. A “Gadget-Enhanced Reinforcement Learning” pipeline (`gadget_RL/`) that trains classical RL agents (CRL) on raw gate sets and then gadget-augmented RL agents (GRL) on harder quantum control tasks (Transverse Field Ising Model).

##### File structure
Top-level:
- `discover_gadgets/` – dreamcoder core, decomposition drivers, analytic scripts, example circuits
- `gadget_RL/` – subfolders `agents/`, `environments/`, `configuration_files/`, `ham_data/`, `utils/` plus entrypoints (`main.py`, `main_synthesized_*.py`)
- `requirements.txt`, `README.md`

Patterns & choices:
- Modular separation of “discovery” vs. “training”
- Config-driven design (all experiment parameters live in `configuration_files`)
- Agent–Environment RL loop (similar to Gym)
- Data‐artifact directories: `ham_data/` (quantum Hamiltonians), `results/` (pickled summaries)

##### README for additional insights
- Describes workflows for CRL vs. GRL, how to run discovery (`run_decomposition.py`) and how to launch training with/without gadgets.
- Defines key configuration parameters (qubit count, layers, decompose flag) and data outputs (`summary_*.pickle`).

##### Capturing essential details
- Break each sub-component into its folder or file group (e.g., list `agents/`, `environments/`).
- That the same environment codebase is reused for CRL and GRL, differing only in the action set (native gates vs. gadgets).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Gadget Discovery Module
    subgraph "Gadget Discovery Module"
        EC["Example Circuits Loader"]:::compute
        DC["DreamCoder Engine"]:::compute
        DS["Decomposition Scripts"]:::control
        GL["Gadget Library Output"]:::data
    end

    EC -->|"circuits"| DC
    DC -->|"synthesis"| DS
    DS -->|"extracted gadgets"| GL

    %% RL Training Module
    subgraph "RL Training Module"
        CL["Config Loader"]:::compute
        TO["Training Orchestrator"]:::control
        AG["RL Agents"]:::compute
        EV["Quantum Environments"]:::compute
        HD["Hamiltonian Data Store"]:::data
        RLRes["Results Logger"]:::data
    end

    GL -->|"gadget library"| CL
    CL -->|"parameters"| TO
    TO -.->|"control"| AG
    TO -.->|"control"| EV
    AG <-->|"action/reward loop"| EV
    EV -->|"loads ham data"| HD
    TO -->|"logs results"| RLRes

    %% Common / External Dependencies
    subgraph "Common/External"
        REQ["requirements.txt"]:::external
        RD["README.md"]:::external
    end

    REQ -.-> EC
    REQ -.-> CL
    RD -.-> EC
    RD -.-> CL

    %% Click Events
    click DC "https://github.com/aqasch/gadget_rl/tree/main/discover_gadgets/dreamcoder/"
    click DS "https://github.com/aqasch/gadget_rl/blob/main/discover_gadgets/run_decomposition.py"
    click DS "https://github.com/aqasch/gadget_rl/blob/main/discover_gadgets/analysing_program_synthesis.py"
    click EC "https://github.com/aqasch/gadget_rl/tree/main/discover_gadgets/example_circuits_to_synthesize/"
    click CL "https://github.com/aqasch/gadget_rl/tree/main/gadget_RL/configuration_files/"
    click AG "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/agents/DeepQ.py"
    click AG "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/agents/DeepQNstep.py"
    click AG "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/agents/DeepQ_PER.py"
    click AG "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/agents/DeepQ_nd_synthesized_1.py"
    click AG "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/agents/DeepQ_synthesized.py"
    click AG "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/agents/DeepQ_synthesized_2.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/environment.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/environment_nd_synthesized_1.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/environment_nd_synthesized_2.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/environment_synthesized_1.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/environment_synthesized_1_gadget_noise.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/environment_synthesized_2.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/VQEs/VQE.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/VQEs/VQE_nd_synthesized_1.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/VQEs/VQE_synthesized_1.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/VQEs/VQE_synthesized_1_gadget_noise.py"
    click EV "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/environments/VQEs/VQE_synthesized_2.py"
    click HD "https://github.com/aqasch/gadget_rl/tree/main/gadget_RL/ham_data/"
    click TO "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/main.py"
    click TO "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/main_nd_synthesized_1.py"
    click TO "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/main_synthesized_1.py"
    click TO "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/main_synthesized_1_gadget_noise.py"
    click TO "https://github.com/aqasch/gadget_rl/blob/main/gadget_RL/main_synthesized_2.py"
    click REQ "https://github.com/aqasch/gadget_rl/blob/main/requirements.txt"
    click RD "https://github.com/aqasch/gadget_rl/blob/main/README.md"

    %% Styles
    classDef compute fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef data fill:#caffbf,stroke:#333,stroke-width:1px
    classDef control fill:#ffadad,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
