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

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-llvm-analysis

Author: Lee Wei (leewei05)

<details>
<summary>Changes</summary>

It took me some time to fully understand the implementation of Fourier–Motzkin elimination in the Constraint System, so I added an example in the comments. Hopefully future developers can understand the algorithm more easily with the example.



---
Full diff: https://github.com/llvm/llvm-project/pull/127351.diff


2 Files Affected:

- (modified) llvm/lib/Analysis/ConstraintSystem.cpp (+25-1) 
- (modified) llvm/lib/Transforms/Scalar/ConstraintElimination.cpp (+1-1) 


``````````diff
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; }

``````````

</details>


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