[Mlir-commits] [mlir] 6b3bc7c - [mlir][sparse] improve sparse attribute documentation

[Aart Bik]

Author: Aart Bik
Date: 2022-08-08T13:21:24-07:00
New Revision: 6b3bc7cd3c6f56a63f97e71dc236b2281d98d9d1

URL: https://github.com/llvm/llvm-project/commit/6b3bc7cd3c6f56a63f97e71dc236b2281d98d9d1
DIFF: https://github.com/llvm/llvm-project/commit/6b3bc7cd3c6f56a63f97e71dc236b2281d98d9d1.diff

LOG: [mlir][sparse] improve sparse attribute documentation

Moved some parts from comments (not user facing) to the actual description
(user facing). Rephrased a bit as well.

Reviewed By: Peiming

Differential Revision: https://reviews.llvm.org/D131418

Added: 
    

Modified: 
    mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorAttrDefs.td

Removed: 
    


################################################################################
diff  --git a/mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorAttrDefs.td b/mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorAttrDefs.td
index 4fbac0db0e90b..4a10b8daf0402 100644
--- a/mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorAttrDefs.td
+++ b/mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorAttrDefs.td
@@ -31,6 +31,28 @@ def SparseTensorEncodingAttr : SparseTensor_Attr<"SparseTensorEncoding",
     passes that run before this sparse compiler pass need to be
     aware of the semantics of tensor types with such an encoding.
 
+    The attribute consists of the following fields.
+    - Dimension level type for each dimension of a tensor type:
+        - **dense** : dimension is dense, all entries along this dimension
+	  are stored.
+        - **compressed** : dimension is sparse, only nonzeros along this dimensions
+	  are stored, without duplicates, i.e., compressed (unique).
+    - Dimension ordering on the indices of this tensor type. Unlike dense
+      storage, most sparse storage schemes do not provide fast random access.
+      This affine map specifies the order of dimensions that should be supported
+      by the sparse storage scheme. For example, for a 2-d tensor, "(i,j) -> (i,j)"
+      requests row-wise storage and "(i,j) -> (j,i)" requests column-wise storage.
+    - The required bit width for "pointer" storage (integral offsets into
+      the sparse storage scheme). A narrow width reduces the memory footprint
+      of overhead storage, as long as the width suffices to define the total
+      required range (viz. the maximum number of stored entries over all indirection
+      dimensions). The choices are `8`, `16`, `32`, `64`, or `0` for a native width.
+    - The required bit width for "index" storage (elements of the coordinates of
+      stored entries). A narrow width reduces the memory footprint of overhead
+      storage, as long as the width suffices to define the total required range
+      (viz. the maximum value of each tensor index over all dimensions). The
+      choices are `8`, `16`, `32`, `64`, or `0` for a native width.
+
     Example:
 
     ```mlir
@@ -41,7 +63,6 @@ def SparseTensorEncodingAttr : SparseTensor_Attr<"SparseTensorEncoding",
       indexBitWidth = 8
     }>
 
-
     ... tensor<8x8xf64, #DCSC> ...
     ```
   }];
@@ -50,32 +71,16 @@ def SparseTensorEncodingAttr : SparseTensor_Attr<"SparseTensorEncoding",
   let parameters = (
     ins
     // A dimension level type for each dimension of a tensor type.
-    // The choices are `dense` (dimension should be stored in its entirety),
-    // `compressed` (only non-zero regions or elements should be stored),
-    // or `singleton` (no sibling elements for parent).
     ArrayRefParameter<
       "SparseTensorEncodingAttr::DimLevelType",
-      "Per-dimension level type"
+      "Per-dimension level type (dense or compressed)"
       >: $dimLevelType,
     // A dimension order on the indices of this tensor type.
-    // Unlike dense storage, most sparse storage schemes do not provide
-    // fast random access. This affine map specifies the order of
-    // dimensions that should be support by the sparse storage scheme
-    // (e.g. (i,j) -> (i,j) requests 2-d row-wise and (i,j) -> (j,i)
-    // requests 2-d column-wise storage).
     // TODO: block structure with higher-dim inputs
     "AffineMap":$dimOrdering,
-    // The required bit width for pointer storage. A narrow width reduces
-    // the memory footprint of overhead storage, as long as the width
-    // suffices to define the total required range (viz. the maximum
-    // number of stored entries over all indirection dimensions). The choices
-    // are `8`, `16`, `32`, `64`, or `0` for a native width.
+    // The required bit width for pointer storage.
     "unsigned":$pointerBitWidth,
-    // The required bit width for index storage. A narrow width reduces
-    // the memory footprint of overhead storage, as long as the width
-    // suffices to define the total required range (viz. the maximum
-    // value of each tensor index over all dimensions). The choices are `8`,
-    // `16`, `32`, `64`, or `0` for a native width.
+    // The required bit width for index storage.
     "unsigned":$indexBitWidth
   );
 
@@ -83,9 +88,7 @@ def SparseTensorEncodingAttr : SparseTensor_Attr<"SparseTensorEncoding",
   let hasCustomAssemblyFormat = 1;
 
   let extraClassDeclaration = [{
-    // Dimension level types that define sparse tensors:
-    //   Dense               - dimension is dense, every entry is stored
-    //   Compressed (unique) - dimension is sparse, only nonzeros are stored (no duplicates)
+    // Dimension level types.
     enum class DimLevelType {
       Dense, Compressed
     };