gpl: per-region GPU density field for multi-region placement

gpl builds one NesterovBase per placement region (top-level core plus one per
power-domain / odb group) but a single shared NesterovBaseCommon with one GPU
DeviceState. The four FFT field Views (d_bin_density / d_bin_phi / d_bin_elec_*)
and the bin-grid metadata lived in that shared DeviceState and were overwritten
per region by DeviceState::initBinViews; the Nesterov loop also solves all
regions and only then gathers all regions, so with more than one region a
region's density solve read another region's (or a wrong-sized) bin buffer.
That is an out-of-bounds device access when the regions' bin counts differ, or
a silently wrong placement when they match (measured +119% HPWL on the dual
voltage-domain region01 design). Single-region placement was unaffected, so the
existing tests passed. Reported by a Codex review.

Move the per-region state into a new RegionDensityField (PIMPL, one per
NesterovBase, declared before fft_/density_grad_backend_ so it outlives the
backends that borrow it); it holds only the four field Views + bin metadata.
The shared DeviceState keeps the netlist/HPWL pool and the per-inst density
params + gather output, which are indexed by the global gCellStor instance id
and identical across regions; their allocation moves out of the old
initBinViews into the DeviceState constructor. Both GPU density paths are
repointed at the region field: the device-resident pipeline
(NesterovDeviceContext) and the host-staged FFT path (GpuFftBackend /
GpuDensityGradientBackend), the latter used in timing-driven / routability mode
where the device context is disabled -- which is why the field is owned by
NesterovBase rather than the device context.

Harden two previously-silent seams: the bin-count check in densitySolveIteration
now aborts in release builds (was a debug-only assert), and NesterovBase errors
out if a GPU region's bin grid is empty instead of silently using CPU density.

Add two GPU-only regression tests (CMake-only, like the other GPU tests):
region01_gpu (two same-size domains; the silent-interleaving case) and
region01_gpu_asym (different-size domains; the out-of-bounds case), each
checking the GPU total HPWL within 3% of the CPU reference and pinned to
ENABLE_GPU=1 so they cannot pass on the CPU backend.

Verified: CPU goldens unchanged (including multi-region CPU region01);
single-region GPU within 0.001% of CPU; multi-region GPU now within 0.7% /
0.28% of CPU (was +119%). Also trimmed redundant comments across the GPU path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Minjae Kim <develop.minjae@gmail.com>

Author: dev-minjae

src/gpl/BUILD

