Add C++17 PERC Runtime Optimizer

PERC Runtime Optimizer/.gitignore

@@ -0,0 +1,3 @@
+perc_optimizer
+test_perc
+*.o

PERC Runtime Optimizer/Makefile

@@ -0,0 +1,34 @@
+CXX      ?= g++
+CXXFLAGS ?= -std=c++17 -O2 -Wall -Wextra -pthread -Iinclude
+LDFLAGS  ?= -pthread
+
+SRC := src/design.cpp src/generator.cpp src/checks.cpp src/metadata.cpp src/engine.cpp
+OBJ := $(SRC:.cpp=.o)
+
+.PHONY: all clean test bench run
+
+all: perc_optimizer test_perc
+
+perc_optimizer: $(OBJ) src/main.o
+	$(CXX) $(CXXFLAGS) -o $@ $^ $(LDFLAGS)
+
+test_perc: $(OBJ) tests/test_perc.o
+	$(CXX) $(CXXFLAGS) -o $@ $^ $(LDFLAGS)
+
+src/%.o: src/%.cpp
+	$(CXX) $(CXXFLAGS) -c -o $@ $<
+
+tests/%.o: tests/%.cpp
+	$(CXX) $(CXXFLAGS) -c -o $@ $<
+
+run: perc_optimizer
+	./perc_optimizer --pads 24 --blocks 6 --devices 200
+
+bench: perc_optimizer
+	./perc_optimizer --bench --eco --workers $$(nproc 2>/dev/null || echo 4)
+
+test: test_perc
+	./test_perc
+
+clean:
+	rm -f $(OBJ) src/main.o tests/test_perc.o perc_optimizer test_perc

PERC Runtime Optimizer/README.md

@@ -0,0 +1,62 @@
+# PERC Runtime Optimizer (C++)
+
+Educational C++17 project: understand **PERC** (Programmable Electrical Rules Checking) in physical design, and measure algorithmic ways to cut runtime.
+
+- **White paper (PDF):** [docs/PERC_Runtime_Optimizer_Whitepaper.pdf](docs/PERC_Runtime_Optimizer_Whitepaper.pdf)
+- Concept notes: [docs/PERC_OVERVIEW.md](docs/PERC_OVERVIEW.md)
+
+Regenerate the PDF: `python3 docs/generate_whitepaper.py` (requires `reportlab`).
+
+## What is implemented
+
+Synthetic hierarchical netlist + resistor-mesh stand-in for extracted parasitics, then PERC-like rules:
+
+| Check | Rule id |
+|-------|---------|
+| ESD clamp present on every IO pad | `ESD_CLAMP_MISSING` |
+| Floating MOSFET gates | `FLOATING_GATE` |
+| Pad→rail point-to-point resistance | `P2P_RESISTANCE_HIGH` / `P2P_PATH_MISSING` |
+| Simplified current-density along ESD path | `CURRENT_DENSITY` |
+
+Engines:
+
+| Mode | Idea |
+|------|------|
+| `baseline` | Full-chip, every rule, every time |
+| `roi` | Prune floating-gate work to ESD-relevant devices |
+| `hierarchical` | Per-block floating-gate + chip-level ESD/P2P/CD |
+| `parallel` | Multi-threaded pad-pair P2P/CD (`std::async`) |
+| `incremental` | Metadata cache keyed by scope fingerprint |
+| `optimized` | Hierarchical ROI + cache + parallel P2P/CD |
+
+This is **not** Calibre/ICV and does not run foundry decks. Geometry/extraction are abstracted as a weighted `RGraph` (Dijkstra).
+
+## Build
+
+```bash
+cd "PERC Runtime Optimizer"
+make -j
+make test
+```
+
+## Run
+
+```bash
+./perc_optimizer --pads 32 --blocks 8 --devices 400
+./perc_optimizer --bench --eco --workers 8
+```
+
+Flags: `--pads`, `--blocks`, `--devices`, `--workers`, `--eco`, `--bench`.
+
+## Layout
+
+```
+include/     design, checks, engines, generator, metadata
+src/         implementations + main CLI
+tests/       self-contained assertions
+docs/        PERC concepts
+```
+
+## Optimization takeaway
+
+Cold full-chip walks dominate when every MOSFET and every pad pair is visited. Speedups come from **not redoing unchanged work**: ROI nets, block scopes, fingerprint caches after ECO, and parallel P2P queries — the same levers used in production reliability flows (LDL / metadata reuse / hierarchy / multi-CPU).

