rsz,dpl: add ECO timing-closure command surface

[saurav-fermions]

Summary

Adds an additive, opt-in ECO (Engineering Change Order) timing-closure command
surface. No existing command's behavior changes: the default repair_timing /
report_checks / placement paths are unchanged unless one of the new commands is
invoked.

The 5 commits build up the surface in order:

1. begin_eco / write_eco / read_eco -- ECO capture-replay journal.
2. repair_timing_eco -- setup-repair ECO closure loop with an accurate change
   summary.
3. repair_hold_eco -- dedicated hold-violation repair.
4. improve_eco_legalization -- legalize only ECO-touched cells (dpl).
5. repair_timing_closure -- unified setup+hold convergence-loop driver that
   iterates the pieces above to convergence in a single command.

repair_timing_closure guarantees termination (bounded by -max_iters plus a
no-improvement detector), no setup regression (each iteration snapshots setup
WNS and rolls back via undo_eco if it worsens), and honors dont_touch
throughout.

Type of Change

• New feature (additive, opt-in)

Verification

• Local build succeeds.
• New tests pass: rsz.eco_round_trip, rsz.repair_timing_eco,
  rsz.repair_hold_eco, rsz.repair_timing_closure, dpl.eco_legalize (5/5).
• Additive: default flows unchanged unless a new command is invoked.
• clang-format + tclfmt clean.
• I have signed my commits (DCO).

Scope

ECO-only: src/rsz, src/dpl, src/OpenRoad.tcl, and tests. No src/sta
changes.

[gemini-code-assist]

Code Review

This pull request introduces ECO (Engineering Change Order) capture and replay capabilities to OpenROAD, including incremental legalization (improve_eco_legalization) and dedicated timing-closure loops (repair_timing_eco, repair_hold_eco, and repair_timing_closure). The review feedback highlights several critical improvements: allowing fractional micron values for -max_displacement validation, clamping converted displacement values to prevent truncation to zero, ensuring database rollback via undoEco if repair_hold_eco aborts, and skipping write_eco in repair_timing_closure if the loop was reverted.

[gemini-code-assist]

The -max_displacement argument is specified in microns (as evidenced by the subsequent conversion using ord::microns_to_dbu). However, the input validation uses sta::check_positive_integer, which restricts the user to integer micron values (e.g., 1 or 2 microns) and rejects perfectly valid fractional micron values (e.g., 0.5 or 1.5 microns).\n\nWe should allow positive floating-point numbers by validating using string is double and checking that the value is greater than zero.

    if { [llength $max_displacement] == 1 } {
      if { ![string is double -strict $max_displacement] || $max_displacement <= 0 } {
        utl::error DPL 1122 "-max_displacement must be a positive number."
      }
      set max_displacement_x $max_displacement
      set max_displacement_y $max_displacement
    } elseif { [llength $max_displacement] == 2 } {
      lassign $max_displacement max_displacement_x max_displacement_y
      if { ![string is double -strict $max_displacement_x] || $max_displacement_x <= 0 || ![string is double -strict $max_displacement_y] || $max_displacement_y <= 0 } {
        utl::error DPL 1122 "-max_displacement must be positive numbers."
      }

[gemini-code-assist]

When converting the user-specified -max_displacement from microns to sites/rows, a very small positive value (e.g., 0.01 microns) can truncate to 0 due to integer division. If either max_displacement_x or max_displacement_y becomes 0, the C++ implementation (ecoLegalizePlacement) interprets this as "not specified" and resets both to their default values (20 sites and 4 rows). This completely defeats the user's intent of restricting cell movement to a very tight window.\n\nTo prevent this, we should:\n1. Ensure the converted values are integers by wrapping the expression in int(...).\n2. Clamp the minimum converted value to 1 so that a very small user-specified displacement does not truncate to 0 and trigger the default reset.

    set max_displacement_x [expr {
      int([ord::microns_to_dbu $max_displacement_x] / [$site getWidth])
    }]
    set max_displacement_y [expr {
      int([ord::microns_to_dbu $max_displacement_y] / [$site getHeight])
    }]
    if { $max_displacement_x < 1 } { set max_displacement_x 1 }
    if { $max_displacement_y < 1 } { set max_displacement_y 1 }

[gemini-code-assist]

If repair_hold_eco aborts because hold repair degraded setup WNS, the ECO changes are left in the database and the ECO journal remains open. If the user catches the Tcl error to handle it gracefully, the design is left in a degraded state.\n\nWe should call odb::dbDatabase_undoEco $block to roll back the changes before raising the error.

  set setup_eps 1e-12
  if { $setup_wns_after < [expr { $setup_wns0 - $setup_eps }] } {
    odb::dbDatabase_undoEco $block
    utl::error RSZ 245 [format "hold repair degraded setup WNS from %.4g to %.4g; aborting." $setup_wns_before $setup_wns_after]
  }

[gemini-code-assist]

If the closure loop was aborted and rolled back due to setup regression (stop_reason is setup_regression_reverted), the ECO journal has already been completely undone via odb::dbDatabase_undoEco. Attempting to call write_eco in this state will either fail (since the ECO session was undone) or write an empty/baseline ECO file, which is misleading.\n\nWe should only write the ECO file if the loop did not revert the ECO.

  if { $eco_file ne "" && $stop_reason ne "setup_regression_reverted" } {
    write_eco $eco_file
    utl::report "ECO change set written ([file tail $eco_file])"
  }

[gudeh]

We should modify our default legalizer to negotiation legalizer soon.

[gudeh]

Just leaving a comment for now. I still want to understand why we need a different DPL behavior for this. I assume it is due to movable instances.

[saurav-fermions]

Thanks for the review — addressed all four findings in the latest commit (ddafe62):

1. -max_displacement validation (Opendp.tcl): switched to check_positive_float, so fractional microns (e.g. 0.5) are accepted. Verified check_positive_float 0.5 passes where check_positive_integer 0.5 errored (STA-0574).
2. micron→site/row truncation: the converted counts are now floored to max(1, …), so a small positive request can't truncate to 0 (which the C++ treats as unset and resets to the defaults).
3. repair_hold_eco rollback: on a setup-WNS regression it now calls odb::dbDatabase_undoEco (and refreshes parasitics) before raising, so a caught error leaves the design in its pre-repair state rather than degraded with the ECO journal still open.
4. repair_timing_closure write_eco: skipped when the loop reverted to baseline (the journal was already undone), instead of writing an empty/misleading ECO file.

All 5 ECO tests still pass. @gudeh — agreed on moving to the negotiation legalizer; happy to follow up on that separately since it's broader than this PR.