1 //===- AffineStructures.h - MLIR Affine Structures Class --------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // Structures for affine/polyhedral analysis of ML functions.
10 //
11 //===----------------------------------------------------------------------===//
13 #ifndef MLIR_ANALYSIS_AFFINE_STRUCTURES_H
14 #define MLIR_ANALYSIS_AFFINE_STRUCTURES_H
16 #include "mlir/Analysis/Presburger/Matrix.h"
17 #include "mlir/IR/AffineExpr.h"
18 #include "mlir/IR/OpDefinition.h"
19 #include "mlir/Support/LogicalResult.h"
21 namespace mlir {
23 class AffineCondition;
24 class AffineForOp;
25 class AffineIfOp;
26 class AffineMap;
27 class AffineValueMap;
28 class IntegerSet;
29 class MLIRContext;
30 class Value;
31 class MemRefType;
32 struct MutableAffineMap;
34 /// A flat list of affine equalities and inequalities in the form.
35 /// Inequality: c_0*x_0 + c_1*x_1 + .... + c_{n-1}*x_{n-1} >= 0
36 /// Equality: c_0*x_0 + c_1*x_1 + .... + c_{n-1}*x_{n-1} == 0
37 ///
38 /// FlatAffineConstraints stores coefficients in a contiguous buffer (one buffer
39 /// for equalities and one for inequalities). The size of each buffer is
40 /// numReservedCols * number of inequalities (or equalities). The reserved size
41 /// is numReservedCols * numReservedInequalities (or numReservedEqualities). A
42 /// coefficient (r, c) lives at the location numReservedCols * r + c in the
43 /// buffer. The extra space between getNumCols() and numReservedCols exists to
44 /// prevent frequent movement of data when adding columns, especially at the
45 /// end.
46 ///
47 /// The identifiers x_0, x_1, ... appear in the order: dimensional identifiers,
48 /// symbolic identifiers, and local identifiers.  The local identifiers
49 /// correspond to local/internal variables created when converting from
50 /// AffineExpr's containing mod's and div's; they are thus needed to increase
51 /// representational power. Each local identifier is always (by construction) a
52 /// floordiv of a pure add/mul affine function of dimensional, symbolic, and
53 /// other local identifiers, in a non-mutually recursive way. Hence, every local
54 /// identifier can ultimately always be recovered as an affine function of
55 /// dimensional and symbolic identifiers (involving floordiv's); note however
56 /// that some floordiv combinations are converted to mod's by AffineExpr
57 /// construction.
58 ///
59 class FlatAffineConstraints {
60 public:
61   enum IdKind { Dimension, Symbol, Local };
63   /// Constructs a constraint system reserving memory for the specified number
64   /// of constraints and identifiers..
65   FlatAffineConstraints(unsigned numReservedInequalities,
66                         unsigned numReservedEqualities,
67                         unsigned numReservedCols, unsigned numDims = 0,
68                         unsigned numSymbols = 0, unsigned numLocals = 0,
69                         ArrayRef<Optional<Value>> idArgs = {})
70       : numReservedCols(numReservedCols), numDims(numDims),
71         numSymbols(numSymbols) {
72     assert(numReservedCols >= numDims + numSymbols + 1);
73     assert(idArgs.empty() || idArgs.size() == numDims + numSymbols + numLocals);
74     equalities.reserve(numReservedCols * numReservedEqualities);
75     inequalities.reserve(numReservedCols * numReservedInequalities);
76     numIds = numDims + numSymbols + numLocals;
77     ids.reserve(numReservedCols);
78     if (idArgs.empty())
79       ids.resize(numIds, None);
80     else
81       ids.append(idArgs.begin(), idArgs.end());
82   }
84   /// Constructs a constraint system with the specified number of
85   /// dimensions and symbols.
86   FlatAffineConstraints(unsigned numDims = 0, unsigned numSymbols = 0,
87                         unsigned numLocals = 0,
88                         ArrayRef<Optional<Value>> idArgs = {})
89       : numReservedCols(numDims + numSymbols + numLocals + 1), numDims(numDims),
90         numSymbols(numSymbols) {
91     assert(numReservedCols >= numDims + numSymbols + 1);
92     assert(idArgs.empty() || idArgs.size() == numDims + numSymbols + numLocals);
93     numIds = numDims + numSymbols + numLocals;
94     ids.reserve(numIds);
95     if (idArgs.empty())
96       ids.resize(numIds, None);
97     else
98       ids.append(idArgs.begin(), idArgs.end());
99   }
101   /// Return a system with no constraints, i.e., one which is satisfied by all
102   /// points.
103   static FlatAffineConstraints getUniverse(unsigned numDims = 0,
104                                            unsigned numSymbols = 0) {
105     return FlatAffineConstraints(numDims, numSymbols);
106   }
108   /// Create a flat affine constraint system from an AffineValueMap or a list of
109   /// these. The constructed system will only include equalities.
110   explicit FlatAffineConstraints(const AffineValueMap &avm);
111   explicit FlatAffineConstraints(ArrayRef<const AffineValueMap *> avmRef);
113   /// Creates an affine constraint system from an IntegerSet.
114   explicit FlatAffineConstraints(IntegerSet set);
116   FlatAffineConstraints(const FlatAffineConstraints &other);
118   FlatAffineConstraints(ArrayRef<const AffineValueMap *> avmRef,
119                         IntegerSet set);
121   FlatAffineConstraints(const MutableAffineMap &map);
123   ~FlatAffineConstraints() {}
125   // Clears any existing data and reserves memory for the specified constraints.
126   void reset(unsigned numReservedInequalities, unsigned numReservedEqualities,
127              unsigned numReservedCols, unsigned numDims, unsigned numSymbols,
128              unsigned numLocals = 0, ArrayRef<Value> idArgs = {});
130   void reset(unsigned numDims = 0, unsigned numSymbols = 0,
131              unsigned numLocals = 0, ArrayRef<Value> idArgs = {});
133   /// Appends constraints from 'other' into this. This is equivalent to an
134   /// intersection with no simplification of any sort attempted.
135   void append(const FlatAffineConstraints &other);
137   /// Checks for emptiness by performing variable elimination on all
138   /// identifiers, running the GCD test on each equality constraint, and
139   /// checking for invalid constraints. Returns true if the GCD test fails for
140   /// any equality, or if any invalid constraints are discovered on any row.
141   /// Returns false otherwise.
142   bool isEmpty() const;
144   /// Runs the GCD test on all equality constraints. Returns 'true' if this test
145   /// fails on any equality. Returns 'false' otherwise.
146   /// This test can be used to disprove the existence of a solution. If it
147   /// returns true, no integer solution to the equality constraints can exist.
148   bool isEmptyByGCDTest() const;
150   /// Runs the GCD test heuristic. If it proves inconclusive, falls back to
151   /// generalized basis reduction if the set is bounded.
152   ///
153   /// Returns true if the set of constraints is found to have no solution,
154   /// false if a solution exists or all tests were inconclusive.
155   bool isIntegerEmpty() const;
157   // Returns a matrix where each row is a vector along which the polytope is
158   // bounded. The span of the returned vectors is guaranteed to contain all
159   // such vectors. The returned vectors are NOT guaranteed to be linearly
160   // independent. This function should not be called on empty sets.
161   Matrix getBoundedDirections() const;
163   /// Find a sample point satisfying the constraints. This uses a branch and
164   /// bound algorithm with generalized basis reduction, which always works if
165   /// the set is bounded. This should not be called for unbounded sets.
166   ///
167   /// Returns such a point if one exists, or an empty Optional otherwise.
168   Optional<SmallVector<int64_t, 8>> findIntegerSample() const;
170   /// Returns true if the given point satisfies the constraints, or false
171   /// otherwise.
172   bool containsPoint(ArrayRef<int64_t> point) const;
174   // Clones this object.
175   std::unique_ptr<FlatAffineConstraints> clone() const;
177   /// Returns the value at the specified equality row and column.
178   inline int64_t atEq(unsigned i, unsigned j) const {
179     return equalities[i * numReservedCols + j];
180   }
181   inline int64_t &atEq(unsigned i, unsigned j) {
182     return equalities[i * numReservedCols + j];
183   }
185   inline int64_t atIneq(unsigned i, unsigned j) const {
186     return inequalities[i * numReservedCols + j];
187   }
189   inline int64_t &atIneq(unsigned i, unsigned j) {
190     return inequalities[i * numReservedCols + j];
191   }
193   /// Returns the number of columns in the constraint system.
194   inline unsigned getNumCols() const { return numIds + 1; }
196   inline unsigned getNumEqualities() const {
197     assert(equalities.size() % numReservedCols == 0 &&
198            "inconsistent equality buffer size");
199     return equalities.size() / numReservedCols;
200   }
202   inline unsigned getNumInequalities() const {
203     assert(inequalities.size() % numReservedCols == 0 &&
204            "inconsistent inequality buffer size");
205     return inequalities.size() / numReservedCols;
206   }
208   inline unsigned getNumReservedEqualities() const {
209     return equalities.capacity() / numReservedCols;
210   }
212   inline unsigned getNumReservedInequalities() const {
213     return inequalities.capacity() / numReservedCols;
214   }
216   inline ArrayRef<int64_t> getEquality(unsigned idx) const {
217     return ArrayRef<int64_t>(&equalities[idx * numReservedCols], getNumCols());
218   }
220   inline ArrayRef<int64_t> getInequality(unsigned idx) const {
221     return ArrayRef<int64_t>(&inequalities[idx * numReservedCols],
222                              getNumCols());
223   }
225   /// Adds constraints (lower and upper bounds) for the specified 'affine.for'
226   /// operation's Value using IR information stored in its bound maps. The
227   /// right identifier is first looked up using forOp's Value. Asserts if the
228   /// Value corresponding to the 'affine.for' operation isn't found in the
229   /// constraint system. Returns failure for the yet unimplemented/unsupported
230   /// cases.  Any new identifiers that are found in the bound operands of the
231   /// 'affine.for' operation are added as trailing identifiers (either
232   /// dimensional or symbolic depending on whether the operand is a valid
233   /// symbol).
234   //  TODO: add support for non-unit strides.
235   LogicalResult addAffineForOpDomain(AffineForOp forOp);
237   /// Adds constraints imposed by the `affine.if` operation. These constraints
238   /// are collected from the IntegerSet attached to the given `affine.if`
239   /// instance argument (`ifOp`). It is asserted that:
240   /// 1) The IntegerSet of the given `affine.if` instance should not contain
241   /// semi-affine expressions,
242   /// 2) The columns of the constraint system created from `ifOp` should match
243   /// the columns in the current one regarding numbers and values.
244   void addAffineIfOpDomain(AffineIfOp ifOp);
246   /// Adds a lower or an upper bound for the identifier at the specified
247   /// position with constraints being drawn from the specified bound map and
248   /// operands. If `eq` is true, add a single equality equal to the bound map's
249   /// first result expr.
250   LogicalResult addLowerOrUpperBound(unsigned pos, AffineMap boundMap,
251                                      ValueRange operands, bool eq,
252                                      bool lower = true);
254   /// Returns the bound for the identifier at `pos` from the inequality at
255   /// `ineqPos` as a 1-d affine value map (affine map + operands). The returned
256   /// affine value map can either be a lower bound or an upper bound depending
257   /// on the sign of atIneq(ineqPos, pos). Asserts if the row at `ineqPos` does
258   /// not involve the `pos`th identifier.
259   void getIneqAsAffineValueMap(unsigned pos, unsigned ineqPos,
260                                AffineValueMap &vmap,
261                                MLIRContext *context) const;
263   /// Returns the constraint system as an integer set. Returns a null integer
264   /// set if the system has no constraints, or if an integer set couldn't be
265   /// constructed as a result of a local variable's explicit representation not
266   /// being known and such a local variable appearing in any of the constraints.
267   IntegerSet getAsIntegerSet(MLIRContext *context) const;
269   /// Computes the lower and upper bounds of the first 'num' dimensional
270   /// identifiers (starting at 'offset') as an affine map of the remaining
271   /// identifiers (dimensional and symbolic). This method is able to detect
272   /// identifiers as floordiv's and mod's of affine expressions of other
273   /// identifiers with respect to (positive) constants. Sets bound map to a
274   /// null AffineMap if such a bound can't be found (or yet unimplemented).
275   void getSliceBounds(unsigned offset, unsigned num, MLIRContext *context,
276                       SmallVectorImpl<AffineMap> *lbMaps,
277                       SmallVectorImpl<AffineMap> *ubMaps);
279   /// Adds slice lower bounds represented by lower bounds in 'lbMaps' and upper
280   /// bounds in 'ubMaps' to each identifier in the constraint system which has
281   /// a value in 'values'. Note that both lower/upper bounds share the same
282   /// operand list 'operands'.
283   /// This function assumes 'values.size' == 'lbMaps.size' == 'ubMaps.size'.
284   /// Note that both lower/upper bounds use operands from 'operands'.
285   LogicalResult addSliceBounds(ArrayRef<Value> values,
286                                ArrayRef<AffineMap> lbMaps,
287                                ArrayRef<AffineMap> ubMaps,
288                                ArrayRef<Value> operands);
290   // Adds an inequality (>= 0) from the coefficients specified in inEq.
291   void addInequality(ArrayRef<int64_t> inEq);
292   // Adds an equality from the coefficients specified in eq.
293   void addEquality(ArrayRef<int64_t> eq);
295   /// Adds a constant lower bound constraint for the specified identifier.
296   void addConstantLowerBound(unsigned pos, int64_t lb);
297   /// Adds a constant upper bound constraint for the specified identifier.
298   void addConstantUpperBound(unsigned pos, int64_t ub);
300   /// Adds a new local identifier as the floordiv of an affine function of other
301   /// identifiers, the coefficients of which are provided in 'dividend' and with
302   /// respect to a positive constant 'divisor'. Two constraints are added to the
303   /// system to capture equivalence with the floordiv:
304   /// q = dividend floordiv c    <=>   c*q <= dividend <= c*q + c - 1.
305   void addLocalFloorDiv(ArrayRef<int64_t> dividend, int64_t divisor);
307   /// Adds a constant lower bound constraint for the specified expression.
308   void addConstantLowerBound(ArrayRef<int64_t> expr, int64_t lb);
309   /// Adds a constant upper bound constraint for the specified expression.
310   void addConstantUpperBound(ArrayRef<int64_t> expr, int64_t ub);
312   /// Sets the identifier at the specified position to a constant.
313   void setIdToConstant(unsigned pos, int64_t val);
315   /// Sets the identifier corresponding to the specified Value id to a
316   /// constant. Asserts if the 'id' is not found.
317   void setIdToConstant(Value id, int64_t val);
319   /// Looks up the position of the identifier with the specified Value. Returns
320   /// true if found (false otherwise). `pos' is set to the (column) position of
321   /// the identifier.
322   bool findId(Value id, unsigned *pos) const;
324   /// Returns true if an identifier with the specified Value exists, false
325   /// otherwise.
326   bool containsId(Value id) const;
328   /// Swap the posA^th identifier with the posB^th identifier.
329   void swapId(unsigned posA, unsigned posB);
331   // Add identifiers of the specified kind - specified positions are relative to
332   // the kind of identifier. The coefficient column corresponding to the added
333   // identifier is initialized to zero. 'id' is the Value corresponding to the
334   // identifier that can optionally be provided.
335   void addDimId(unsigned pos, Value id = nullptr);
336   void addSymbolId(unsigned pos, Value id = nullptr);
337   void addLocalId(unsigned pos);
338   void addId(IdKind kind, unsigned pos, Value id = nullptr);
340   /// Add the specified values as a dim or symbol id depending on its nature, if
341   /// it already doesn't exist in the system. `id' has to be either a terminal
342   /// symbol or a loop IV, i.e., it cannot be the result affine.apply of any
343   /// symbols or loop IVs. The identifier is added to the end of the existing
344   /// dims or symbols. Additional information on the identifier is extracted
345   /// from the IR and added to the constraint system.
346   void addInductionVarOrTerminalSymbol(Value id);
348   /// Composes the affine value map with this FlatAffineConstrains, adding the
349   /// results of the map as dimensions at the front [0, vMap->getNumResults())
350   /// and with the dimensions set to the equalities specified by the value map.
351   /// Returns failure if the composition fails (when vMap is a semi-affine map).
352   /// The vMap's operand Value's are used to look up the right positions in
353   /// the FlatAffineConstraints with which to associate. The dimensional and
354   /// symbolic operands of vMap should match 1:1 (in the same order) with those
355   /// of this constraint system, but the latter could have additional trailing
356   /// operands.
357   LogicalResult composeMap(const AffineValueMap *vMap);
359   /// Composes an affine map whose dimensions match one to one to the
360   /// dimensions of this FlatAffineConstraints. The results of the map 'other'
361   /// are added as the leading dimensions of this constraint system. Returns
362   /// failure if 'other' is a semi-affine map.
363   LogicalResult composeMatchingMap(AffineMap other);
365   /// Projects out (aka eliminates) 'num' identifiers starting at position
366   /// 'pos'. The resulting constraint system is the shadow along the dimensions
367   /// that still exist. This method may not always be integer exact.
368   // TODO: deal with integer exactness when necessary - can return a value to
369   // mark exactness for example.
370   void projectOut(unsigned pos, unsigned num);
371   inline void projectOut(unsigned pos) { return projectOut(pos, 1); }
373   /// Projects out the identifier that is associate with Value .
374   void projectOut(Value id);
376   /// Removes the specified identifier from the system.
377   void removeId(unsigned pos);
379   void removeEquality(unsigned pos);
380   void removeInequality(unsigned pos);
382   /// Changes the partition between dimensions and symbols. Depending on the new
383   /// symbol count, either a chunk of trailing dimensional identifiers becomes
384   /// symbols, or some of the leading symbols become dimensions.
385   void setDimSymbolSeparation(unsigned newSymbolCount);
387   /// Changes all symbol identifiers which are loop IVs to dim identifiers.
388   void convertLoopIVSymbolsToDims();
390   /// Sets the specified identifier to a constant and removes it.
391   void setAndEliminate(unsigned pos, int64_t constVal);
393   /// Tries to fold the specified identifier to a constant using a trivial
394   /// equality detection; if successful, the constant is substituted for the
395   /// identifier everywhere in the constraint system and then removed from the
396   /// system.
397   LogicalResult constantFoldId(unsigned pos);
399   /// This method calls constantFoldId for the specified range of identifiers,
400   /// 'num' identifiers starting at position 'pos'.
401   void constantFoldIdRange(unsigned pos, unsigned num);
403   /// Updates the constraints to be the smallest bounding (enclosing) box that
404   /// contains the points of 'this' set and that of 'other', with the symbols
405   /// being treated specially. For each of the dimensions, the min of the lower
406   /// bounds (symbolic) and the max of the upper bounds (symbolic) is computed
407   /// to determine such a bounding box. `other' is expected to have the same
408   /// dimensional identifiers as this constraint system (in the same order).
409   ///
410   /// Eg: if 'this' is {0 <= d0 <= 127}, 'other' is {16 <= d0 <= 192}, the
411   ///      output is {0 <= d0 <= 192}.
412   /// 2) 'this' = {s0 + 5 <= d0 <= s0 + 20}, 'other' is {s0 + 1 <= d0 <= s0 +
413   ///     9}, output = {s0 + 1 <= d0 <= s0 + 20}.
414   /// 3) 'this' = {0 <= d0 <= 5, 1 <= d1 <= 9}, 'other' = {2 <= d0 <= 6, 5 <= d1
415   ///     <= 15}, output = {0 <= d0 <= 6, 1 <= d1 <= 15}.
416   LogicalResult unionBoundingBox(const FlatAffineConstraints &other);
418   /// Returns 'true' if this constraint system and 'other' are in the same
419   /// space, i.e., if they are associated with the same set of identifiers,
420   /// appearing in the same order. Returns 'false' otherwise.
421   bool areIdsAlignedWithOther(const FlatAffineConstraints &other);
423   /// Merge and align the identifiers of 'this' and 'other' starting at
424   /// 'offset', so that both constraint systems get the union of the contained
425   /// identifiers that is dimension-wise and symbol-wise unique; both
426   /// constraint systems are updated so that they have the union of all
427   /// identifiers, with this's original identifiers appearing first followed by
428   /// any of other's identifiers that didn't appear in 'this'. Local
429   /// identifiers of each system are by design separate/local and are placed
430   /// one after other (this's followed by other's).
431   //  Eg: Input: 'this'  has ((%i %j) [%M %N])
432   //             'other' has (%k, %j) [%P, %N, %M])
433   //      Output: both 'this', 'other' have (%i, %j, %k) [%M, %N, %P]
434   //
435   void mergeAndAlignIdsWithOther(unsigned offset, FlatAffineConstraints *other);
437   unsigned getNumConstraints() const {
438     return getNumInequalities() + getNumEqualities();
439   }
440   inline unsigned getNumIds() const { return numIds; }
441   inline unsigned getNumDimIds() const { return numDims; }
442   inline unsigned getNumSymbolIds() const { return numSymbols; }
443   inline unsigned getNumDimAndSymbolIds() const { return numDims + numSymbols; }
444   inline unsigned getNumLocalIds() const {
445     return numIds - numDims - numSymbols;
446   }
448   inline ArrayRef<Optional<Value>> getIds() const {
449     return {ids.data(), ids.size()};
450   }
451   inline MutableArrayRef<Optional<Value>> getIds() {
452     return {ids.data(), ids.size()};
453   }
455   /// Returns the optional Value corresponding to the pos^th identifier.
456   inline Optional<Value> getId(unsigned pos) const { return ids[pos]; }
457   inline Optional<Value> &getId(unsigned pos) { return ids[pos]; }
459   /// Returns the Value associated with the pos^th identifier. Asserts if
460   /// no Value identifier was associated.
461   inline Value getIdValue(unsigned pos) const {
462     assert(ids[pos].hasValue() && "identifier's Value not set");
463     return ids[pos].getValue();
464   }
466   /// Returns the Values associated with identifiers in range [start, end).
467   /// Asserts if no Value was associated with one of these identifiers.
468   void getIdValues(unsigned start, unsigned end,
469                    SmallVectorImpl<Value> *values) const {
470     assert((start < numIds || start == end) && "invalid start position");
471     assert(end <= numIds && "invalid end position");
472     values->clear();
473     values->reserve(end - start);
474     for (unsigned i = start; i < end; i++) {
475       values->push_back(getIdValue(i));
476     }
477   }
478   inline void getAllIdValues(SmallVectorImpl<Value> *values) const {
479     getIdValues(0, numIds, values);
480   }
482   /// Sets Value associated with the pos^th identifier.
483   inline void setIdValue(unsigned pos, Value val) {
484     assert(pos < numIds && "invalid id position");
485     ids[pos] = val;
486   }
487   /// Sets Values associated with identifiers in the range [start, end).
488   void setIdValues(unsigned start, unsigned end, ArrayRef<Value> values) {
489     assert((start < numIds || end == start) && "invalid start position");
490     assert(end <= numIds && "invalid end position");
491     assert(values.size() == end - start);
492     for (unsigned i = start; i < end; ++i)
493       ids[i] = values[i - start];
494   }
496   /// Clears this list of constraints and copies other into it.
497   void clearAndCopyFrom(const FlatAffineConstraints &other);
499   /// Returns the smallest known constant bound for the extent of the specified
500   /// identifier (pos^th), i.e., the smallest known constant that is greater
501   /// than or equal to 'exclusive upper bound' - 'lower bound' of the
502   /// identifier. Returns None if it's not a constant. This method employs
503   /// trivial (low complexity / cost) checks and detection. Symbolic identifiers
504   /// are treated specially, i.e., it looks for constant differences between
505   /// affine expressions involving only the symbolic identifiers. `lb` and
506   /// `ub` (along with the `boundFloorDivisor`) are set to represent the lower
507   /// and upper bound associated with the constant difference: `lb`, `ub` have
508   /// the coefficients, and boundFloorDivisor, their divisor. `minLbPos` and
509   /// `minUbPos` if non-null are set to the position of the constant lower bound
510   /// and upper bound respectively (to the same if they are from an equality).
511   /// Ex: if the lower bound is [(s0 + s2 - 1) floordiv 32] for a system with
512   /// three symbolic identifiers, *lb = [1, 0, 1], lbDivisor = 32. See comments
513   /// at function definition for examples.
514   Optional<int64_t> getConstantBoundOnDimSize(
515       unsigned pos, SmallVectorImpl<int64_t> *lb = nullptr,
516       int64_t *boundFloorDivisor = nullptr,
517       SmallVectorImpl<int64_t> *ub = nullptr, unsigned *minLbPos = nullptr,
518       unsigned *minUbPos = nullptr) const;
520   /// Returns the constant lower bound for the pos^th identifier if there is
521   /// one; None otherwise.
522   Optional<int64_t> getConstantLowerBound(unsigned pos) const;
524   /// Returns the constant upper bound for the pos^th identifier if there is
525   /// one; None otherwise.
526   Optional<int64_t> getConstantUpperBound(unsigned pos) const;
528   /// Gets the lower and upper bound of the `offset` + `pos`th identifier
529   /// treating [0, offset) U [offset + num, symStartPos) as dimensions and
530   /// [symStartPos, getNumDimAndSymbolIds) as symbols, and `pos` lies in
531   /// [0, num). The multi-dimensional maps in the returned pair represent the
532   /// max and min of potentially multiple affine expressions. The upper bound is
533   /// exclusive. `localExprs` holds pre-computed AffineExpr's for all local
534   /// identifiers in the system.
535   std::pair<AffineMap, AffineMap>
536   getLowerAndUpperBound(unsigned pos, unsigned offset, unsigned num,
537                         unsigned symStartPos, ArrayRef<AffineExpr> localExprs,
538                         MLIRContext *context) const;
540   /// Gather positions of all lower and upper bounds of the identifier at `pos`,
541   /// and optionally any equalities on it. In addition, the bounds are to be
542   /// independent of identifiers in position range [`offset`, `offset` + `num`).
543   void
544   getLowerAndUpperBoundIndices(unsigned pos,
545                                SmallVectorImpl<unsigned> *lbIndices,
546                                SmallVectorImpl<unsigned> *ubIndices,
547                                SmallVectorImpl<unsigned> *eqIndices = nullptr,
548                                unsigned offset = 0, unsigned num = 0) const;
550   /// Removes constraints that are independent of (i.e., do not have a
551   /// coefficient for) for identifiers in the range [pos, pos + num).
552   void removeIndependentConstraints(unsigned pos, unsigned num);
554   /// Returns true if the set can be trivially detected as being
555   /// hyper-rectangular on the specified contiguous set of identifiers.
556   bool isHyperRectangular(unsigned pos, unsigned num) const;
558   /// Removes duplicate constraints, trivially true constraints, and constraints
559   /// that can be detected as redundant as a result of differing only in their
560   /// constant term part. A constraint of the form <non-negative constant> >= 0
561   /// is considered trivially true. This method is a linear time method on the
562   /// constraints, does a single scan, and updates in place. It also normalizes
563   /// constraints by their GCD and performs GCD tightening on inequalities.
564   void removeTrivialRedundancy();
566   /// A more expensive check to detect redundant inequalities thatn
567   /// removeTrivialRedundancy.
568   void removeRedundantInequalities();
570   /// Removes redundant constraints using Simplex. Although the algorithm can
571   /// theoretically take exponential time in the worst case (rare), it is known
572   /// to perform much better in the average case. If V is the number of vertices
573   /// in the polytope and C is the number of constraints, the algorithm takes
574   /// O(VC) time.
575   void removeRedundantConstraints();
577   // Removes all equalities and inequalities.
578   void clearConstraints();
580   void print(raw_ostream &os) const;
581   void dump() const;
583 private:
584   /// Returns false if the fields corresponding to various identifier counts, or
585   /// equality/inequality buffer sizes aren't consistent; true otherwise. This
586   /// is meant to be used within an assert internally.
587   bool hasConsistentState() const;
589   /// Checks all rows of equality/inequality constraints for trivial
590   /// contradictions (for example: 1 == 0, 0 >= 1), which may have surfaced
591   /// after elimination. Returns 'true' if an invalid constraint is found;
592   /// 'false'otherwise.
593   bool hasInvalidConstraint() const;
595   /// Returns the constant lower bound bound if isLower is true, and the upper
596   /// bound if isLower is false.
597   template <bool isLower>
598   Optional<int64_t> computeConstantLowerOrUpperBound(unsigned pos);
600   // Eliminates a single identifier at 'position' from equality and inequality
601   // constraints. Returns 'success' if the identifier was eliminated, and
602   // 'failure' otherwise.
603   inline LogicalResult gaussianEliminateId(unsigned position) {
604     return success(gaussianEliminateIds(position, position + 1) == 1);
605   }
607   // Eliminates identifiers from equality and inequality constraints
608   // in column range [posStart, posLimit).
609   // Returns the number of variables eliminated.
610   unsigned gaussianEliminateIds(unsigned posStart, unsigned posLimit);
612   /// Eliminates identifier at the specified position using Fourier-Motzkin
613   /// variable elimination, but uses Gaussian elimination if there is an
614   /// equality involving that identifier. If the result of the elimination is
615   /// integer exact, *isResultIntegerExact is set to true. If 'darkShadow' is
616   /// set to true, a potential under approximation (subset) of the rational
617   /// shadow / exact integer shadow is computed.
618   // See implementation comments for more details.
619   void FourierMotzkinEliminate(unsigned pos, bool darkShadow = false,
620                                bool *isResultIntegerExact = nullptr);
622   /// Tightens inequalities given that we are dealing with integer spaces. This
623   /// is similar to the GCD test but applied to inequalities. The constant term
624   /// can be reduced to the preceding multiple of the GCD of the coefficients,
625   /// i.e.,
626   ///  64*i - 100 >= 0  =>  64*i - 128 >= 0 (since 'i' is an integer). This is a
627   /// fast method (linear in the number of coefficients).
628   void GCDTightenInequalities();
630   /// Normalized each constraints by the GCD of its coefficients.
631   void normalizeConstraintsByGCD();
633   /// Removes identifiers in the column range [idStart, idLimit), and copies any
634   /// remaining valid data into place, updates member variables, and resizes
635   /// arrays as needed.
636   void removeIdRange(unsigned idStart, unsigned idLimit);
638   /// Coefficients of affine equalities (in == 0 form).
639   SmallVector<int64_t, 64> equalities;
641   /// Coefficients of affine inequalities (in >= 0 form).
642   SmallVector<int64_t, 64> inequalities;
644   /// Number of columns reserved. Actual ones in used are returned by
645   /// getNumCols().
646   unsigned numReservedCols;
648   /// Total number of identifiers.
649   unsigned numIds;
651   /// Number of identifiers corresponding to real dimensions.
652   unsigned numDims;
654   /// Number of identifiers corresponding to symbols (unknown but constant for
655   /// analysis).
656   unsigned numSymbols;
658   /// Values corresponding to the (column) identifiers of this constraint
659   /// system appearing in the order the identifiers correspond to columns.
660   /// Temporary ones or those that aren't associated to any Value are set to
661   /// None.
662   SmallVector<Optional<Value>, 8> ids;
664   /// A parameter that controls detection of an unrealistic number of
665   /// constraints. If the number of constraints is this many times the number of
666   /// variables, we consider such a system out of line with the intended use
667   /// case of FlatAffineConstraints.
668   // The rationale for 32 is that in the typical simplest of cases, an
669   // identifier is expected to have one lower bound and one upper bound
670   // constraint. With a level of tiling or a connection to another identifier
671   // through a div or mod, an extra pair of bounds gets added. As a limit, we
672   // don't expect an identifier to have more than 32 lower/upper/equality
673   // constraints. This is conservatively set low and can be raised if needed.
674   constexpr static unsigned kExplosionFactor = 32;
675 };
677 /// Flattens 'expr' into 'flattenedExpr', which contains the coefficients of the
678 /// dimensions, symbols, and additional variables that represent floor divisions
679 /// of dimensions, symbols, and in turn other floor divisions.  Returns failure
680 /// if 'expr' could not be flattened (i.e., semi-affine is not yet handled).
681 /// 'cst' contains constraints that connect newly introduced local identifiers
682 /// to existing dimensional and symbolic identifiers. See documentation for
683 /// AffineExprFlattener on how mod's and div's are flattened.
684 LogicalResult getFlattenedAffineExpr(AffineExpr expr, unsigned numDims,
685                                      unsigned numSymbols,
686                                      SmallVectorImpl<int64_t> *flattenedExpr,
687                                      FlatAffineConstraints *cst = nullptr);
689 /// Flattens the result expressions of the map to their corresponding flattened
690 /// forms and set in 'flattenedExprs'. Returns failure if any expression in the
691 /// map could not be flattened (i.e., semi-affine is not yet handled). 'cst'
692 /// contains constraints that connect newly introduced local identifiers to
693 /// existing dimensional and / symbolic identifiers. See documentation for
694 /// AffineExprFlattener on how mod's and div's are flattened. For all affine
695 /// expressions that share the same operands (like those of an affine map), this
696 /// method should be used instead of repeatedly calling getFlattenedAffineExpr
697 /// since local variables added to deal with div's and mod's will be reused
698 /// across expressions.
699 LogicalResult
700 getFlattenedAffineExprs(AffineMap map,
701                         std::vector<SmallVector<int64_t, 8>> *flattenedExprs,
702                         FlatAffineConstraints *cst = nullptr);
703 LogicalResult
704 getFlattenedAffineExprs(IntegerSet set,
705                         std::vector<SmallVector<int64_t, 8>> *flattenedExprs,
706                         FlatAffineConstraints *cst = nullptr);
708 } // end namespace mlir.
710 #endif // MLIR_ANALYSIS_AFFINE_STRUCTURES_H