@@ -50,6 +50,7 @@ cc_library(
         "src/fftsg2d.cpp",
         "src/gpu/deviceState.h",
         "src/gpu/nesterovDeviceContext.h",
+        "src/gpu/regionDensityField.h",
         "src/graphicsNone.cpp",
         "src/hpwl.cpp",
         "src/hpwlBackend.h",

src/gpl/CMakeLists.txt

@@ -63,6 +63,7 @@ if(ENABLE_GPU)
     src/gpu/poissonSolver.cpp
     src/gpu/dct.cpp
     src/gpu/deviceState.cpp
+    src/gpu/regionDensityField.cpp
     src/gpu/gpuWirelengthGradientBackend.cpp
     src/gpu/wirelengthOp.cpp
     src/gpu/gpuDensityGradientBackend.cpp
@@ -89,6 +90,7 @@ if(ENABLE_GPU)
     set_source_files_properties(
       src/gpu/gpuHpwlBackend.cpp src/gpu/gpuRuntime.cpp src/gpu/gpuFftBackend.cpp
       src/gpu/poissonSolver.cpp src/gpu/dct.cpp src/gpu/deviceState.cpp
+      src/gpu/regionDensityField.cpp
       src/gpu/gpuWirelengthGradientBackend.cpp src/gpu/wirelengthOp.cpp
       src/gpu/gpuDensityGradientBackend.cpp src/gpu/densityOp.cpp
       src/gpu/nesterovOp.cpp src/gpu/nesterovDeviceContext.cpp
@@ -98,6 +100,7 @@ if(ENABLE_GPU)
     set_source_files_properties(
       src/gpu/gpuHpwlBackend.cpp src/gpu/gpuRuntime.cpp src/gpu/gpuFftBackend.cpp
       src/gpu/poissonSolver.cpp src/gpu/dct.cpp src/gpu/deviceState.cpp
+      src/gpu/regionDensityField.cpp
       src/gpu/gpuWirelengthGradientBackend.cpp src/gpu/wirelengthOp.cpp
       src/gpu/gpuDensityGradientBackend.cpp src/gpu/densityOp.cpp
       src/gpu/nesterovOp.cpp src/gpu/nesterovDeviceContext.cpp

src/gpl/src/backendContext.h

@@ -8,8 +8,8 @@
 // Each factory consumes the subset of fields it needs and ignores the rest;
 // callers build one context per construction site and reuse it across the
 // four factory calls. Plain C++ — Kokkos types are forward-declared elsewhere
-// and pointers (DeviceState*, NesterovBase*, NesterovBaseCommon*) are only
-// dereferenced inside backend translation units.
+// and pointers (DeviceState*, NesterovBase*, NesterovBaseCommon*,
+// RegionDensityField*) are only dereferenced inside backend translation units.
 
 #pragma once
 
@@ -18,15 +18,21 @@ namespace gpl {
 class DeviceState;
 class NesterovBase;
 class NesterovBaseCommon;
+class RegionDensityField;
 
 struct BackendContext
 {
   // Owning / context pointers. nbc is required by the wirelength gradient
   // backend; nb is required by the density gradient backend; device_state is
-  // borrowed by every GPU backend and ignored by the CPU backends.
+  // borrowed by the GPU HPWL, wirelength-gradient, and density-gradient
+  // backends (ignored by the CPU backends and by the GPU FFT backend, which
+  // uses region_field instead). region_field carries the per-region FFT field
+  // Views; borrowed by the GPU FFT and density-gradient backends (one per
+  // placement region), ignored by the CPU and wirelength/HPWL backends.
   NesterovBaseCommon* nbc = nullptr;
   NesterovBase* nb = nullptr;
   DeviceState* device_state = nullptr;
+  RegionDensityField* region_field = nullptr;
 
   // OpenMP fan-out for the CPU backends.
   int num_threads = 1;

src/gpl/src/densityGradient.cpp

@@ -16,6 +16,7 @@
 #include "gpu/deviceState.h"
 #include "gpu/gpuDensityGradientBackend.h"
 #include "gpu/gpuRuntime.h"
+#include "gpu/regionDensityField.h"
 #endif
 
 namespace gpl {
@@ -55,9 +56,10 @@ std::unique_ptr<DensityGradientBackend> makeDensityGradientBackend(
     const BackendContext& ctx)
 {
 #ifdef ENABLE_GPU
-  if (gpuEnabled() && ctx.device_state && ctx.device_state->numBins() > 0) {
-    return std::make_unique<GpuDensityGradientBackend>(ctx.nb,
-                                                       ctx.device_state);
+  if (gpuEnabled() && ctx.device_state && ctx.region_field
+      && ctx.region_field->numBins() > 0) {
+    return std::make_unique<GpuDensityGradientBackend>(
+        ctx.nb, ctx.device_state, ctx.region_field);
   }
 #endif
   return std::make_unique<CpuDensityGradientBackend>(ctx.nb);

src/gpl/src/fft.cpp

@@ -2,12 +2,9 @@
 // Copyright (c) 2018-2025, The OpenROAD Authors
 
 // FFT — the density-grid context — and CpuFftBackend, the Ooura DCT solver.
-//
-// FFT owns the staging grids and the backend-agnostic accessors; doFFT()
-// delegates to the FftBackend chosen at construction. CpuFftBackend (always
-// compiled) is the Ooura DCT. makeFftBackend() is the single place the runtime
-// backend choice is made: on an ENABLE_GPU build with the GPU path selected
-// (gpl::gpuEnabled()) it returns the Kokkos GpuFftBackend.
+// doFFT() delegates to the FftBackend chosen at construction. makeFftBackend()
+// makes that choice: GpuFftBackend on an ENABLE_GPU build with gpuEnabled(),
+// else the always-compiled CpuFftBackend (Ooura DCT).
 
 #include "fft.h"
 
@@ -205,7 +202,7 @@ std::unique_ptr<FftBackend> makeFftBackend(const BackendContext& ctx)
                                            ctx.bin_cnt_y,
                                            ctx.bin_size_x,
                                            ctx.bin_size_y,
-                                           ctx.device_state);
+                                           ctx.region_field);
   }
 #endif
   return std::make_unique<CpuFftBackend>(
@@ -217,14 +214,14 @@ BackendContext makeFftCtx(int bin_cnt_x,
                           int bin_cnt_y,
                           float bin_size_x,
                           float bin_size_y,
-                          DeviceState* device_state)
+                          RegionDensityField* region_field)
 {
   BackendContext ctx;
   ctx.bin_cnt_x = bin_cnt_x;
   ctx.bin_cnt_y = bin_cnt_y;
   ctx.bin_size_x = bin_size_x;
   ctx.bin_size_y = bin_size_y;
-  ctx.device_state = device_state;
+  ctx.region_field = region_field;
   return ctx;
 }
 }  // namespace
@@ -233,7 +230,7 @@ FFT::FFT(int bin_cnt_x,
          int bin_cnt_y,
          float bin_size_x,
          float bin_size_y,
-         DeviceState* device_state)
+         RegionDensityField* region_field)
     : bin_density_(static_cast<std::size_t>(bin_cnt_x) * bin_cnt_y, 0.0f),
       electro_phi_(static_cast<std::size_t>(bin_cnt_x) * bin_cnt_y, 0.0f),
       electro_field_x_(static_cast<std::size_t>(bin_cnt_x) * bin_cnt_y, 0.0f),
@@ -244,7 +241,7 @@ FFT::FFT(int bin_cnt_x,
                                          bin_cnt_y,
                                          bin_size_x,
                                          bin_size_y,
-                                         device_state)))
+                                         region_field)))
 {
 }
 

