[mlir][sparse] update doc for sparse_tensor.foreach operator.

[Peiming]

Summary

Clarify that sparse_tensor.foreach iterates sparse_tensor in stored dim order.

[Peiming]

remove spaces.

[aartbik]

mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorOps.td

850

I would say that the "loop iterates over the stored elements in the storage order" or something like htat (since stored dimension order still implies some order, but for unsorted versions, all is lost

and add:

No matter what storage order is used, however, the indices passed to the block always obey the original dimension order.

[Peiming]

update doc.

[wrengr]

mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorOps.td

850

I would say that the "loop iterates over the stored elements in the storage order"

+1. "Stored dimension order" will become more and more of a misnomer as we start adding support for more unique sparsity formats. (E.g., the storage levels of formats like DIA don't really have anything to do with "dimensions" anymore)

and add:

No matter what storage order is used, however, the indices passed to the block always obey the original dimension order.

+1. That's very well phrased

mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorOps.td

let description = [{
      non-zero for sparse tensors) and executes the block.
 
      For an input tensor with rank n, the block must take n + 1 arguments. The
      first n arguments must be Index type, together indicating the current coordinates
      of the element being visited. The last argument must have the same type as the
      tensor's element type, representing the actual value loaded from the input
      tensor at the given coordinates.
 
+     Note that iterations on sparse tensors are performed by the actual stored dimension
+     order instead the declared dimension order in types.
+
+     For example:
+     ```mlir
+     #COL_MAJOR = #sparse_tensor.encoding<{
+       dimLevelType = [ "compressed", "compressed" ],
+       dimOrdering = affine_map<(i,j) -> (j,i)>
+     }>
+     
+     // foreach on a column-major sparse tensor
+     sparse_tensor.foreach in %0 : tensor<2x3xf64, #COL_MAJOR> do {
+      ^bb0(%row: index, %col: index, %arg3: f64): 
+         // [%row, %col] -> [0, 0], [1, 0], [2, 0], [0, 1], [1, 1], [2, 1]
+     }
+
+     #ROW_MAJOR = #sparse_tensor.encoding<{
+       dimLevelType = [ "compressed", "compressed" ],
+     }>
+
+     // foreach on a row-major sparse tensor
+     sparse_tensor.foreach in %0 : tensor<2x3xf64, #ROW_MAJOR> do {
+      ^bb0(%row: index, %col: index, %arg3: f64): 
+         // [%row, %col] -> [0, 0], [0, 1], [1, 0], [1, 1], [2, 0], [2, 1]
+     }
+
+     ```
+
      Example:
 
      ```mlir
      sparse_tensor.foreach in %0 : tensor<?x?xf64, #DCSR> do {
       ^bb0(%arg1: index, %arg2: index, %arg3: f64):
         do something...
      }
      ```