# qilimanjaro-tech/circopt-rl-zxcalc architecture

> Architecture diagram of the GitHub repository qilimanjaro-tech/circopt-rl-zxcalc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qilimanjaro-tech/circopt-rl-zxcalc
- Repository: https://github.com/qilimanjaro-tech/circopt-rl-zxcalc

## Overview

##### Project type and purpose
- This is a research‐grade, full‐stack Python tool for “Reinforcement Learning Based Quantum Circuit Optimization via ZX‐Calculus.”
- It provides:
- A custom OpenAI‐Gym environment for ZX‐calculus circuit transformations
- An RL agent that learns optimization policies
- Experiment scripts that run the agent on benchmark circuits and produce JSON results
- Jupyter notebooks to generate figures and tables for the paper

##### File structure
- Top‐level files:
- README.md, requirements.txt, installation.py
- rl_agent.py: the core agent architecture
- agent_test.py & benchmark.py: entry points that run experiments and gather stats
- Jupyter notebooks (benchmark.ipynb, results.ipynb) for data processing and visualization
- “rl-zx/gym-zx” is a pip‐installable Python package defining the Gym environment:
- gym_zx/envs/zx_env.py implements the ZX‐calculus environment
- setup.py makes it installable as `gym-zx`
- “rl-zx/results” stores:
- Raw circuits (Original, gflow-cflow-opt, NRSCM, rl-zx-opt) in subfolders
- JSON statistics under results/data (random_stats, rl_stats)
- Figures and time‐depth JSON within results/5x60_non_clifford

##### README for additional insights
- The README explicitly points to:
- Agent code in rl_agent.py
- Environment in gym_zx/envs/zx_env.py
- Scripts that generate data for figures (agent_test.py, benchmark.py, results.ipynb)
- It describes four optimization backends:
Original, Staudacher+Holker (gflow-cflow-opt), Nam et al. (NRSCM), and the new RL agent (rl-zx-opt).

##### Detail
- Four optimization backends as distinct flows
- How `installation.py` and `setup.py` fit into packaging/install
- Which modules import from which (e.g., agent_test.py imports rl_agent and gym_zx)
- Agent–environment interface via standard Gym methods (reset(), step(), render())

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Setup & Packaging
    subgraph "Setup & Packaging"
        README["README.md"]:::code
        REQ["requirements.txt"]:::code
        INSTALL["installation.py"]:::code
        SETUP["setup.py"]:::code
    end

    %% Experiment Layer
    subgraph "Experiment Layer"
        USER["Researcher (CLI/Notebook)"]:::code
        EX_TEST["agent_test.py"]:::code
        EX_BENCH_SCRIPT["benchmark.py"]:::code
        subgraph "Notebooks"
            NB_BENCH["benchmark.ipynb"]:::code
            NB_RESULTS["results.ipynb"]:::code
        end
    end

    %% RL Layer
    subgraph "RL Layer"
        AGENT["rl_agent.py"]:::code
        ENV["gym_zx/envs/zx_env.py"]:::code
        PYZX["PyZX Library"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        CIRCUITS["Circuit Data Store"]:::data
        JSON_STATS["JSON Statistics Store"]:::data
        FIGURES["Figures & Tables"]:::data
    end

    %% Interactions
    USER -->|runs| EX_TEST
    USER -->|views| NB_BENCH
    USER -->|views| NB_RESULTS

    EX_TEST -->|imports| AGENT
    EX_TEST -->|imports| ENV
    EX_TEST -->|writes metrics| JSON_STATS

    EX_BENCH_SCRIPT -->|imports| AGENT
    EX_BENCH_SCRIPT -->|imports| ENV
    EX_BENCH_SCRIPT -->|writes metrics| JSON_STATS

    AGENT -->|"calls step(), reset()"| ENV
    ENV -->|"uses ZX rewrites"| PYZX
    ENV -->|outputs optimized circuits| CIRCUITS

    NB_BENCH -->|reads| JSON_STATS
    NB_BENCH -->|reads| CIRCUITS
    NB_BENCH -->|generates| FIGURES

    NB_RESULTS -->|reads| JSON_STATS
    NB_RESULTS -->|reads| CIRCUITS
    NB_RESULTS -->|generates| FIGURES

    %% Click Events
    click README "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/README.md"
    click REQ "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/requirements.txt"
    click INSTALL "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/installation.py"
    click SETUP "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/rl-zx/gym-zx/setup.py"
    click AGENT "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/rl_agent.py"
    click EX_TEST "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/rl-zx/agent_test.py"
    click NB_BENCH "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/rl-zx/benchmark.ipynb"
    click NB_RESULTS "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/rl-zx/results.ipynb"
    click ENV "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/blob/main/rl-zx/gym-zx/gym_zx/envs/zx_env.py"
    click CIRCUITS "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/tree/main/rl-zx/results/circuits"
    click JSON_STATS "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/tree/main/rl-zx/results/data/random_stats"
    click JSON_STATS "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/tree/main/rl-zx/results/data/rl_stats"
    click FIGURES "https://github.com/qilimanjaro-tech/circopt-rl-zxcalc/tree/main/rl-zx/results/5x60_non_clifford/figures"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px;
```
