[mlir][sparse] Implementing sparse=>dense conversion.

[wrengr]

Summary

Depends On D110882, D110883, D110884

[wrengr]

linting

[wrengr]

Implementing some of my todo notes

[wrengr]

Splitting off D110882

[wrengr]

Splitting out D110883 and D110884

[wrengr]

Moving the new functions to the right section.

[wrengr]

Updating commentary about the code generated for sparse=>dense conversion.

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

445

Technically, we also fall into this branch for the strange dense to dense conversion. We will have typically folded those away, but I would not completely rely on this having taken place always and defend against that in the code.

451–453

Note that in the context of another project, we may migrate library code to actual codegen (which has the advantage of a smaller memory footprint potentially and allows for "unforeseen" type combinations). Such a migration may take care of all such performance concerns.

459

I think we need a subtle rewriting of the new call utility since we need the sparse encoding for some info, but the id permutation for the "new" tensor (ie. the dense result)

mlir/lib/ExecutionEngine/SparseUtils.cpp

145–146

this sentence does not flow quite well, or am I reading it wrong?

602–603

We really should not need permutation here. If you call toCOO with ID permutation, it restores the indices to original order.

Note that toCOO takes the permutation of the *target*, and internally restores permutation, if there was one from *source* (the internally stored inverse permutation). So if you call toCOO with ID perm, you don't need the perm here anymore, since indices are in the natural "dense" order MLIR expects.

[aartbik]

Also, please add tests for this

(1) in mlir/test/Dialect/SparseTensor conversion, a CHECK test on the expected loop structure (see examples there)
(2) in mlir/test/Integration/Dialect/SparseTensor/CPU, add a new "end-to-end" test that does a dense->sparse->dense roundtrip

[bixia]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

459

this should be encSrc, not encDst, right?

mlir/lib/ExecutionEngine/SparseUtils.cpp

111

nested

[wrengr]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

445

Just to be clear, that should only ever happen when the source is a "sparse" tensor that happens to use dense storage for all dimensions, right? Which is to say, the destination is always a bog-standard dense tensor, right? If so then the code should still work; if not then we'll have to figure out how to tighten up the guards for detecting the different cases.

I'll update the commentary (on the assumption that the answer to the first question is yes; of course, if that's true, then shouldn't the "sparse=>sparse" case have the same caveat?)

451–453

Yep, that's what I was thinking re "good enough for now" :) I mainly added the comment since when discussing the design with Tatiana, she raised some concerns about the performance implications of the method/function calls. For our current goals, I can't imagine this branch would be taken often enough to constitute a performance bottleneck. (And whenever it does, it's easy enough to fix at that point.)

459

Yeah, I've been mulling over a few ways to clean genNewCall up. Did you want me to do that in/before this differential, or is it okay to do afterwards?

mlir/lib/ExecutionEngine/SparseUtils.cpp

145–146

I'll try rewording

602–603

Oh good. I thought that's how things worked, but I wasn't quite certain.

[wrengr]

Addressing comments

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

445

No, I really means no encoding at all. There is a subtle difference between an un-annotated tensor and a tensor with all-dense annotations. All conversions work for the all-dense annotated case (it is treated as a sort of sparse tensors). But the logic on falling into a branch based on encDst, !encDest, srcDest, !srcDest (so four truth values) fell into this branch for two cases, but you only implemented the sparse->dense.

So you will have to add one if-test and return failure.

[wrengr]

Re-updating commentary about covering dense=>sparse not dense=>dense. Also some preliminary WIP towards adding tests.

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

445

Got it

[wrengr]

Debugging some errors

[wrengr]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

459

Good catch :) That lead to an utterly inscrutable crash stacktrace

[wrengr]

(more debugging attempt; not much progress)

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

448

using the "zero" data value itself has a bit of a risk that a sparse data structure with a few explicitly stored zeros will bail this loop too soon; having a 0/1 result and passing the value as another ref parameter seems safer

474

