MAGE

MAGE — a vision-language-model-driven macro placement framework. Prompts, tooling, and reference designs for running VLM-guided macro placement and scoring the result with a commercial physical-design flow.

Repository layout

MAGE/
├── prompts/                    # Prompt library + shared Python tooling
│   ├── MAIN.md, RULE.md, …     # Engine prompts (orchestration, grouping,
│   │                             macro ref placement, validation, …)
│   ├── run_parallel.py         # Multi-variant runner that drives the LLM,
│   │                             applies the prompts, and evaluates results
│   ├── validate_placement.py   # Design-agnostic 26-check validator + viz
│   └── visualize_placement.py  # Canonical diagnostic visualisations
├── configs/
│   └── run_ariane.json         # Example config for the Ariane design
├── designs/
│   └── ariane/                 # Ariane reference design (see below)
├── results/
│   └── NG45/                   # MAGE/VLM macro-placement solution DEFs
│       ├── README.md           #   index of every solution DEF (start here)
│       ├── main_full_MAGE/     #   full MAGE (vision + corpus)
│       ├── ablation_no_vision/ #   MAGE∖V
│       ├── ablation_no_corpus/ #   MAGE∖K
│       └── rectilinear_cutout/ #   dense rectilinear floorplans
└── LICENSE

What you need to run the full pipeline

Dependency	Purpose	Notes
Python ≥ 3.9	Drives the pipeline	numpy, matplotlib, scipy (optional but recommended)
Anthropic API key	LLM calls in run_parallel.py	set ANTHROPIC_API_KEY
Cadence Innovus 21.1	Physical-design evaluation	any recent Innovus should work; tested on 21.1
NanGate45 libs / LEFs	Shipped in designs/ariane/enablement/	Ariane-only subset committed

Quick start — Ariane

Synthesis hand-off is not committed. The synth_handoff/ payloads (post-synthesis netlist *.v.gz, constraints *.CON.sdc.gz, and the placed-macros DEF *.def.gz) are not shipped in this repo. Generate them with the scripts in the MacroPlacement repository and place them under designs/<design>/synth_handoff/ before running the flow.

# 1. Clone the repo.
git clone <this repo> MAGE
cd MAGE

# 2. Unpack the committed .gz data payloads into their raw form.
bash designs/ariane/scripts/extract_data.sh

# 3. Export your Anthropic key (for the LLM stages).
export ANTHROPIC_API_KEY=sk-ant-...

# 4. Launch the multi-variant runner. It expands ${VLM_MP_ROOT} in the
#    config automatically; no env var setup needed if you cd'd into the
#    repo first.
python3 prompts/run_parallel.py --config configs/run_ariane.json

Outputs land under runs/ariane/<timestamp>/ (gitignored).

Adding a new design

Mirror the layout in designs/ariane/:

designs/<your_design>/
├── data/              # <design>_{floorplan,io,macro,master,master_pin,inst,net[,stdcell]}.csv.gz
├── synth_handoff/     # <design>.{v,CON.sdc,def}.gz — generate via the MacroPlacement flow (not committed)
├── floorplan/         # <design>_fp.def.gz
├── enablement/        # lib/ lef/ qrc/ (technology files)
├── flow/              # Innovus TCL flow, using $env(VLM_MP_ROOT)
├── scripts/           # extract_data.sh, pack_data.sh, run_eval.sh
└── README.md

Then write a configs/run_<your_design>.json that points at those paths via ${VLM_MP_ROOT}.

Path portability

All config paths and flow TCLs reference ${VLM_MP_ROOT}. run_parallel.py auto-sets this to the grandparent directory of the config file (typically the repo root) if the environment variable is unset. Set it explicitly if you move the config elsewhere:

export VLM_MP_ROOT=/path/to/MAGE

Data scaling

Each extraction run multiplies every coordinate, width, and height in the generated CSVs (<design>_{inst,macro,stdcell,io,floorplan,master_pin,master}.csv) by a deterministic per-design integer scaling factor sf in the range [1001, 1999]. The factor is derived from a hash of the core's width and height, so the same design always yields the same sf. Master cell names are rewritten as master_0, master_1, … and site names as site_0, site_1, … so the CSVs do not leak library identifiers.

The exact sf is printed at the end of write_all_details:

All details written successfully (scaling factor: <sf>)

Spacing values in the config must use the same scaled units. Update channel_width in configs/run_<design>.json so that

channel_width_in_config = channel_width_in_microns * sf

The shipped CSVs are already pre-scaled, and the shipped configs already use matching scaled units — no action is needed to run the provided designs. A new design will receive its own sf; multiply its intended channel width (in microns) by that sf and put the result in configs/run_<your_design>.json.

place_macro reverses the scaling at placement time, so coordinates emitted by the LLM are interpreted in scaled units consistently with the CSVs — no per-design plumbing needed in the orchestrator.

