[llvm] [ConstraintSystem] Update comments (PR #127351)

[Lee Wei via llvm-commits]

https://github.com/leewei05 updated https://github.com/llvm/llvm-project/pull/127351

>From ab925f1c6b52fdf75f086f32c7e01b6f71ca172f Mon Sep 17 00:00:00 2001
From: Lee <lee10202013 at gmail.com>
Date: Fri, 14 Feb 2025 13:37:33 -0700
Subject: [PATCH 1/2] Update comments

---
 llvm/lib/Analysis/ConstraintSystem.cpp        | 26 ++++++++++++++++++-
 .../Scalar/ConstraintElimination.cpp          |  2 +-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/llvm/lib/Analysis/ConstraintSystem.cpp b/llvm/lib/Analysis/ConstraintSystem.cpp
index 7216a0219080f..155d9f6bca883 100644
--- a/llvm/lib/Analysis/ConstraintSystem.cpp
+++ b/llvm/lib/Analysis/ConstraintSystem.cpp
@@ -8,10 +8,10 @@
 
 #include "llvm/Analysis/ConstraintSystem.h"
 #include "llvm/ADT/SmallVector.h"
-#include "llvm/Support/MathExtras.h"
 #include "llvm/ADT/StringExtras.h"
 #include "llvm/IR/Value.h"
 #include "llvm/Support/Debug.h"
+#include "llvm/Support/MathExtras.h"
 
 #include <string>
 
@@ -52,6 +52,12 @@ bool ConstraintSystem::eliminateUsingFM() {
   for (unsigned R1 = 0; R1 < NumRemainingConstraints; R1++) {
     // FIXME do not use copy
     for (unsigned R2 = R1 + 1; R2 < NumRemainingConstraints; R2++) {
+      // Examples of constraints stored as {Constant, Coeff_x, Coeff_y}
+      // R1:  0 >=  1 * x + (-2) * y  => { 0,  1, -2 }
+      // R2:  3 >=  2 * x +  3 * y    => { 3,  2,  3 }
+      // LastIdx = 2 (tracking coefficient of y)
+      // UpperLast: 3
+      // LowerLast: -2
       int64_t UpperLast = getLastCoefficient(RemainingRows[R2], LastIdx);
       int64_t LowerLast = getLastCoefficient(RemainingRows[R1], LastIdx);
       assert(
@@ -73,10 +79,13 @@ bool ConstraintSystem::eliminateUsingFM() {
       unsigned IdxLower = 0;
       auto &LowerRow = RemainingRows[LowerR];
       auto &UpperRow = RemainingRows[UpperR];
+      // Update constant and coefficients of both constraints.
+      // Stops until every coefficient is updated or overflow.
       while (true) {
         if (IdxUpper >= UpperRow.size() || IdxLower >= LowerRow.size())
           break;
         int64_t M1, M2, N;
+        // Starts with index 0 and updates every coefficients.
         int64_t UpperV = 0;
         int64_t LowerV = 0;
         uint16_t CurrentId = std::numeric_limits<uint16_t>::max();
@@ -92,6 +101,14 @@ bool ConstraintSystem::eliminateUsingFM() {
           IdxUpper++;
         }
 
+        // The new coefficient for CurrentId is
+        // N = UpperV * (-1) * LowerLast + LowerV * UpperLast
+        //
+        // LowerRow: { 0,  1, -2 }, UpperLast: 3
+        // UpperRow: { 3,  2,  3 }, LowerLast: -2
+        //
+        // Multiply by -1 is to ensure the last variable has opposite sign,
+        // so that it can be eliminated with addition.
         if (MulOverflow(UpperV, -1 * LowerLast, M1))
           return false;
         if (IdxLower < LowerRow.size() && LowerRow[IdxLower].Id == CurrentId) {
@@ -101,8 +118,15 @@ bool ConstraintSystem::eliminateUsingFM() {
 
         if (MulOverflow(LowerV, UpperLast, M2))
           return false;
+        // After multiplication:
+        // UpperRow: { 6, 4, 6 }
+        // LowerRow: { 0, 3, -6 }
+        //
+        // Eliminates y after addition:
+        // N: { 6, 7, 0 } => 6 >= 7 * x
         if (AddOverflow(M1, M2, N))
           return false;
+        // Skip variable that is completely eliminated.
         if (N == 0)
           continue;
         NR.emplace_back(N, CurrentId);
diff --git a/llvm/lib/Transforms/Scalar/ConstraintElimination.cpp b/llvm/lib/Transforms/Scalar/ConstraintElimination.cpp
index e0861fbedc560..8f379db1ca2fc 100644
--- a/llvm/lib/Transforms/Scalar/ConstraintElimination.cpp
+++ b/llvm/lib/Transforms/Scalar/ConstraintElimination.cpp
@@ -239,7 +239,7 @@ struct ConstraintTy {
   unsigned empty() const { return Coefficients.empty(); }
 
   /// Returns true if all preconditions for this list of constraints are
-  /// satisfied given \p CS and the corresponding \p Value2Index mapping.
+  /// satisfied given \p Info.
   bool isValid(const ConstraintInfo &Info) const;
 
   bool isEq() const { return IsEq; }

>From 723520a816d5538d6989a74f4ea91197bad9b923 Mon Sep 17 00:00:00 2001
From: Lee <lee10202013 at gmail.com>
Date: Fri, 4 Apr 2025 12:52:31 -0600
Subject: [PATCH 2/2] Fix nits

---
 llvm/lib/Analysis/ConstraintSystem.cpp | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/llvm/lib/Analysis/ConstraintSystem.cpp b/llvm/lib/Analysis/ConstraintSystem.cpp
index 155d9f6bca883..6457b6b425c6c 100644
--- a/llvm/lib/Analysis/ConstraintSystem.cpp
+++ b/llvm/lib/Analysis/ConstraintSystem.cpp
@@ -80,7 +80,7 @@ bool ConstraintSystem::eliminateUsingFM() {
       auto &LowerRow = RemainingRows[LowerR];
       auto &UpperRow = RemainingRows[UpperR];
       // Update constant and coefficients of both constraints.
-      // Stops until every coefficient is updated or overflow.
+      // Stops until every coefficient is updated or overflows.
       while (true) {
         if (IdxUpper >= UpperRow.size() || IdxLower >= LowerRow.size())
           break;
@@ -101,14 +101,6 @@ bool ConstraintSystem::eliminateUsingFM() {
           IdxUpper++;
         }
 
-        // The new coefficient for CurrentId is
-        // N = UpperV * (-1) * LowerLast + LowerV * UpperLast
-        //
-        // LowerRow: { 0,  1, -2 }, UpperLast: 3
-        // UpperRow: { 3,  2,  3 }, LowerLast: -2
-        //
-        // Multiply by -1 is to ensure the last variable has opposite sign,
-        // so that it can be eliminated with addition.
         if (MulOverflow(UpperV, -1 * LowerLast, M1))
           return false;
         if (IdxLower < LowerRow.size() && LowerRow[IdxLower].Id == CurrentId) {
@@ -118,6 +110,14 @@ bool ConstraintSystem::eliminateUsingFM() {
 
         if (MulOverflow(LowerV, UpperLast, M2))
           return false;
+        // This algorithm is a variant of sparse Gaussian elimination.
+        //
+        // The new coefficient for CurrentId is
+        // N = UpperV * (-1) * LowerLast + LowerV * UpperLast
+        //
+        // UpperRow: { 3,  2,  3 }, LowerLast: -2
+        // LowerRow: { 0,  1, -2 }, UpperLast: 3
+        //
         // After multiplication:
         // UpperRow: { 6, 4, 6 }
         // LowerRow: { 0, 3, -6 }