you cannot just pass "indices" to next call and use it here; you will need the IR to load the contents returned through the memref by the getNext() call, using explicit memref::LoadOp ops on the elements in the memref and passing this to the StoreOp

477

You are replacing the op (which returns a tensor) with the result of an alloc (which is a memref).
That type mismatch will fail. You need a buffer cast in between.

477

This replacement will also need some legality check changes. Up to now, we were replacing sparse tensors with opague pointers, and the checks/rewriting did all the work

But now we have

dense_tensor = convert ....
return dense_tenor

and the mechanism will need some "love" to make it accept the rewriting even though the types were already legal to start with

[wrengr]

rebased, and factored out D111763 and D111766

[wrengr]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

448

Gross; but yes, you're right.

I think I'll leave the commentary here as-is, however, since —like the field accesses on line 452, and like the commentary for other branches— it's reflecting more what the C++ code in the ExecutionEngine does, rather than reflecting what the generated MLIR code does; and there's no ambiguity about what the getNext() method returns, even though IMPL_COO_GETNEXT introduces the problem you mention.

[wrengr]

Everything should now be ready for review. I've added integration and codegen tests, fixed various infelicities, and rebased.

[wrengr]

N.B., I'm planning to add support for dynamic sizes, but I want to do that in a separate differential

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

125

returns (to be consistent with Generates)

also "as" instead of "at"? (2x)

127

is the "inline" really important (here and below)

internal linkage gives the compiler sufficient room to make that decision using built-in heuristics?

263

we typically do not show that much detail of the C++ lib in this file

270

This is not a style we use in MLIR, and especially for an internally linked method, and compared to the surrounding methods, it feels a bit heavy

271

let's not document SparseUtils inside this file

338

not in this revision yet? seems a relatively minor addition (and then we are done for all cases!)

352

same

451–453

remove this; it more or less applies to all method calls here, and it will fall under the general umbrella of perhaps moving to 100% codegen over support lib usage....

457

we don't emit errors when rewriting rules fail to apply

466

all this block scoping makes the code more lengthy than it could be

I would either break this up in methods where it makes sense, or otherwise just take the scoping hit for readability

487

shouldn't we bail out if there are dynamic sizes?
or, better yet, just add those in this revision

mlir/lib/ExecutionEngine/SparseUtils.cpp

150–151

this class adds an enormous amount of code for a very thin iterator

how about just having the very simple start()/next() iteration inside the COO class itself?
That way, we can also assert an error if you try to insert while iterating

556

assert(action == kEmpty); disappeared in your rewrite

556

this is of course inside a macro now, but LLVM wants braces {} on all branches if one of them is branched

643

if you use a shorter name, perhaps it fits on one line

758–767

I prefer not to have this function at all; but if we keep it, it should go to CRunnerUtils.cpp since we have some other printing utilities there

but this is not related to sparse

mlir/test/Dialect/SparseTensor/conversion_sparse2dense.mlir

16 ↗