Defaults are min_sf = 1000, max_sf = 2000, passed to write_all_details / place_macro in designs/<design>/flow/util/invs_utils.tcl. To disable obfuscation during development, call write_all_details llm_eval 1 2, which forces sf = 1 (unscaled, real master/site names still obfuscated).

Experimental results (MAGE / VLM)

Why this section exists. Due to space constraints, the manuscript reports the vision and knowledge-corpus ablations only briefly (as averaged percentage degradations). For reproducibility we give the full per-design numbers here, in easy-to-read tables, together with the macro-placement solution DEFs that produced them. The solution DEFs live under results/NG45/ and each one was selected by matching the run's postRouteOpt WNS/TNS in <design>_DETAILS.rpt to the manuscript.

📂 MAGE solution DEFs for every testcase → results/NG45/README.md. That file is the index of all macro-placement solution DEFs (main results, vision/corpus ablations, and rectilinear-cutout cases), with the source run and verified postRouteOpt metrics for each one.

All numbers below are NG45, post-route: rWL in mm, Pwr in mW, WNS in ps, TNS in ns. MAGE is the full framework (with vision and knowledge corpus).

Reference: full MAGE (main results)

Design	rWL	Pwr	WNS	TNS	Solution DEF
Ariane	4424	832	−81	−32.7	results/NG45/main_full_MAGE/ariane
BP	26987	4479	−88	−139.7	results/NG45/main_full_MAGE/bp
MemPool	107309	2636	−32	−0.8	results/NG45/main_full_MAGE/mempool

Vision ablation — with vs. without visual feedback (MAGE vs. MAGE∖V)

Removing visual feedback bypasses the visualization gates, the auxiliary vision pipeline, and the three visual quality assessments; sub-agents must reason from numerical data alone. Detailed per-design numbers (not in the manuscript, which reports only the averaged degradation):

Design	Variant	rWL	Pwr	WNS	TNS	S_HM
Ariane	MAGE (with vision)	4424	832	−81	−32.7	0.72
Ariane	MAGE∖V (no vision)	4628	839	−119	−109.0	0.70
BP	MAGE (with vision)	26987	4479	−88	−139.7	0.68
BP	MAGE∖V (no vision)	27145	4475	−122	−221.9	0.64
Avg. degradation		2.3%	0.4%	40.5%	133.0%	4.2%

Solutions: results/NG45/ablation_no_vision/. Without visual feedback, WNS degrades 40.5% and TNS 133.0% on average; visual feedback catches irregular stacking, fragmented whitespace, and poor boundary utilization that pass script-based legality checks but still hurt routing/timing.

Knowledge-corpus ablation — with vs. without corpus (MAGE vs. MAGE∖K)

MAGE∖K disables retrieval from the knowledge corpus K (design-specific grouping preferences, known congestion risks, macro-organization patterns). Detailed per-design numbers (not in the manuscript, which reports only the averaged degradation):

Design	Variant	rWL	Pwr	WNS	TNS	S_HM
Ariane	MAGE (with corpus)	4424	832	−81	−32.7	0.72
Ariane	MAGE∖K (no corpus)	4536	836	−99	−60.2	0.73
BP	MAGE (with corpus)	26987	4479	−88	−139.7	0.68
BP	MAGE∖K (no corpus)	28056	4492	−132	−258.0	0.68
Avg. degradation		3.7%	0.3%	35.2%	106.9%	−0.7%

Solutions: results/NG45/ablation_no_corpus/. Removing K mainly hurts timing (WNS 35.2%, TNS 106.9% avg) while leaving human-likeness S_HM essentially unchanged (−0.7%) — i.e. K supplies design-specific PPA context, whereas structural regularity is governed by the prompt-encoded placement principles.

Rectilinear cutout (dense floorplans, >70% utilization)

HV = horizontal-and-vertical convexity; Mixed = horizontal top / vertical bottom. MAGE values; commercial baseline shown for reference.

Design	Type	Method	rWL	Pwr	WNS	TNS
Ariane	HV	MAGE	4859	829	−105	−70.1
Ariane	Mixed	MAGE	4934	843.5	−112	−94.0
BP	HV	MAGE	32757	4597	−123	−326.9
BP	Mixed	MAGE	32252	4633	−354	−11959.2

Solutions: results/NG45/rectilinear_cutout/. See results/NG45/README.md for the per-solution provenance (source run + verified postRouteOpt metrics) of every DEF.

Development utilities

• prompts/validate_placement.py — standalone validation and diagnostic visualisation. Supports --no-viz for fast CI use.
• prompts/visualize_placement.py — comparison mode for iteration-over- iteration regression checks.

License

See LICENSE. The Innovus TCL flow and reference enablement files retain their upstream attribution (ABKGroup UCSD / Cadence for the flow; NanGate / FakeRAM for the libraries).