add various references to sparse tensor api, extend type doc (#901)

* add references to sparse section

* remove _ from label reference

docs_input/api/linalg/matvec/matmul.rst

@@ -13,6 +13,8 @@ is supported for any tensor with a rank higher than 2.
 .. doxygenfunction:: matmul(const OpA &A, const OpB &B, float alpha = 1.0, float beta = 0.0)
 .. doxygenfunction:: matmul(const OpA &A, const OpB &B, const int32_t (&axis)[2], float alpha = 1.0, float beta = 0.0)
 
+For information on experimental sparse tensor support for Sparse-Matrix x Matrix (SpMM), please see :ref:`sparse_tensor_api`.
+
 Examples
 ~~~~~~~~
 

docs_input/api/linalg/other/solve.rst

@@ -0,0 +1,10 @@
+.. _solve_func:
+
+solve
+=====
+
+Solves the system of equations AX=Y, where X is the unknown.
+
+.. doxygenfunction:: solve(const OpA &A, const OpB &B)
+
+Currently only supported for sparse matrix A, please see :ref:`sparse_tensor_api`.

docs_input/basics/creation.rst

@@ -8,6 +8,8 @@ to pick up the syntax quickly without understanding the underlying architecture.
 it lacks flexibility and can prevent your code from running at the highest performance possible. This document walks through the
 different ways to construct tensors, and when you should use certain methods over others.
 
+For information on creating the still experimental sparse tensors, please see :ref:`sparse_tensor_api`.
+
 A Quick Primer On MatX Types
 ----------------------------
 The basic type of tensor used in most examples and tests is the ``tensor_t`` object. ``tensor_t`` is the highest-level tensor class, and

docs_input/basics/sparse_tensor.rst

@@ -1,3 +1,5 @@
+.. _sparse_tensor_api:
+
 Sparse Tensor Type
 ##################
 
@@ -89,8 +91,8 @@ operations for sparse-to-dense, dense-to-sparse, matmul, and solve::
 
    (A = sparse2dense(Acoo)).run(exec);
    (Acoo = dense2sparse(D)).run(exec);
-   (C = matmul(Acoo, B)).run(exec);
-   (X = solve(Acsr, Y)).run(exec);     // CSR only
+   (C = matmul(Acoo, B)).run(exec); // only Sparse-Matrix x Matrix (SpMM)
+   (X = solve(Acsr, Y)).run(exec);  // only on CSR format
 
 We expect the assortment of supported sparse operations and storage
 formats to grow if the experimental implementation is well-received.
@@ -150,6 +152,32 @@ to where the tensor is being used, including device memory, managed memory,
 and host memory. MatX sparse tensors are very similar to e.g. SciPy's or
 cuPy sparse arrays.
 
+The implementation of the UST follows the MatX design philosophy of using
+a header-only, ``constexpr``-heavy, templated approach, which facilitates
+applications to only compile what is used, and nothing more.
+The ``sparse_tensor_t`` type is essentially the following class,
+where the tensor format ``TF`` is part of the template::
+
+  template <typename VAL, typename CRD, typename POS, typename TF, ...>
+  class sparse_tensor_t : public detail::tensor_impl_t<...> {
+    
+    static constexpr int DIM = TF::DIM;
+    static constexpr int LVL = TF::LVL;
+
+  private:
+    // Primary storage of sparse tensor (explicitly stored element values).
+    StorageV values_;
+
+    // Secondary storage of sparse tensor (coordinates and positions).
+    StorageC coordinates_[LVL];
+    StorageP positions_[LVL];
+  }
+
+Using this design, many tests (e.g. is this tensor in COO format) 
+evaluate as ``constexpr`` at compile-time, keeping the binary
+size restricted to only what is actually used in a MatX computation.
+
+
 Matx Implementation of the Tensor Format DSL
 --------------------------------------------
 
@@ -237,14 +265,15 @@ Historical Background of the UST Type
 -------------------------------------
 
 The concept of the UST type has its roots in sparse compilers, first pioneered
-for sparse linear algebra in [`B&W95`_, `Bik96`_, `Bik98`_] and formalized to
-sparse tensor algebra in [`Kjolstad20`_, `Chou22`_, `Yadav22`_]. The tensor
-format DSL for the UST type, including the generalization to higher-dimensional
-levels, was introduced in [`MLIR22`_, `MLIR`_]. Please refer to this literature
-for a more extensive presentation of all topics only briefly discussed in this
-online documentation.
-
-.. _B&W95: https://dl.acm.org/doi/10.1145/169627.169765
+for sparse linear algebra in [`B&W95`_, `B&W96`_, `Bik96`_, `Bik98`_] and
+formalized to sparse tensor algebra in [`Kjolstad20`_, `Chou22`_, `Yadav22`_].
+The tensor format DSL for the UST type, including the generalization to
+higher-dimensional levels, was introduced in [`MLIR22`_, `MLIR`_]. Please
+refer to this literature for a more extensive presentation of all topics only
+briefly discussed in this online documentation.
+
+.. _B&W95: https://dl.acm.org/doi/10.1006/jpdc.1995.1141
+.. _B&W96: https://ieeexplore.ieee.org/document/485501
 .. _Bik96: https://theses.liacs.nl/1315
 .. _Bik98: https://dl.acm.org/doi/10.1145/290200.287636
 .. _Chou22: http://tensor-compiler.org/files/chou-phd-thesis-taco-formats.pdf

docs_input/basics/tensor.rst

@@ -22,6 +22,7 @@ contains only types that are available on both the host and device, and provides
 needed for device code.
 
 For information on creating tensors, please see :ref:`creating` or :ref:`quickstart` for common usage.
+For information on experimental sparse tensor support, please see :ref:`sparse_tensor_api`.
 
 .. doxygenclass:: matx::tensor_t
     :members: