gpl: Fix overflow, sampling bias, and edge cases in MBFF KMeans, GetS…

[debayanbandyopadhyay]

Summary

1. Fix 32-bit float precision absorption, float-to-int cast overflow UB, and K-Means++ sampling bias in MBFF::KMeans:
   • Accumulate squared distances (tot_sum, cum_sum) and prob in double rather than 32-bit float to prevent mantissa absorption (> 1.67e7) on large clock domains (100k+ flops) and eliminate float-to-integer cast overflow UB even for extreme coordinates (tot_sum * 100.0 > INT64_MAX, or near the INT_MAX boundary where static_cast<float>(INT_MAX) rounds up to 2147483648.0f).
   • Use named constants (kLegacyProbScale = 100.0, kLargeDesignProbResolution = 1000000): preserve exact RNG modulo scaling for small designs (1.0 <= raw_scaled_sum <= INT_MAX), and combine two 15+ bit draws from next_rand() ((rand_hi << 15) ^ rand_lo) for uniform 6-digit fractional scaling (tot_sum * fraction) when raw_scaled_sum > INT_MAX so prob is not hard-capped at RAND_MAX / 100.0 (even when RAND_MAX == 32767).
   • Add a bounds-safe next_rand() helper that wraps rand_nums modulo rand_nums.size(), preserves the lower 31 bits of entropy (val & 0x7FFFFFFF) for negative 32-bit integers, guards against empty rand_nums, and keeps the RNG stream aligned when raw_scaled_sum < 1.0.
   • Update d[i] incrementally against centers.back().pt during K-Means++ center selection, reducing center initialization complexity from O(K^2 * N) to O(K * N).
2. Fix latent infinite loop when knn > num_flops:
   • Clamp actual_knn = std::min(knn, num_flops) in MBFF::KMeans (and return early if num_flops == 0 || knn <= 0).
   • Bound max_k = std::min(8, num_flops) and best_k = std::min(4, max_k) in MBFF::KMeansDecomp (and return early if num_flops < 2).
3. Guard silhouette score calculation against NaN and float::max() overflow:
   • Guard against 0.0f / 0.0f (NaN) and std::numeric_limits<float>::max() overflow in MBFF::GetSilh and MBFF::GetKSilh when flops or tray slots are co-located or when only a single tray/center exists.
4. Add unit tests and struct documentation:
   • Document Point, Tray, and Flop in src/gpl/src/mbff.h and add unit tests in src/gpl/test/mbff_test.cpp covering large/extreme distances, negative 32-bit rand_nums, co-located flops/slots, knn > num_flops, short/empty rand_nums, GetSilh, and GetKSilh.

Type of Change

• Bug fix

Impact

• Preserves exact RNG trajectory and clustering behavior on existing small designs where 1.0 <= tot_sum * 100.0 <= INT_MAX.
• Eliminates K-Means++ center-selection truncation bias and float mantissa absorption on large designs (tot_sum * 100.0 > INT_MAX) and reduces K-Means++ initialization from O(K^2 * N) to O(K * N).
• Prevents infinite loops when MBFF::KMeans or MBFF::KMeansDecomp is invoked on small flop partitions (num_flops < knn or num_flops < 8).
• Prevents NaN or float::max() silhouette scores in MBFF::GetSilh and MBFF::GetKSilh on co-located flops/slots or single-tray/single-center cases.

Verification

• I have verified that the local build succeeds (./etc/Build.sh / bazelisk).
• I have run the relevant tests and they pass (bazelisk test //src/gpl/test/... — 109 passed).
• My code follows the repository's formatting guidelines (git clang-format upstream/master).
• I have included tests to prevent regressions.
• I have signed my commits (DCO).

Related Issues

Follow-up to #11426

[gemini-code-assist]

Code Review

This pull request introduces several robustness improvements to the multi-bit flip-flop (MBFF) clustering algorithms, including guarding against division-by-zero and NaN cases in silhouette calculations, preventing infinite loops and integer overflows in K-Means++ when handling large designs or co-located flops, and using double-precision floats for distance accumulation. The reviewer suggested a valuable performance optimization in the K-Means center selection phase to update distances using only the latest center, which reduces the complexity from O(K^2 * N) to O(K * N).