flow/designs: per-PDK WNS plots and README from rules-base.json

[oharboe]

What

Adds flow/util/plot_wns.py, a small local script (just python3, no bazel) that reads the committed rules-base.json baselines and regenerates two things, all committed so they render on GitHub with nothing to run:

1. Per-PDK WNS by design — flow/designs/<pdk>/wns.png + a ## WNS section in flow/designs/<pdk>/README.md (bar = finish WNS, markers = cts/globalroute). Covers all 9 PDKs with timing baselines (76 designs).

2. Cross-PDK WNS estimate accuracy — flow/designs/wns_accuracy.png + a ## WNS estimate accuracy across PDKs section in flow/designs/README.md. For each design, the per-stage estimate error (stage − finish) / clock_period (clock period parsed from the .sdc) so the PDKs are comparable; + = optimistic, − = pessimistic. 67 designs / 8 PDKs (designs with no cts/globalroute slack or no parsable period are omitted).

Run with:

python3 flow/util/plot_wns.py            # all PDKs + cross-PDK accuracy
python3 flow/util/plot_wns.py --pdk asap7

Regeneration is idempotent: generated content lives between markers, so hand-written findings prose is preserved.

Why

No OpenROAD/ORFS run is needed — the data already lives in the tree, so the plots are deterministic and the committed PNGs + tables render directly on GitHub. The goal is to share the code and the findings in a form that can be viewed and discussed online without running anything.

Findings

WNS estimate accuracy (cross-PDK):

• Global route usually tightens the estimate (MAE drops cts→globalroute): sky130hs 10.5%→1.9%, gt2n 3.3%→0.0%, gf12 2.2%→1.1%. ihp-sg13g2/gf180 are accurate already at cts.
• cts is biased optimistic everywhere (bias ≥ 0); globalroute over-corrects into pessimism for sky130hd (−3.5%), sky130hs, gf12, nangate45.
• sky130hd is the exception where routing makes the estimate worse (grt MAE 3.5% > cts 2.9%).
• Design-specific outliers dominate: sky130hs/gcd cts +45.9% (corrected by grt), asap7/swerv_wrapper +14.9% at both stages.

This is the design-level companion to the per-net GRT-vs-RCX divergence in flow/docs/rcx (#4302).

asap7 WNS by design:

All 18 asap7 designs close with negative setup slack; swerv_wrapper/mock-alu are ~10× the −15…−50 cluster.

Notes

• Only matplotlib (already pinned in flow/util/requirements_lock.txt) + stdlib.
• Designs without rules-base.json (e.g. asap7 minimal, rcx-fanout-*) are skipped; finish-only designs (e.g. gf55/aes) appear in the per-PDK view but not the accuracy view.
• Per-PDK WNS values are each PDK's native unit (ps/ns); the accuracy view is unitless (% of clock period), comparable across PDKs.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a Python script, plot_wns.py, to automatically parse worst setup slack (WNS) data from rules-base.json baselines and generate markdown tables and bar charts in the README files of various PDKs. The review feedback highlights three key areas for improvement: adding explicit encoding="utf-8" parameters to file operations to prevent encoding crashes on non-UTF-8 platforms (such as Windows), utilizing the defined FINISH_KEY constant within the STAGES list to eliminate unused code, and adding a type check to ensure the parsed JSON is a dictionary to avoid potential AttributeError crashes.

[gemini-code-assist]

The generated README files contain non-ASCII characters such as em-dashes (—) and almost-equal-to signs (≈). When running this script on platforms where the default system encoding is not UTF-8 (such as Windows), opening these files without explicitly specifying encoding="utf-8" will cause UnicodeDecodeError or UnicodeEncodeError crashes. Specifying encoding="utf-8" on both read and write operations prevents this.

Suggested change

	if os.path.isfile(readme_path):
	with open(readme_path) as f:
	text = f.read()
	if BEGIN in text and END in text:
	pre = text[: text.index(BEGIN)]
	post = text[text.index(END) + len(END):]
	new = pre + section + post.lstrip("\n")
	else:
	new = text.rstrip("\n") + "\n\n" + section
	else:
	new = f"# {pdk} designs\n\n" + section
	with open(readme_path, "w") as f:
	f.write(new)
	if os.path.isfile(readme_path):
	with open(readme_path, encoding="utf-8") as f:
	text = f.read()
	if BEGIN in text and END in text:
	pre = text[: text.index(BEGIN)]
	post = text[text.index(END) + len(END):]
	new = pre + section + post.lstrip("\n")
	else:
	new = text.rstrip("\n") + "\n\n" + section
	else:
	new = f"# {pdk} designs\n\n" + section
	with open(readme_path, "w", encoding="utf-8") as f:
	f.write(new)

[gemini-code-assist]

The constant FINISH_KEY is defined but never used in the script. It is cleaner and more maintainable to define it first and use it directly in the STAGES list to avoid hardcoding the string twice.

Suggested change

	# Stage key -> (short label, plot marker). Order is flow order.
	STAGES = [
	("cts__timing__setup__ws", "cts", "v"),
	("globalroute__timing__setup__ws", "globalroute", "^"),
	("finish__timing__setup__ws", "finish", None), # finish is drawn as the bar
	]
	FINISH_KEY = "finish__timing__setup__ws"
	FINISH_KEY = "finish__timing__setup__ws"
	# Stage key -> (short label, plot marker). Order is flow order.
	STAGES = [
	("cts__timing__setup__ws", "cts", "v"),
	("globalroute__timing__setup__ws", "globalroute", "^"),
	(FINISH_KEY, "finish", None), # finish is drawn as the bar
	]

[gemini-code-assist]

If rules-base.json is malformed or empty, json.load(f) could return a non-dictionary object (like a list or string). Calling data.get(key) would then raise an AttributeError, which is not caught by the except (OSError, ValueError) block and would crash the script. Additionally, specifying encoding="utf-8" when opening files is a best practice to ensure cross-platform compatibility (especially on Windows).

Suggested change

	try:
	with open(path) as f:
	data = json.load(f)
	except (OSError, ValueError):
	return None
	entry = data.get(key)
	if isinstance(entry, dict) and isinstance(entry.get("value"), (int, float)):
	return float(entry["value"])
	return None
	try:
	with open(path, encoding="utf-8") as f:
	data = json.load(f)
	except (OSError, ValueError):
	return None
	if not isinstance(data, dict):
	return None
	entry = data.get(key)
	if isinstance(entry, dict) and isinstance(entry.get("value"), (int, float)):
	return float(entry["value"])
	return None

[oharboe]

@maliberty grt is pretty accurate for the designs in ORFS... so the pathology I saw is not present there...