src/gpl/src/fft.h

@@ -11,21 +11,19 @@
 
 namespace gpl {
 
-class DeviceState;
+class RegionDensityField;
 
-// FFT — the density-grid context for the Poisson solve. It owns the staging
-// grids and the backend-agnostic accessors; the solve itself is delegated to
-// an FftBackend (the CPU Ooura DCT or the GPU Kokkos solver) selected at
-// construction by makeFftBackend(). Callers see one concrete class regardless
-// of backend.
+// FFT — the density-grid context for the Poisson solve. Owns the staging grids
+// and backend-agnostic accessors; the solve is delegated to an FftBackend (CPU
+// Ooura DCT or GPU Kokkos) chosen by makeFftBackend() at construction.
 class FFT
 {
  public:
   FFT(int bin_cnt_x,
       int bin_cnt_y,
       float bin_size_x,
       float bin_size_y,
-      DeviceState* device_state = nullptr);
+      RegionDensityField* region_field = nullptr);
   ~FFT();
 
   // input func
@@ -53,8 +51,7 @@ class FFT
   int bin_cnt_x_ = 0;
   int bin_cnt_y_ = 0;
 
-  // The Poisson solve backend (CPU Ooura or GPU Kokkos), selected at run time
-  // in the constructor. doFFT() delegates to it.
+  // Poisson solve backend (CPU Ooura or GPU Kokkos), chosen in the ctor.
   std::unique_ptr<FftBackend> backend_;
 };
 

src/gpl/src/fftBackend.h

@@ -63,9 +63,9 @@ struct BackendContext;
 
 // Factory: returns GpuFftBackend on an ENABLE_GPU build with the GPU path
 // selected at run time, otherwise CpuFftBackend. Consumes ctx.bin_cnt_x /
