attar 1.0.0__tar.gz

attar-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RayChang987
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

attar-1.0.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.1
+Name: attar
+Version: 1.0.0
+Summary: The fast loop for physical design: any benchmark as GPU tensors, place and evaluate in seconds, validate in ORFS
+Author: RayChang987
+License: MIT
+Project-URL: Homepage, https://github.com/RayChang987/Attar
+Project-URL: Documentation, https://github.com/RayChang987/Attar/tree/main/docs
+Project-URL: Changelog, https://github.com/RayChang987/Attar/blob/main/CHANGELOG.md
+Project-URL: Dataset, https://huggingface.co/datasets/RayChang987/attar-zoo
+Project-URL: Issues, https://github.com/RayChang987/Attar/issues
+Keywords: eda,physical design,placement,floorplanning,static timing analysis,vlsi,pytorch,gpu
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: huggingface_hub>=0.20
+Requires-Dist: zstandard
+Provides-Extra: docs
+Requires-Dist: pillow; extra == "docs"
+Requires-Dist: pygments; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/logo.png" alt="Attar: the fast loop for physical design" width="640">
+
+Diverse P&R benchmarks, distilled into one plug-and-play PyTorch environment on the GPU.<br>
+Evolve placement and timing-optimization algorithms in minutes, not days.
+
+[![Python](https://img.shields.io/badge/python-3.8%2B-d9622b?style=flat-square)](https://github.com/RayChang987/Attar/blob/main/pyproject.toml)
+[![PyTorch](https://img.shields.io/badge/PyTorch-CUDA-d99a1e?style=flat-square)](https://pytorch.org)
+[![Validated](https://img.shields.io/badge/validated%20against-OpenROAD-8f6a3f?style=flat-square)](https://github.com/RayChang987/Attar/blob/main/docs/validation/orfs_check.md)
+[![Tests](https://img.shields.io/badge/tests-107%20passing-5f7f1e?style=flat-square)](https://github.com/RayChang987/Attar/tree/main/tests)
+[![License](https://img.shields.io/badge/license-MIT-a8946f?style=flat-square)](https://github.com/RayChang987/Attar/blob/main/LICENSE)
+
+[Install](#install) &nbsp;·&nbsp; [Why Attar](#why-attar) &nbsp;·&nbsp; [Roadmap](#roadmap) &nbsp;·&nbsp; [Two modes](#two-modes) &nbsp;·&nbsp;
+[How it works](#how-it-works) &nbsp;·&nbsp; [Gallery](#gallery)
+
+</div>
+
+<br>
+
+## Install
+
+```bash
+pip install attar
+```
+
+```python
+import attar
+d = attar.load('after_fp/orfs_asap7/aes', device='cuda')   # downloaded from the zoo on first use
+```
+
+Python 3.8 or newer, with PyTorch (a CUDA GPU for the speed; everything also runs on the CPU). The designs come from
+the [Attar zoo](https://huggingface.co/datasets/RayChang987/attar-zoo) on the Hugging Face Hub (246 designs, 731 MB
+in all); `attar.zoo(remote=True)` lists them. The latest code: `pip install git+https://github.com/RayChang987/Attar`.
+
+- The first timing run on a GPU machine compiles the timer's Triton kernels (about two minutes, once); later runs
+  reuse them and take seconds.
+- With `g++` on the path, nets of more than 256 pins get OpenROAD's exact Steiner parasitics (built on first use);
+  without it they fall back to a lumped wire model, with a warning.
+
+## Why Attar
+
+1. **Speed decides quality.** When AI agents do the research, iteration speed is more than a metric: in our view it
+   decides the quality of results (QoR). An agent that can propose, test and discard an idea in seconds finds what
+   works. When every run takes hours, even the best algorithm starves for feedback.
+2. **Data preparation is painful.** Traditional place-and-route (P&R) tools take minutes to hours per run, and every
+   benchmark suite comes in its own format (LEF/DEF, Bookshelf, YAL, GSRC blocks) with its own gaps. Getting a design
+   ready to experiment on is slow, fragmented work, repeated for every suite.
+3. **Attar is the fast loop.** Attar distills diverse P&R benchmarks into one plug-and-play PyTorch environment:
+   `attar.load` a name, and the design is on the GPU. Each reader hands over only the facts its source has, with
+   their provenance, and nothing missing is made up ([a design is a state](#a-design-is-a-state)). The fast loop
+   stays faithful to the full flows without their overhead: its HPWL equals OpenROAD's to 7 digits,
+   its legality equals `check_placement`, its placements route in OpenROAD-flow-scripts with 0 DRC, and HPWL ranks
+   placements as routed wirelength does in 951 routed Innovus runs, once they differ by 2% or more
+   ([validation](https://github.com/RayChang987/Attar/blob/main/docs/validation/orfs_check.md)).
+4. **GPU-native.** Layouts and design features are tensors on the GPU, so researchers, developers and AI agents
+   train, evaluate and debug in the same few lines of Python: exact HPWL of 8.9M pins in 3 ms, a 2.2M-cell design
+   placed and legalized in 49 s. An algorithm is a function from tensors to positions: no database
+   API, no TCL, no file formats.
+
+## Roadmap
+
+<p align="center"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/roadmap.svg" alt="Roadmap mind map. Attar in the center. Left, Data, as tensors: contest benchmarks, one per suite (placement: ISPD 2005, 2015, 2018, 2019, 2024, ICCAD 2025, GSRC placement; floorplan: MCNC, GSRC blocks, IBM-HB+), ASAP7 (15 placement, 5 floorplan designs) and NS3K (99 placement designs). Right, Naive Engine: floorplan (packing, macro placement, IO placement) and placement (placer, legalizer, PDN-aware refinement), all done. Right, Evaluation: HPWL, global routing OVF and timing done; blocked pin checking not yet; detailed routing and DRV checks will not be built" width="100%"></p>
+
+### Evaluation
+
+Each evaluator against OpenROAD on the same netlist and placement; full tables in
+[docs/validation](https://github.com/RayChang987/Attar/blob/main/docs/validation/timing_routing.md).
+
+| Evaluator | Call | Compared with | Accuracy |
+| --- | --- | --- | --- |
+| **HPWL** | `ev.hpwl` | OpenROAD's HPWL from its database; 23 ORFS designs (ASAP7, Nangate45) up to 1.05M cells | within **0.00002%** on every design ([table](https://github.com/RayChang987/Attar/blob/main/docs/validation/orfs_check.md)) |
+| **Legality** | `ev.legality` | OpenROAD `check_placement` | same verdict on all **23** ORFS designs and the **62** NS3K floorplans OpenROAD can check; placements broken by half a site rejected by both |
+| **Timing** | `d.timing()` | OpenSTA after `estimate_parasitics -placement`; 31 designs (ASAP7, Nangate45, NS3K) up to 1.05M cells | WNS median error **0.00%** (ORFS) and **0.11%** (NS3K), max **0.34%**; hold slack MAE at most 0.36 ps; 5-30x faster than OpenSTA |
+| **Pin and net slack** | `d.timing().pin_slack()`, `.net_slack()` | OpenSTA's `slack_max` of every pin; 8 designs (ASAP7, Nangate45) up to 384k pins | Pearson at least **0.9995**; on the pins with negative slack, MAE at most **1.03 ps**; 7-32 ms after a timing run |
+| **Timing after sizing** | `d.resize` + `d.timing()` | OpenROAD `replace_cell` + OpenSTA, 20% of the cells swapped at random; 16 designs | WNS error at most **0.23%**, TNS at most 0.37% |
+| **Timing after netlist edits** | `d.edit()`, `d.debuffer()` + `d.timing()` | OpenSTA on the DEF Attar exports: after 1,548 buffers and 443 clones inserted (10 NS3K designs up to 163k cells), and after `d.debuffer()` removed 45,991 buffers and 83 inverters (10 ORFS designs) | setup Pearson at least **0.9997**, WNS error at most **0.04%** after debuffer and **1.18%** after the NS3K edits; hold MAE at most 0.36 ps |
+| **Global routing OVF** | `d.gr_overflow()` | OpenROAD's gcell capacities and global route; 13 ORFS designs | capacities exact without macros, within **0.16%** with them; ranks designs as OpenROAD does (Spearman **0.97**); a pre-route estimate: reads mild congestion high and heavy congestion low |
+| **Steiner wirelength, RUDY, density overflow** | `ev.steiner_wirelength`, `ev.rudy`, `ev.density_overflow` |  | |
+
+### Naive Engine
+
+| Engine | Mode | Call | What it does |
+| --- | --- | --- | --- |
+| **Packing** | `before_fp` | `naive.place_macros(packing=True)` | block-level designs: B*-tree packing, annealed into the core, then for HPWL |
+| **Macro placement** | `before_fp` | `naive.place_macros` | mixed-size global placement, then macros legalized on their routing tracks with a halo |
+| **IO placement** | `before_fp` | `naive.place_io` | IO pins on the die boundary, net-aware once cells are placed |
+| **Placer** | both | `naive.global_place` | electrostatic (ePlace/DREAMPlace style, Nesterov, CUDA graphs) at the source flow's own target density; `routability=True`: DREAMPlace's cell inflation |
+| **Legalizer** | `after_fp` | `naive.legalize` | multi-row-height cells, power-rail parity, signal pins clear of the PDN's via metal |
+| **PDN-aware refinement** | `after_fp` | inside `naive.legalize` | row DP and repair that keep cells clear of the PDN |
+
+`d.floorplan(utilization=...)` sizes the die (`naive.make_die`), then places the IO pins and the macros;
+`d.place()` is global placement plus legalization.
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/demo_placement.gif" alt="Timing-driven placement written in fifteen lines of Python, run on cva6 and swerv: place for wirelength, time it, weight the nets by their slack as OpenROAD's global placement does, place again, time it" width="920">
+
+<sub><b>Your algorithm, in fifteen lines</b> (<a href="examples/timing_driven.py">examples/timing_driven.py</a>). Real
+runs on an RTX 3080 Ti, the same code on two ASAP7 designs: place for wirelength, take every net's slack
+(<code>net_slack()</code>, as OpenSTA's), weight the worst 10% of the nets from 1 to 5 by criticality as OpenROAD's
+timing-driven global placement does, place again. <b>cva6</b> (121k cells, 8 SRAMs): WNS -195 to -75 ps, TNS
+-85.7k to -5.1k ps, HPWL +6.7%, in 2.2 s. <b>swerv</b> (103k cells): WNS -205 to -117 ps, TNS -39.5k to -1.2k ps,
+HPWL +1.1%, in 1.9 s. Both legal.</sub>
+
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/demo_floorplan.gif" alt="Floorplan mode: GSRC n100 at 85% block area, floorplanned twice: GP plus LP legalization leaves 5 macros outside the core (not legal), B*-tree packing fits them all (legal)" width="920">
+
+<sub><b>Floorplan mode</b> (<code>before_fp</code>). GSRC <b>n100</b>: 100 hard blocks, no die; Attar sizes one for 85%
+block area, places the IO pins and the macros. GP + LP legalization never overlaps macros, but here 5 stick out of
+the core: not legal. <code>packing=True</code> (B*-tree, annealed into the core, then for HPWL) fits them all in
+5.1 s, at 8% more wire. The lines are the strongest connections between macros and IO pins.</sub>
+
+</div>
+
+## Two modes
+
+In production chip design, the power delivery network (PDN) is the dividing line: once the power grid and the macros
+are locked down, the design enters a different phase. Attar splits its problems at that line. It does not synthesize
+a PDN, and it should not: a `before_fp` answer goes to a flow that draws one, and an `after_fp` problem comes
+with the PDN its flow drew.
+
+| | **Before-floorplan** (`before_fp`) | **After-floorplan** (`after_fp`) |
+| --- | --- | --- |
+| given | the netlist (an initial die for ORFS designs) | die, IO pins, macros, rows and PDN: a fixed floorplan |
+| the answer | target utilization (the die), IO pin placement, macro placement | standard-cell placement; then timing optimization and global routing on the same floorplan |
+| one call | `d.floorplan(utilization=0.6)` | `d.place()` |
+| goes out as | a DEF: your flow draws the PDN and places | a DEF: your flow routes and times |
+| in the zoo | 55 designs, 6 suites | 191 designs, 16 suites |
+
+Attar measures wirelength, congestion (RUDY, GROV), density, legality and timing; see the [roadmap](#roadmap).
+
+## How it works
+
+<p align="center"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/flow.svg" alt="Sources (LEF/DEF, Bookshelf, YAL, GSRC blocks) are distilled into the Attar IR and loaded as a Design on the GPU; attar.naive moves it and adds facts, the Evaluator measures it; export writes a DEF for your own flow (OpenROAD, Innovus, ICC2, ...)" width="100%"></p>
+
+1. **Distill.** A reader turns a benchmark into the Attar IR: integer arrays in a safetensors file, plus a manifest
+   that lists which facts the source provides and where each came from. Readers exist for LEF/DEF, Bookshelf, YAL
+   and GSRC blocks.
+2. **Load.** `attar.load` puts the arrays on the GPU as a `Design`. `d.status()` shows each fact, each capability,
+   and what is left before export.
+3. **Move.** Your algorithm, or the [built-in engines](#roadmap) (`attar.naive`), changes the positions:
+   die, IO pins and macros for `before_fp`, cells for `after_fp`.
+4. **Measure.** `attar.Evaluator` computes HPWL (exact, batched), Steiner wirelength, RUDY, density overflow and
+   legality, on the current placement or on any positions you pass.
+5. **Export.** `d.export(out_def)` writes the design back into its source DEF's frame: the PDN, IO pin shapes and
+   fixed cells as they were, the cells and nets from the IR (a changed die, IO pins and macros included). Your own
+   flow (OpenROAD, Innovus, ICC2, ...) takes it from there.
+
+More: [concepts](https://github.com/RayChang987/Attar/blob/main/docs/concepts.md) · [benchmarks](https://github.com/RayChang987/Attar/blob/main/docs/benchmarks.md) · [API](https://github.com/RayChang987/Attar/blob/main/docs/api.md) ·
+[validation](https://github.com/RayChang987/Attar/blob/main/docs/validation/timing_routing.md)
+
+## Gallery
+
+What the Evaluator sees: each view is `d.plot(tiles=...)` on a real run of `attar.naive`.
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/eval_grov.png" alt="cva6 after placement, colored by global-routing load on OpenROAD's gcells"></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/eval_pin_access.png" alt="ariane136 after global placement: cells with a signal pin on the PDN, in stripes along the power grid"></td>
+</tr>
+<tr>
+<td><sub><b>Global-routing overflow</b> (<code>d.gr_overflow()</code>, <code>tiles='gr_overflow'</code>): cva6 (ASAP7)
+placed in 2.4 s, RUDY demand against OpenROAD's gcell capacities. GROV 0.73%: the channel left of the SRAMs and
+the dense logic at the lower right are where the router will struggle.</sub></td>
+<td><sub><b>Pin access</b> (<code>tiles='pin_access'</code>): ariane136 (NS3K, 136 SRAMs) right after global
+placement. 12,165 cells have a signal pin on the PDN's via metal, in stripes along the power grid: NS3K's via
+stacks cross the M1 pin layer.</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/eval_placed.png" alt="ariane136 legalized: legal, rails and PDN included"></td>
+<td><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/fp_n300.png" alt="GSRC n300 floorplanned by B*-tree packing, with the strongest connections between blocks and IO pins"></td>
+</tr>
+<tr>
+<td><sub><b>Legality</b> (<code>ev.legality()</code>): the same design legalized in 2.4 s. Rows, sites, overlaps,
+power-rail parity and the PDN all check out: 0 cells left on the PDN.</sub></td>
+<td><sub><b>Floorplan legality and connections</b> (<code>d.floorplan_legal()</code>, <code>nets</code>): GSRC n300,
+300 hard blocks and 569 IO pins, no die given. Attar sizes one for 85% block area and packs the blocks (B*-tree) in
+43 s: legal, HPWL 565k. The lines are the strongest connections between blocks and IO pins.</sub></td>
+</tr>
+</table>
+
+## A design is a state
+
+```text
+>>> d = attar.load('after_fp/orfs_asap7/aes'); d.status()
+aes_cipher_top  (orfs/asap7, fidelity F1)
+  placement target density 0.71 (orfs 3_3 global_place (GPL-0023))
+Problem facts
+  ✅ netlist           def             12268 nets, 42885 pins
+  ✅ cell_geometry     lef             12420 cells (12009 movable, 0 macros), 56 masters
+  ✅ floorplan.die     def             1 die(s), 48.71 x 48.71 um
+  ✅ floorplan.io      def             388 IO pins placed
+  ✅ rows              def             164 rows, height 0.27 um
+  ✅ pdn               def             1815 wire and 4785 via shapes on M1, M2, M3
+  ✅ def_frame         def             PDN, pins, fixed cells of the source DEF, kept verbatim (849 kB)
+  ...
+Solution state
+  ❌ placement         12009 movable cells unplaced  (snapshots: reference)
+  ...
+  -> only a placement is missing: place the design (or restore a snapshot), then d.export("out.def")
+```
+
+Every reader states which facts it provides, and every engine and metric states which facts it needs:
+- a Bookshelf design has no cell library, so it does not export to DEF;
+- a design with no special nets on the pin layers has no `pdn` rule to keep;
+- a block floorplan has no rows;
+- a soft-block benchmark has no cell geometry.
+
+Each can do exactly what its facts allow. Engines add facts with provenance (`placement: naive`), so it is always
+clear which part of a design came from where. See [docs/concepts.md](https://github.com/RayChang987/Attar/blob/main/docs/concepts.md).
+
+## Acknowledgements
+
+Attar's global placement follows ePlace, DREAMPlace and Xplace, and its routability option DREAMPlace's cell
+inflation; its rail and PDN checks follow OpenROAD's detailed placer, and its PDN repair the row DP of pa_pdn.
+Attar is validated against [OpenROAD-flow-scripts](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts) on
+the ASAP7 and Nangate45 platforms. Benchmarks are from the ISPD, ICCAD and GSRC contests, MCNC and ORFS.
+
+## License
+
+<div align="center">
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-a8946f?style=for-the-badge" alt="MIT License"></a>
+<br><br>
+<sub>Copyright &copy; 2026 RayChang987 &nbsp;·&nbsp; free to use, modify and distribute; see <a href="LICENSE">LICENSE</a></sub>
+<br><br>
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/logo.png" alt="Attar" width="180">
+</div>

attar-1.0.0/README.md

@@ -0,0 +1,227 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/logo.png" alt="Attar: the fast loop for physical design" width="640">
+
+Diverse P&R benchmarks, distilled into one plug-and-play PyTorch environment on the GPU.<br>
+Evolve placement and timing-optimization algorithms in minutes, not days.
+
+[![Python](https://img.shields.io/badge/python-3.8%2B-d9622b?style=flat-square)](https://github.com/RayChang987/Attar/blob/main/pyproject.toml)
+[![PyTorch](https://img.shields.io/badge/PyTorch-CUDA-d99a1e?style=flat-square)](https://pytorch.org)
+[![Validated](https://img.shields.io/badge/validated%20against-OpenROAD-8f6a3f?style=flat-square)](https://github.com/RayChang987/Attar/blob/main/docs/validation/orfs_check.md)
+[![Tests](https://img.shields.io/badge/tests-107%20passing-5f7f1e?style=flat-square)](https://github.com/RayChang987/Attar/tree/main/tests)
+[![License](https://img.shields.io/badge/license-MIT-a8946f?style=flat-square)](https://github.com/RayChang987/Attar/blob/main/LICENSE)
+
+[Install](#install) &nbsp;·&nbsp; [Why Attar](#why-attar) &nbsp;·&nbsp; [Roadmap](#roadmap) &nbsp;·&nbsp; [Two modes](#two-modes) &nbsp;·&nbsp;
+[How it works](#how-it-works) &nbsp;·&nbsp; [Gallery](#gallery)
+
+</div>
+
+<br>
+
+## Install
+
+```bash
+pip install attar
+```
+
+```python
+import attar
+d = attar.load('after_fp/orfs_asap7/aes', device='cuda')   # downloaded from the zoo on first use
+```
+
+Python 3.8 or newer, with PyTorch (a CUDA GPU for the speed; everything also runs on the CPU). The designs come from
+the [Attar zoo](https://huggingface.co/datasets/RayChang987/attar-zoo) on the Hugging Face Hub (246 designs, 731 MB
+in all); `attar.zoo(remote=True)` lists them. The latest code: `pip install git+https://github.com/RayChang987/Attar`.
+
+- The first timing run on a GPU machine compiles the timer's Triton kernels (about two minutes, once); later runs
+  reuse them and take seconds.
+- With `g++` on the path, nets of more than 256 pins get OpenROAD's exact Steiner parasitics (built on first use);
+  without it they fall back to a lumped wire model, with a warning.
+
+## Why Attar
+
+1. **Speed decides quality.** When AI agents do the research, iteration speed is more than a metric: in our view it
+   decides the quality of results (QoR). An agent that can propose, test and discard an idea in seconds finds what
+   works. When every run takes hours, even the best algorithm starves for feedback.
+2. **Data preparation is painful.** Traditional place-and-route (P&R) tools take minutes to hours per run, and every
+   benchmark suite comes in its own format (LEF/DEF, Bookshelf, YAL, GSRC blocks) with its own gaps. Getting a design
+   ready to experiment on is slow, fragmented work, repeated for every suite.
+3. **Attar is the fast loop.** Attar distills diverse P&R benchmarks into one plug-and-play PyTorch environment:
+   `attar.load` a name, and the design is on the GPU. Each reader hands over only the facts its source has, with
+   their provenance, and nothing missing is made up ([a design is a state](#a-design-is-a-state)). The fast loop
+   stays faithful to the full flows without their overhead: its HPWL equals OpenROAD's to 7 digits,
+   its legality equals `check_placement`, its placements route in OpenROAD-flow-scripts with 0 DRC, and HPWL ranks
+   placements as routed wirelength does in 951 routed Innovus runs, once they differ by 2% or more
+   ([validation](https://github.com/RayChang987/Attar/blob/main/docs/validation/orfs_check.md)).
+4. **GPU-native.** Layouts and design features are tensors on the GPU, so researchers, developers and AI agents
+   train, evaluate and debug in the same few lines of Python: exact HPWL of 8.9M pins in 3 ms, a 2.2M-cell design
+   placed and legalized in 49 s. An algorithm is a function from tensors to positions: no database
+   API, no TCL, no file formats.
+
+## Roadmap
+
+<p align="center"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/roadmap.svg" alt="Roadmap mind map. Attar in the center. Left, Data, as tensors: contest benchmarks, one per suite (placement: ISPD 2005, 2015, 2018, 2019, 2024, ICCAD 2025, GSRC placement; floorplan: MCNC, GSRC blocks, IBM-HB+), ASAP7 (15 placement, 5 floorplan designs) and NS3K (99 placement designs). Right, Naive Engine: floorplan (packing, macro placement, IO placement) and placement (placer, legalizer, PDN-aware refinement), all done. Right, Evaluation: HPWL, global routing OVF and timing done; blocked pin checking not yet; detailed routing and DRV checks will not be built" width="100%"></p>
+
+### Evaluation
+
+Each evaluator against OpenROAD on the same netlist and placement; full tables in
+[docs/validation](https://github.com/RayChang987/Attar/blob/main/docs/validation/timing_routing.md).
+
+| Evaluator | Call | Compared with | Accuracy |
+| --- | --- | --- | --- |
+| **HPWL** | `ev.hpwl` | OpenROAD's HPWL from its database; 23 ORFS designs (ASAP7, Nangate45) up to 1.05M cells | within **0.00002%** on every design ([table](https://github.com/RayChang987/Attar/blob/main/docs/validation/orfs_check.md)) |
+| **Legality** | `ev.legality` | OpenROAD `check_placement` | same verdict on all **23** ORFS designs and the **62** NS3K floorplans OpenROAD can check; placements broken by half a site rejected by both |
+| **Timing** | `d.timing()` | OpenSTA after `estimate_parasitics -placement`; 31 designs (ASAP7, Nangate45, NS3K) up to 1.05M cells | WNS median error **0.00%** (ORFS) and **0.11%** (NS3K), max **0.34%**; hold slack MAE at most 0.36 ps; 5-30x faster than OpenSTA |
+| **Pin and net slack** | `d.timing().pin_slack()`, `.net_slack()` | OpenSTA's `slack_max` of every pin; 8 designs (ASAP7, Nangate45) up to 384k pins | Pearson at least **0.9995**; on the pins with negative slack, MAE at most **1.03 ps**; 7-32 ms after a timing run |
+| **Timing after sizing** | `d.resize` + `d.timing()` | OpenROAD `replace_cell` + OpenSTA, 20% of the cells swapped at random; 16 designs | WNS error at most **0.23%**, TNS at most 0.37% |
+| **Timing after netlist edits** | `d.edit()`, `d.debuffer()` + `d.timing()` | OpenSTA on the DEF Attar exports: after 1,548 buffers and 443 clones inserted (10 NS3K designs up to 163k cells), and after `d.debuffer()` removed 45,991 buffers and 83 inverters (10 ORFS designs) | setup Pearson at least **0.9997**, WNS error at most **0.04%** after debuffer and **1.18%** after the NS3K edits; hold MAE at most 0.36 ps |
+| **Global routing OVF** | `d.gr_overflow()` | OpenROAD's gcell capacities and global route; 13 ORFS designs | capacities exact without macros, within **0.16%** with them; ranks designs as OpenROAD does (Spearman **0.97**); a pre-route estimate: reads mild congestion high and heavy congestion low |
+| **Steiner wirelength, RUDY, density overflow** | `ev.steiner_wirelength`, `ev.rudy`, `ev.density_overflow` |  | |
+
+### Naive Engine
+
+| Engine | Mode | Call | What it does |
+| --- | --- | --- | --- |
+| **Packing** | `before_fp` | `naive.place_macros(packing=True)` | block-level designs: B*-tree packing, annealed into the core, then for HPWL |
+| **Macro placement** | `before_fp` | `naive.place_macros` | mixed-size global placement, then macros legalized on their routing tracks with a halo |
+| **IO placement** | `before_fp` | `naive.place_io` | IO pins on the die boundary, net-aware once cells are placed |
+| **Placer** | both | `naive.global_place` | electrostatic (ePlace/DREAMPlace style, Nesterov, CUDA graphs) at the source flow's own target density; `routability=True`: DREAMPlace's cell inflation |
+| **Legalizer** | `after_fp` | `naive.legalize` | multi-row-height cells, power-rail parity, signal pins clear of the PDN's via metal |
+| **PDN-aware refinement** | `after_fp` | inside `naive.legalize` | row DP and repair that keep cells clear of the PDN |
+
+`d.floorplan(utilization=...)` sizes the die (`naive.make_die`), then places the IO pins and the macros;
+`d.place()` is global placement plus legalization.
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/demo_placement.gif" alt="Timing-driven placement written in fifteen lines of Python, run on cva6 and swerv: place for wirelength, time it, weight the nets by their slack as OpenROAD's global placement does, place again, time it" width="920">
+
+<sub><b>Your algorithm, in fifteen lines</b> (<a href="examples/timing_driven.py">examples/timing_driven.py</a>). Real
+runs on an RTX 3080 Ti, the same code on two ASAP7 designs: place for wirelength, take every net's slack
+(<code>net_slack()</code>, as OpenSTA's), weight the worst 10% of the nets from 1 to 5 by criticality as OpenROAD's
+timing-driven global placement does, place again. <b>cva6</b> (121k cells, 8 SRAMs): WNS -195 to -75 ps, TNS
+-85.7k to -5.1k ps, HPWL +6.7%, in 2.2 s. <b>swerv</b> (103k cells): WNS -205 to -117 ps, TNS -39.5k to -1.2k ps,
+HPWL +1.1%, in 1.9 s. Both legal.</sub>
+
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/demo_floorplan.gif" alt="Floorplan mode: GSRC n100 at 85% block area, floorplanned twice: GP plus LP legalization leaves 5 macros outside the core (not legal), B*-tree packing fits them all (legal)" width="920">
+
+<sub><b>Floorplan mode</b> (<code>before_fp</code>). GSRC <b>n100</b>: 100 hard blocks, no die; Attar sizes one for 85%
+block area, places the IO pins and the macros. GP + LP legalization never overlaps macros, but here 5 stick out of
+the core: not legal. <code>packing=True</code> (B*-tree, annealed into the core, then for HPWL) fits them all in
+5.1 s, at 8% more wire. The lines are the strongest connections between macros and IO pins.</sub>
+
+</div>
+
+## Two modes
+
+In production chip design, the power delivery network (PDN) is the dividing line: once the power grid and the macros
+are locked down, the design enters a different phase. Attar splits its problems at that line. It does not synthesize
+a PDN, and it should not: a `before_fp` answer goes to a flow that draws one, and an `after_fp` problem comes
+with the PDN its flow drew.
+
+| | **Before-floorplan** (`before_fp`) | **After-floorplan** (`after_fp`) |
+| --- | --- | --- |
+| given | the netlist (an initial die for ORFS designs) | die, IO pins, macros, rows and PDN: a fixed floorplan |
+| the answer | target utilization (the die), IO pin placement, macro placement | standard-cell placement; then timing optimization and global routing on the same floorplan |
+| one call | `d.floorplan(utilization=0.6)` | `d.place()` |
+| goes out as | a DEF: your flow draws the PDN and places | a DEF: your flow routes and times |
+| in the zoo | 55 designs, 6 suites | 191 designs, 16 suites |
+
+Attar measures wirelength, congestion (RUDY, GROV), density, legality and timing; see the [roadmap](#roadmap).
+
+## How it works
+
+<p align="center"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/flow.svg" alt="Sources (LEF/DEF, Bookshelf, YAL, GSRC blocks) are distilled into the Attar IR and loaded as a Design on the GPU; attar.naive moves it and adds facts, the Evaluator measures it; export writes a DEF for your own flow (OpenROAD, Innovus, ICC2, ...)" width="100%"></p>
+
+1. **Distill.** A reader turns a benchmark into the Attar IR: integer arrays in a safetensors file, plus a manifest
+   that lists which facts the source provides and where each came from. Readers exist for LEF/DEF, Bookshelf, YAL
+   and GSRC blocks.
+2. **Load.** `attar.load` puts the arrays on the GPU as a `Design`. `d.status()` shows each fact, each capability,
+   and what is left before export.
+3. **Move.** Your algorithm, or the [built-in engines](#roadmap) (`attar.naive`), changes the positions:
+   die, IO pins and macros for `before_fp`, cells for `after_fp`.
+4. **Measure.** `attar.Evaluator` computes HPWL (exact, batched), Steiner wirelength, RUDY, density overflow and
+   legality, on the current placement or on any positions you pass.
+5. **Export.** `d.export(out_def)` writes the design back into its source DEF's frame: the PDN, IO pin shapes and
+   fixed cells as they were, the cells and nets from the IR (a changed die, IO pins and macros included). Your own
+   flow (OpenROAD, Innovus, ICC2, ...) takes it from there.
+
+More: [concepts](https://github.com/RayChang987/Attar/blob/main/docs/concepts.md) · [benchmarks](https://github.com/RayChang987/Attar/blob/main/docs/benchmarks.md) · [API](https://github.com/RayChang987/Attar/blob/main/docs/api.md) ·
+[validation](https://github.com/RayChang987/Attar/blob/main/docs/validation/timing_routing.md)
+
+## Gallery
+
+What the Evaluator sees: each view is `d.plot(tiles=...)` on a real run of `attar.naive`.
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/eval_grov.png" alt="cva6 after placement, colored by global-routing load on OpenROAD's gcells"></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/eval_pin_access.png" alt="ariane136 after global placement: cells with a signal pin on the PDN, in stripes along the power grid"></td>
+</tr>
+<tr>
+<td><sub><b>Global-routing overflow</b> (<code>d.gr_overflow()</code>, <code>tiles='gr_overflow'</code>): cva6 (ASAP7)
+placed in 2.4 s, RUDY demand against OpenROAD's gcell capacities. GROV 0.73%: the channel left of the SRAMs and
+the dense logic at the lower right are where the router will struggle.</sub></td>
+<td><sub><b>Pin access</b> (<code>tiles='pin_access'</code>): ariane136 (NS3K, 136 SRAMs) right after global
+placement. 12,165 cells have a signal pin on the PDN's via metal, in stripes along the power grid: NS3K's via
+stacks cross the M1 pin layer.</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/eval_placed.png" alt="ariane136 legalized: legal, rails and PDN included"></td>
+<td><img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/gallery/fp_n300.png" alt="GSRC n300 floorplanned by B*-tree packing, with the strongest connections between blocks and IO pins"></td>
+</tr>
+<tr>
+<td><sub><b>Legality</b> (<code>ev.legality()</code>): the same design legalized in 2.4 s. Rows, sites, overlaps,
+power-rail parity and the PDN all check out: 0 cells left on the PDN.</sub></td>
+<td><sub><b>Floorplan legality and connections</b> (<code>d.floorplan_legal()</code>, <code>nets</code>): GSRC n300,
+300 hard blocks and 569 IO pins, no die given. Attar sizes one for 85% block area and packs the blocks (B*-tree) in
+43 s: legal, HPWL 565k. The lines are the strongest connections between blocks and IO pins.</sub></td>
+</tr>
+</table>
+
+## A design is a state
+
+```text
+>>> d = attar.load('after_fp/orfs_asap7/aes'); d.status()
+aes_cipher_top  (orfs/asap7, fidelity F1)
+  placement target density 0.71 (orfs 3_3 global_place (GPL-0023))
+Problem facts
+  ✅ netlist           def             12268 nets, 42885 pins
+  ✅ cell_geometry     lef             12420 cells (12009 movable, 0 macros), 56 masters
+  ✅ floorplan.die     def             1 die(s), 48.71 x 48.71 um
+  ✅ floorplan.io      def             388 IO pins placed
+  ✅ rows              def             164 rows, height 0.27 um
+  ✅ pdn               def             1815 wire and 4785 via shapes on M1, M2, M3
+  ✅ def_frame         def             PDN, pins, fixed cells of the source DEF, kept verbatim (849 kB)
+  ...
+Solution state
+  ❌ placement         12009 movable cells unplaced  (snapshots: reference)
+  ...
+  -> only a placement is missing: place the design (or restore a snapshot), then d.export("out.def")
+```
+
+Every reader states which facts it provides, and every engine and metric states which facts it needs:
+- a Bookshelf design has no cell library, so it does not export to DEF;
+- a design with no special nets on the pin layers has no `pdn` rule to keep;
+- a block floorplan has no rows;
+- a soft-block benchmark has no cell geometry.
+
+Each can do exactly what its facts allow. Engines add facts with provenance (`placement: naive`), so it is always
+clear which part of a design came from where. See [docs/concepts.md](https://github.com/RayChang987/Attar/blob/main/docs/concepts.md).
+
+## Acknowledgements
+
+Attar's global placement follows ePlace, DREAMPlace and Xplace, and its routability option DREAMPlace's cell
+inflation; its rail and PDN checks follow OpenROAD's detailed placer, and its PDN repair the row DP of pa_pdn.
+Attar is validated against [OpenROAD-flow-scripts](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts) on
+the ASAP7 and Nangate45 platforms. Benchmarks are from the ISPD, ICCAD and GSRC contests, MCNC and ORFS.
+
+## License
+
+<div align="center">
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-a8946f?style=for-the-badge" alt="MIT License"></a>
+<br><br>
+<sub>Copyright &copy; 2026 RayChang987 &nbsp;·&nbsp; free to use, modify and distribute; see <a href="LICENSE">LICENSE</a></sub>
+<br><br>
+<img src="https://raw.githubusercontent.com/RayChang987/Attar/main/docs/images/logo.png" alt="Attar" width="180">
+</div>

attar-1.0.0/attar/__init__.py

@@ -0,0 +1,11 @@
+"""Attar: a fast loop for physical design. Designs from any source become GPU tensors (Design), metrics evaluate
+them (Evaluator), and a basic set of tensorized engines (attar.naive) makes them move. What a design can do follows
+from the facts it has. See README.md."""
+__version__ = '1.0.0'
+
+from .design import Design, load, zoo
+from .io.distill import distill
+from .evaluator import Evaluator
+from .hub import fetch
+
+__all__ = ['Design', 'load', 'zoo', 'fetch', 'distill', 'Evaluator', '__version__']

attar-1.0.0/attar/_slow_loop.py

@@ -0,0 +1,58 @@
+"""Internal: handing a design back to the slow loop it came from (ORFS), for Attar's own validation.
+
+Not part of the user API. Users take the result out with Design.export (a DEF) into their own flow (OpenROAD,
+Innovus, ICC2, ...). Attar keeps this only to check itself against ORFS: tools/orfs_roundtrip.py (a placement into an
+ORFS run), tools/orfs_handoff.py (a floorplan into ORFS 2_1) and their tests use it.
+
+The fact 'slow_loop' says that a design comes from an ORFS stage on a platform ORFS knows; an engine that changes the
+floorplan after ORFS built tapcells and PDN around it drops the fact (Design._floorplan_changed).
+"""
+import os
+
+from .facts import MissingFacts
+
+# what a hand-off needs, beyond what export needs
+CAPABILITIES = {
+    'orfs_handoff': {'cell_library', 'def_frame', 'slow_loop', 'floorplan.io', 'floorplan.macros', 'placement'},
+    'orfs_floorplan_handoff': {'cell_library', 'def_frame', 'slow_loop', 'floorplan.io', 'floorplan.macros'},  # 2_1
+}
+
+
+def missing(d, capability='orfs_handoff'):
+    """The facts a hand-off still needs (sorted)."""
+    return sorted(CAPABILITIES[capability] - d.present)
+
+
+def can(d, capability='orfs_handoff'):
+    return not missing(d, capability)
+
+
+def tier(d):
+    """A: an ORFS hand-off is possible (given a placement); B: a cell library, so export onto a DEF; C: neither."""
+    if CAPABILITIES['orfs_handoff'] - {'placement'} <= set(d.facts):
+        return 'A'
+    return 'B' if 'cell_library' in d.facts else 'C'
+
+
+def handoff_command(d, out_def, run_dir=None):
+    """The command that hands an exported DEF to an ORFS run of this design (run_dir: its WORK_HOME) and finishes the
+    flow there (spec 7.2). A floorplan (from ORFS 2_1) goes to ORFS only when it is legal (Design.floorplan_legal)."""
+    o = d.manifest.get('orfs')
+    fp = (o or {}).get('stage') == '2_1_floorplan'
+    cap = 'orfs_floorplan_handoff' if fp else 'orfs_handoff'
+    miss = missing(d, cap)
+    if miss:
+        raise MissingFacts(d.manifest.get('design', d.path), cap, miss)
+    if fp:
+        ok, issues = d.floorplan_legal()
+        if not ok:
+            raise ValueError('%s: the floorplan is not legal (%s); ORFS would not take it'
+                             % (d.manifest.get('design'), '; '.join(issues)))
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    key = o['design'] if o.get('platform', 'asap7') == 'asap7' else '%s/%s' % (o['platform'], o['design'])
+    run = run_dir or '<ORFS WORK_HOME of %s>' % key
+    if fp:                                 # the floorplan goes to ORFS, which places and routes from there
+        return 'python3 %s %s %s %s' % (os.path.relpath(os.path.join(root, 'tools', 'orfs_handoff.py')), key, run,
+                                        out_def)
+    return 'python3 %s %s %s def=%s --stage %s' % (os.path.relpath(os.path.join(root, 'tools', 'orfs_roundtrip.py')),
+                                                  key, run, out_def, o['stage'])