PERC Runtime Optimizer/docs/PERC_OVERVIEW.md

@@ -0,0 +1,73 @@
+# PERC in Physical Design — Concepts & Why It Is Slow
+
+## What is PERC?
+
+**PERC (Programmable Electrical Rules Checking)** verifies IC reliability issues that **DRC** and **LVS** cannot catch. Rules are programmable because foundries and design houses customize ESD/EOS/ERC methodology per process and product.
+
+Industry tools: **Calibre PERC** (Siemens), **IC Validator PERC** (Synopsys).
+
+PERC sits in **physical verification / reliability signoff**, typically after LVS-clean layout (or on schematic netlists for early checks).
+
+---
+
+## The Four Check Families
+
+| Family | Inputs | What it verifies | Cost driver |
+|--------|--------|------------------|-------------|
+| **Netlist checks** | Schematic or extracted netlist | ESD clamp presence, floating gates, EOS/level-shifter topology, multi-power-domain rules | Graph traversal over huge netlists |
+| **Netlist-driven layout (LDL / NDL)** | Netlist + GDS | Voltage-aware spacing, geometry on *regions of interest* identified from connectivity | Finding ROI + geometry ops |
+| **Current density (CD)** | Layout + R-extraction + ESD path current | Metal can carry ESD current without melting / EM fail | Parasitic R mesh + current solve |
+| **Point-to-point (P2P) resistance** | Layout + R-extraction | ESD discharge path R is below limit so current takes the clamp path | Many source→sink R queries on resistor networks |
+
+All flows start with a **Netlist Analysis Engine** (the “programmable” core). Layout-heavy checks then call extraction (e.g. StarRC) on selected nets/paths.
+
+---
+
+## Typical ESD Flow (why wall-clock explodes)
+
+```
+Netlist / LVS extract
+        │
+        ▼
+ Netlist analysis  ──► clamp / diode / rail topology errors
+        │
+        ▼
+ Identify ESD paths & ROIs (pad → clamp → rail / ground)
+        │
+        ▼
+ R-extract only (ideally) those nets / polygons
+        │
+        ├──► P2P resistance checks (pad to clamp, clamp to rail, …)
+        └──► Current-density checks along discharge path
+```
+
+At full-chip SoC scale:
+
+- Millions–billions of devices/nets in the connectivity graph
+- Thousands of IO pads × many path endpoints → combinatorial P2P queries
+- Naïve flows **flatten** hierarchy and **re-extract** everything every ECO
+- Rule decks are deep (context-aware voltage propagation, multi-domain)
+
+That combination makes PERC one of the longest reliability signoff steps.
+
+---
+
+## Where Runtime Goes (and how to cut it)
+
+| Bottleneck | Optimization idea | What this C++ project models |
+|------------|-------------------|------------------------------|
+| Full-chip netlist walk every rule | Rule-aware **ROI pruning** | `run_roi` |
+| Re-running unchanged blocks after ECO | **Incremental metadata reuse** | `run_incremental` / `MetadataStore` |
+| Flat chip analysis | **Hierarchical partition** | `run_hierarchical` |
+| Sequential pad-pair P2P | **Parallel path queries** | `run_parallel` (`std::async`) |
+| Extracting entire design for CD/P2P | Extract **only marked ESD nets** (LDL) | ROI net set + pad-scoped Dijkstra |
+
+Commercial tools also use distributed multi-CPU scaling and foundry-tuned rule decks; those are orthogonal to the algorithmic wins above.
+
+---
+
+## What This Project Is (and Is Not)
+
+**Is:** A C++17 stand-in for PERC’s expensive cores — netlist topology checks + graph-based P2P resistance — with measurable baseline vs optimized runtimes on synthetic circuits.
+
+**Is not:** A replacement for Calibre / ICV, a foundry runset, or a full parasitic extractor. Geometry and StarRC-class extraction are abstracted as a weighted resistor graph (`RGraph` + Dijkstra).