(On Diff #382805)

Ah, you made this much more accurate checking than conversion.mlir does (good).
But, let's also add a check in that file in the more informal way there

mlir/test/Integration/Dialect/SparseTensor/CPU/sparse_conversion_sparse2dense.mlir

45 ↗

(On Diff #382805)

from dense to sparse

64–69 ↗

(On Diff #382805)

I think you are overthinking this

I agree that the silent exit(1) is not good (so perhaps we should just go back to fully FileChecked cases)
But how about just printing -12345 on error and exiting and then also add a CHECK-NOT -12345 or something like that

but again, I actually prefer the fully FileChecked cases and just rely on printing and verifying the output

132–133 ↗

(On Diff #382805)

yeah, we need to do that or asan will fail

Proper way, I think

(1) memref.buffer_cast from tensor to memref
(2) dealloc memref

[aartbik]

In D110790#3091638, @wrengr wrote:

N.B., I'm planning to add support for dynamic sizes, but I want to do that in a separate differential

Ah, I saw this after writing my comments. So you can ignore the part where I asked about that ;-)

[wrengr]

Added child differential D112674 for handling dynamic sizes

[wrengr]

Addressing comments

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

338

It's done in D112674.

459

Ha, actually I was right(-ish) the first time. We want the destination encoding here, so we don't apply the dimOrdering permutation twice. The problem was that I was passing a nullptr rather than explicitly constructing the SparseTensorEncodingAttr

487

Done in D112674

mlir/lib/ExecutionEngine/SparseUtils.cpp

758–767

Yeah, I'd rather not have this function too. Unfortunately, when I tried using the CRunnerUtils.cpp functions that vector.print does, I could never get it to link right: it either complained about re-defining a symbol, or about using an un-defined symbol. As for implementing it in the integration test itself, I can't seem to find a way to define string values (not attributes) for passing to fputs()

Moved to CRunnerUtils.cpp for now. Will try to rip it out in a future differential.

mlir/test/Dialect/SparseTensor/conversion_sparse2dense.mlir

16 ↗

(On Diff #382805)

I'm not sure I follow. I was just trying to do the same as conversion.mlir (but in the opposite direction, naturally); and elsewhere you suggested breaking things out into a separate test rather than reusing the ones already there.

[aartbik]

mlir/lib/ExecutionEngine/SparseUtils.cpp

758–767

How about just leaving it at the exit(1) for not and think about this in a future differential.
Rather than introducing something we want to rip again anyway?

mlir/test/Dialect/SparseTensor/conversion_sparse2dense.mlir

16 ↗

(On Diff #382805)

Ok, fair enough. I was suggesting to have one sparse->dense check in the conversion.mlir in the more concise style of that test, but having this more rigid tests is indeed sufficient. You can ignore the suggestion ;-)

[aartbik]

mlir/lib/ExecutionEngine/CRunnerUtils.cpp

47–58 ↗

(On Diff #382862)

Let's not do this at all, but let's go with just using CHECKs
I moved the sparse_conversion test back to this format as well:

https://reviews.llvm.org/D112688

[wrengr]

Addressing comments

[aartbik]

yeah, looking good. few last nits before we submit...

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

349

Inserts

(I usually use the s-form of a verb in the top level comment, but the imperative form in the inlined code)

356–357

is this comment still relevant? I think we can safely remove it?

485

you still have some block scoping left?
none of these really release stuff early to keep memory lower
so I would opt for readability over block scoping

mlir/lib/ExecutionEngine/SparseUtils.cpp

96

yeah, this is awesome!

120

iteratorLocked = false?

753

feel free to rename this into more intuitive names in a follow up revision too, btw

[wrengr]

Addressing nits

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

485

Imo the blocks improve readability rather than detract.

mlir/lib/ExecutionEngine/SparseUtils.cpp

753

Will do

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

459–470

how about removing this comment block and simply using

// Setup a synthetic all-dense, no-permutation encoding for the dense destination.
encDst = SparseTensorEncodingAttr::get(

      op->getContext(),
      SmallVector<SparseTensorEncodingAttr::DimLevelType>(
          rank, SparseTensorEncodingAttr::DimLevelType::Dense),
AffineMap(), 0, 0);

we don't need anything copied from src here.

[wrengr]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

459–470

We need the (ptrTp,indTp,valTp) values for _mlir_ciface_newSparseTensor to enter the right CASE. But I can abbreviate the commentary

[wrengr]

Addressing nits

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

459–470

this last one may have crossed. I just feel L601-612 takes too much real estate explaining what could be a onliner

485

Ok, acceptable ;-)

mlir/lib/ExecutionEngine/SparseUtils.cpp

603

tensor is a bit more consistent name with IMPL3

612

oh, we will leak memory right now!

When iteration is done, we should release the COO tensor/
The easiest way would be to do this

if (elem == nullptr) {

delete iter;  
return false;

}

and document that tensor can no longer be used once getNext returns false

mlir/test/Integration/Dialect/SparseTensor/CPU/sparse_conversion_sparse2dense.mlir

79–81 ↗

(On Diff #383144)

this is taken from the original sparse_conversion.mlir
but with your addition it feels like we should

(1) remove this comment, or
(2) add a comment for tensor4,5,6 as well

[aartbik]

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

459–470

Oh yeah, right you are. Okay, then indeed just a bit less comment, but same code ;-)

mlir/lib/ExecutionEngine/SparseUtils.cpp

612

this is the most important issue, since without this fix, asan will break the test

[wrengr]

Fixing memory leak

[aartbik]

Ship it, Wren!

mlir/lib/Dialect/SparseTensor/Transforms/SparseTensorConversion.cpp

static FlatSymbolRefAttr getFunc(Operation *op, StringRef name, Type resultType,
   }
   return result;
 }
 
 /// Generates a call into the "swiss army knife" method of the sparse runtime
 /// support library for materializing sparse tensors into the computation. The
 /// method returns the call value and assigns the permutation to 'perm'.
 static Value genNewCall(ConversionPatternRewriter &rewriter, Operation *op,
                         SparseTensorEncodingAttr &enc, uint32_t action,
                         Value &perm, Value ptr = Value()) {
   Location loc = op->getLoc();
   ShapedType resType = op->getResult(0).getType().cast<ShapedType>();
   SmallVector<Value, 8> params;
   // Sparsity annotations in tensor constant form.
   SmallVector<APInt, 4> attrs;
   unsigned sz = enc.getDimLevelType().size();
   for (unsigned i = 0; i < sz; i++)
     attrs.push_back(
         APInt(8, getDimLevelTypeEncoding(enc.getDimLevelType()[i])));
static void genAddEltCall(ConversionPatternRewriter &rewriter, Operation *op,
   params.push_back(ind);
   params.push_back(perm);
   Type pTp = LLVM::LLVMPointerType::get(IntegerType::get(op->getContext(), 8));
   rewriter.create<CallOp>(
       loc, pTp, getFunc(op, name, pTp, params, /*emitCInterface=*/true),
       params);
 }
 
+/// Generates a call to SparseTensorCOO<V>::Iterator::getNext()
+/// If there is a next `Element<V>`: the `indices` will be filled from
+/// that element, and the returned `Value` will be the `V` of that element.
+/// If there is no next `Element<V>`: the `indices` will be left in an
+/// indeterminate state (in practice it'll be left unmodified), and
+/// the returned `Value` is zero-- which (by definition) is never a
+/// valid `V` for `SparseTensorCOO<V>` to contain, so there's no chance
+/// of confusion, nor any loss of expressivity.
+static Value genGetNextCall(ConversionPatternRewriter &rewriter, Operation *op,
+                            Value iter, Value indices, Value perm) {
+  Location loc = op->getLoc();
+  Type elemTp = iter.getType().cast<ShapedType>().getElementType();
+  StringRef name;
+  if (elemTp.isF64())
+    name = "getNextF64";
+  else if (elemTp.isF32())
+    name = "getNextF32";
+  else if (elemTp.isInteger(64))
+    name = "getNextI64";
+  else if (elemTp.isInteger(32))
+    name = "getNextI32";
+  else if (elemTp.isInteger(16))
+    name = "getNextI16";
+  else if (elemTp.isInteger(8))
+    name = "getNextI8";
+  else
+    llvm_unreachable("Unknown element type");
+  SmallVector<Value, 8> params;
+  params.push_back(iter);
+  params.push_back(indices);
+  params.push_back(perm);
+  auto call = rewriter.create<CallOp>(
+      loc, elemTp, getFunc(op, name, elemTp, params, /*emitCInterface=*/true),
+      params);
+  return call.getResult(0);
+}
+
 /// If the tensor is a sparse constant, generates and returns the pair of
 /// the constants for the indices and the values.
 static Optional<std::pair<Value, Value>>
 genSplitSparseConstant(ConversionPatternRewriter &rewriter, ConvertOp op,
                        Value tensor) {
   if (auto constOp = tensor.getDefiningOp<ConstantOp>()) {
     if (auto attr = constOp.value().dyn_cast<SparseElementsAttr>()) {
       Location loc = op->getLoc();
for (unsigned i = 0; i < rank; i++) {
     rewriter.create<memref::StoreOp>(loc, val, ind, idx);
   }
   return rewriter.create<tensor::ExtractOp>(loc, values, ivs[0]);
 }
 
 /// Generates code to stack-allocate a `memref<?xindex>` where the `?`
 /// is the given `rank`.  This array is intended to serve as a reusable
 /// buffer for storing the indices of a single tensor element, to avoid
 /// allocation in the body of loops.
 static Value allocaIndices(ConversionPatternRewriter &rewriter, Location loc,
                            int64_t rank) {
   auto indexTp = rewriter.getIndexType();
   auto memTp = MemRefType::get({ShapedType::kDynamicSize}, indexTp);
   Value arg = rewriter.create<ConstantOp>(loc, rewriter.getIndexAttr(rank));
   return rewriter.create<memref::AllocaOp>(loc, memTp, ValueRange{arg});
 }
 
+/// Generates code to allocate a memref with the shape and element-type
+/// given by `shapeTp`, and zero initialize it.
+static Value allocDenseTensor(ConversionPatternRewriter &rewriter, Location loc,
+                              ShapedType shapeTp) {
+  Type elemTp = shapeTp.getElementType();
+  Value tensor = rewriter.create<memref::AllocOp>(
+      loc, MemRefType::get(shapeTp.getShape(), elemTp));
+  rewriter.create<linalg::FillOp>(loc, getZero(rewriter, loc, elemTp), tensor);
+  return tensor;
+}
+
 //===----------------------------------------------------------------------===//
 // Conversion rules.
 //===----------------------------------------------------------------------===//
 
 /// Sparse conversion rule for returns.
 class SparseReturnConverter : public OpConversionPattern<ReturnOp> {
 public:
   using OpConversionPattern::OpConversionPattern;
if (encDst && encSrc) {
       // yield the fastest conversion but avoids the need for a full
       // O(N^2) conversion matrix.
       Value perm;
       Value coo = genNewCall(rewriter, op, encDst, 3, perm, src);
       rewriter.replaceOp(op, genNewCall(rewriter, op, encDst, 1, perm, coo));
       return success();
     }
     if (!encDst || encSrc) {
-      // TODO: sparse => dense
-      return failure();
+      // This is sparse => dense conversion, which is handled as follows:
+      //   dst = new MemRef(0);
+      //   iter = src->toCOO()->getIterator();
+      //   while (elem = iter->getNext()) {
+      //     dst[elem.indices] = elem.value;
+      //   }
+      // While it would be more efficient to inline the iterator logic
+      // directly rather than allocating an object and calling methods,
+      // this is good enough for now.
+      Location loc = op->getLoc();
+      ShapedType shapeTp = resType.cast<ShapedType>();
+      Value dst = allocDenseTensor(rewriter, loc, shapeTp);
+      Value indices = allocaIndices(rewriter, loc, shapeTp.getRank());
+      Value perm;
+      Value iter = genNewCall(rewriter, op, encDst, 4, perm, src);
+      // Generate the while-loop Op itself.
+      TypeRange argTypes{};
+      ValueRange args{};
+      scf::WhileOp whileOp = rewriter.create<scf::WhileOp>(loc, argTypes, args);
+      Block *before = rewriter.createBlock(&whileOp.before(), {}, argTypes);
+      Block *after = rewriter.createBlock(&whileOp.after(), {}, argTypes);
+      // Build the while-loop's "before" region.
+      rewriter.setInsertionPointToEnd(before);
+      Value elemVal = genGetNextCall(rewriter, op, iter, indices, perm);
+      Value cond = genIsNonzero(rewriter, loc, elemVal);
+      rewriter.create<scf::ConditionOp>(loc, cond, before->getArguments());
+      // Build the while-loop's "after" region.
+      rewriter.setInsertionPointToStart(after);
+      rewriter.create<memref::StoreOp>(loc, elemVal, dst, indices);
+      // Finish up.
+      rewriter.replaceOp(op, dst);
+      return success();
     }
     // This is a dense => sparse conversion or a sparse constant in COO =>
     // sparse conversion, which is handled as follows:
     //   t = newSparseCOO()
     //   ...code to fill the COO tensor t...
     //   s = newSparseTensor(t)
     //
     // To fill the COO tensor from a dense tensor:
     //   for i1 in dim1
     //    ..
     //     for ik in dimk
     //       val = a[i1,..,ik]
     //       if val != 0
     //         t->add(val, [i1,..,ik], [p1,..,pk])
     //
     // To fill the COO tensor from a sparse constant in COO format:
     //   for i in range(NNZ)
     //     val = values[i]
     //     [i1,..,ik] = indices[i]

mlir/lib/ExecutionEngine/SparseUtils.cpp

 public:
   SparseTensorCOO(const std::vector<uint64_t> &szs, uint64_t capacity)
       : sizes(szs) {
     if (capacity)
       elements.reserve(capacity);
   }
   /// Adds element as indices and value.
   void add(const std::vector<uint64_t> &ind, V val) {
     assert(getRank() == ind.size());
     for (uint64_t r = 0, rank = getRank(); r < rank; r++)
       assert(ind[r] < sizes[r]); // within bounds
     elements.emplace_back(ind, val);
   }
   /// Sorts elements lexicographically by index.
   void sort() { std::sort(elements.begin(), elements.end(), lexOrder); }
   /// Returns rank.
   uint64_t getRank() const { return sizes.size(); }
   /// Getter for sizes array.
   const std::vector<uint64_t> &getSizes() const { return sizes; }
   /// Getter for elements array.
   const std::vector<Element<V>> &getElements() const { return elements; }
 
+  // Forward declaration of the class required by getIterator.  We make
+  // it a nexted class so that it can access the private fields.
+  class Iterator;
+  /// Returns an iterator over the elements of a SparseTensorCOO.
+  Iterator *getIterator() const { return new Iterator(*this); }
+
   /// Factory method. Permutes the original dimensions according to
   /// the given ordering and expects subsequent add() calls to honor
   /// that same ordering for the given indices. The result is a
   /// fully permuted coordinate scheme.
   static SparseTensorCOO<V> *newSparseTensorCOO(uint64_t size,
                                                 const uint64_t *sizes,
                                                 const uint64_t *perm,
                                                 uint64_t capacity = 0) {
     std::vector<uint64_t> permsz(size);
     for (uint64_t r = 0; r < size; r++)
       permsz[perm[r]] = sizes[r];
     return new SparseTensorCOO<V>(permsz, capacity);
   }
 
 private:
   /// Returns true if indices of e1 < indices of e2.
   static bool lexOrder(const Element<V> &e1, const Element<V> &e2) {
     assert(e1.indices.size() == e2.indices.size());
     for (uint64_t r = 0, rank = e1.indices.size(); r < rank; r++) {
       if (e1.indices[r] == e2.indices[r])
         continue;
       return e1.indices[r] < e2.indices[r];
     }
     return false;
   }
-  std::vector<uint64_t> sizes; // per-rank dimension sizes
+  const std::vector<uint64_t> sizes; // per-rank dimension sizes
   std::vector<Element<V>> elements;
 };
 
+/// This iterator is specifically designed for the needs of the MLIR
+/// generated for sparse=>dense conversion; hence why it is so
+/// idiosyncratic compared to a more conventional iterator for use within
+/// C++ itself.
+template <typename V>
+class SparseTensorCOO<V>::Iterator {
+  // TODO(wrengr): really this class should be a thin wrapper/subclass
+  // of the std::vector, rather than needing to do a dereference every
+  // time a method is called; but we don't want to actually copy the whole
+  // contents of the underlying array(s) when this class is initialized.
+  // Maybe we should be a thin wrapper/subclass of SparseTensorCOO?
+  // Or have a variant of SparseTensorStorage::toCOO() to construct this
+  // iterator directly?
+  const std::vector<Element<V>> &elements;
+  unsigned pos;
+
+public:
+  // TODO(wrengr): to guarantee safety we'd either need to consume the
+  // SparseTensorCOO (e.g., requiring an rvalue-reference) or get notified
+  // somehow whenever the SparseTensorCOO adds new elements, sorts, etc.
+  Iterator(const SparseTensorCOO<V> &coo) : elements(coo.elements), pos(0) {}
+
+  const Element<V> *getNext() {
+    if (pos < elements.size())
+      return &(elements[pos++]);
+    return nullptr;
+  }
+};
+
 /// Abstract base class of sparse tensor storage. Note that we use
 /// function overloading to implement "partial" method specialization.
 class SparseTensorStorageBase {
 public:
   enum DimLevelType : uint8_t { kDense = 0, kCompressed = 1, kSingleton = 2 };
 
   virtual uint64_t getDimSize(uint64_t) = 0;
 
if (ptrTp == (p) && indTp == (i) && valTp == (v)) {                          \
     SparseTensorCOO<V> *tensor = nullptr;                                      \
     if (action == 0)                                                           \
       tensor =                                                                 \
           openSparseTensorCOO<V>(static_cast<char *>(ptr), size, sizes, perm); \
     else if (action == 1)                                                      \
       tensor = static_cast<SparseTensorCOO<V> *>(ptr);                         \
     else if (action == 2)                                                      \
       return SparseTensorCOO<V>::newSparseTensorCOO(size, sizes, perm);        \
-    else                                                                       \
-      return static_cast<SparseTensorStorage<P, I, V> *>(ptr)->toCOO(perm);    \
+    else {                                                                     \
+      tensor = static_cast<SparseTensorStorage<P, I, V> *>(ptr)->toCOO(perm);  \
+      if (action == 3)                                                         \
+        return tensor;                                                         \
+      return tensor->getIterator();                                            \
+    }                                                                          \
     return SparseTensorStorage<P, I, V>::newSparseTensor(tensor, sparsity,     \
                                                          perm);                \
   }
 
 #define IMPL1(NAME, TYPE, LIB)                                                 \
   void _mlir_ciface_##NAME(StridedMemRefType<TYPE, 1> *ref, void *tensor) {    \
     std::vector<TYPE> *v;                                                      \
     static_cast<SparseTensorStorageBase *>(tensor)->LIB(&v);                   \
void *_mlir_ciface_##NAME(void *tensor, TYPE value,                          \
     uint64_t isize = iref->sizes[0];                                           \
     std::vector<uint64_t> indices(isize);                                      \
     for (uint64_t r = 0; r < isize; r++)                                       \
       indices[perm[r]] = indx[r];                                              \
     static_cast<SparseTensorCOO<TYPE> *>(tensor)->add(indices, value);         \
     return tensor;                                                             \
   }
 
+// TODO(wrengr): Why do we need to handle the permutation manually
+// here? Why doesn't the SparseTensorCOO type handle it itself when constructed?
+/// Calls SparseTensorCOO<V>::Iterator::getNext() with the following semantics.
+/// If there is a next `Element<V>`: the `iref` will be filled from that
+/// element, and the element's value is returned.
+/// If there is no next `Element<V>`: the `iref` will be left in an
+/// indeterminate state (in practice it'll be left unmodified), and
+/// the return value is zero-- which (by definition) is never a valid `V`
+/// for `SparseTensorCOO<V>` to contain, so there's no chance of confusion,
+/// nor any loss of expressivity.
+#define IMPL_COO_GETNEXT(NAME, V)                                              \
+  V _mlir_ciface_##NAME(void *ptr, StridedMemRefType<uint64_t, 1> *iref,       \
+                        StridedMemRefType<uint64_t, 1> *pref) {                \
+    assert(iref->strides[0] == 1 && pref->strides[0] == 1);                    \
+    assert(iref->sizes[0] == pref->sizes[0]);                                  \
+    uint64_t *indx = iref->data + iref->offset;                                \
+    const uint64_t *perm = pref->data + pref->offset;                          \
+    const uint64_t isize = iref->sizes[0];                                     \
+    auto iter = static_cast<SparseTensorCOO<V>::Iterator *>(ptr);              \
+    const Element<V> *elem = iter->getNext();                                  \
+    if (elem == nullptr)                                                       \
+      return 0;                                                                \
+    for (uint64_t r = 0; r < isize; r++)                                       \
+      indx[r] = elem->indices[perm[r]];                                        \
+    return elem->value;                                                        \
+  }
+
 enum OverheadTypeEnum : uint64_t { kU64 = 1, kU32 = 2, kU16 = 3, kU8 = 4 };
 
 enum PrimaryTypeEnum : uint64_t {
   kF64 = 1,
   kF32 = 2,
   kI64 = 3,
   kI32 = 4,
   kI16 = 5,
   kI8 = 6
 };
 
 /// Constructs a new sparse tensor. This is the "swiss army knife"
 /// method for materializing sparse tensors into the computation.
 ///  action
 ///  0 : ptr contains filename to read into storage
 ///  1 : ptr contains coordinate scheme to assign to new storage
 ///  2 : returns empty coordinate scheme to fill (call back 1 to setup)
 ///  3 : returns coordinate scheme from storage in ptr (call back 1 to convert)
+///  4 : returns iterator from storage in ptr (call IMPL_COO_GETNEXT to use)
 void *
 _mlir_ciface_newSparseTensor(StridedMemRefType<uint8_t, 1> *aref, // NOLINT
                              StridedMemRefType<uint64_t, 1> *sref,
                              StridedMemRefType<uint64_t, 1> *pref,
                              uint64_t ptrTp, uint64_t indTp, uint64_t valTp,
                              uint32_t action, void *ptr) {
   assert(aref->strides[0] == 1 && sref->strides[0] == 1 &&
          pref->strides[0] == 1);

 /// Helper to add value to coordinate scheme, one per value type.
 IMPL3(addEltF64, double)
 IMPL3(addEltF32, float)
 IMPL3(addEltI64, int64_t)
 IMPL3(addEltI32, int32_t)
 IMPL3(addEltI16, int16_t)
 IMPL3(addEltI8, int8_t)
 
+/// Helper to enumerate elements of coordinate scheme, one per value type.
+IMPL_COO_GETNEXT(getNextF64, double)
+IMPL_COO_GETNEXT(getNextF32, float)
+IMPL_COO_GETNEXT(getNextI64, int64_t)
+IMPL_COO_GETNEXT(getNextI32, int32_t)
+IMPL_COO_GETNEXT(getNextI16, int16_t)
+IMPL_COO_GETNEXT(getNextI8, int8_t)
+
 #undef CASE
 #undef IMPL1
 #undef IMPL2
 #undef IMPL3
+#undef IMPL_COO_GETNEXT
 
 //===----------------------------------------------------------------------===//
 //
 // Public API with methods that accept C-style data structures to interact
 // with sparse tensors, which are only visible as opaque pointers externally.
 // These methods can be used both by MLIR compiler-generated code as well as by
 // an external runtime that wants to interact with MLIR compiler-generated code.
 //
 //===----------------------------------------------------------------------===//
 
 /// Returns size of sparse tensor in given dimension.
 uint64_t sparseDimSize(void *tensor, uint64_t d) {
   return static_cast<SparseTensorStorageBase *>(tensor)->getDimSize(d);
 }
 
 /// Releases sparse tensor storage.
 void delSparseTensor(void *tensor) {
   delete static_cast<SparseTensorStorageBase *>(tensor);
 }