PACT Post-route Agentic Checkpoint Tuning for FPGA Timing Closure

PACT Artifact Workspace<p dir="ltr">This repository contains the PACT post-route FPGA checkpoint optimization agent, the Vivado and RapidWright MCP servers it drives, and the optimization knowledge base.</p><p dir="ltr">The 35 benchmark DCPs are included through Git LFS; proprietary FPGA tools are not included.</p><h2 dir="ltr">Layout</h2><ul><li><code>FDAgents/</code>: agent, typed skills, recipe planner, decision logic, and memory</li><li><code>baselines/codex_agent/</code>: free-form Codex Agent harness and reference results</li><li><code>baselines/datuner/</code>: DATuner checkpoint runner and reference results</li><li><code>RapidWrightMCP/</code>, <code>VivadoMCP/</code>: backend MCP servers</li><li><code>knowledge/</code>, <code>knowledge.md</code>: optimization knowledge and experimental notes</li><li><code>benchmarks/</code>: 35 evaluation DCPs, manifest, and checksums</li><li><code>journals/</code>: manuscript source retained for artifact preparation</li><li><code>tests/</code>: unit tests that do not require benchmark DCPs</li><li><code>runs/</code>: generated run outputs (ignored by Git)</li></ul><h2 dir="ltr">Environment</h2><p dir="ltr">The full artifact requires Python 3, Vivado 2025.1, Java, and a built RapidWright checkout.</p><p dir="ltr">Copy <code>.env.example</code> to <code>.env</code> and set local paths and the LLM credential there.</p><p dir="ltr"><code>.env</code> and generated DCPs are ignored by Git.</p><h2 dir="ltr">Run</h2><pre><pre>python -m pip install -r requirements.txt<br>python -m FDAgents.agent /path/to/design.dcp --model</pre></pre><h2 dir="ltr">Deterministic functional smoke test</h2><p dir="ltr">Two no-LLM flows exercise both backends and are suitable for an initial artifact check.</p><p dir="ltr">Put the following contest checkpoints in one directory:</p><ul><li><code>vexriscv_re-place_2025.1.dcp</code></li><li><code>logicnets_jscl_2025.1.dcp</code></li></ul><p dir="ltr">Then run:</p><pre><pre>DCP_DIR=/path/to/checkpoints \<br>OUT_ROOT="$PWD/reproduction-smoke" \<br>PYTHON=/path/to/python \<br>VIVADO_EXEC=/path/to/vivado \<br>scripts/run_functional_smoke.sh</pre></pre><p dir="ltr">Pass <code>vexriscv</code> or <code>logicnets</code> to run only one design.</p><p dir="ltr">The command fails if:</p><ul><li>an MCP backend returns an application-level error,</li><li>no cell is moved in the VexRiscv flow,</li><li>Vivado reports any routing error,</li><li>the output DCP is missing, or</li><li>the independently reopened checkpoint fails route signoff.</li></ul><p dir="ltr">Logs, checksums, exit codes, signoff timing reports, and output DCPs are written below <code>OUT_ROOT</code>.</p><p dir="ltr">Run the lightweight gate regression without Vivado:</p><pre><code>python tests/test_smoke_checks.py</code></pre><p dir="ltr">For structural and simulation-based comparison of an input and output DCP:</p><pre><pre>python validate_dcps.py input.dcp output.dcp \<br> --precheck-vectors 50 \<br> --vectors 200</pre></pre><p dir="ltr">The full 35-design experiment and benchmark acquisition procedure will be documented separately before artifact submission.</p><h2 dir="ltr">Snapshot</h2><p dir="ltr">This artifact branch starts from the implementation snapshot dated 2026-06-25.</p><p dir="ltr">Its Git history is intentionally squashed</p>