[erendn]

Summary

This improves mpl (HierRTLMP) simulated annealing robustness, packing quality, and determinism across cluster placement (SACoreSoftMacro) and hard macro placement (SACoreHardMacro):

1. Per-Move Evaluation, -random_seed, and Diagnostic MPL-0003:

• Refactors SimulatedAnnealingCore::perturb() so every candidate move (packFloorplan(), singleSeqSwap(), doubleSeqSwap(), resizeOneCluster()) immediately calls packFloorplan(), keeping macro coordinates and width_/height_ synchronized with the Sequence Pair after every perturbation.
• Replaces the single-solution results_saved_ overwrite with true best-ever best_result_ tracking (best_cost_, best_pre_cost_, best_norm_*, best_seq_, best_macros_) updated whenever a valid/improved state is discovered and restored via useBestResult().
• Adds -random_seed (default 1) to rtl_macro_placer to thread deterministic base seeds across all SA workers without static RNG state, ensuring repeatable back-to-back runs within a single OpenROAD session.
• Expands MPL-0003 (SACoreSoftMacro::printResults()) to report exact cluster area vs. outline area (in $\mu\text{m}^2$) and excess percentage on failure.

2. CP-SAT Packing Oracle & Annealer Test Harness:

• Adds an exact OR-Tools CP-SAT 2D non-overlapping rectangle packing oracle (PackingOracle, //src/mpl/test:mpl_packing_oracle) with disjunctive interval constraints and a fast deadspace pre-filter.
• Adds a 60-instance deterministic packing corpus (src/mpl/test/testcases/packing_corpus.txt) and GTest suites (mpl_annealer_core_unittest, mpl_annealer_packing_unittest).

3. Relative Cooling Schedule, Patience Early-Stopping, and Incremental Wirelength:

• Replaces the step-based geometric cooling schedule with a relative progress-based geometric cooling schedule ($T(s) = T_{\text{init}} \cdot (T_{\text{min}} / T_{\text{init}})^{s/N}$) and bounded stagnation/patience early-stopping ($\max(500, \lceil 0.25 \cdot N \rceil)$ steps) gated on outline validity.
• Adds an $O(\text{incident nets})$ incremental wirelength delta cache (NetEndpointEntry, macro_to_nets_, cached_net_hpwl_) for swap and resize moves while keeping centralized full-recomputation verification in calNormCost().

4. Multi-Seed Cluster Placement, Fallback Recovery, and Common-Cost Candidate Selection:

• Expands HierRTLMP::runCoarseShaping() tilings with exact deadspace-free bounding boxes ($\sum A_i$) when child shapes have zero deadspace.
• Replaces the single-run placeMacro retry loop in HierRTLMP::updateMacroClusters() with a deterministic OpenMP parallel multi-seed sweep across valid utilization indices and 3 deterministic seeds per index, plus a two-stage high-budget fallback (2x steps with 1.5x outline penalty, then 4x steps with 2.0x outline penalty) when no outline-valid placement is found.
• Adds selectBestCandidateByCommonCost() so candidate SA workers with heterogeneous per-worker normalization baselines (norm_area_penalty_, norm_wl_, norm_guidance_cost_, norm_fence_cost_, norm_ macro_blockage_cost_, norm_notch_cost_) are compared on a unified common normalization baseline rather than raw per-worker normalized costs.

Type of Change

• Bug fix
• New feature
• Refactoring
• Documentation update

Impact

• CLI / Tcl: Adds optional -random_seed integer argument (default 1) to rtl_macro_placer. Existing scripts run unchanged.
• Determinism: Calling rtl_macro_placer multiple times in the same OpenROAD session now produces identical placements (//src/mpl/test:rerun1-tcl_test).
• Diagnostics: MPL-0003 now prints cluster area vs. outline area in $\mu\text{m}^2$ and excess percentage; adds MPL-0081, MPL-0082, and MPL-0083 for -random_seed validation and fallback recovery reporting.
• QoR & Runtime:
  • Improves packing feasibility on the 60-instance CP-SAT feasible benchmark corpus (mpl_annealer_packing_unittest) to 95.0% (SACoreHardMacro) and 91.7% (SACoreSoftMacro).
  • Across 16 macro-containing designs in OpenROAD-flow-scripts (asap7, gf180, ihp-sg13g2, nangate45, sky130hd, sky130hs), mpl completes with 0 errors, reduces mean mpl runtime by ~41% via patience early-stopping and incremental wirelength evaluation, and reduces post-MPL macro HPWL by up to 27.6% (nangate45/mempool_group) and 19.7% (nangate45/bp_fe).

Verification

• I have verified that the local build succeeds (./etc/Build.sh).
• I have run the relevant tests and they pass.
• My code follows the repository's formatting guidelines.
• I have included tests to prevent regressions.
• I have signed my commits (DCO).

Related Issues

#11807

[github-actions]

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[gemini-code-assist]

Code Review

This pull request introduces several enhancements to the macro placer, including an O(n log n) Fenwick tree-based floorplan packing algorithm, incremental wirelength calculations, relative cooling schedules, and multi-seed simulated annealing with common-cost candidate selection. It also exposes new parameters (-random_seed, -anneal_end_acceptance, -anneal_patience, and -placement_seeds) to the Tcl interface and adds comprehensive unit tests. A critical issue was identified in runSingleSeedClusterPlacement where run_id is never incremented, which prevents the exploration of higher utilization levels when running with fewer threads.

[oharboe]

@joaomai I added a CP SAT solver too to have a ground truth... It adds code and perhaps not part of production code, but this is the second time someone found CP SAT ground truth useful for evaluation RTL MP.