feat: add ML congestion/thermal prediction and deterministic P&R optimization tooling

[JayRaj21]

Intent

The developer wanted to augment (not modify) the P&R stage of an OpenROAD-flow-scripts (ORFS) design flow to demonstrate understanding of the flow, without touching the core routing/placement algorithms. They chose a deterministic (non-ML) approach for P&R augmentation, reserving ML for the existing thermal/congestion prediction work where no deterministic solver exists. Over the session they built and validated a stage-by-stage metrics aggregator (pr_metrics.py), a post-CTS timing repair hook, a triage agent to diagnose timing failures (e.g. the CTS→GRT parasitic underestimation cliff), and a closed-loop optimization agent (loop_agent.py) that autonomously diagnoses, applies config parameter fixes, re-runs affected flow stages via Docker, verifies improvement, and writes successful parameters back to config.mk. They required the implementation be verified with unit tests that need no API key or Docker, wanted all decisions/changes documented in a running dev log and memory for session continuity, and ultimately had the developer open a GitHub PR (#1) on their own fork for this pr-extension branch work, explicitly deferring further placement-stage and multi-design end-to-end testing to a follow-up session.

What Changed

• Added an ML pipeline under flow/ml/congestion/ for congestion and thermal prediction: GNN/U-Net models, training scripts, inference/evaluation/visualization tools, data collection utilities (feature/label extraction, batch/thermal extraction, variant generation), a Dockerfile, synthetic-data generators, and unit tests.
• Added deterministic P&R augmentation tooling under flow/util/ and flow/scripts/: pr_metrics.py (stage-by-stage metrics aggregator), triage_agent.py (timing-failure diagnosis), loop_agent.py with test_loop_agent.py (closed-loop config-fix/re-run/verify optimizer), compare_hook.sh, and new Tcl timing-repair hooks (post_cts_timing_repair.tcl, post_grt_timing_repair.tcl, timing_repair_common.tcl).
• Added supporting docs and config updates: PR_EXTENSION_DEV_LOG.md, create_pr.sh/create_pr_body.md, a thermal/overview findings PDF under docs/references/, a small flow/designs/nangate45/aes/config.mk change, and .gitignore/.gitmodules updates.

Risk Assessment

✅ Low: All three rounds of prior review findings (Make-injection value validation for both $( and ${ forms, Tcl hook deduplication, and behavioral regression tests) were correctly and completely implemented, verified by tracing the actual diffs against the shared timing_repair_common.tcl and loop_agent.py logic; the final commit in scope is a pure documentation/formatting sync with no functional changes.

Testing

All 28 tests in flow/util/test_loop_agent.py pass, including the new value-side blocklist regression tests for both $( and ${ Make-injection variants requested in review round 3, run end-to-end through validate_param_value() and write_config_params() with no API key or Docker required; the deduplicated Tcl timing-repair hooks (post_cts/post_grt wrappers over timing_repair_common.tcl) also parse without syntax errors under plain tclsh, the closest available check without a full OpenROAD/Docker environment.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• python3 -m pytest flow/util/test_loop_agent.py -v (28 passed) — includes the round-3-requested regression tests test_rejects_injected_value_dollar_paren, test_rejects_injected_value_dollar_brace, test_refuses_to_write_dollar_paren_injection, test_refuses_to_write_dollar_brace_injection which exercise validate_param_value()/write_config_params() end-to-end with '$(shell ...)' and '${shell ...}' payloads on an allowlisted param
• echo 'source "flow/scripts/post_cts_timing_repair.tcl"' | tclsh and same for post_grt_timing_repair.tcl and timing_repair_common.tcl — confirms the deduped shared-library refactor parses with no Tcl syntax errors (failure is only the expected 'invalid command name sta::worst_slack' since OpenROAD-specific procs aren't available outside the OpenROAD Tcl interpreter)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.