-// bin_cnt_y / bin_size_x / bin_size_y (grid geometry) and ctx.device_state
-// (GPU path; may be null for CPU path — GpuFftBackend borrows its bin Views
-// when available, falling back to self-owned Views).
+// bin_cnt_y / bin_size_x / bin_size_y (grid geometry) and ctx.region_field
+// (GPU path; may be null — GpuFftBackend borrows the region's bin Views when
+// available, falling back to self-owned Views).
 std::unique_ptr<FftBackend> makeFftBackend(const BackendContext& ctx);
 
 static_assert(!std::is_copy_constructible_v<FftBackend>);

src/gpl/src/gpu/dct.cpp

@@ -202,8 +202,6 @@ void dct_2d_fft(const int M,
       });
 }
 
-////////////////////////////////////////////////////////////////////////////////////
-
 void idct_2d_fft(
     const int M,
     const int N,

src/gpl/src/gpu/densityOp.cpp

@@ -17,6 +17,7 @@
 #include "deviceState_kokkos.h"
 #include "nesterovDeviceState.h"
 #include "poissonSolver.h"
+#include "regionDensityField_kokkos.h"
 
 namespace gpl {
 namespace densop {
@@ -49,6 +50,7 @@ CoordPair getSlpCoords(const KokkosNesterovState& ns, SlpSlot slot)
 }  // namespace
 
 void launchDensityGather(KokkosDeviceState& ds,
+                         const KokkosRegionDensityField& rdf,
                          int n_insts,
                          int bin_cnt_x,
                          int bin_cnt_y,
@@ -66,8 +68,8 @@ void launchDensityGather(KokkosDeviceState& ds,
   auto d_inst_density_half_dx = ds.d_inst_density_half_dx;
   auto d_inst_density_half_dy = ds.d_inst_density_half_dy;
   auto d_inst_density_scale = ds.d_inst_density_scale;
-  auto d_bin_elec_x = ds.d_bin_elec_x;
-  auto d_bin_elec_y = ds.d_bin_elec_y;
+  auto d_bin_elec_x = rdf.d_bin_elec_x;
+  auto d_bin_elec_y = rdf.d_bin_elec_y;
   auto d_inst_density_grad_x = ds.d_inst_density_grad_x;
   auto d_inst_density_grad_y = ds.d_inst_density_grad_y;
 
@@ -121,7 +123,6 @@ void launchDensityGather(KokkosDeviceState& ds,
 
         for (int bxi = min_bx; bxi < max_bx; ++bxi) {
           for (int byi = min_by; byi < max_by; ++byi) {
-            // Bin bounds.
             const int b_lx = glx + static_cast<int>(bxi * bsx);
             const int b_ly = gly + static_cast<int>(byi * bsy);
             const int b_ux = glx + static_cast<int>((bxi + 1) * bsx);
@@ -156,7 +157,7 @@ void launchDensityGather(KokkosDeviceState& ds,
 }
 
 void launchNbDensityScatter(KokkosNesterovState& ns,
-                            KokkosDeviceState& ds,
+                            KokkosRegionDensityField& rdf,
                             int n_cells,
                             SlpSlot src,
                             float& overflow_area,
@@ -258,7 +259,7 @@ void launchNbDensityScatter(KokkosNesterovState& ns,
 
   // Pass 2 — per-bin density write + overflow reductions. Mirrors the
   // tail loop of BinGrid::updateBinsGCellDensityArea.
-  auto d_bin_density = ds.d_bin_density;
+  auto d_bin_density = rdf.d_bin_density;
   auto d_bin_scaled_area = ns.d_bin_scaled_area;
   auto d_bin_nonplace = ns.d_bin_nonplace;
   auto d_bin_nonplace_unscaled = ns.d_bin_nonplace_unscaled;
@@ -295,7 +296,7 @@ void launchNbDensityScatter(KokkosNesterovState& ns,
 }
 
 void launchNbDensityGather(KokkosNesterovState& ns,
-                           const KokkosDeviceState& ds,
+                           const KokkosRegionDensityField& rdf,
                            int n_cells,
                            SlpSlot src)
 {
@@ -313,8 +314,8 @@ void launchNbDensityGather(KokkosNesterovState& ns,
   auto d_bin_ly = ns.d_bin_ly;
   auto d_bin_ux = ns.d_bin_ux;
   auto d_bin_uy = ns.d_bin_uy;
-  auto d_bin_elec_x = ds.d_bin_elec_x;
-  auto d_bin_elec_y = ds.d_bin_elec_y;
+  auto d_bin_elec_x = rdf.d_bin_elec_x;
+  auto d_bin_elec_y = rdf.d_bin_elec_y;
   auto d_grad_x = ns.d_density_grad_x;
   auto d_grad_y = ns.d_density_grad_y;
 
@@ -371,13 +372,14 @@ void launchNbDensityGather(KokkosNesterovState& ns,
       });
 }
 
-float launchNbSumPhi(const KokkosNesterovState& ns, const KokkosDeviceState& ds)
+float launchNbSumPhi(const KokkosNesterovState& ns,
+                     const KokkosRegionDensityField& rdf)
 {
   const int nbins = ns.bin_cnt_x * ns.bin_cnt_y;
   if (nbins == 0) {
     return 0.0f;
   }
-  auto d_bin_phi = ds.d_bin_phi;
+  auto d_bin_phi = rdf.d_bin_phi;
   auto d_bin_inst_area = ns.d_bin_inst_area;
   auto d_bin_filler_area = ns.d_bin_filler_area;
   auto d_bin_nonplace = ns.d_bin_nonplace;

src/gpl/src/gpu/densityOp.h

@@ -16,13 +16,16 @@ namespace gpl {
 
 struct KokkosDeviceState;
 struct KokkosNesterovState;
+struct KokkosRegionDensityField;
 
 namespace densop {
 
-// Per-inst density gradient gather: reads d_bin_elec_x/y (solver convention),
-// applies axis swap + 0.5× scale, accumulates overlap × field per overlapping
-// bin. Writes d_inst_density_grad_x/y.
+// Per-inst density gradient gather: reads the region's d_bin_elec_x/y (solver
+// convention) from `rdf`, applies axis swap + 0.5× scale, accumulates
+// overlap × field per overlapping bin using the per-inst params in `ds`.
+// Writes ds.d_inst_density_grad_x/y.
 void launchDensityGather(KokkosDeviceState& ds,
+                         const KokkosRegionDensityField& rdf,
                          int n_insts,
                          int bin_cnt_x,
                          int bin_cnt_y,
@@ -36,28 +39,28 @@ void launchDensityGather(KokkosDeviceState& ds,
 // Reads the float coords of `src`, truncates to int density centers (same
 // conversion as GCell::setDensityCenterLocation), accumulates per-bin areas
 // with int64 per-contribution truncation (bit-equal to the serial CPU sums),
-// writes ds.d_bin_density (FFT layout), and reduces the two overflow sums.
+// writes rdf.d_bin_density (FFT layout), and reduces the two overflow sums.
 void launchNbDensityScatter(KokkosNesterovState& ns,
-                            KokkosDeviceState& ds,
+                            KokkosRegionDensityField& rdf,
                             int n_cells,
                             SlpSlot src,
                             float& overflow_area,
                             float& overflow_area_unscaled);
 
 // NB-level density gradient gather for all nb cells (fillers included):
-// overlap-weighted sum of the bin electric field at the `src` coords.
+// overlap-weighted sum of the region bin electric field at the `src` coords.
 // Writes ns.d_density_grad_x/y directly (no host round-trip). Bin bounds
 // come from the exact per-bin ints (ns.d_bin_lx etc.), matching the CPU's
 // lround()-derived Bin geometry.
 void launchNbDensityGather(KokkosNesterovState& ns,
-                           const KokkosDeviceState& ds,
+                           const KokkosRegionDensityField& rdf,
                            int n_cells,
                            SlpSlot src);
 
 // Σ phi[bin] × float(nonPlace + instPlaced + filler) over all bins — the
 // sumPhi_ debug metric. Only call after launchNbDensityScatter + solve.
 float launchNbSumPhi(const KokkosNesterovState& ns,
-                     const KokkosDeviceState& ds);
+                     const KokkosRegionDensityField& rdf);
 
 }  // namespace densop
 }  // namespace gpl