# From Tool Invocation to Source-Mechanism Exploration: Protected White-Box DSE for Open-Source EDA This repository contains the artifact for *From Tool Invocation to Source-Mechanism Exploration: Protected White-Box DSE for Open-Source EDA* and the implementation of ReviewDSE, a protected white-box design-space exploration framework for OpenROAD detailed placement. It provides the source programs, experiment configurations, protected evaluator, and reproduction workflows for Tables 4--6 and Figures 4--5. The artifact uses a pinned open-source EDA toolchain and requires authenticated Codex access for the configured Teacher and Student agents. [Paper link](https://arxiv.org/abs/2607.11294) [Paper with Artifact Appendix](paper/artifact_evaluation.pdf) [Evaluated Zenodo snapshot](https://doi.org/10.5281/zenodo.21629308) https://github.com/user-attachments/assets/af3152b9-612f-42a6-b955-9ed0e0f041fa ## Code Structure ```text DPLEvolve-AE/ ├── artifacts/ │ ├── 01-table4-qor/ # Table 4: default, BO, ReviewDSE-HPWL/GHR │ │ ├── README.md # Experiment instructions │ │ ├── reproduce.sh # Complete Table 4 entry point │ │ ├── config/ # Baseline, BO, and search configurations │ │ ├── inputs/ # Retained experiment inputs │ │ ├── selected-programs/ # 18 HPWL/GHR source programs │ │ ├── expected/ # Numerical acceptance values │ │ └── output/ # Output contract │ ├── 02-table5-composability/ # Table 5: stage composability │ ├── 03-table6-cutrow/ # Table 6: hard cut-row legality │ ├── 04-figures/ # Figures 4 and 5 │ ├── 05-reviewdse-search/ # Level 1 and Teacher/Student search │ └── 06-ariane-diagnostic/ # Ariane source-mechanism diagnostic ├── scripts/ │ ├── human/ # Environment setup scripts │ ├── reproduce/ # Experiment runners and evaluators │ ├── agent/ # Fixed agent-facing execution scripts │ ├── shared/ # Shared runtime utilities │ └── maintenance/ # Release and provenance scripts ├── configs/reproduction/ # Paper experiment configurations ├── paper/artifact_evaluation.pdf # Paper PDF with the Artifact Appendix ├── paper-data/ # Downloaded Table 6 inputs ├── src/dpl_evolve_agent/ # ReviewDSE implementation ├── docs/ # Human-facing detailed documentation ├── agent/ # Agent-facing rules and task recipes ├── tests/toolchain/aes-smoke/ # Non-paper EDA toolchain test ├── web-demo/ # Browser interface to fixed commands ├── Makefile # Root command interface └── LICENSE ``` ## Dependencies - [Python](https://www.python.org/) 3.11 or newer - PyYAML 6.0.3 is installed automatically by the setup script. - [GCC/G++](https://gcc.gnu.org/) 9 or newer - [CMake](https://cmake.org/) 3.16 or newer - Bison, Flex, SWIG, Tcl/Tk, Boost, Eigen, spdlog, zlib, and libffi - These are standard OpenROAD build dependencies. - [OpenROAD-flow-scripts](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts) - [OpenROAD](https://github.com/The-OpenROAD-Project/OpenROAD) - [Yosys](https://github.com/YosysHQ/yosys) 0.64 - [yosys-slang](https://github.com/povik/yosys-slang) - The exact EDA source revisions are recorded in [`provenance/source-commits.json`](provenance/source-commits.json) and are prepared by `make bootstrap` and `make build-tools`. - [Ray Tune](https://docs.ray.io/en/latest/tune/) 2.31.0, [Optuna](https://optuna.org/) >= 3.6 and < 5.0, and [NumPy](https://numpy.org/) >= 1.26 and < 2.0 (Table 4 BO only) - Installed by `make setup-bo`. ## 1. Install the Environment Review the host and filesystem checklist in [docs/requirements.md](docs/requirements.md). ```bash git clone https://github.com/yuan-fd/DPLEvolve-AE.git cd DPLEvolve-AE # Check the host and print missing dependencies make doctor # Fetch and build the pinned ORFS, OpenROAD, and Yosys revisions make bootstrap make build-tools THREADS=8 # Generate the nine paper placement inputs make prepare-paper-inputs THREADS=8 ``` ## 2. Run the Experiments ### Table 4: QoR and Runtime ```bash # Nine defaults, 3,600 BO trials, and 18 selected-source replays bash artifacts/01-table4-qor/reproduce.sh --threads 10 ``` Result: ```text ../dpl_evolve_state/paper_reproduction/table4/table4-fresh.tsv ``` ### Table 5: Stage Composability The artifact retains one checksummed source snapshot for each of LEGALM, Diamond, and Negotiation. The Table 5 runner maps the six selected/reference roles to those three implementations and regenerates the AES, JPEG, and SWERV inputs with local `CORE_UTILIZATION` values 70, 90, and 60, respectively. ```bash make check-table5-data make reproduce-table5 THREADS=10 ``` Fresh comparisons are written to `../dpl_evolve_state/paper_reproduction/table5_*/table5-fresh.tsv`. See [docs/table5-status.md](docs/table5-status.md) for the exact role mapping. ### Table 6: Hard Cut-Row Legality ```bash # Download the experiment inputs, then execute all 27 runs bash artifacts/03-table6-cutrow/reproduce.sh --fetch --threads 10 ``` Result: ```text ../dpl_evolve_state/paper_reproduction/table6_*/table6-fresh.tsv ``` ### ReviewDSE Search ```bash # Inspect the configured Level 1 and nine-case search plans bash artifacts/05-reviewdse-search/reproduce.sh --plan # Run one Teacher/Student iteration bash artifacts/05-reviewdse-search/reproduce.sh \ --small --case aes_nangate45 --threads 8 # Full paper search: requires authenticated Codex/API access and the # paper-scale token budget. bash artifacts/05-reviewdse-search/reproduce.sh \ --level1 --acknowledge-cost --threads 10 bash artifacts/05-reviewdse-search/reproduce.sh \ --paper --run-prefix review_run_01 --acknowledge-cost --threads 10 ``` Result: ```text ../dpl_evolve_state/experiment_batches/review_run_01_paper9_place/ ``` ### Figures 4 and 5 ```bash # Rebuild from retained paper-search logs bash artifacts/04-figures/reproduce.sh # Rebuild from the fresh search above bash artifacts/04-figures/reproduce.sh \ --fresh --run-prefix review_run_01 ``` Results: ```text ../dpl_evolve_state/paper_reproduction/figures/retained/ ../dpl_evolve_state/paper_reproduction/figures/fresh/ ``` ### Ariane Diagnostic ```bash bash artifacts/06-ariane-diagnostic/reproduce.sh --threads 10 ``` Result: ```text ../dpl_evolve_state/paper_reproduction/ariane_diagnostic_*/ariane-diagnostic-fresh.tsv ``` ## 3. Evaluate the Results The experiment scripts evaluate each fresh run before returning success. Table 4 can be summarized again after its runs complete: ```bash make summarize-table4 ``` All summaries, legality reports, metrics, and generated figures are written under: ```text ../dpl_evolve_state/ ├── paper_reproduction/ │ ├── table4/table4-fresh.tsv │ ├── table6_*/table6-fresh.tsv │ ├── figures/{retained,fresh}/ │ └── ariane_diagnostic_*/ariane-diagnostic-fresh.tsv └── experiment_batches/_paper9_place/ ``` ## Web Demo Start the browser interface from the repository root: ```bash bash web-demo/start.sh ``` Open `http://127.0.0.1:8080`. The Web Demo provides visual controls and live logs for the same environment setup, experiment reproduction, and result evaluation commands described above. It can be used in place of the terminal Make commands. For a remote evaluation server, run the following command on the local machine and then open the same address in the local browser: ```bash ssh -N -L 8080:127.0.0.1:8080 USER@SERVER ``` ## Authors and Artifact Evaluation Contributor ### Paper Authors - **Zhiyu Zheng** — Fudan University - **Yiming Du** — Fudan University - **Ziyi Wang** — The Chinese University of Hong Kong - **Zhiang Wang** — Fudan University ### Artifact Evaluation Contributor - **Wenjie Yuan** — Fudan University ([25303060069@m.fudan.edu.cn](mailto:25303060069@m.fudan.edu.cn))