CINXE.COM

<!doctype html><html lang=en-us><head><meta charset=utf-8><meta http-equiv=x-ua-compatible content="IE=edge"><meta name=viewport content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no"><title>'sparse_tensor' Dialect - MLIR</title><meta name=description content="Multi-Level IR Compiler Framework"><meta name=generator content="Hugo 0.119.0"><link href=https://mlir.llvm.org/index.xml rel=alternate type=application/rss+xml><link rel=canonical href=https://mlir.llvm.org/docs/Dialects/SparseTensorOps/><link rel=stylesheet href=https://mlir.llvm.org/css/theme.css><script src=https://use.fontawesome.com/releases/v5.0.6/js/all.js></script> <link rel=stylesheet href=https://mlir.llvm.org/css/chroma.min.css><script src=https://cdn.jsdelivr.net/npm/jquery@3.3.1/dist/jquery.min.js></script> <script src=https://cdn.jsdelivr.net/npm/jquery.easing@1.4.1/jquery.easing.min.js></script> <script src=https://mlir.llvm.org/js/bundle.js></script> <script type=text/javascript src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> <script type=text/x-mathjax-config> MathJax.Hub.Config({ tex2jax: { inlineMath: [['$', '$'] ], displayMath: [ ['$$','$$'], ["\\[","\\]"] ] } }); </script><link rel=apple-touch-icon sizes=180x180 href="/apple-touch-icon.png?v=1"><link rel=icon type=image/png sizes=32x32 href="/favicon-32x32.png?v=1"><link rel=icon type=image/png sizes=16x16 href="/favicon-16x16.png?v=1"><link rel=manifest href="/site.webmanifest?v=1"><link rel=mask-icon href="/safari-pinned-tab.svg?v=1" color=#3775e0><link rel="shortcut icon" href="/favicon.ico?v=1"><meta name=msapplication-TileColor content="#2d89ef"><meta name=theme-color content="#ffffff"><link rel=icon href=/favicon.svg type=image/svg+xml sizes=any><style>:root{}</style></head><body><div class=container><header><h1><div><img src=https://mlir.llvm.org//mlir-logo.png width=40px align=absmiddle> MLIR</div></h1>Multi-Level IR Compiler Framework</header><div class=global-menu><nav><ul><li class=parent><a href>Community</a><ul class=sub-menu><li class=child><a href=https://llvm.discourse.group/c/mlir/31>Forums</a></li><li class=child><a href=https://discord.gg/xS7Z362>Chat</a></li></ul></li><li><a href=/getting_started/Debugging/>Debugging Tips</a></li><li><a href=/getting_started/Faq/>FAQ</a></li><li class=parent><a href=https://github.com/llvm/llvm-project/tree/main/mlir>Source</a><ul class=sub-menu><li class=child><a href=/doxygen/>Doxygen</a></li><li class=child><a href=https://github.com/llvm/llvm-project/tree/main/mlir>GitHub</a></li></ul></li><li><a href="https://bugs.llvm.org/buglist.cgi?bug_status=__open__&list_id=177877&order=changeddate%20DESC%2Cpriority%2Cbug_severity&product=MLIR&query_format=specific">Bugs</a></li><li><a href=https://github.com/llvm/mlir-www/tree/main/website/static/LogoAssets>Logo Assets</a></li><li><a href=https://www.youtube.com/MLIRCompiler>Youtube Channel</a></li></ul></nav></div><div class=content-container><main><h1>'sparse_tensor' Dialect</h1>The <code>SparseTensor</code> dialect supports all the attributes, types, operations, and passes that are required to make sparse tensor types first class citizens within the MLIR compiler infrastructure. The dialect forms a bridge between high-level operations on sparse tensors types and lower-level operations on the actual sparse storage schemes consisting of positions, coordinates, and values. Lower-level support may consist of fully generated code or may be provided by means of a small sparse runtime support library.The concept of treating sparsity as a property, not a tedious implementation detail, by letting a sparsifier generate sparse code automatically was pioneered for linear algebra by [Bik96] in MT1 (see <a href=https://www.aartbik.com/sparse.php>https://www.aartbik.com/sparse.php</a>) and formalized to tensor algebra by [Kjolstad17,Kjolstad20] in the Sparse Tensor Algebra Compiler (TACO) project (see <a href=http://tensor-compiler.org>http://tensor-compiler.org</a>). Please note that we started to prefer the term “sparsifier” over the also commonly used “sparse compiler” terminology to refer to such a pass to make it clear that the sparsifier pass is not a separate compiler, but should be an integral part of any compiler pipeline that is built with the MLIR compiler infrastructureThe MLIR implementation [Biketal22] closely follows the “sparse iteration theory” that forms the foundation of TACO. A rewriting rule is applied to each tensor expression in the Linalg dialect (MLIR’s tensor index notation) where the sparsity of tensors is indicated using the per-level level-types (e.g., dense, compressed, singleton) together with a specification of the order on the levels (see [Chou18] for an in-depth discussions and possible extensions to these level-types). Subsequently, a topologically sorted iteration graph, reflecting the required order on coordinates with respect to the levels of each tensor, is constructed to ensure that all tensors are visited in natural level-coordinate order. Next, iteration lattices are constructed for the tensor expression for every index in topological order. Each iteration lattice point consists of a conjunction of tensor coordinates together with a tensor (sub)expression that needs to be evaluated for that conjunction. Within the lattice, iteration points are ordered according to the way coordinates are exhausted. As such these iteration lattices drive actual sparse code generation, which consists of a relatively straightforward one-to-one mapping from iteration lattices to combinations of for-loops, while-loops, and if-statements. Sparse tensor outputs that materialize uninitialized are handled with direct insertions if all parallel loops are outermost or insertions that indirectly go through a 1-dimensional access pattern expansion (a.k.a. workspace) where feasible [Gustavson72,Bik96,Kjolstad19].<ul><li>[Bik96] Aart J.C. Bik. Compiler Support for Sparse Matrix Computations. PhD thesis, Leiden University, May 1996.</li><li>[Biketal22] Aart J.C. Bik, Penporn Koanantakool, Tatiana Shpeisman, Nicolas Vasilache, Bixia Zheng, and Fredrik Kjolstad. Compiler Support for Sparse Tensor Computations in MLIR. ACM Transactions on Architecture and Code Optimization, June, 2022. See: <a href=https://dl.acm.org/doi/10.1145/3544559>https://dl.acm.org/doi/10.1145/3544559</a></li><li>[Chou18] Stephen Chou, Fredrik Berg Kjolstad, and Saman Amarasinghe. Format Abstraction for Sparse Tensor Algebra Compilers. Proceedings of the ACM on Programming Languages, October 2018.</li><li>[Chou20] Stephen Chou, Fredrik Berg Kjolstad, and Saman Amarasinghe. Automatic Generation of Efficient Sparse Tensor Format Conversion Routines. Proceedings of the 41st ACM SIGPLAN Conference on Programming Language Design and Implementation, June, 2020.</li><li>[Gustavson72] Fred G. Gustavson. Some basic techniques for solving sparse systems of linear equations. In Sparse Matrices and Their Applications, pages 41–52. Plenum Press, New York, 1972.</li><li>[Kjolstad17] Fredrik Berg Kjolstad, Shoaib Ashraf Kamil, Stephen Chou, David Lugato, and Saman Amarasinghe. The Tensor Algebra Compiler. Proceedings of the ACM on Programming Languages, October 2017.</li><li>[Kjolstad19] Fredrik Berg Kjolstad, Peter Ahrens, Shoaib Ashraf Kamil, and Saman Amarasinghe. Tensor Algebra Compilation with Workspaces, Proceedings of the IEEE/ACM International Symposium on Code Generation and Optimization, 2019.</li><li>[Kjolstad20] Fredrik Berg Kjolstad. Sparse Tensor Algebra Compilation. PhD thesis, MIT, February, 2020.</li></ul><nav id=TableOfContents><ul><li><a href=#operations>Operations</a><ul><li><a href=#sparse_tensorassemble-sparse_tensorassembleop><code>sparse_tensor.assemble</code> (sparse_tensor::AssembleOp)</a></li><li><a href=#sparse_tensorbinary-sparse_tensorbinaryop><code>sparse_tensor.binary</code> (sparse_tensor::BinaryOp)</a></li><li><a href=#sparse_tensorcoiterate-sparse_tensorcoiterateop><code>sparse_tensor.coiterate</code> (sparse_tensor::CoIterateOp)</a></li><li><a href=#sparse_tensorcompress-sparse_tensorcompressop><code>sparse_tensor.compress</code> (sparse_tensor::CompressOp)</a></li><li><a href=#sparse_tensorconcatenate-sparse_tensorconcatenateop><code>sparse_tensor.concatenate</code> (sparse_tensor::ConcatenateOp)</a></li><li><a href=#sparse_tensorconvert-sparse_tensorconvertop><code>sparse_tensor.convert</code> (sparse_tensor::ConvertOp)</a></li><li><a href=#sparse_tensorcoordinates-sparse_tensortocoordinatesop><code>sparse_tensor.coordinates</code> (sparse_tensor::ToCoordinatesOp)</a></li><li><a href=#sparse_tensorcoordinates_buffer-sparse_tensortocoordinatesbufferop><code>sparse_tensor.coordinates_buffer</code> (sparse_tensor::ToCoordinatesBufferOp)</a></li><li><a href=#sparse_tensorcrd_translate-sparse_tensorcrdtranslateop><code>sparse_tensor.crd_translate</code> (sparse_tensor::CrdTranslateOp)</a></li><li><a href=#sparse_tensordisassemble-sparse_tensordisassembleop><code>sparse_tensor.disassemble</code> (sparse_tensor::DisassembleOp)</a></li><li><a href=#sparse_tensorexpand-sparse_tensorexpandop><code>sparse_tensor.expand</code> (sparse_tensor::ExpandOp)</a></li><li><a href=#sparse_tensorextract_iteration_space-sparse_tensorextractiterspaceop><code>sparse_tensor.extract_iteration_space</code> (sparse_tensor::ExtractIterSpaceOp)</a></li><li><a href=#sparse_tensorextract_value-sparse_tensorextractvalop><code>sparse_tensor.extract_value</code> (sparse_tensor::ExtractValOp)</a></li><li><a href=#sparse_tensorforeach-sparse_tensorforeachop><code>sparse_tensor.foreach</code> (sparse_tensor::ForeachOp)</a></li><li><a href=#sparse_tensorhas_runtime_library-sparse_tensorhasruntimelibraryop><code>sparse_tensor.has_runtime_library</code> (sparse_tensor::HasRuntimeLibraryOp)</a></li><li><a href=#sparse_tensoriterate-sparse_tensoriterateop><code>sparse_tensor.iterate</code> (sparse_tensor::IterateOp)</a></li><li><a href=#sparse_tensorload-sparse_tensorloadop><code>sparse_tensor.load</code> (sparse_tensor::LoadOp)</a></li><li><a href=#sparse_tensorlvl-sparse_tensorlvlop><code>sparse_tensor.lvl</code> (sparse_tensor::LvlOp)</a></li><li><a href=#sparse_tensornew-sparse_tensornewop><code>sparse_tensor.new</code> (sparse_tensor::NewOp)</a></li><li><a href=#sparse_tensornumber_of_entries-sparse_tensornumberofentriesop><code>sparse_tensor.number_of_entries</code> (sparse_tensor::NumberOfEntriesOp)</a></li><li><a href=#sparse_tensorout-sparse_tensoroutop><code>sparse_tensor.out</code> (sparse_tensor::OutOp)</a></li><li><a href=#sparse_tensorpositions-sparse_tensortopositionsop><code>sparse_tensor.positions</code> (sparse_tensor::ToPositionsOp)</a></li><li><a href=#sparse_tensorprint-sparse_tensorprintop><code>sparse_tensor.print</code> (sparse_tensor::PrintOp)</a></li><li><a href=#sparse_tensorpush_back-sparse_tensorpushbackop><code>sparse_tensor.push_back</code> (sparse_tensor::PushBackOp)</a></li><li><a href=#sparse_tensorreduce-sparse_tensorreduceop><code>sparse_tensor.reduce</code> (sparse_tensor::ReduceOp)</a></li><li><a href=#sparse_tensorreinterpret_map-sparse_tensorreinterpretmapop><code>sparse_tensor.reinterpret_map</code> (sparse_tensor::ReinterpretMapOp)</a></li><li><a href=#sparse_tensorreorder_coo-sparse_tensorreordercooop><code>sparse_tensor.reorder_coo</code> (sparse_tensor::ReorderCOOOp)</a></li><li><a href=#sparse_tensorselect-sparse_tensorselectop><code>sparse_tensor.select</code> (sparse_tensor::SelectOp)</a></li><li><a href=#sparse_tensorsliceoffset-sparse_tensortosliceoffsetop><code>sparse_tensor.slice.offset</code> (sparse_tensor::ToSliceOffsetOp)</a></li><li><a href=#sparse_tensorslicestride-sparse_tensortoslicestrideop><code>sparse_tensor.slice.stride</code> (sparse_tensor::ToSliceStrideOp)</a></li><li><a href=#sparse_tensorsort-sparse_tensorsortop><code>sparse_tensor.sort</code> (sparse_tensor::SortOp)</a></li><li><a href=#sparse_tensorstorage_specifierget-sparse_tensorgetstoragespecifierop><code>sparse_tensor.storage_specifier.get</code> (sparse_tensor::GetStorageSpecifierOp)</a></li><li><a href=#sparse_tensorstorage_specifierinit-sparse_tensorstoragespecifierinitop><code>sparse_tensor.storage_specifier.init</code> (sparse_tensor::StorageSpecifierInitOp)</a></li><li><a href=#sparse_tensorstorage_specifierset-sparse_tensorsetstoragespecifierop><code>sparse_tensor.storage_specifier.set</code> (sparse_tensor::SetStorageSpecifierOp)</a></li><li><a href=#sparse_tensorunary-sparse_tensorunaryop><code>sparse_tensor.unary</code> (sparse_tensor::UnaryOp)</a></li><li><a href=#sparse_tensorvalues-sparse_tensortovaluesop><code>sparse_tensor.values</code> (sparse_tensor::ToValuesOp)</a></li><li><a href=#sparse_tensoryield-sparse_tensoryieldop><code>sparse_tensor.yield</code> (sparse_tensor::YieldOp)</a></li></ul></li><li><a href=#attributes-17>Attributes</a><ul><li><a href=#crdtransdirectionkindattr>CrdTransDirectionKindAttr</a></li><li><a href=#sparsetensordimsliceattr>SparseTensorDimSliceAttr</a></li><li><a href=#sparsetensorencodingattr>SparseTensorEncodingAttr</a></li><li><a href=#sparsetensorsortkindattr>SparseTensorSortKindAttr</a></li><li><a href=#storagespecifierkindattr>StorageSpecifierKindAttr</a></li></ul></li><li><a href=#types>Types</a><ul><li><a href=#iterspacetype>IterSpaceType</a></li><li><a href=#iteratortype>IteratorType</a></li><li><a href=#storagespecifiertype>StorageSpecifierType</a></li></ul></li><li><a href=#enums>Enums</a><ul><li><a href=#crdtransdirectionkind>CrdTransDirectionKind</a></li><li><a href=#sparsetensorsortkind>SparseTensorSortKind</a></li><li><a href=#storagespecifierkind>StorageSpecifierKind</a></li></ul></li></ul></nav><h2 id=operations>Operations <a class=headline-hash href=#operations>¶</a></h2><a href=https://github.com/llvm/llvm-project/blob/main/mlir/include/mlir/Dialect/SparseTensor/IR/SparseTensorOps.td>source</a><h3 id=sparse_tensorassemble-sparse_tensorassembleop><code>sparse_tensor.assemble</code> (sparse_tensor::AssembleOp) <a class=headline-hash href=#sparse_tensorassemble-sparse_tensorassembleop>¶</a></h3>Returns a sparse tensor assembled from the given levels and valuesSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.assemble` ` ` `(` $levels `)` `,` $values attr-dict `:` `(` type($levels) `)` `,` type($values) `to` type($result) </code></pre>Assembles the per-level position and coordinate arrays together with the values arrays into a sparse tensor. The order and types of the provided levels must be consistent with the actual storage layout of the returned sparse tensor described below.<ul><li><code>levels: [tensor<? x iType>, ...]</code> supplies the sparse tensor position and coordinate arrays of the sparse tensor for the corresponding level as specifed by <code>sparse_tensor::StorageLayout</code>.</li><li><code>values : tensor<? x V></code> supplies the values array for the stored elements in the sparse tensor.</li></ul>This operation can be used to assemble a sparse tensor from an external source; e.g., by passing numpy arrays from Python. It is the user’s responsibility to provide input that can be correctly interpreted by the sparsifier, which does not perform any sanity test to verify data integrity.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%pos = arith.constant dense<[0, 3]> : tensor<2xindex> %index = arith.constant dense<[[0,0], [1,2], [1,3]]> : tensor<3x2xindex> %values = arith.constant dense<[ 1.1, 2.2, 3.3 ]> : tensor<3xf64> %s = sparse_tensor.assemble (%pos, %index), %values : (tensor<2xindex>, tensor<3x2xindex>), tensor<3xf64> to tensor<3x4xf64, #COO> // yields COO format |1.1, 0.0, 0.0, 0.0| // of 3x4 matrix |0.0, 0.0, 2.2, 3.3| // |0.0, 0.0, 0.0, 0.0| </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands>Operands: <a class=headline-hash href=#operands>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>levels</code></td><td>variadic of ranked tensor of signless integer or index values</td></tr><tr><td style=text-align:center><code>values</code></td><td>ranked tensor of any type values</td></tr></tbody></table><h4 id=results>Results: <a class=headline-hash href=#results>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorbinary-sparse_tensorbinaryop><code>sparse_tensor.binary</code> (sparse_tensor::BinaryOp) <a class=headline-hash href=#sparse_tensorbinary-sparse_tensorbinaryop>¶</a></h3>Binary set operation utilized within linalg.genericSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.binary` $x `,` $y `:` attr-dict type($x) `,` type($y) `to` type($output) `\n` `overlap` `=` $overlapRegion `\n` `left` `=` (`identity` $left_identity^):($leftRegion)? `\n` `right` `=` (`identity` $right_identity^):($rightRegion)? </code></pre>Defines a computation within a <code>linalg.generic</code> operation that takes two operands and executes one of the regions depending on whether both operands or either operand is nonzero (i.e. stored explicitly in the sparse storage format).Three regions are defined for the operation and must appear in this order:<ul><li>overlap (elements present in both sparse tensors)</li><li>left (elements only present in the left sparse tensor)</li><li>right (element only present in the right sparse tensor)</li></ul>Each region contains a single block describing the computation and result. Every non-empty block must end with a sparse_tensor.yield and the return type must match the type of <code>output</code>. The primary region’s block has two arguments, while the left and right region’s block has only one argument.A region may also be declared empty (i.e. <code>left={}</code>), indicating that the region does not contribute to the output. For example, setting both <code>left={}</code> and <code>right={}</code> is equivalent to the intersection of the two inputs as only the overlap region will contribute values to the output.As a convenience, there is also a special token <code>identity</code> which can be used in place of the left or right region. This token indicates that the return value is the input value (i.e. func(%x) => return %x). As a practical example, setting <code>left=identity</code> and <code>right=identity</code> would be equivalent to a union operation where non-overlapping values in the inputs are copied to the output unchanged.Due to the possibility of empty regions, i.e. lack of a value for certain cases, the result of this operation may only feed directly into the output of the <code>linalg.generic</code> operation or into into a custom reduction <code>sparse_tensor.reduce</code> operation that follows in the same region.Example of isEqual applied to intersecting elements only:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%C = tensor.empty(...) %0 = linalg.generic #trait ins(%A: tensor<?xf64, #SparseVector>, %B: tensor<?xf64, #SparseVector>) outs(%C: tensor<?xi8, #SparseVector>) { ^bb0(%a: f64, %b: f64, %c: i8) : %result = sparse_tensor.binary %a, %b : f64, f64 to i8 overlap={ ^bb0(%arg0: f64, %arg1: f64): %cmp = arith.cmpf "oeq", %arg0, %arg1 : f64 %ret_i8 = arith.extui %cmp : i1 to i8 sparse_tensor.yield %ret_i8 : i8 } left={} right={} linalg.yield %result : i8 } -> tensor<?xi8, #SparseVector> </code></pre></div>Example of A+B in upper triangle, A-B in lower triangle:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%C = tensor.empty(...) %1 = linalg.generic #trait ins(%A: tensor<?x?xf64, #CSR>, %B: tensor<?x?xf64, #CSR> outs(%C: tensor<?x?xf64, #CSR> { ^bb0(%a: f64, %b: f64, %c: f64) : %row = linalg.index 0 : index %col = linalg.index 1 : index %result = sparse_tensor.binary %a, %b : f64, f64 to f64 overlap={ ^bb0(%x: f64, %y: f64): %cmp = arith.cmpi "uge", %col, %row : index %upperTriangleResult = arith.addf %x, %y : f64 %lowerTriangleResult = arith.subf %x, %y : f64 %ret = arith.select %cmp, %upperTriangleResult, %lowerTriangleResult : f64 sparse_tensor.yield %ret : f64 } left=identity right={ ^bb0(%y: f64): %cmp = arith.cmpi "uge", %col, %row : index %lowerTriangleResult = arith.negf %y : f64 %ret = arith.select %cmp, %y, %lowerTriangleResult : f64 sparse_tensor.yield %ret : f64 } linalg.yield %result : f64 } -> tensor<?x?xf64, #CSR> </code></pre></div>Example of set difference. Returns a copy of A where its sparse structure is not overlapped by B. The element type of B can be different than A because we never use its values, only its sparse structure:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%C = tensor.empty(...) %2 = linalg.generic #trait ins(%A: tensor<?x?xf64, #CSR>, %B: tensor<?x?xi32, #CSR> outs(%C: tensor<?x?xf64, #CSR> { ^bb0(%a: f64, %b: i32, %c: f64) : %result = sparse_tensor.binary %a, %b : f64, i32 to f64 overlap={} left=identity right={} linalg.yield %result : f64 } -> tensor<?x?xf64, #CSR> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes>Attributes: <a class=headline-hash href=#attributes>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>left_identity</code></td><td>::mlir::UnitAttr</td><td>unit attribute</td></tr><tr><td><code>right_identity</code></td><td>::mlir::UnitAttr</td><td>unit attribute</td></tr></table><h4 id=operands-1>Operands: <a class=headline-hash href=#operands-1>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>x</code></td><td>any type</td></tr><tr><td style=text-align:center><code>y</code></td><td>any type</td></tr></tbody></table><h4 id=results-1>Results: <a class=headline-hash href=#results-1>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>output</code></td><td>any type</td></tr></tbody></table><h3 id=sparse_tensorcoiterate-sparse_tensorcoiterateop><code>sparse_tensor.coiterate</code> (sparse_tensor::CoIterateOp) <a class=headline-hash href=#sparse_tensorcoiterate-sparse_tensorcoiterateop>¶</a></h3>Co-iterates over a set of sparse iteration spacesThe <code>sparse_tensor.coiterate</code> operation represents a loop (nest) over a set of iteration spaces. The operation can have multiple regions, with each of them defining a case to compute a result at the current iterations. The case condition is defined solely based on the pattern of specified iterators. For example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%ret = sparse_tensor.coiterate (%sp1, %sp2) at(%coord) iter_args(%arg = %init) : (!sparse_tensor.iter_space<#CSR, lvls = 0>, !sparse_tensor.iter_space<#COO, lvls = 0>) -> index case %it1, _ { // %coord is specifed in space %sp1 but *NOT* specified in space %sp2. } case %it1, %it2 { // %coord is specifed in *BOTH* spaces %sp1 and %sp2. } </code></pre></div><code>sparse_tensor.coiterate</code> can also operate on loop-carried variables. It returns the final value for each loop-carried variable after loop termination. The initial values of the variables are passed as additional SSA operands to the iterator SSA value and used coordinate SSA values. Each operation region has variadic arguments for specified (used), one argument for each loop-carried variable, representing the value of the variable at the current iteration, followed by a list of arguments for iterators. The body region must contain exactly one block that terminates with <code>sparse_tensor.yield</code>.The results of an <code>sparse_tensor.coiterate</code> hold the final values after the last iteration. If the <code>sparse_tensor.coiterate</code> defines any values, a yield must be explicitly present in every region defined in the operation. The number and types of the <code>sparse_tensor.coiterate</code> results must match the initial values in the iter_args binding and the yield operands.A <code>sparse_tensor.coiterate</code> example that does elementwise addition between two sparse vectors.<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%ret = sparse_tensor.coiterate (%sp1, %sp2) at(%coord) iter_args(%arg = %init) : (!sparse_tensor.iter_space<#CSR, lvls = 0>, !sparse_tensor.iter_space<#CSR, lvls = 0>) -> tensor<?xindex, #CSR> case %it1, _ { // v = v1 + 0 = v1 %v1 = sparse_tensor.extract_value %t1 at %it1 : index %yield = sparse_tensor.insert %v1 into %arg[%coord] sparse_tensor.yield %yield } case _, %it2 { // v = v2 + 0 = v2 %v2 = sparse_tensor.extract_value %t2 at %it2 : index %yield = sparse_tensor.insert %v1 into %arg[%coord] sparse_tensor.yield %yield } case %it1, %it2 { // v = v1 + v2 %v1 = sparse_tensor.extract_value %t1 at %it1 : index %v2 = sparse_tensor.extract_value %t2 at %it2 : index %v = arith.addi %v1, %v2 : index %yield = sparse_tensor.insert %v into %arg[%coord] sparse_tensor.yield %yield } </code></pre></div>Traits: <code>AttrSizedOperandSegments</code>, <code>RecursiveMemoryEffects</code>, <code>SingleBlockImplicitTerminator<sparse_tensor::YieldOp></code>, <code>SingleBlock</code><h4 id=attributes-1>Attributes: <a class=headline-hash href=#attributes-1>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>crdUsedLvls</code></td><td>::mlir::IntegerAttr</td><td>LevelSet attribute</td></tr><tr><td><code>cases</code></td><td>::mlir::ArrayAttr</td><td>I64BitSet array attribute</td></tr></table><h4 id=operands-2>Operands: <a class=headline-hash href=#operands-2>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>iterSpaces</code></td><td>variadic of sparse iteration space</td></tr><tr><td style=text-align:center><code>initArgs</code></td><td>variadic of any type</td></tr></tbody></table><h4 id=results-2>Results: <a class=headline-hash href=#results-2>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>results</code></td><td>variadic of any type</td></tr></tbody></table><h3 id=sparse_tensorcompress-sparse_tensorcompressop><code>sparse_tensor.compress</code> (sparse_tensor::CompressOp) <a class=headline-hash href=#sparse_tensorcompress-sparse_tensorcompressop>¶</a></h3>Compressed an access pattern for insertionSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.compress` $values `,` $filled `,` $added `,` $count `into` $tensor `[` $lvlCoords `]` attr-dict `:` type($values) `,` type($filled) `,` type($added) `,` type($tensor) </code></pre>Finishes a single access pattern expansion by moving inserted elements into the sparse storage scheme of the given tensor with the given level-coordinates. The arity of <code>lvlCoords</code> is one less than the level-rank of the tensor, with the coordinate of the innermost level defined through the <code>added</code> array. The <code>values</code> and <code>filled</code> arrays are reset in a sparse fashion by only iterating over set elements through an indirection using the <code>added</code> array, so that the operations are kept proportional to the number of nonzeros. See the <code>sparse_tensor.expand</code> operation for more details.Note that this operation is “impure” in the sense that even though the result is modeled through an SSA value, the insertion is eventually done “in place”, and referencing the old SSA value is undefined behavior.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%result = sparse_tensor.compress %values, %filled, %added, %count into %tensor[%i] : memref<?xf64>, memref<?xi1>, memref<?xindex>, tensor<4x4xf64, #CSR> </code></pre></div>Interfaces: <code>InferTypeOpInterface</code><h4 id=operands-3>Operands: <a class=headline-hash href=#operands-3>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>values</code></td><td>strided memref of any type values of rank 1</td></tr><tr><td style=text-align:center><code>filled</code></td><td>1D memref of 1-bit signless integer values</td></tr><tr><td style=text-align:center><code>added</code></td><td>1D memref of index values</td></tr><tr><td style=text-align:center><code>count</code></td><td>index</td></tr><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr><tr><td style=text-align:center><code>lvlCoords</code></td><td>variadic of index</td></tr></tbody></table><h4 id=results-3>Results: <a class=headline-hash href=#results-3>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorconcatenate-sparse_tensorconcatenateop><code>sparse_tensor.concatenate</code> (sparse_tensor::ConcatenateOp) <a class=headline-hash href=#sparse_tensorconcatenate-sparse_tensorconcatenateop>¶</a></h3>Concatenates a list of tensors into a single tensor.Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.concatenate` $inputs attr-dict `:` type($inputs) `to` type($result) </code></pre>Concatenates a list input tensors and the output tensor with the same dimension-rank. The concatenation happens on the specified <code>dimension</code> (0 <= dimension < dimRank). The resulting <code>dimension</code> size is the sum of all the input sizes for that dimension, while all the other dimensions should have the same size in the input and output tensors.Only statically-sized input tensors are accepted, while the output tensor can be dynamically-sized.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = sparse_tensor.concatenate %1, %2 { dimension = 0 : index } : tensor<64x64xf64, #CSR>, tensor<64x64xf64, #CSR> to tensor<128x64xf64, #CSR> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>, <code>StageWithSortSparseOpInterface</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-2>Attributes: <a class=headline-hash href=#attributes-2>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>dimension</code></td><td>::mlir::IntegerAttr</td><td>dimension attribute</td></tr></table><h4 id=operands-4>Operands: <a class=headline-hash href=#operands-4>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>inputs</code></td><td>variadic of ranked tensor of any type values</td></tr></tbody></table><h4 id=results-4>Results: <a class=headline-hash href=#results-4>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>ranked tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorconvert-sparse_tensorconvertop><code>sparse_tensor.convert</code> (sparse_tensor::ConvertOp) <a class=headline-hash href=#sparse_tensorconvert-sparse_tensorconvertop>¶</a></h3>Converts between different tensor typesSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.convert` $source attr-dict `:` type($source) `to` type($dest) </code></pre>Converts one sparse or dense tensor type to another tensor type. The rank of the source and destination types must match exactly, and the dimension sizes must either match exactly or relax from a static to a dynamic size. The sparse encoding of the two types can obviously be completely different. The name <code>convert</code> was preferred over <code>cast</code>, since the operation may incur a non-trivial cost.When converting between two different sparse tensor types, only explicitly stored values are moved from one underlying sparse storage format to the other. When converting from an unannotated dense tensor type to a sparse tensor type, an explicit test for nonzero values is used. When converting to an unannotated dense tensor type, implicit zeroes in the sparse storage format are made explicit. Note that the conversions can have non-trivial costs associated with them, since they may involve elaborate data structure transformations. Also, conversions from sparse tensor types into dense tensor types may be infeasible in terms of storage requirements.Trivial dense-to-dense convert will be removed by canonicalization while trivial sparse-to-sparse convert will be removed by the sparse codegen. This is because we use trivial sparse-to-sparse convert to tell bufferization that the sparse codegen will expand the tensor buffer into sparse tensor storage.Examples:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = sparse_tensor.convert %a : tensor<32x32xf32> to tensor<32x32xf32, #CSR> %1 = sparse_tensor.convert %a : tensor<32x32xf32> to tensor<?x?xf32, #CSR> %2 = sparse_tensor.convert %b : tensor<8x8xi32, #CSC> to tensor<8x8xi32, #CSR> %3 = sparse_tensor.convert %c : tensor<4x8xf64, #CSR> to tensor<4x?xf64, #CSC> // The following conversion is not allowed (since it would require a // runtime assertion that the source's dimension size is actually 100). %4 = sparse_tensor.convert %d : tensor<?xf64> to tensor<100xf64, #SV> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>, <code>StageWithSortSparseOpInterface</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-5>Operands: <a class=headline-hash href=#operands-5>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>source</code></td><td>ranked tensor of any type values</td></tr></tbody></table><h4 id=results-5>Results: <a class=headline-hash href=#results-5>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>dest</code></td><td>ranked tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorcoordinates-sparse_tensortocoordinatesop><code>sparse_tensor.coordinates</code> (sparse_tensor::ToCoordinatesOp) <a class=headline-hash href=#sparse_tensorcoordinates-sparse_tensortocoordinatesop>¶</a></h3>Extracts the <code>level</code>-th coordinates array of the <code>tensor</code>Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.coordinates` $tensor attr-dict `:` type($tensor) `to` type($result) </code></pre>Returns the coordinates array of the tensor’s storage at the given level. This is similar to the <code>bufferization.to_memref</code> operation in the sense that it provides a bridge between a tensor world view and a bufferized world view. Unlike the <code>bufferization.to_memref</code> operation, however, this sparse operation actually lowers into code that extracts the coordinates array from the sparse storage itself (either by calling a support library or through direct code).Writing into the result of this operation is undefined behavior.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%1 = sparse_tensor.coordinates %0 { level = 1 : index } : tensor<64x64xf64, #CSR> to memref<?xindex> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-3>Attributes: <a class=headline-hash href=#attributes-3>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>level</code></td><td>::mlir::IntegerAttr</td><td>level attribute</td></tr></table><h4 id=operands-6>Operands: <a class=headline-hash href=#operands-6>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-6>Results: <a class=headline-hash href=#results-6>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>non-0-ranked.memref of any type values</td></tr></tbody></table><h3 id=sparse_tensorcoordinates_buffer-sparse_tensortocoordinatesbufferop><code>sparse_tensor.coordinates_buffer</code> (sparse_tensor::ToCoordinatesBufferOp) <a class=headline-hash href=#sparse_tensorcoordinates_buffer-sparse_tensortocoordinatesbufferop>¶</a></h3>Extracts the linear coordinates array from a tensorSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.coordinates_buffer` $tensor attr-dict `:` type($tensor) `to` type($result) </code></pre>Returns the linear coordinates array for a sparse tensor with a trailing COO region with at least two levels. It is an error if the tensor doesn’t contain such a COO region. This is similar to the <code>bufferization.to_memref</code> operation in the sense that it provides a bridge between a tensor world view and a bufferized world view. Unlike the <code>bufferization.to_memref</code> operation, however, this operation actually lowers into code that extracts the linear coordinates array from the sparse storage scheme that stores the coordinates for the COO region as an array of structures. For example, a 2D COO sparse tensor with two non-zero elements at coordinates (1, 3) and (4, 6) are stored in a linear buffer as (1, 4, 3, 6) instead of two buffer as (1, 4) and (3, 6).Writing into the result of this operation is undefined behavior.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%1 = sparse_tensor.coordinates_buffer %0 : tensor<64x64xf64, #COO> to memref<?xindex> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-7>Operands: <a class=headline-hash href=#operands-7>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-7>Results: <a class=headline-hash href=#results-7>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>non-0-ranked.memref of any type values</td></tr></tbody></table><h3 id=sparse_tensorcrd_translate-sparse_tensorcrdtranslateop><code>sparse_tensor.crd_translate</code> (sparse_tensor::CrdTranslateOp) <a class=headline-hash href=#sparse_tensorcrd_translate-sparse_tensorcrdtranslateop>¶</a></h3>Performs coordinate translation between level and dimension coordinate space.Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.crd_translate` $direction `[` $in_crds `]` `as` $encoder attr-dict `:` type($out_crds) </code></pre>Performs coordinate translation between level and dimension coordinate space according to the affine maps defined by $encoder.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%l0, %l1, %l2, %l3 = sparse_tensor.crd_translate dim_to_lvl [%d0, %d1] as #BSR : index, index, index, index </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-4>Attributes: <a class=headline-hash href=#attributes-4>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>direction</code></td><td>::mlir::sparse_tensor::CrdTransDirectionKindAttr</td><td><details><summary>sparse tensor coordinate translation direction</summary>Enum cases:<ul><li>dim_to_lvl (<code>dim2lvl</code>)</li><li>lvl_to_dim (<code>lvl2dim</code>)</li></ul></details></td></tr><tr><td><code>encoder</code></td><td>::mlir::sparse_tensor::SparseTensorEncodingAttr</td><td><details><summary></summary><pre><code>An attribute to encode information on sparsity properties of tensors, inspired by the TACO formalization of sparse tensors. This encoding is eventually used by a **sparsifier** pass to generate sparse code fully automatically from a sparsity-agnostic representation of the computation, i.e., an implicit sparse representation is converted to an explicit sparse representation where co-iterating loops operate on sparse storage formats rather than tensors with a sparsity encoding. Compiler passes that run before this sparsifier pass need to be aware of the semantics of tensor types with such a sparsity encoding. In this encoding, we use dimension to refer to the axes of the semantic tensor, and level to refer to the axes of the actual storage format, i.e., the operational representation of the sparse tensor in memory. The number of dimensions is usually the same as the number of levels (such as CSR storage format). However, the encoding can also map dimensions to higher-order levels (for example, to encode a block-sparse BSR storage format) or to lower-order levels (for example, to linearize dimensions as a single level in the storage). The encoding contains a map that provides the following: <ul> <li>An ordered sequence of dimension specifications, each of which defines: <ul> <li>the dimension-size (implicit from the tensor’s dimension-shape)</li> <li>a dimension-expression</li> </ul> </li> <li>An ordered sequence of level specifications, each of which includes a required level-type, which defines how the level should be stored. Each level-type consists of: <ul> <li>a level-expression, which defines what is stored</li> <li>a level-format</li> <li>a collection of level-properties that apply to the level-format</li> </ul> </li> </ul> Each level-expression is an affine expression over dimension-variables. Thus, the level-expressions collectively define an affine map from dimension-coordinates to level-coordinates. The dimension-expressions collectively define the inverse map, which only needs to be provided for elaborate cases where it cannot be inferred automatically. Each dimension could also have an optional <code>SparseTensorDimSliceAttr</code>. Within the sparse storage format, we refer to indices that are stored explicitly as coordinates and offsets into the storage format as positions. The supported level-formats are the following: <ul> <li>dense : all entries along this level are stored and linearized.</li> <li>batch : all entries along this level are stored but not linearized.</li> <li>compressed : only nonzeros along this level are stored</li> <li>loose_compressed : as compressed, but allows for free space between regions</li> <li>singleton : a variant of the compressed format, where coordinates have no siblings</li> <li>structured[n, m] : the compression uses a n:m encoding (viz. n out of m consecutive elements are nonzero)</li> </ul> For a compressed level, each position interval is represented in a compact way with a lowerbound <code>pos(i)</code> and an upperbound <code>pos(i+1) - 1</code>, which implies that successive intervals must appear in order without any "holes" in between them. The loose compressed format relaxes these constraints by representing each position interval with a lowerbound <code>lo(i)</code> and an upperbound <code>hi(i)</code>, which allows intervals to appear in arbitrary order and with elbow room between them. By default, each level-type has the property of being unique (no duplicate coordinates at that level) and ordered (coordinates appear sorted at that level). For singleton levels, the coordinates are fused with its parents in AoS (array of structures) scheme. The following properties can be added to a level-format to change this default behavior: <ul> <li>nonunique : duplicate coordinates may appear at the level</li> <li>nonordered : coordinates may appear in arbribratry order</li> <li>soa : only applicable to singleton levels, fuses the singleton level in SoA (structure of arrays) scheme.</li> </ul> In addition to the map, the following fields are optional: <ul> <li> The required bitwidth for position 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 levels). The choices are <code>8</code>, <code>16</code>, <code>32</code>, <code>64</code>, or, the default, <code>0</code> to indicate the native bitwidth. </li> <li> The required bitwidth for coordinate storage (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 coordinate over all levels). The choices are <code>8</code>, <code>16</code>, <code>32</code>, <code>64</code>, or, the default, <code>0</code> to indicate a native bitwidth. </li> <li> The explicit value for the sparse tensor. If explicitVal is set, then all the non-zero values in the tensor have the same explicit value. The default value Attribute() indicates that it is not set. This is useful for binary-valued sparse tensors whose values can either be an implicit value (0 by default) or an explicit value (such as 1). In this approach, we don’t store explicit/implicit values, and metadata (such as position and coordinate arrays) alone fully defines the original tensor. This yields additional savings for the storage requirements, as well as for the computational time, since we skip operating on implicit values and can constant fold the explicit values where they are used. </li> <li> The implicit value for the sparse tensor. If implicitVal is set, then the "zero" value in the tensor is equal to the implicit value. For now, we only support <code>0</code> as the implicit value but it could be extended in the future. The default value Attribute() indicates that the implicit value is <code>0</code> (same type as the tensor element type). </li> </ul> Examples: <div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// Sparse vector. #SparseVector = #sparse_tensor.encoding&lt;{ map = (i) -&gt; (i : compressed) }&gt; ... tensor&lt;?xf32, #SparseVector&gt; ... // Sorted coordinate scheme (arranged in AoS format by default). #SortedCOO = #sparse_tensor.encoding&lt;{ map = (i, j) -&gt; (i : compressed(nonunique), j : singleton) }&gt; // coordinates = {x_crd, y_crd}[nnz] ... tensor&lt;?x?xf64, #SortedCOO&gt; ... // Sorted coordinate scheme (arranged in SoA format). #SortedCOO = #sparse_tensor.encoding&lt;{ map = (i, j) -&gt; (i : compressed(nonunique), j : singleton(soa)) }&gt; // coordinates = {x_crd[nnz], y_crd[nnz]} ... tensor&lt;?x?xf64, #SortedCOO&gt; ... // Batched sorted coordinate scheme, with high encoding. #BCOO = #sparse_tensor.encoding&lt;{ map = (i, j, k) -&gt; (i : dense, j : compressed(nonunique, high), k : singleton) }&gt; ... tensor&lt;10x10xf32, #BCOO&gt; ... // Compressed sparse row. #CSR = #sparse_tensor.encoding&lt;{ map = (i, j) -&gt; (i : dense, j : compressed) }&gt; ... tensor&lt;100x100xbf16, #CSR&gt; ... // Doubly compressed sparse column storage with specific bitwidths. #DCSC = #sparse_tensor.encoding&lt;{ map = (i, j) -&gt; (j : compressed, i : compressed), posWidth = 32, crdWidth = 8 }&gt; ... tensor&lt;8x8xf64, #DCSC&gt; ... // Doubly compressed sparse column storage with specific // explicit and implicit values. #DCSC = #sparse_tensor.encoding&lt;{ map = (i, j) -&gt; (j : compressed, i : compressed), explicitVal = 1 : i64, implicitVal = 0 : i64 }&gt; ... tensor&lt;8x8xi64, #DCSC&gt; ... // Block sparse row storage (2x3 blocks). #BSR = #sparse_tensor.encoding&lt;{ map = ( i, j ) -&gt; ( i floordiv 2 : dense, j floordiv 3 : compressed, i mod 2 : dense, j mod 3 : dense ) }&gt; ... tensor&lt;20x30xf32, #BSR&gt; ... // Same block sparse row storage (2x3 blocks) but this time // also with a redundant reverse mapping, which can be inferred. #BSR_explicit = #sparse_tensor.encoding&lt;{ map = { ib, jb, ii, jj } ( i = ib * 2 + ii, j = jb * 3 + jj) -&gt; ( ib = i floordiv 2 : dense, jb = j floordiv 3 : compressed, ii = i mod 2 : dense, jj = j mod 3 : dense) }&gt; ... tensor&lt;20x30xf32, #BSR_explicit&gt; ... // ELL format. // In the simple format for matrix, one array stores values and another // array stores column indices. The arrays have the same number of rows // as the original matrix, but only have as many columns as // the maximum number of nonzeros on a row of the original matrix. // There are many variants for ELL such as jagged diagonal scheme. // To implement ELL, map provides a notion of &quot;counting a // dimension&quot;, where every stored element with the same coordinate // is mapped to a new slice. For instance, ELL storage of a 2-d // tensor can be defined with the mapping (i, j) -&gt; (#i, i, j) // using the notation of [Chou20]. Lacking the # symbol in MLIR's // affine mapping, we use a free symbol c to define such counting, // together with a constant that denotes the number of resulting // slices. For example, the mapping [c](i, j) -&gt; (c * 3 * i, i, j) // with the level-types [&quot;dense&quot;, &quot;dense&quot;, &quot;compressed&quot;] denotes ELL // storage with three jagged diagonals that count the dimension i. #ELL = #sparse_tensor.encoding&lt;{ map = [c](i, j) -&gt; (c * 3 * i : dense, i : dense, j : compressed) }&gt; ... tensor&lt;?x?xf64, #ELL&gt; ... // CSR slice (offset = 0, size = 4, stride = 1 on the first dimension; // offset = 0, size = 8, and a dynamic stride on the second dimension). #CSR_SLICE = #sparse_tensor.encoding&lt;{ map = (i : #sparse_tensor&lt;slice(0, 4, 1)&gt;, j : #sparse_tensor&lt;slice(0, 8, ?)&gt;) -&gt; (i : dense, j : compressed) }&gt; ... tensor&lt;?x?xf64, #CSR_SLICE&gt; ... </code></pre></div></code></pre></details></td></tr></table><h4 id=operands-8>Operands: <a class=headline-hash href=#operands-8>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>in_crds</code></td><td>variadic of index</td></tr></tbody></table><h4 id=results-8>Results: <a class=headline-hash href=#results-8>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>out_crds</code></td><td>variadic of index</td></tr></tbody></table><h3 id=sparse_tensordisassemble-sparse_tensordisassembleop><code>sparse_tensor.disassemble</code> (sparse_tensor::DisassembleOp) <a class=headline-hash href=#sparse_tensordisassemble-sparse_tensordisassembleop>¶</a></h3>Copies the levels and values of the given sparse tensorSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.disassemble` $tensor attr-dict `:` type($tensor)`out_lvls` `(` $out_levels `:` type($out_levels) `)` `out_vals` `(` $out_values `:` type($out_values) `)` `->``(` type($ret_levels) `)` `,` type($ret_values) `,` `(` type($lvl_lens) `)` `,` type($val_len) </code></pre>The disassemble operation is the inverse of <code>sparse_tensor::assemble</code>. It copies the per-level position and coordinate arrays together with the values array of the given sparse tensor into the user-supplied buffers along with the actual length of the memory used in each returned buffer.This operation can be used for returning a disassembled MLIR sparse tensor; e.g., copying the sparse tensor contents into pre-allocated numpy arrays back to Python. It is the user’s responsibility to allocate large enough buffers of the appropriate types to hold the sparse tensor contents. The sparsifier simply copies all fields of the sparse tensor into the user-supplied buffers without any sanity test to verify data integrity.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// input COO format |1.1, 0.0, 0.0, 0.0| // of 3x4 matrix |0.0, 0.0, 2.2, 3.3| // |0.0, 0.0, 0.0, 0.0| %p, %c, %v, %p_len, %c_len, %v_len = sparse_tensor.disassemble %s : tensor<3x4xf64, #COO> out_lvls(%op, %oi : tensor<2xindex>, tensor<3x2xindex>) out_vals(%od : tensor<3xf64>) -> (tensor<2xindex>, tensor<3x2xindex>), tensor<3xf64>, (index, index), index // %p = arith.constant dense<[ 0, 3 ]> : tensor<2xindex> // %c = arith.constant dense<[[0,0], [1,2], [1,3]]> : tensor<3x2xindex> // %v = arith.constant dense<[ 1.1, 2.2, 3.3 ]> : tensor<3xf64> // %p_len = 2 // %c_len = 6 (3x2) // %v_len = 3 </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>, <code>SameVariadicResultSize</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-9>Operands: <a class=headline-hash href=#operands-9>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr><tr><td style=text-align:center><code>out_levels</code></td><td>variadic of ranked tensor of signless integer or index values</td></tr><tr><td style=text-align:center><code>out_values</code></td><td>ranked tensor of any type values</td></tr></tbody></table><h4 id=results-9>Results: <a class=headline-hash href=#results-9>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>ret_levels</code></td><td>variadic of ranked tensor of signless integer or index values</td></tr><tr><td style=text-align:center><code>ret_values</code></td><td>ranked tensor of any type values</td></tr><tr><td style=text-align:center><code>lvl_lens</code></td><td>variadic of scalar like</td></tr><tr><td style=text-align:center><code>val_len</code></td><td>scalar like</td></tr></tbody></table><h3 id=sparse_tensorexpand-sparse_tensorexpandop><code>sparse_tensor.expand</code> (sparse_tensor::ExpandOp) <a class=headline-hash href=#sparse_tensorexpand-sparse_tensorexpandop>¶</a></h3>Expands an access pattern for insertionSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.expand` $tensor attr-dict `:` type($tensor) `to` type($values) `,` type($filled) `,` type($added) </code></pre>Performs an access pattern expansion for the innermost levels of the given tensor. This operation is useful to implement kernels in which a sparse tensor appears as output. This technique is known under several different names and using several alternative implementations, for example, phase counter [Gustavson72], expanded or switch array [Pissanetzky84], in phase scan [Duff90], access pattern expansion [Bik96], and workspaces [Kjolstad19].The <code>values</code> and <code>filled</code> arrays must have lengths equal to the level-size of the innermost level (i.e., as if the innermost level were dense). The <code>added</code> array and <code>count</code> are used to store new level-coordinates when a false value is encountered in the <code>filled</code> array. All arrays should be allocated before the loop (possibly even shared between loops in a future optimization) so that their dense initialization can be amortized over many iterations. Setting and resetting the dense arrays in the loop nest itself is kept sparse by only iterating over set elements through an indirection using the added array, so that the operations are kept proportional to the number of nonzeros.Note that this operation is “impure” in the sense that even though the results are modeled through SSA values, the operation relies on a proper side-effecting context that sets and resets the expanded arrays.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%values, %filled, %added, %count = sparse_tensor.expand %tensor : tensor<4x4xf64, #CSR> to memref<?xf64>, memref<?xi1>, memref<?xindex> </code></pre></div><h4 id=operands-10>Operands: <a class=headline-hash href=#operands-10>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-10>Results: <a class=headline-hash href=#results-10>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>values</code></td><td>strided memref of any type values of rank 1</td></tr><tr><td style=text-align:center><code>filled</code></td><td>1D memref of 1-bit signless integer values</td></tr><tr><td style=text-align:center><code>added</code></td><td>1D memref of index values</td></tr><tr><td style=text-align:center><code>count</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensorextract_iteration_space-sparse_tensorextractiterspaceop><code>sparse_tensor.extract_iteration_space</code> (sparse_tensor::ExtractIterSpaceOp) <a class=headline-hash href=#sparse_tensorextract_iteration_space-sparse_tensorextractiterspaceop>¶</a></h3>Extracts an iteration space from a sparse tensor between certain levelsSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.extract_iteration_space` $tensor (`at` $parentIter^)? `lvls` `=` custom<LevelRange>($loLvl, $hiLvl) attr-dict `:` type($tensor) (`,` type($parentIter)^)? `->` qualified(type($extractedSpace)) </code></pre>Extracts a <code>!sparse_tensor.iter_space</code> from a sparse tensor between certain (consecutive) levels. For sparse levels, it is usually done by loading a postion range from the underlying sparse tensor storage. E.g., for a compressed level, the iteration space is extracted by [pos[i], pos[i+1]) supposing the the parent iterator points at <code>i</code>.<code>tensor</code>: the input sparse tensor that defines the iteration space. <code>parentIter</code>: the iterator for the previous level, at which the iteration space at the current levels will be extracted. <code>loLvl</code>, <code>hiLvl</code>: the level range between [loLvl, hiLvl) in the input tensor that the returned iteration space covers. <code>hiLvl - loLvl</code> defines the dimension of the iteration space.The type of returned the value is must be <code>!sparse_tensor.iter_space<#INPUT_ENCODING, lvls = $loLvl to $hiLvl></code>. The returned iteration space can then be iterated over by <code>sparse_tensor.iterate</code> operations to visit every stored element (usually nonzeros) in the input sparse tensor.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// Extracts a 1-D iteration space from a COO tensor at level 1. %space = sparse_tensor.iteration.extract_space %sp at %it1 lvls = 1 : tensor<4x8xf32, #COO>, !sparse_tensor.iterator<#COO, lvls = 0> ->!sparse_tensor.iter_space<#COO, lvls = 1> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-5>Attributes: <a class=headline-hash href=#attributes-5>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>loLvl</code></td><td>::mlir::IntegerAttr</td><td>level attribute</td></tr><tr><td><code>hiLvl</code></td><td>::mlir::IntegerAttr</td><td>level attribute</td></tr></table><h4 id=operands-11>Operands: <a class=headline-hash href=#operands-11>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr><tr><td style=text-align:center><code>parentIter</code></td><td>sparse iterator</td></tr></tbody></table><h4 id=results-11>Results: <a class=headline-hash href=#results-11>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>extractedSpace</code></td><td>sparse iteration space</td></tr></tbody></table><h3 id=sparse_tensorextract_value-sparse_tensorextractvalop><code>sparse_tensor.extract_value</code> (sparse_tensor::ExtractValOp) <a class=headline-hash href=#sparse_tensorextract_value-sparse_tensorextractvalop>¶</a></h3>Extracts a value from a sparse tensor using an iterator.Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.extract_value` $tensor `at` $iterator attr-dict `:` type($tensor)`,` qualified(type($iterator)) </code></pre>The <code>sparse_tensor.extract_value</code> operation extracts the value pointed to by a sparse iterator from a sparse tensor.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%val = sparse_tensor.extract_value %sp at %it : tensor<?x?xf32, #CSR>, !sparse_tensor.iterator<#CSR, lvl = 1> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-12>Operands: <a class=headline-hash href=#operands-12>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr><tr><td style=text-align:center><code>iterator</code></td><td>sparse iterator</td></tr></tbody></table><h4 id=results-12>Results: <a class=headline-hash href=#results-12>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>any type</td></tr></tbody></table><h3 id=sparse_tensorforeach-sparse_tensorforeachop><code>sparse_tensor.foreach</code> (sparse_tensor::ForeachOp) <a class=headline-hash href=#sparse_tensorforeach-sparse_tensorforeachop>¶</a></h3>Iterates over elements in a tensorSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.foreach` `in` $tensor (`init``(`$initArgs^`)`)? attr-dict `:` type($tensor) (`,` type($initArgs)^)? (`->` type($results)^)? `do` $region </code></pre>Iterates over stored elements in a tensor (which are typically, but not always, non-zero for sparse tensors) and executes the block.<code>tensor</code>: the input tensor to iterate over. <code>initArgs</code>: the initial loop argument to carry and update during each iteration. <code>order</code>: an optional permutation affine map that specifies the order in which the dimensions are visited (e.g., row first or column first). This is only applicable when the input tensor is a non-annotated dense tensor.For an input tensor with dim-rank <code>n</code>, the block must take <code>n + 1</code> arguments (plus additional loop-carried variables as described below). The first <code>n</code> arguments provide the dimension-coordinates of the element being visited, and must all have <code>index</code> type. The <code>(n+1)</code>-th argument provides the element’s value, and must have the tensor’s element type.<code>sparse_tensor.foreach</code> can also operate on loop-carried variables and returns the final values after loop termination. The initial values of the variables are passed as additional SSA operands to the “sparse_tensor.foreach” following the n + 1 SSA values mentioned above (n coordinates and 1 value).The region must terminate with a “sparse_tensor.yield” that passes the current values of all loop-carried variables to the next iteration, or to the result, if at the last iteration. The number and static types of loop-carried variables may not change with iterations.For example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%c0 = arith.constant 0 : i32 %ret = sparse_tensor.foreach in %0 init(%c0): tensor<?x?xi32, #DCSR>, i32 -> i32 do { ^bb0(%arg1: index, %arg2: index, %arg3: i32, %iter: i32): %sum = arith.add %iter, %arg3 sparse_tensor.yield %sum } </code></pre></div>It is important to note that the generated loop iterates over elements in their storage order. However, regardless of the storage scheme used by the tensor, the block is always given the dimension-coordinates.For example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>#COL_MAJOR = #sparse_tensor.encoding<{ map = (d0, d1) -> (d1 : compressed, d0 : compressed) }> // 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<{ map = (d0, d1) -> (d0 : compressed, d1 : 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] } // foreach on a row-major dense tensor but visit column first sparse_tensor.foreach in %0 {order=affine_map<(i,j)->(j,i)>}: tensor<2x3xf64> do { ^bb0(%row: index, %col: index, %arg3: f64): // [%row, %col] -> [0, 0], [1, 0], [2, 0], [0, 1], [1, 1], [2, 1] } </code></pre></div>Traits: <code>SingleBlockImplicitTerminator<YieldOp></code>, <code>SingleBlock</code><h4 id=attributes-6>Attributes: <a class=headline-hash href=#attributes-6>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>order</code></td><td>::mlir::AffineMapAttr</td><td>AffineMap attribute</td></tr></table><h4 id=operands-13>Operands: <a class=headline-hash href=#operands-13>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>ranked tensor of any type values</td></tr><tr><td style=text-align:center><code>initArgs</code></td><td>variadic of any type</td></tr></tbody></table><h4 id=results-13>Results: <a class=headline-hash href=#results-13>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>results</code></td><td>variadic of any type</td></tr></tbody></table><h3 id=sparse_tensorhas_runtime_library-sparse_tensorhasruntimelibraryop><code>sparse_tensor.has_runtime_library</code> (sparse_tensor::HasRuntimeLibraryOp) <a class=headline-hash href=#sparse_tensorhas_runtime_library-sparse_tensorhasruntimelibraryop>¶</a></h3>Indicates whether running in runtime/codegen modeSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.has_runtime_library` attr-dict </code></pre>Returns a boolean value that indicates whether the sparsifier runs in runtime library mode or not. For testing only! This operation is useful for writing test cases that require different code depending on runtime/codegen mode.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%has_runtime = sparse_tensor.has_runtime_library scf.if %has_runtime { ... } </code></pre></div>Interfaces: <code>InferTypeOpInterface</code><h4 id=results-14>Results: <a class=headline-hash href=#results-14>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>1-bit signless integer</td></tr></tbody></table><h3 id=sparse_tensoriterate-sparse_tensoriterateop><code>sparse_tensor.iterate</code> (sparse_tensor::IterateOp) <a class=headline-hash href=#sparse_tensoriterate-sparse_tensoriterateop>¶</a></h3>Iterates over a sparse iteration spaceThe <code>sparse_tensor.iterate</code> operation represents a loop (nest) over the provided iteration space extracted from a specific sparse tensor. The operation defines an SSA value for a sparse iterator that points to the current stored element in the sparse tensor and SSA values for coordinates of the stored element. The coordinates are always converted to <code>index</code> type despite of the underlying sparse tensor storage. When coordinates are not used, the SSA values can be skipped by <code>_</code> symbols, which usually leads to simpler generated code after sparsification. For example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// The coordinate for level 0 is not used when iterating over a 2-D // iteration space. %sparse_tensor.iterate %iterator in %space at(_, %crd_1) : !sparse_tensor.iter_space<#CSR, lvls = 0 to 2> </code></pre></div><code>sparse_tensor.iterate</code> can also operate on loop-carried variables. It returns the final values after loop termination. The initial values of the variables are passed as additional SSA operands to the iterator SSA value and used coordinate SSA values mentioned above. The operation region has an argument for the iterator, variadic arguments for specified (used) coordiates and followed by one argument for each loop-carried variable, representing the value of the variable at the current iteration. The body region must contain exactly one block that terminates with <code>sparse_tensor.yield</code>.The results of an <code>sparse_tensor.iterate</code> hold the final values after the last iteration. If the <code>sparse_tensor.iterate</code> defines any values, a yield must be explicitly present. The number and types of the <code>sparse_tensor.iterate</code> results must match the initial values in the iter_args binding and the yield operands.A nested <code>sparse_tensor.iterate</code> example that prints all the coordinates stored in the sparse input:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>func.func @nested_iterate(%sp : tensor<4x8xf32, #COO>) { // Iterates over the first level of %sp %l1 = sparse_tensor.extract_iteration_space %sp lvls = 0 : tensor<4x8xf32, #COO> -> !sparse_tensor.iter_space<#COO, lvls = 0 to 1> %r1 = sparse_tensor.iterate %it1 in %l1 at (%coord0) : !sparse_tensor.iter_space<#COO, lvls = 0 to 1> { // Iterates over the second level of %sp %l2 = sparse_tensor.extract_iteration_space %sp at %it1 lvls = 1 : tensor<4x8xf32, #COO>, !sparse_tensor.iterator<#COO, lvls = 0 to 1> -> !sparse_tensor.iter_space<#COO, lvls = 1 to 2> %r2 = sparse_tensor.iterate %it2 in %l2 at (coord1) : !sparse_tensor.iter_space<#COO, lvls = 1 to 2> { vector.print %coord0 : index vector.print %coord1 : index } } } </code></pre></div>Traits: <code>RecursiveMemoryEffects</code>, <code>RecursivelySpeculatableImplTrait</code>, <code>SingleBlockImplicitTerminator<sparse_tensor::YieldOp></code>, <code>SingleBlock</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>LoopLikeOpInterface</code>, <code>RegionBranchOpInterface</code><h4 id=attributes-7>Attributes: <a class=headline-hash href=#attributes-7>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>crdUsedLvls</code></td><td>::mlir::IntegerAttr</td><td>LevelSet attribute</td></tr></table><h4 id=operands-14>Operands: <a class=headline-hash href=#operands-14>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>iterSpace</code></td><td>sparse iteration space</td></tr><tr><td style=text-align:center><code>initArgs</code></td><td>variadic of any type</td></tr></tbody></table><h4 id=results-15>Results: <a class=headline-hash href=#results-15>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>results</code></td><td>variadic of any type</td></tr></tbody></table><h3 id=sparse_tensorload-sparse_tensorloadop><code>sparse_tensor.load</code> (sparse_tensor::LoadOp) <a class=headline-hash href=#sparse_tensorload-sparse_tensorloadop>¶</a></h3>Rematerializes tensor from underlying sparse storage formatSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.load` $tensor (`hasInserts` $hasInserts^)? attr-dict `:` type($tensor) </code></pre>Rematerializes a tensor from the underlying sparse storage format of the given tensor. This is similar to the <code>bufferization.to_tensor</code> operation in the sense that it provides a bridge between a bufferized world view and a tensor world view. Unlike the <code>bufferization.to_tensor</code> operation, however, this sparse operation is used only temporarily to maintain a correctly typed intermediate representation during progressive bufferization.The <code>hasInserts</code> attribute denote whether insertions to the underlying sparse storage format may have occurred, in which case the underlying sparse storage format needs to be finalized. Otherwise, the operation simply folds away.Note that this operation is “impure” in the sense that even though the result is modeled through an SSA value, the operation relies on a proper context of materializing and inserting the tensor value.Examples:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%result = sparse_tensor.load %tensor : tensor<8xf64, #SV> %1 = sparse_tensor.load %0 hasInserts : tensor<16x32xf32, #CSR> </code></pre></div>Traits: <code>SameOperandsAndResultType</code>Interfaces: <code>InferTypeOpInterface</code><h4 id=attributes-8>Attributes: <a class=headline-hash href=#attributes-8>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>hasInserts</code></td><td>::mlir::UnitAttr</td><td>unit attribute</td></tr></table><h4 id=operands-15>Operands: <a class=headline-hash href=#operands-15>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-16>Results: <a class=headline-hash href=#results-16>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorlvl-sparse_tensorlvlop><code>sparse_tensor.lvl</code> (sparse_tensor::LvlOp) <a class=headline-hash href=#sparse_tensorlvl-sparse_tensorlvlop>¶</a></h3>Level index operationSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.lvl` attr-dict $source `,` $index `:` type($source) </code></pre>The <code>sparse_tensor.lvl</code> behaves similar to <code>tensor.dim</code> operation. It takes a sparse tensor and a level operand of type <code>index</code> and returns the size of the requested level of the given sparse tensor. If the sparse tensor has an identity dimension to level mapping, it returns the same result as <code>tensor.dim</code>. If the level index is out of bounds, the behavior is undefined.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>#BSR = #sparse_tensor.encoding<{ map = ( i, j ) -> ( i floordiv 2 : dense, j floordiv 3 : compressed, i mod 2 : dense, j mod 3 : dense ) }> // Always returns 2 (4 floordiv 2), can be constant folded: %c0 = arith.constant 0 : index %x = sparse_tensor.lvl %A, %c0 : tensor<4x?xf32, #BSR> // Return the dynamic dimension of %A computed by %j mod 3. %c1 = arith.constant 1 : index %y = sparse_tensor.lvl %A, %c1 : tensor<4x?xf32, #BSR> // Always return 3 (since j mod 3 < 3), can be constant fold %c3 = arith.constant 3 : index %y = sparse_tensor.lvl %A, %c3 : tensor<4x?xf32, #BSR> </code></pre></div>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-16>Operands: <a class=headline-hash href=#operands-16>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>source</code></td><td>sparse tensor of any type values</td></tr><tr><td style=text-align:center><code>index</code></td><td>index</td></tr></tbody></table><h4 id=results-17>Results: <a class=headline-hash href=#results-17>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensornew-sparse_tensornewop><code>sparse_tensor.new</code> (sparse_tensor::NewOp) <a class=headline-hash href=#sparse_tensornew-sparse_tensornewop>¶</a></h3>Materializes a new sparse tensor from given sourceSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.new` $source attr-dict `:` type($source) `to` type($result) </code></pre>Materializes a sparse tensor with contents taken from an opaque pointer provided by <code>source</code>. For targets that have access to a file system, for example, this pointer may be a filename (or file) of a sparse tensor in a particular external storage format. The form of the operation is kept deliberately very general to allow for alternative implementations in the future, such as pointers to buffers or runnable initialization code. The operation is provided as an anchor that materializes a properly typed sparse tensor with inital contents into a computation.Reading in a symmetric matrix will result in just the lower/upper triangular part of the matrix (so that only relevant information is stored). Proper symmetry support for operating on symmetric matrices is still TBD.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>sparse_tensor.new %source : !Source to tensor<1024x1024xf64, #CSR> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-17>Operands: <a class=headline-hash href=#operands-17>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>source</code></td><td>any type</td></tr></tbody></table><h4 id=results-18>Results: <a class=headline-hash href=#results-18>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensornumber_of_entries-sparse_tensornumberofentriesop><code>sparse_tensor.number_of_entries</code> (sparse_tensor::NumberOfEntriesOp) <a class=headline-hash href=#sparse_tensornumber_of_entries-sparse_tensornumberofentriesop>¶</a></h3>Returns the number of entries that are stored in the tensor.Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.number_of_entries` $tensor attr-dict `:` type($tensor) </code></pre>Returns the number of entries that are stored in the given sparse tensor. Note that this is typically the number of nonzero elements in the tensor, but since explicit zeros may appear in the storage formats, the more accurate nomenclature is used.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%noe = sparse_tensor.number_of_entries %tensor : tensor<64x64xf64, #CSR> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-18>Operands: <a class=headline-hash href=#operands-18>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-19>Results: <a class=headline-hash href=#results-19>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensorout-sparse_tensoroutop><code>sparse_tensor.out</code> (sparse_tensor::OutOp) <a class=headline-hash href=#sparse_tensorout-sparse_tensoroutop>¶</a></h3>Outputs a sparse tensor to the given destinationSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.out` $tensor `,` $dest attr-dict `:` type($tensor) `,` type($dest) </code></pre>Outputs the contents of a sparse tensor to the destination defined by an opaque pointer provided by <code>dest</code>. For targets that have access to a file system, for example, this pointer may specify a filename (or file) for output. The form of the operation is kept deliberately very general to allow for alternative implementations in the future, such as sending the contents to a buffer defined by a pointer.Note that this operation is “impure” in the sense that its behavior is solely defined by side-effects and not SSA values.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>sparse_tensor.out %t, %dest : tensor<1024x1024xf64, #CSR>, !Dest </code></pre></div><h4 id=operands-19>Operands: <a class=headline-hash href=#operands-19>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr><tr><td style=text-align:center><code>dest</code></td><td>any type</td></tr></tbody></table><h3 id=sparse_tensorpositions-sparse_tensortopositionsop><code>sparse_tensor.positions</code> (sparse_tensor::ToPositionsOp) <a class=headline-hash href=#sparse_tensorpositions-sparse_tensortopositionsop>¶</a></h3>Extracts the <code>level</code>-th positions array of the <code>tensor</code>Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.positions` $tensor attr-dict `:` type($tensor) `to` type($result) </code></pre>Returns the positions array of the tensor’s storage at the given level. This is similar to the <code>bufferization.to_memref</code> operation in the sense that it provides a bridge between a tensor world view and a bufferized world view. Unlike the <code>bufferization.to_memref</code> operation, however, this sparse operation actually lowers into code that extracts the positions array from the sparse storage itself (either by calling a support library or through direct code).Writing into the result of this operation is undefined behavior.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%1 = sparse_tensor.positions %0 { level = 1 : index } : tensor<64x64xf64, #CSR> to memref<?xindex> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-9>Attributes: <a class=headline-hash href=#attributes-9>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>level</code></td><td>::mlir::IntegerAttr</td><td>level attribute</td></tr></table><h4 id=operands-20>Operands: <a class=headline-hash href=#operands-20>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-20>Results: <a class=headline-hash href=#results-20>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>non-0-ranked.memref of any type values</td></tr></tbody></table><h3 id=sparse_tensorprint-sparse_tensorprintop><code>sparse_tensor.print</code> (sparse_tensor::PrintOp) <a class=headline-hash href=#sparse_tensorprint-sparse_tensorprintop>¶</a></h3>Prints a sparse tensor (for testing and debugging)Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.print` $tensor attr-dict `:` type($tensor) </code></pre>Prints the individual components of a sparse tensors (the positions, coordinates, and values components) to stdout for testing and debugging purposes. This operation lowers to just a few primitives in a light-weight runtime support to simplify supporting this operation on new platforms.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>sparse_tensor.print %tensor : tensor<1024x1024xf64, #CSR> </code></pre></div><h4 id=operands-21>Operands: <a class=headline-hash href=#operands-21>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorpush_back-sparse_tensorpushbackop><code>sparse_tensor.push_back</code> (sparse_tensor::PushBackOp) <a class=headline-hash href=#sparse_tensorpush_back-sparse_tensorpushbackop>¶</a></h3>Pushes a value to the back of a given bufferSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.push_back` (`inbounds` $inbounds^)? $curSize `,` $inBuffer `,` $value (`,` $n^ )? attr-dict `:` type($curSize) `,` type($inBuffer) `,` type($value) (`,` type($n)^ )? </code></pre>Pushes <code>value</code> to the end of the given sparse tensor storage buffer <code>inBuffer</code> as indicated by the value of <code>curSize</code> and returns the new size of the buffer in <code>newSize</code> (<code>newSize = curSize + n</code>). The capacity of the buffer is recorded in the memref type of <code>inBuffer</code>. If the current buffer is full, then <code>inBuffer.realloc</code> is called before pushing the data to the buffer. This is similar to std::vector push_back.The optional input <code>n</code> specifies the number of times to repeately push the value to the back of the tensor. When <code>n</code> is a compile-time constant, its value can’t be less than 1. If <code>n</code> is a runtime value that is less than 1, the behavior is undefined. Although using input <code>n</code> is semantically equivalent to calling push_back n times, it gives compiler more chances to to optimize the memory reallocation and the filling of the memory with the same value.The <code>inbounds</code> attribute tells the compiler that the insertion won’t go beyond the current storage buffer. This allows the compiler to not generate the code for capacity check and reallocation. The typical usage will be for “dynamic” sparse tensors for which a capacity can be set beforehand.Note that this operation is “impure” in the sense that even though the result is modeled through an SSA value, referencing the memref through the old SSA value after this operation is undefined behavior.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%buf, %newSize = sparse_tensor.push_back %curSize, %buffer, %val : index, memref<?xf64>, f64 </code></pre></div><div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%buf, %newSize = sparse_tensor.push_back inbounds %curSize, %buffer, %val : xindex, memref<?xf64>, f64 </code></pre></div><div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%buf, %newSize = sparse_tensor.push_back inbounds %curSize, %buffer, %val, %n : xindex, memref<?xf64>, f64 </code></pre></div>Interfaces: <code>InferTypeOpInterface</code><h4 id=attributes-10>Attributes: <a class=headline-hash href=#attributes-10>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>inbounds</code></td><td>::mlir::UnitAttr</td><td>unit attribute</td></tr></table><h4 id=operands-22>Operands: <a class=headline-hash href=#operands-22>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>curSize</code></td><td>index</td></tr><tr><td style=text-align:center><code>inBuffer</code></td><td>1D memref of any type values</td></tr><tr><td style=text-align:center><code>value</code></td><td>any type</td></tr><tr><td style=text-align:center><code>n</code></td><td>index</td></tr></tbody></table><h4 id=results-21>Results: <a class=headline-hash href=#results-21>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>outBuffer</code></td><td>1D memref of any type values</td></tr><tr><td style=text-align:center><code>newSize</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensorreduce-sparse_tensorreduceop><code>sparse_tensor.reduce</code> (sparse_tensor::ReduceOp) <a class=headline-hash href=#sparse_tensorreduce-sparse_tensorreduceop>¶</a></h3>Custom reduction operation utilized within linalg.genericSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.reduce` $x `,` $y `,` $identity attr-dict `:` type($output) $region </code></pre>Defines a computation with a <code>linalg.generic</code> operation that takes two operands and an identity value and reduces all stored values down to a single result based on the computation in the region.The region must contain exactly one block taking two arguments. The block must end with a sparse_tensor.yield and the output must match the input argument types.Note that this operation is only required for custom reductions beyond the standard reduction operations (add, sub, or, xor) that can be sparsified by merely reducing the stored values. More elaborate reduction operations (mul, and, min, max, etc.) would need to account for implicit zeros as well. They can still be handled using this custom reduction operation. The <code>linalg.generic</code> <code>iterator_types</code> defines which indices are being reduced. When the associated operands are used in an operation, a reduction will occur. The use of this explicit <code>reduce</code> operation is not required in most cases.Example of Matrix->Vector reduction using max(product(x_i), 100):<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%cf1 = arith.constant 1.0 : f64 %cf100 = arith.constant 100.0 : f64 %C = tensor.empty(...) %0 = linalg.generic #trait ins(%A: tensor<?x?xf64, #SparseMatrix>) outs(%C: tensor<?xf64, #SparseVector>) { ^bb0(%a: f64, %c: f64) : %result = sparse_tensor.reduce %c, %a, %cf1 : f64 { ^bb0(%arg0: f64, %arg1: f64): %0 = arith.mulf %arg0, %arg1 : f64 %cmp = arith.cmpf "ogt", %0, %cf100 : f64 %ret = arith.select %cmp, %cf100, %0 : f64 sparse_tensor.yield %ret : f64 } linalg.yield %result : f64 } -> tensor<?xf64, #SparseVector> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>, <code>SameOperandsAndResultType</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-23>Operands: <a class=headline-hash href=#operands-23>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>x</code></td><td>any type</td></tr><tr><td style=text-align:center><code>y</code></td><td>any type</td></tr><tr><td style=text-align:center><code>identity</code></td><td>any type</td></tr></tbody></table><h4 id=results-22>Results: <a class=headline-hash href=#results-22>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>output</code></td><td>any type</td></tr></tbody></table><h3 id=sparse_tensorreinterpret_map-sparse_tensorreinterpretmapop><code>sparse_tensor.reinterpret_map</code> (sparse_tensor::ReinterpretMapOp) <a class=headline-hash href=#sparse_tensorreinterpret_map-sparse_tensorreinterpretmapop>¶</a></h3>Reinterprets the dimension/level maps of the source tensorSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.reinterpret_map` $source attr-dict `:` type($source) `to` type($dest) </code></pre>Reinterprets the dimension-to-level and level-to-dimension map specified in <code>source</code> according to the type of <code>dest</code>. <code>reinterpret_map</code> is a no-op and is introduced merely to resolve type conflicts. It does not make any modification to the source tensor and source/dest tensors are considered to be aliases.<code>source</code> and <code>dest</code> tensors are “reinterpretable” if and only if they have the exactly same storage at a low level. That is, both <code>source</code> and <code>dest</code> has the same number of levels and level types, and their shape is consistent before and after <code>reinterpret_map</code>.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>#CSC = #sparse_tensor.encoding<{ map = (d0, d1) -> (d1: dense, d0: compressed) }> #CSR = #sparse_tensor.encoding<{ map = (d0, d1) -> (d0: dense, d1: compressed) }> %t1 = sparse_tensor.reinterpret_map %t0 : tensor<3x4xi32, #CSC> to tensor<4x3xi32, #CSR> #BSR = #sparse_tensor.encoding<{ map = ( i, j ) -> ( i floordiv 2 : dense, j floordiv 3 : compressed, i mod 2 : dense, j mod 3 : dense ) }> #DSDD = #sparse_tensor.encoding<{ map = (i, j, k, l) -> (i: dense, j: compressed, k: dense, l: dense) }> %t1 = sparse_tensor.reinterpret_map %t0 : tensor<6x12xi32, #BSR> to tensor<3x4x2x3xi32, #DSDD> </code></pre></div>Interfaces: <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-24>Operands: <a class=headline-hash href=#operands-24>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>source</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-23>Results: <a class=headline-hash href=#results-23>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>dest</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorreorder_coo-sparse_tensorreordercooop><code>sparse_tensor.reorder_coo</code> (sparse_tensor::ReorderCOOOp) <a class=headline-hash href=#sparse_tensorreorder_coo-sparse_tensorreordercooop>¶</a></h3>Reorder the input COO such that it has the the same order as the output COOSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.reorder_coo` $algorithm $input_coo attr-dict`:` type($input_coo) `to` type($result_coo) </code></pre>Reorders the input COO to the same order as specified by the output format. E.g., reorder an unordered COO into an ordered one.The input and result COO tensor must have the same element type, position type and coordinate type. At the moment, the operation also only supports ordering input and result COO with the same dim2lvl map.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%res = sparse_tensor.reorder_coo quick_sort %coo : tensor<?x?xf64 : #Unordered_COO> to tensor<?x?xf64 : #Ordered_COO> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-11>Attributes: <a class=headline-hash href=#attributes-11>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>algorithm</code></td><td>::mlir::sparse_tensor::SparseTensorSortKindAttr</td><td><details><summary>sparse tensor sort algorithm</summary>Enum cases:<ul><li>hybrid_quick_sort (<code>HybridQuickSort</code>)</li><li>insertion_sort_stable (<code>InsertionSortStable</code>)</li><li>quick_sort (<code>QuickSort</code>)</li><li>heap_sort (<code>HeapSort</code>)</li></ul></details></td></tr></table><h4 id=operands-25>Operands: <a class=headline-hash href=#operands-25>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>input_coo</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-24>Results: <a class=headline-hash href=#results-24>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result_coo</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h3 id=sparse_tensorselect-sparse_tensorselectop><code>sparse_tensor.select</code> (sparse_tensor::SelectOp) <a class=headline-hash href=#sparse_tensorselect-sparse_tensorselectop>¶</a></h3>Select operation utilized within linalg.genericSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.select` $x attr-dict `:` type($x) $region </code></pre>Defines an evaluation within a <code>linalg.generic</code> operation that takes a single operand and decides whether or not to keep that operand in the output.A single region must contain exactly one block taking one argument. The block must end with a sparse_tensor.yield and the output type must be boolean.Value threshold is an obvious usage of the select operation. However, by using <code>linalg.index</code>, other useful selection can be achieved, such as selecting the upper triangle of a matrix.Example of selecting A >= 4.0:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%C = tensor.empty(...) %0 = linalg.generic #trait ins(%A: tensor<?xf64, #SparseVector>) outs(%C: tensor<?xf64, #SparseVector>) { ^bb0(%a: f64, %c: f64) : %result = sparse_tensor.select %a : f64 { ^bb0(%arg0: f64): %cf4 = arith.constant 4.0 : f64 %keep = arith.cmpf "uge", %arg0, %cf4 : f64 sparse_tensor.yield %keep : i1 } linalg.yield %result : f64 } -> tensor<?xf64, #SparseVector> </code></pre></div>Example of selecting lower triangle of a matrix:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%C = tensor.empty(...) %1 = linalg.generic #trait ins(%A: tensor<?x?xf64, #CSR>) outs(%C: tensor<?x?xf64, #CSR>) { ^bb0(%a: f64, %c: f64) : %row = linalg.index 0 : index %col = linalg.index 1 : index %result = sparse_tensor.select %a : f64 { ^bb0(%arg0: f64): %keep = arith.cmpf "olt", %col, %row : f64 sparse_tensor.yield %keep : i1 } linalg.yield %result : f64 } -> tensor<?x?xf64, #CSR> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>, <code>SameOperandsAndResultType</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-26>Operands: <a class=headline-hash href=#operands-26>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>x</code></td><td>any type</td></tr></tbody></table><h4 id=results-25>Results: <a class=headline-hash href=#results-25>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>output</code></td><td>any type</td></tr></tbody></table><h3 id=sparse_tensorsliceoffset-sparse_tensortosliceoffsetop><code>sparse_tensor.slice.offset</code> (sparse_tensor::ToSliceOffsetOp) <a class=headline-hash href=#sparse_tensorsliceoffset-sparse_tensortosliceoffsetop>¶</a></h3>Extracts the offset of the sparse tensor slice at the given dimensionSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.slice.offset` $slice `at` $dim attr-dict `:` type($slice) </code></pre>Extracts the offset of the sparse tensor slice at the given dimension.Currently, sparse tensor slices are still a work in progress, and only works when runtime library is disabled (i.e., running the sparsifier with <code>enable-runtime-library=false</code>).Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = tensor.extract_slice %s[%v1, %v2][64, 64][1, 1] : tensor<128x128xf64, #DCSR> to tensor<64x64xf64, #Slice> %1 = sparse_tensor.slice.offset %0 at 0 : tensor<64x64xf64, #Slice> %2 = sparse_tensor.slice.offset %0 at 1 : tensor<64x64xf64, #Slice> // %1 = %v1 // %2 = %v2 </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-12>Attributes: <a class=headline-hash href=#attributes-12>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>dim</code></td><td>::mlir::IntegerAttr</td><td>index attribute</td></tr></table><h4 id=operands-27>Operands: <a class=headline-hash href=#operands-27>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>slice</code></td><td>sparse tensor slice of any type values</td></tr></tbody></table><h4 id=results-26>Results: <a class=headline-hash href=#results-26>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>offset</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensorslicestride-sparse_tensortoslicestrideop><code>sparse_tensor.slice.stride</code> (sparse_tensor::ToSliceStrideOp) <a class=headline-hash href=#sparse_tensorslicestride-sparse_tensortoslicestrideop>¶</a></h3>Extracts the stride of the sparse tensor slice at the given dimensionSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.slice.stride` $slice `at` $dim attr-dict `:` type($slice) </code></pre>Extracts the stride of the sparse tensor slice at the given dimension.Currently, sparse tensor slices are still a work in progress, and only works when runtime library is disabled (i.e., running the sparsifier with <code>enable-runtime-library=false</code>).Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = tensor.extract_slice %s[%v1, %v2][64, 64][%s1, %s2] : tensor<128x128xf64, #DCSR> to tensor<64x64xf64, #Slice> %1 = sparse_tensor.slice.stride %0 at 0 : tensor<64x64xf64, #Slice> %2 = sparse_tensor.slice.stride %0 at 1 : tensor<64x64xf64, #Slice> // %1 = %s1 // %2 = %s2 </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-13>Attributes: <a class=headline-hash href=#attributes-13>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>dim</code></td><td>::mlir::IntegerAttr</td><td>index attribute</td></tr></table><h4 id=operands-28>Operands: <a class=headline-hash href=#operands-28>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>slice</code></td><td>sparse tensor slice of any type values</td></tr></tbody></table><h4 id=results-27>Results: <a class=headline-hash href=#results-27>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>stride</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensorsort-sparse_tensorsortop><code>sparse_tensor.sort</code> (sparse_tensor::SortOp) <a class=headline-hash href=#sparse_tensorsort-sparse_tensorsortop>¶</a></h3>Sorts the arrays in xs and ys lexicographically on the integral values found in the xs listSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.sort` $algorithm $n`,`$xy (`jointly` $ys^)? attr-dict`:` type($xy) (`jointly` type($ys)^)? </code></pre>Sorts the <code>xs</code> values along with some <code>ys</code> values that are put in a single linear buffer <code>xy</code>. The affine map attribute <code>perm_map</code> specifies the permutation to be applied on the <code>xs</code> before comparison, the rank of the permutation map also specifies the number of <code>xs</code> values in <code>xy</code>. The optional index attribute <code>ny</code> provides the number of <code>ys</code> values in <code>xy</code>. When <code>ny</code> is not explicitly specified, its value is 0. This instruction supports a more efficient way to store the COO definition in sparse tensor type.The buffer xy should have a dimension not less than n * (rank(perm_map) + ny) while the buffers in <code>ys</code> should have a dimension not less than <code>n</code>. The behavior of the operator is undefined if this condition is not met.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>sparse_tensor.sort insertion_sort_stable %n, %x { perm_map = affine_map<(i,j) -> (j,i)> } : memref<?xindex> </code></pre></div><h4 id=attributes-14>Attributes: <a class=headline-hash href=#attributes-14>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>perm_map</code></td><td>::mlir::AffineMapAttr</td><td>AffineMap attribute</td></tr><tr><td><code>ny</code></td><td>::mlir::IntegerAttr</td><td>index attribute</td></tr><tr><td><code>algorithm</code></td><td>::mlir::sparse_tensor::SparseTensorSortKindAttr</td><td><details><summary>sparse tensor sort algorithm</summary>Enum cases:<ul><li>hybrid_quick_sort (<code>HybridQuickSort</code>)</li><li>insertion_sort_stable (<code>InsertionSortStable</code>)</li><li>quick_sort (<code>QuickSort</code>)</li><li>heap_sort (<code>HeapSort</code>)</li></ul></details></td></tr></table><h4 id=operands-29>Operands: <a class=headline-hash href=#operands-29>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>n</code></td><td>index</td></tr><tr><td style=text-align:center><code>xy</code></td><td>1D memref of integer or index values</td></tr><tr><td style=text-align:center><code>ys</code></td><td>variadic of 1D memref of any type values</td></tr></tbody></table><h3 id=sparse_tensorstorage_specifierget-sparse_tensorgetstoragespecifierop><code>sparse_tensor.storage_specifier.get</code> (sparse_tensor::GetStorageSpecifierOp) <a class=headline-hash href=#sparse_tensorstorage_specifierget-sparse_tensorgetstoragespecifierop>¶</a></h3>Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.storage_specifier.get` $specifier $specifierKind (`at` $level^)? attr-dict`:` qualified(type($specifier)) </code></pre>Returns the requested field of the given storage_specifier.Example of querying the size of the coordinates array for level 0:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = sparse_tensor.storage_specifier.get %arg0 crd_mem_sz at 0 : !sparse_tensor.storage_specifier<#COO> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-15>Attributes: <a class=headline-hash href=#attributes-15>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>specifierKind</code></td><td>::mlir::sparse_tensor::StorageSpecifierKindAttr</td><td><details><summary>sparse tensor storage specifier kind</summary>Enum cases:<ul><li>lvl_sz (<code>LvlSize</code>)</li><li>pos_mem_sz (<code>PosMemSize</code>)</li><li>crd_mem_sz (<code>CrdMemSize</code>)</li><li>val_mem_sz (<code>ValMemSize</code>)</li><li>dim_offset (<code>DimOffset</code>)</li><li>dim_stride (<code>DimStride</code>)</li></ul></details></td></tr><tr><td><code>level</code></td><td>::mlir::IntegerAttr</td><td>level attribute</td></tr></table><h4 id=operands-30>Operands: <a class=headline-hash href=#operands-30>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>specifier</code></td><td>metadata</td></tr></tbody></table><h4 id=results-28>Results: <a class=headline-hash href=#results-28>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>index</td></tr></tbody></table><h3 id=sparse_tensorstorage_specifierinit-sparse_tensorstoragespecifierinitop><code>sparse_tensor.storage_specifier.init</code> (sparse_tensor::StorageSpecifierInitOp) <a class=headline-hash href=#sparse_tensorstorage_specifierinit-sparse_tensorstoragespecifierinitop>¶</a></h3>Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.storage_specifier.init` attr-dict (`with` $source^)? `:` (`from` qualified(type($source))^ `to`)? qualified(type($result)) </code></pre>Returns an initial storage specifier value. A storage specifier value holds the level-sizes, position arrays, coordinate arrays, and the value array. If this is a specifier for slices, it also holds the extra strides/offsets for each tensor dimension.TODO: The sparse tensor slice support is currently in a unstable state, and is subject to change in the future.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>#CSR = #sparse_tensor.encoding<{ map = (i, j) -> (i : dense, j : compressed) }> #CSR_SLICE = #sparse_tensor.encoding<{ map = (d0 : #sparse_tensor<slice(1, 4, 1)>, d1 : #sparse_tensor<slice(1, 4, 2)>) -> (d0 : dense, d1 : compressed) }> %0 = sparse_tensor.storage_specifier.init : !sparse_tensor.storage_specifier<#CSR> %1 = sparse_tensor.storage_specifier.init with %src : !sparse_tensor.storage_specifier<#CSR> to !sparse_tensor.storage_specifier<#CSR_SLICE> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-31>Operands: <a class=headline-hash href=#operands-31>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>source</code></td><td>metadata</td></tr></tbody></table><h4 id=results-29>Results: <a class=headline-hash href=#results-29>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>metadata</td></tr></tbody></table><h3 id=sparse_tensorstorage_specifierset-sparse_tensorsetstoragespecifierop><code>sparse_tensor.storage_specifier.set</code> (sparse_tensor::SetStorageSpecifierOp) <a class=headline-hash href=#sparse_tensorstorage_specifierset-sparse_tensorsetstoragespecifierop>¶</a></h3>Syntax:<pre tabindex=0><code>operation ::= `sparse_tensor.storage_specifier.set` $specifier $specifierKind (`at` $level^)? `with` $value attr-dict `:` qualified(type($result)) </code></pre>Set the field of the storage specifier to the given input value. Returns the updated storage_specifier as a new SSA value.Example of updating the sizes of the coordinates array for level 0:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = sparse_tensor.storage_specifier.set %arg0 crd_mem_sz at 0 with %new_sz : !sparse_tensor.storage_specifier<#COO> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=attributes-16>Attributes: <a class=headline-hash href=#attributes-16>¶</a></h4><table><tr><th>Attribute</th><th>MLIR Type</th><th>Description</th></tr><tr><td><code>specifierKind</code></td><td>::mlir::sparse_tensor::StorageSpecifierKindAttr</td><td><details><summary>sparse tensor storage specifier kind</summary>Enum cases:<ul><li>lvl_sz (<code>LvlSize</code>)</li><li>pos_mem_sz (<code>PosMemSize</code>)</li><li>crd_mem_sz (<code>CrdMemSize</code>)</li><li>val_mem_sz (<code>ValMemSize</code>)</li><li>dim_offset (<code>DimOffset</code>)</li><li>dim_stride (<code>DimStride</code>)</li></ul></details></td></tr><tr><td><code>level</code></td><td>::mlir::IntegerAttr</td><td>level attribute</td></tr></table><h4 id=operands-32>Operands: <a class=headline-hash href=#operands-32>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>specifier</code></td><td>metadata</td></tr><tr><td style=text-align:center><code>value</code></td><td>index</td></tr></tbody></table><h4 id=results-30>Results: <a class=headline-hash href=#results-30>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>metadata</td></tr></tbody></table><h3 id=sparse_tensorunary-sparse_tensorunaryop><code>sparse_tensor.unary</code> (sparse_tensor::UnaryOp) <a class=headline-hash href=#sparse_tensorunary-sparse_tensorunaryop>¶</a></h3>Unary set operation utilized within linalg.genericSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.unary` $x attr-dict `:` type($x) `to` type($output) `\n` `present` `=` $presentRegion `\n` `absent` `=` $absentRegion </code></pre>Defines a computation with a <code>linalg.generic</code> operation that takes a single operand and executes one of two regions depending on whether the operand is nonzero (i.e. stored explicitly in the sparse storage format).Two regions are defined for the operation must appear in this order:<ul><li>present (elements present in the sparse tensor)</li><li>absent (elements not present in the sparse tensor)</li></ul>Each region contains a single block describing the computation and result. A non-empty block must end with a sparse_tensor.yield and the return type must match the type of <code>output</code>. The primary region’s block has one argument, while the missing region’s block has zero arguments. The absent region may only generate constants or values already computed on entry of the <code>linalg.generic</code> operation.A region may also be declared empty (i.e. <code>absent={}</code>), indicating that the region does not contribute to the output.Due to the possibility of empty regions, i.e. lack of a value for certain cases, the result of this operation may only feed directly into the output of the <code>linalg.generic</code> operation or into into a custom reduction <code>sparse_tensor.reduce</code> operation that follows in the same region.Example of A+1, restricted to existing elements:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%C = tensor.empty(...) : tensor<?xf64, #SparseVector> %0 = linalg.generic #trait ins(%A: tensor<?xf64, #SparseVector>) outs(%C: tensor<?xf64, #SparseVector>) { ^bb0(%a: f64, %c: f64) : %result = sparse_tensor.unary %a : f64 to f64 present={ ^bb0(%arg0: f64): %cf1 = arith.constant 1.0 : f64 %ret = arith.addf %arg0, %cf1 : f64 sparse_tensor.yield %ret : f64 } absent={} linalg.yield %result : f64 } -> tensor<?xf64, #SparseVector> </code></pre></div>Example returning +1 for existing values and -1 for missing values:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%p1 = arith.constant 1 : i32 %m1 = arith.constant -1 : i32 %C = tensor.empty(...) : tensor<?xi32, #SparseVector> %1 = linalg.generic #trait ins(%A: tensor<?xf64, #SparseVector>) outs(%C: tensor<?xi32, #SparseVector>) { ^bb0(%a: f64, %c: i32) : %result = sparse_tensor.unary %a : f64 to i32 present={ ^bb0(%x: f64): sparse_tensor.yield %p1 : i32 } absent={ sparse_tensor.yield %m1 : i32 } linalg.yield %result : i32 } -> tensor<?xi32, #SparseVector> </code></pre></div>Example showing a structural inversion (existing values become missing in the output, while missing values are filled with 1):<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%c1 = arith.constant 1 : i64 %C = tensor.empty(...) : tensor<?xi64, #SparseVector> %2 = linalg.generic #trait ins(%A: tensor<?xf64, #SparseVector>) outs(%C: tensor<?xi64, #SparseVector>) { ^bb0(%a: f64, %c: i64) : %result = sparse_tensor.unary %a : f64 to i64 present={} absent={ sparse_tensor.yield %c1 : i64 } linalg.yield %result : i64 } -> tensor<?xi64, #SparseVector> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-33>Operands: <a class=headline-hash href=#operands-33>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>x</code></td><td>any type</td></tr></tbody></table><h4 id=results-31>Results: <a class=headline-hash href=#results-31>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>output</code></td><td>any type</td></tr></tbody></table><h3 id=sparse_tensorvalues-sparse_tensortovaluesop><code>sparse_tensor.values</code> (sparse_tensor::ToValuesOp) <a class=headline-hash href=#sparse_tensorvalues-sparse_tensortovaluesop>¶</a></h3>Extracts numerical values array from a tensorSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.values` $tensor attr-dict `:` type($tensor) `to` type($result) </code></pre>Returns the values array of the sparse storage format for the given sparse tensor, independent of the actual dimension. This is similar to the <code>bufferization.to_memref</code> operation in the sense that it provides a bridge between a tensor world view and a bufferized world view. Unlike the <code>bufferization.to_memref</code> operation, however, this sparse operation actually lowers into code that extracts the values array from the sparse storage scheme (either by calling a support library or through direct code).Writing into the result of this operation is undefined behavior.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%1 = sparse_tensor.values %0 : tensor<64x64xf64, #CSR> to memref<?xf64> </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>InferTypeOpInterface</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-34>Operands: <a class=headline-hash href=#operands-34>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>tensor</code></td><td>sparse tensor of any type values</td></tr></tbody></table><h4 id=results-32>Results: <a class=headline-hash href=#results-32>¶</a></h4><table><thead><tr><th style=text-align:center>Result</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>result</code></td><td>non-0-ranked.memref of any type values</td></tr></tbody></table><h3 id=sparse_tensoryield-sparse_tensoryieldop><code>sparse_tensor.yield</code> (sparse_tensor::YieldOp) <a class=headline-hash href=#sparse_tensoryield-sparse_tensoryieldop>¶</a></h3>Yield from sparse_tensor set-like operationsSyntax:<pre tabindex=0><code>operation ::= `sparse_tensor.yield` $results attr-dict `:` type($results) </code></pre>Yields a value from within a <code>binary</code>, <code>unary</code>, <code>reduce</code>, <code>select</code> or <code>foreach</code> block.Example:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>%0 = sparse_tensor.unary %a : i64 to i64 { present={ ^bb0(%arg0: i64): %cst = arith.constant 1 : i64 %ret = arith.addi %arg0, %cst : i64 sparse_tensor.yield %ret : i64 } } </code></pre></div>Traits: <code>AlwaysSpeculatableImplTrait</code>, <code>HasParent<BinaryOp, UnaryOp, ReduceOp, SelectOp, ForeachOp, IterateOp, CoIterateOp></code>, <code>Terminator</code>Interfaces: <code>ConditionallySpeculatable</code>, <code>NoMemoryEffect (MemoryEffectOpInterface)</code>Effects: <code>MemoryEffects::Effect{}</code><h4 id=operands-35>Operands: <a class=headline-hash href=#operands-35>¶</a></h4><table><thead><tr><th style=text-align:center>Operand</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center><code>results</code></td><td>variadic of any type</td></tr></tbody></table><h2 id=attributes-17>Attributes <a class=headline-hash href=#attributes-17>¶</a></h2><h3 id=crdtransdirectionkindattr>CrdTransDirectionKindAttr <a class=headline-hash href=#crdtransdirectionkindattr>¶</a></h3>sparse tensor coordinate translation directionSyntax:<pre tabindex=0><code>#sparse_tensor.CrdTransDirection< ::mlir::sparse_tensor::CrdTransDirectionKind # value > </code></pre>Enum cases:<ul><li>dim_to_lvl (<code>dim2lvl</code>)</li><li>lvl_to_dim (<code>lvl2dim</code>)</li></ul><h4 id=parameters>Parameters: <a class=headline-hash href=#parameters>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>value</td><td style=text-align:center><code>::mlir::sparse_tensor::CrdTransDirectionKind</code></td><td>an enum of type CrdTransDirectionKind</td></tr></tbody></table><h3 id=sparsetensordimsliceattr>SparseTensorDimSliceAttr <a class=headline-hash href=#sparsetensordimsliceattr>¶</a></h3>An attribute to encode slice information of a sparse tensor on a particular dimension (a tuple of offset, size, stride).<h4 id=parameters-1>Parameters: <a class=headline-hash href=#parameters-1>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>offset</td><td style=text-align:center><code>int64_t</code></td><td></td></tr><tr><td style=text-align:center>size</td><td style=text-align:center><code>int64_t</code></td><td></td></tr><tr><td style=text-align:center>stride</td><td style=text-align:center><code>int64_t</code></td><td></td></tr></tbody></table><h3 id=sparsetensorencodingattr>SparseTensorEncodingAttr <a class=headline-hash href=#sparsetensorencodingattr>¶</a></h3>An attribute to encode information on sparsity properties of tensors, inspired by the TACO formalization of sparse tensors. This encoding is eventually used by a sparsifier pass to generate sparse code fully automatically from a sparsity-agnostic representation of the computation, i.e., an implicit sparse representation is converted to an explicit sparse representation where co-iterating loops operate on sparse storage formats rather than tensors with a sparsity encoding. Compiler passes that run before this sparsifier pass need to be aware of the semantics of tensor types with such a sparsity encoding.In this encoding, we use dimension to refer to the axes of the semantic tensor, and level to refer to the axes of the actual storage format, i.e., the operational representation of the sparse tensor in memory. The number of dimensions is usually the same as the number of levels (such as CSR storage format). However, the encoding can also map dimensions to higher-order levels (for example, to encode a block-sparse BSR storage format) or to lower-order levels (for example, to linearize dimensions as a single level in the storage).The encoding contains a map that provides the following:<ul><li>An ordered sequence of dimension specifications, each of which defines:<ul><li>the dimension-size (implicit from the tensor’s dimension-shape)</li><li>a dimension-expression</li></ul></li><li>An ordered sequence of level specifications, each of which includes a required level-type, which defines how the level should be stored. Each level-type consists of:<ul><li>a level-expression, which defines what is stored</li><li>a level-format</li><li>a collection of level-properties that apply to the level-format</li></ul></li></ul>Each level-expression is an affine expression over dimension-variables. Thus, the level-expressions collectively define an affine map from dimension-coordinates to level-coordinates. The dimension-expressions collectively define the inverse map, which only needs to be provided for elaborate cases where it cannot be inferred automatically.Each dimension could also have an optional <code>SparseTensorDimSliceAttr</code>. Within the sparse storage format, we refer to indices that are stored explicitly as coordinates and offsets into the storage format as positions.The supported level-formats are the following:<ul><li>dense : all entries along this level are stored and linearized.</li><li>batch : all entries along this level are stored but not linearized.</li><li>compressed : only nonzeros along this level are stored</li><li>loose_compressed : as compressed, but allows for free space between regions</li><li>singleton : a variant of the compressed format, where coordinates have no siblings</li><li>structured[n, m] : the compression uses a n:m encoding (viz. n out of m consecutive elements are nonzero)</li></ul>For a compressed level, each position interval is represented in a compact way with a lowerbound <code>pos(i)</code> and an upperbound <code>pos(i+1) - 1</code>, which implies that successive intervals must appear in order without any “holes” in between them. The loose compressed format relaxes these constraints by representing each position interval with a lowerbound <code>lo(i)</code> and an upperbound <code>hi(i)</code>, which allows intervals to appear in arbitrary order and with elbow room between them.By default, each level-type has the property of being unique (no duplicate coordinates at that level) and ordered (coordinates appear sorted at that level). For singleton levels, the coordinates are fused with its parents in AoS (array of structures) scheme. The following properties can be added to a level-format to change this default behavior:<ul><li>nonunique : duplicate coordinates may appear at the level</li><li>nonordered : coordinates may appear in arbribratry order</li><li>soa : only applicable to singleton levels, fuses the singleton level in SoA (structure of arrays) scheme.</li></ul>In addition to the map, the following fields are optional:<ul><li>The required bitwidth for position 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 levels). The choices are <code>8</code>, <code>16</code>, <code>32</code>, <code>64</code>, or, the default, <code>0</code> to indicate the native bitwidth.</li><li>The required bitwidth for coordinate storage (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 coordinate over all levels). The choices are <code>8</code>, <code>16</code>, <code>32</code>, <code>64</code>, or, the default, <code>0</code> to indicate a native bitwidth.</li><li>The explicit value for the sparse tensor. If explicitVal is set, then all the non-zero values in the tensor have the same explicit value. The default value Attribute() indicates that it is not set. This is useful for binary-valued sparse tensors whose values can either be an implicit value (0 by default) or an explicit value (such as 1). In this approach, we don’t store explicit/implicit values, and metadata (such as position and coordinate arrays) alone fully defines the original tensor. This yields additional savings for the storage requirements, as well as for the computational time, since we skip operating on implicit values and can constant fold the explicit values where they are used.</li><li>The implicit value for the sparse tensor. If implicitVal is set, then the “zero” value in the tensor is equal to the implicit value. For now, we only support <code>0</code> as the implicit value but it could be extended in the future. The default value Attribute() indicates that the implicit value is <code>0</code> (same type as the tensor element type).</li></ul>Examples:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// Sparse vector. #SparseVector = #sparse_tensor.encoding<{ map = (i) -> (i : compressed) }> ... tensor<?xf32, #SparseVector> ... // Sorted coordinate scheme (arranged in AoS format by default). #SortedCOO = #sparse_tensor.encoding<{ map = (i, j) -> (i : compressed(nonunique), j : singleton) }> // coordinates = {x_crd, y_crd}[nnz] ... tensor<?x?xf64, #SortedCOO> ... // Sorted coordinate scheme (arranged in SoA format). #SortedCOO = #sparse_tensor.encoding<{ map = (i, j) -> (i : compressed(nonunique), j : singleton(soa)) }> // coordinates = {x_crd[nnz], y_crd[nnz]} ... tensor<?x?xf64, #SortedCOO> ... // Batched sorted coordinate scheme, with high encoding. #BCOO = #sparse_tensor.encoding<{ map = (i, j, k) -> (i : dense, j : compressed(nonunique, high), k : singleton) }> ... tensor<10x10xf32, #BCOO> ... // Compressed sparse row. #CSR = #sparse_tensor.encoding<{ map = (i, j) -> (i : dense, j : compressed) }> ... tensor<100x100xbf16, #CSR> ... // Doubly compressed sparse column storage with specific bitwidths. #DCSC = #sparse_tensor.encoding<{ map = (i, j) -> (j : compressed, i : compressed), posWidth = 32, crdWidth = 8 }> ... tensor<8x8xf64, #DCSC> ... // Doubly compressed sparse column storage with specific // explicit and implicit values. #DCSC = #sparse_tensor.encoding<{ map = (i, j) -> (j : compressed, i : compressed), explicitVal = 1 : i64, implicitVal = 0 : i64 }> ... tensor<8x8xi64, #DCSC> ... // Block sparse row storage (2x3 blocks). #BSR = #sparse_tensor.encoding<{ map = ( i, j ) -> ( i floordiv 2 : dense, j floordiv 3 : compressed, i mod 2 : dense, j mod 3 : dense ) }> ... tensor<20x30xf32, #BSR> ... // Same block sparse row storage (2x3 blocks) but this time // also with a redundant reverse mapping, which can be inferred. #BSR_explicit = #sparse_tensor.encoding<{ map = { ib, jb, ii, jj } ( i = ib * 2 + ii, j = jb * 3 + jj) -> ( ib = i floordiv 2 : dense, jb = j floordiv 3 : compressed, ii = i mod 2 : dense, jj = j mod 3 : dense) }> ... tensor<20x30xf32, #BSR_explicit> ... // ELL format. // In the simple format for matrix, one array stores values and another // array stores column indices. The arrays have the same number of rows // as the original matrix, but only have as many columns as // the maximum number of nonzeros on a row of the original matrix. // There are many variants for ELL such as jagged diagonal scheme. // To implement ELL, map provides a notion of "counting a // dimension", where every stored element with the same coordinate // is mapped to a new slice. For instance, ELL storage of a 2-d // tensor can be defined with the mapping (i, j) -> (#i, i, j) // using the notation of [Chou20]. Lacking the # symbol in MLIR's // affine mapping, we use a free symbol c to define such counting, // together with a constant that denotes the number of resulting // slices. For example, the mapping [c](i, j) -> (c * 3 * i, i, j) // with the level-types ["dense", "dense", "compressed"] denotes ELL // storage with three jagged diagonals that count the dimension i. #ELL = #sparse_tensor.encoding<{ map = [c](i, j) -> (c * 3 * i : dense, i : dense, j : compressed) }> ... tensor<?x?xf64, #ELL> ... // CSR slice (offset = 0, size = 4, stride = 1 on the first dimension; // offset = 0, size = 8, and a dynamic stride on the second dimension). #CSR_SLICE = #sparse_tensor.encoding<{ map = (i : #sparse_tensor<slice(0, 4, 1)>, j : #sparse_tensor<slice(0, 8, ?)>) -> (i : dense, j : compressed) }> ... tensor<?x?xf64, #CSR_SLICE> ... </code></pre></div><h4 id=parameters-2>Parameters: <a class=headline-hash href=#parameters-2>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>lvlTypes</td><td style=text-align:center><code>::llvm::ArrayRef<::mlir::sparse_tensor::LevelType></code></td><td>level-types</td></tr><tr><td style=text-align:center>dimToLvl</td><td style=text-align:center><code>AffineMap</code></td><td></td></tr><tr><td style=text-align:center>lvlToDim</td><td style=text-align:center><code>AffineMap</code></td><td></td></tr><tr><td style=text-align:center>posWidth</td><td style=text-align:center><code>unsigned</code></td><td></td></tr><tr><td style=text-align:center>crdWidth</td><td style=text-align:center><code>unsigned</code></td><td></td></tr><tr><td style=text-align:center>explicitVal</td><td style=text-align:center><code>::mlir::Attribute</code></td><td></td></tr><tr><td style=text-align:center>implicitVal</td><td style=text-align:center><code>::mlir::Attribute</code></td><td></td></tr><tr><td style=text-align:center>dimSlices</td><td style=text-align:center><code>::llvm::ArrayRef<::mlir::sparse_tensor::SparseTensorDimSliceAttr></code></td><td>per dimension slice metadata</td></tr></tbody></table><h3 id=sparsetensorsortkindattr>SparseTensorSortKindAttr <a class=headline-hash href=#sparsetensorsortkindattr>¶</a></h3>sparse tensor sort algorithmSyntax:<pre tabindex=0><code>#sparse_tensor.SparseTensorSortAlgorithm< ::mlir::sparse_tensor::SparseTensorSortKind # value > </code></pre>Enum cases:<ul><li>hybrid_quick_sort (<code>HybridQuickSort</code>)</li><li>insertion_sort_stable (<code>InsertionSortStable</code>)</li><li>quick_sort (<code>QuickSort</code>)</li><li>heap_sort (<code>HeapSort</code>)</li></ul><h4 id=parameters-3>Parameters: <a class=headline-hash href=#parameters-3>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>value</td><td style=text-align:center><code>::mlir::sparse_tensor::SparseTensorSortKind</code></td><td>an enum of type SparseTensorSortKind</td></tr></tbody></table><h3 id=storagespecifierkindattr>StorageSpecifierKindAttr <a class=headline-hash href=#storagespecifierkindattr>¶</a></h3>sparse tensor storage specifier kindSyntax:<pre tabindex=0><code>#sparse_tensor.kind< ::mlir::sparse_tensor::StorageSpecifierKind # value > </code></pre>Enum cases:<ul><li>lvl_sz (<code>LvlSize</code>)</li><li>pos_mem_sz (<code>PosMemSize</code>)</li><li>crd_mem_sz (<code>CrdMemSize</code>)</li><li>val_mem_sz (<code>ValMemSize</code>)</li><li>dim_offset (<code>DimOffset</code>)</li><li>dim_stride (<code>DimStride</code>)</li></ul><h4 id=parameters-4>Parameters: <a class=headline-hash href=#parameters-4>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>value</td><td style=text-align:center><code>::mlir::sparse_tensor::StorageSpecifierKind</code></td><td>an enum of type StorageSpecifierKind</td></tr></tbody></table><h2 id=types>Types <a class=headline-hash href=#types>¶</a></h2><h3 id=iterspacetype>IterSpaceType <a class=headline-hash href=#iterspacetype>¶</a></h3>Syntax:<pre tabindex=0><code>!sparse_tensor.iter_space< ::mlir::sparse_tensor::SparseTensorEncodingAttr, # encoding Level, # loLvl Level # hiLvl > </code></pre>A sparse iteration space that represents an abstract N-D (sparse) iteration space extracted from a sparse tensor, i.e., a set of (crd_0, crd_1, &mldr;, crd_N) for every stored element (usually nonzeros) in a sparse tensor between the specified [$loLvl, $hiLvl) levels.Examples:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// An iteration space extracted from a CSR tensor between levels [0, 2). !iter_space<#CSR, lvls = 0 to 2> </code></pre></div><h4 id=parameters-5>Parameters: <a class=headline-hash href=#parameters-5>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>encoding</td><td style=text-align:center><code>::mlir::sparse_tensor::SparseTensorEncodingAttr</code></td><td></td></tr><tr><td style=text-align:center>loLvl</td><td style=text-align:center><code>Level</code></td><td></td></tr><tr><td style=text-align:center>hiLvl</td><td style=text-align:center><code>Level</code></td><td></td></tr></tbody></table><h3 id=iteratortype>IteratorType <a class=headline-hash href=#iteratortype>¶</a></h3>Syntax:<pre tabindex=0><code>!sparse_tensor.iterator< ::mlir::sparse_tensor::SparseTensorEncodingAttr, # encoding Level, # loLvl Level # hiLvl > </code></pre>An iterator that points to the current element in the corresponding iteration space.Examples:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// An iterator that iterates over a iteration space of type `!iter_space<#CSR, lvls = 0 to 2>` !iterator<#CSR, lvls = 0 to 2> </code></pre></div><h4 id=parameters-6>Parameters: <a class=headline-hash href=#parameters-6>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>encoding</td><td style=text-align:center><code>::mlir::sparse_tensor::SparseTensorEncodingAttr</code></td><td></td></tr><tr><td style=text-align:center>loLvl</td><td style=text-align:center><code>Level</code></td><td></td></tr><tr><td style=text-align:center>hiLvl</td><td style=text-align:center><code>Level</code></td><td></td></tr></tbody></table><h3 id=storagespecifiertype>StorageSpecifierType <a class=headline-hash href=#storagespecifiertype>¶</a></h3>Structured metadata for sparse tensor low-level storage schemeSyntax:<pre tabindex=0><code>!sparse_tensor.storage_specifier< ::mlir::sparse_tensor::SparseTensorEncodingAttr # encoding > </code></pre>Values with storage_specifier types represent aggregated storage scheme metadata for the given sparse tensor encoding. It currently holds a set of values for level-sizes, coordinate arrays, position arrays, and value array. Note that the type is not yet stable and subject to change in the near future.Examples:<div class=highlight><pre tabindex=0 class=chroma><code class=language-mlir data-lang=mlir>// A storage specifier that can be used to store storage scheme metadata from CSR matrix. !storage_specifier<#CSR> </code></pre></div><h4 id=parameters-7>Parameters: <a class=headline-hash href=#parameters-7>¶</a></h4><table><thead><tr><th style=text-align:center>Parameter</th><th style=text-align:center>C++ type</th><th>Description</th></tr></thead><tbody><tr><td style=text-align:center>encoding</td><td style=text-align:center><code>::mlir::sparse_tensor::SparseTensorEncodingAttr</code></td><td></td></tr></tbody></table><h2 id=enums>Enums <a class=headline-hash href=#enums>¶</a></h2><h3 id=crdtransdirectionkind>CrdTransDirectionKind <a class=headline-hash href=#crdtransdirectionkind>¶</a></h3>sparse tensor coordinate translation direction<h4 id=cases>Cases: <a class=headline-hash href=#cases>¶</a></h4><table><thead><tr><th style=text-align:center>Symbol</th><th style=text-align:center>Value</th><th>String</th></tr></thead><tbody><tr><td style=text-align:center>dim2lvl</td><td style=text-align:center><code>0</code></td><td>dim_to_lvl</td></tr><tr><td style=text-align:center>lvl2dim</td><td style=text-align:center><code>1</code></td><td>lvl_to_dim</td></tr></tbody></table><h3 id=sparsetensorsortkind>SparseTensorSortKind <a class=headline-hash href=#sparsetensorsortkind>¶</a></h3>sparse tensor sort algorithm<h4 id=cases-1>Cases: <a class=headline-hash href=#cases-1>¶</a></h4><table><thead><tr><th style=text-align:center>Symbol</th><th style=text-align:center>Value</th><th>String</th></tr></thead><tbody><tr><td style=text-align:center>HybridQuickSort</td><td style=text-align:center><code>0</code></td><td>hybrid_quick_sort</td></tr><tr><td style=text-align:center>InsertionSortStable</td><td style=text-align:center><code>1</code></td><td>insertion_sort_stable</td></tr><tr><td style=text-align:center>QuickSort</td><td style=text-align:center><code>2</code></td><td>quick_sort</td></tr><tr><td style=text-align:center>HeapSort</td><td style=text-align:center><code>3</code></td><td>heap_sort</td></tr></tbody></table><h3 id=storagespecifierkind>StorageSpecifierKind <a class=headline-hash href=#storagespecifierkind>¶</a></h3>sparse tensor storage specifier kind<h4 id=cases-2>Cases: <a class=headline-hash href=#cases-2>¶</a></h4><table><thead><tr><th style=text-align:center>Symbol</th><th style=text-align:center>Value</th><th>String</th></tr></thead><tbody><tr><td style=text-align:center>LvlSize</td><td style=text-align:center><code>0</code></td><td>lvl_sz</td></tr><tr><td style=text-align:center>PosMemSize</td><td style=text-align:center><code>1</code></td><td>pos_mem_sz</td></tr><tr><td style=text-align:center>CrdMemSize</td><td style=text-align:center><code>2</code></td><td>crd_mem_sz</td></tr><tr><td style=text-align:center>ValMemSize</td><td style=text-align:center><code>3</code></td><td>val_mem_sz</td></tr><tr><td style=text-align:center>DimOffset</td><td style=text-align:center><code>4</code></td><td>dim_offset</td></tr><tr><td style=text-align:center>DimStride</td><td style=text-align:center><code>5</code></td><td>dim_stride</td></tr></tbody></table><div class=edit-meta> </div><nav class=pagination><a class="nav nav-prev" href=https://mlir.llvm.org/docs/Dialects/ShapeDialect/ title="'shape' Dialect"> Prev - 'shape' Dialect</a> <a class="nav nav-next" href=https://mlir.llvm.org/docs/Dialects/TensorOps/ title="'tensor' Dialect">Next - 'tensor' Dialect </a></nav><footer>Powered by <a href=https://gohugo.io>Hugo</a>. Theme by <a href=https://themes.gohugo.io/hugo-theme-techdoc/>TechDoc</a>. Designed by <a href=https://github.com/thingsym/hugo-theme-techdoc>Thingsym</a>.</footer></main><div class=sidebar><nav class=slide-menu><ul><li><a href=https://mlir.llvm.org/>Home</a></li><li><a href=https://mlir.llvm.org/users/>Users of MLIR</a></li><li><a href=https://mlir.llvm.org/pubs/>MLIR Related Publications</a></li><li><a href=https://mlir.llvm.org/talks/>Talks</a></li><li><a href=https://mlir.llvm.org/deprecation/>Deprecations & Current Refactoring</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/getting_started/>Getting Started+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/getting_started/ReportingIssues/>Reporting Issues</a></li><li><a href=https://mlir.llvm.org/getting_started/Debugging/>Debugging Tips</a></li><li><a href=https://mlir.llvm.org/getting_started/Faq/>FAQ</a></li><li><a href=https://mlir.llvm.org/getting_started/Contributing/>How to Contribute</a></li><li><a href=https://mlir.llvm.org/getting_started/DeveloperGuide/>Developer Guide</a></li><li><a href=https://mlir.llvm.org/getting_started/openprojects/>Open Projects</a></li><li><a href=https://mlir.llvm.org/getting_started/Glossary/>Glossary</a></li><li><a href=https://mlir.llvm.org/getting_started/TestingGuide/>Testing Guide</a></li></ul></li><li class="parent has-sub-menu"><a href=https://mlir.llvm.org/docs/>Code Documentation-</a><ul class=sub-menu><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Bindings/>Bindings+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Bindings/Python/>MLIR Python Bindings</a></li></ul></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Tools/>Tools+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Tools/MLIRLSP/>MLIR : Language Server Protocol</a></li><li><a href=https://mlir.llvm.org/docs/Tools/mlir-reduce/>MLIR Reduce</a></li><li><a href=https://mlir.llvm.org/docs/Tools/mlir-rewrite/>mlir-rewrite</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/QuantPasses/></a></li><li><a href=https://mlir.llvm.org/docs/ActionTracing/>Action: Tracing and Debugging MLIR-based Compilers</a></li><li><a href=https://mlir.llvm.org/docs/BufferDeallocationInternals/>Buffer Deallocation - Internals</a></li><li><a href=https://mlir.llvm.org/docs/Bufferization/>Bufferization</a></li><li><a href=https://mlir.llvm.org/docs/DataLayout/>Data Layout Modeling</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/DefiningDialects/>Defining Dialects+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/DefiningDialects/Constraints/>Constraints</a></li><li><a href=https://mlir.llvm.org/docs/DefiningDialects/AttributesAndTypes/>Defining Dialect Attributes and Types</a></li><li><a href=https://mlir.llvm.org/docs/DefiningDialects/Operations/>Operation Definition Specification (ODS)</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/Diagnostics/>Diagnostic Infrastructure</a></li><li><a href=https://mlir.llvm.org/docs/DialectConversion/>Dialect Conversion</a></li><li class="parent has-sub-menu"><a href=https://mlir.llvm.org/docs/Dialects/>Dialects-</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Dialects/DLTITransformOps/></a></li><li><a href=https://mlir.llvm.org/docs/Dialects/OpenACCDialect/>'acc' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/Affine/>'affine' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/AMDGPU/>'amdgpu' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/AMX/>'amx' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ArithOps/>'arith' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ArmNeon/>'arm_neon' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ArmSVE/>'arm_sve' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ArmSME/>'ArmSME' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/AsyncDialect/>'async' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/BufferizationOps/>'bufferization' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ControlFlowDialect/>'cf' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ComplexOps/>'complex' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/DLTIDialect/>'dlti' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/EmitC/>'emitc' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/Func/>'func' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/GPU/>'gpu' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/IndexOps/>'index' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/IRDL/>'irdl' Dialect</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Dialects/Linalg/>'linalg' Dialect+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Dialects/Linalg/OpDSL/>Linalg OpDSL</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/Dialects/LLVM/>'llvm' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/MathOps/>'math' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/MemRef/>'memref' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/Mesh/>'mesh' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/MLProgramOps/>'ml_program' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/MPI/>'mpi' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/NVGPU/>'nvgpu' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/NVVMDialect/>'nvvm' Dialect</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Dialects/OpenMPDialect/>'omp' Dialect+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Dialects/OpenMPDialect/ODS/>ODS Documentation</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/Dialects/PDLInterpOps/>'pdl_interp' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/PDLOps/>'pdl' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/PolynomialDialect/>'polynomial' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/PtrOps/>'ptr' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/QuantDialect/>'quant' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ROCDLDialect/>'rocdl' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/SCFDialect/>'scf' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/ShapeDialect/>'shape' Dialect</a></li><li class=active><a href=https://mlir.llvm.org/docs/Dialects/SparseTensorOps/>'sparse_tensor' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/TensorOps/>'tensor' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/UBOps/>'ub' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/VCIXDialect/>'vcix' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/Vector/>'vector' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/X86Vector/>'x86vector' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/XeGPU/>'xegpu' Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/Builtin/>Builtin Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/MatchOpInterfaces/>OpInterface definitions</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/SPIR-V/>SPIR-V Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/TOSA/>Tensor Operator Set Architecture (TOSA) Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Dialects/Transform/>Transform Dialect</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/Interfaces/>Interfaces</a></li><li><a href=https://mlir.llvm.org/docs/TargetLLVMIR/>LLVM IR Target</a></li><li><a href=https://mlir.llvm.org/docs/BytecodeFormat/>MLIR Bytecode Format</a></li><li><a href=https://mlir.llvm.org/docs/CAPI/>MLIR C API</a></li><li><a href=https://mlir.llvm.org/docs/LangRef/>MLIR Language Reference</a></li><li><a href=https://mlir.llvm.org/docs/ReleaseNotes/>MLIR Release Notes</a></li><li><a href=https://mlir.llvm.org/docs/Canonicalization/>Operation Canonicalization</a></li><li><a href=https://mlir.llvm.org/docs/OwnershipBasedBufferDeallocation/>Ownership-based Buffer Deallocation</a></li><li><a href=https://mlir.llvm.org/docs/PassManagement/>Pass Infrastructure</a></li><li><a href=https://mlir.llvm.org/docs/Passes/>Passes</a></li><li><a href=https://mlir.llvm.org/docs/PatternRewriter/>Pattern Rewriting : Generic DAG-to-DAG Rewriting</a></li><li><a href=https://mlir.llvm.org/docs/PDLL/>PDLL - PDL Language</a></li><li><a href=https://mlir.llvm.org/docs/Quantization/>Quantization</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Rationale/>Rationale+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Rationale/RationaleGenericDAGRewriter/>Generic DAG Rewriter Infrastructure Rationale</a></li><li><a href=https://mlir.llvm.org/docs/Rationale/RationaleLinalgDialect/>Linalg Dialect Rationale: The Case For Compiler-Friendly Custom Operations</a></li><li><a href=https://mlir.llvm.org/docs/Rationale/Rationale/>MLIR Rationale</a></li><li><a href=https://mlir.llvm.org/docs/Rationale/MLIRForGraphAlgorithms/>MLIR: Incremental Application to Graph Algorithms in ML Frameworks</a></li><li><a href=https://mlir.llvm.org/docs/Rationale/RationaleSimplifiedPolyhedralForm/>MLIR: The case for a simplified polyhedral form</a></li><li><a href=https://mlir.llvm.org/docs/Rationale/SideEffectsAndSpeculation/>Side Effects & Speculation</a></li><li><a href=https://mlir.llvm.org/docs/Rationale/UsageOfConst/>Usage of 'const' in MLIR, for core IR types</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/ShapeInference/>Shape Inference</a></li><li><a href=https://mlir.llvm.org/docs/SPIRVToLLVMDialectConversion/>SPIR-V Dialect to LLVM Dialect conversion manual</a></li><li><a href=https://mlir.llvm.org/docs/SymbolsAndSymbolTables/>Symbols and Symbol Tables</a></li><li><a href=https://mlir.llvm.org/docs/DeclarativeRewrites/>Table-driven Declarative Rewrite Rule (DRR)</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Traits/>Traits+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Traits/Broadcastable/>The `Broadcastable` Trait</a></li></ul></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Tutorials/>Tutorials+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Tutorials/CreatingADialect/>Creating a Dialect</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/QuickstartRewrites/>Quickstart tutorial to adding MLIR graph rewrite</a></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Tutorials/Toy/>Toy Tutorial+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-1/>Chapter 1: Toy Language and AST</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-2/>Chapter 2: Emitting Basic MLIR</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-3/>Chapter 3: High-level Language-Specific Analysis and Transformation</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-4/>Chapter 4: Enabling Generic Transformation with Interfaces</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-5/>Chapter 5: Partial Lowering to Lower-Level Dialects for Optimization</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-6/>Chapter 6: Lowering to LLVM and CodeGeneration</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/Toy/Ch-7/>Chapter 7: Adding a Composite Type to Toy</a></li></ul></li><li class=has-sub-menu><a href=https://mlir.llvm.org/docs/Tutorials/transform/>Transform Dialect Tutorial+</a><ul class=sub-menu><li><a href=https://mlir.llvm.org/docs/Tutorials/transform/Ch0/>Chapter 0: A Primer on “Structured” Linalg Operations</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/transform/Ch1/>Chapter 1: Combining Existing Transformations</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/transform/Ch2/>Chapter 2: Adding a Simple New Transformation Operation</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/transform/Ch3/>Chapter 3: More than Simple Transform Operations</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/transform/Ch4/>Chapter 4: Matching Payload with Transform Operations</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/transform/ChH/>Chapter H: Reproducing Halide Schedule</a></li></ul></li><li><a href=https://mlir.llvm.org/docs/Tutorials/UnderstandingTheIRStructure/>Understanding the IR Structure</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/MlirOpt/>Using `mlir-opt`</a></li><li><a href=https://mlir.llvm.org/docs/Tutorials/DataFlowAnalysis/>Writing DataFlow Analyses in MLIR</a></li></ul></li></ul></li></ul></nav><div class=sidebar-footer></div></div></div><a href=# id=backtothetop-fixed class=backtothetop data-backtothetop-duration=600 data-backtothetop-easing=easeOutQuart data-backtothetop-fixed-fadein=1000 data-backtothetop-fixed-fadeout=1000 data-backtothetop-fixed-bottom=10 data-backtothetop-fixed-right=20> </a></div></body></html>