temporarily remove implementation notes from web doc

RandBLAS/dense_skops.hh

@@ -188,9 +188,28 @@ struct DenseSkOp {
     DenseSkOp(
         DenseDist dist,
         RNGState<RNG> const &state,
-        T *buff = nullptr
+        T *buff
     );
 
+    ///---------------------------------------------------------------------------
+    /// The preferred constructor for DenseSkOp objects. There are other 
+    /// constructors, but they don't appear in the web documentation.
+    ///
+    /// @param[in] dist
+    ///     A DenseDist object.
+    ///     - Defines the number of rows and columns in this sketching operator.
+    ///     - Defines the (scalar-valued) distribution of each entry in this sketching operator.
+    ///
+    /// @param[in] state
+    ///     An RNGState object.
+    ///     - The RNG will use this as the starting point to generate all 
+    ///       random numbers needed for this sketching operator.
+    ///
+    DenseSkOp(
+        DenseDist dist,
+        RNGState<RNG> const &state
+    ) : DenseSkOp(dist, state, nullptr) {};
+
     //  Convenience constructor (a wrapper)
     DenseSkOp(
         DenseDist dist,

RandBLAS/skge.hh

@@ -764,7 +764,6 @@ inline void sketch_vector(
 ///     
 ///      S - [in]  
 ///       * A DenseSkOp or SparseSkOp object.
-///       * Defines :math:`S.`
 ///
 ///      x - [in]
 ///       * Pointer to a 1D array of real scalars.

RandBLAS/sparse_skops.hh

@@ -118,35 +118,35 @@ struct SparseSkOp {
     /////////////////////////////////////////////////////////////////////
 
     // ---------------------------------------------------------------------------
-    ///
-    /// @param[in] dist
-    ///     A SparseDist object.
-    ///     - Defines the number of rows and columns in this sketching operator.
-    ///     - Indirectly controls sparsity pattern.
-    ///     - Directly controls sparsity level.
-    ///
-    /// @param[in] state
-    ///     An RNGState object.
-    ///     - The RNG will use this as the starting point to generate all 
-    ///       random numbers needed for this sketching operator.
-    ///
-    /// @param[in] rows
-    ///     Pointer to int64_t array.
-    ///     - stores row indices as part of the COO format.
-    ///
-    /// @param[in] cols
-    ///     Pointer to int64_t array.
-    ///     - stores column indices as part of the COO format.
-    ///
-    /// @param[in] vals
-    ///     Pointer to array of real numerical type T.
-    ///     - stores nonzeros as part of the COO format.
-    /// 
-    /// @param[in] known_filled
-    ///     A boolean. If true, then the arrays pointed to by
-    ///     (rows, cols, vals) already contain the randomly sampled
-    ///     data defining this sketching operator.
-    ///     
+    // 
+    //  @param[in] dist
+    //      A SparseDist object.
+    //      - Defines the number of rows and columns in this sketching operator.
+    //      - Indirectly controls sparsity pattern.
+    //      - Directly controls sparsity level.
+    // 
+    //  @param[in] state
+    //      An RNGState object.
+    //      - The RNG will use this as the starting point to generate all 
+    //        random numbers needed for this sketching operator.
+    // 
+    //  @param[in] rows
+    //      Pointer to int64_t array.
+    //      - stores row indices as part of the COO format.
+    // 
+    //  @param[in] cols
+    //      Pointer to int64_t array.
+    //      - stores column indices as part of the COO format.
+    // 
+    //  @param[in] vals
+    //      Pointer to array of real numerical type T.
+    //      - stores nonzeros as part of the COO format.
+    //  
+    //  @param[in] known_filled
+    //      A boolean. If true, then the arrays pointed to by
+    //      (rows, cols, vals) already contain the randomly sampled
+    //      data defining this sketching operator.
+    //      
     SparseSkOp(
         SparseDist dist,
         const RNGState<RNG> &state,
@@ -164,6 +164,22 @@ struct SparseSkOp {
         T *vals 
     ) : SparseSkOp(dist, RNGState<RNG>(key), rows, cols, vals) {};
 
+
+    ///---------------------------------------------------------------------------
+    /// The preferred constructor for SparseSkOp objects. There are other 
+    /// constructors, but they don't appear in the web documentation.
+    ///
+    /// @param[in] dist
+    ///     A SparseDist object.
+    ///     - Defines the number of rows and columns in this sketching operator.
+    ///     - Indirectly controls sparsity pattern.
+    ///     - Directly controls sparsity level.
+    ///
+    /// @param[in] state
+    ///     An RNGState object.
+    ///     - The RNG will use this as the starting point to generate all 
+    ///       random numbers needed for this sketching operator.
+    ///
     SparseSkOp(
         SparseDist dist,
         const RNGState<RNG> &state

rtd/source/api_reference/index.rst

@@ -5,9 +5,8 @@
 API Reference
 #############
 
-.. warning::
 
-  TODO. Explain that we always say data matrices are :math:`m \times n`. Sketching involves matrices (S, A, B).
+..  TODO. Explain that we always say data matrices are :math:`m \times n`. Sketching involves matrices (S, A, B).
 
 .. toctree::
     :maxdepth: 4

rtd/source/api_reference/skops_and_dists.rst

@@ -17,13 +17,13 @@ The state of a random number generator
 DenseDist and DenseSkOp
 ============================================
 
+.. doxygenenum:: RandBLAS::DenseDistName
+    :project: RandBLAS
+
 .. doxygenstruct:: RandBLAS::DenseDist
    :project: RandBLAS
    :members:
 
-
-TODO: document the DenseSkOp constructor(s) I care about!
-
 .. doxygenstruct:: RandBLAS::DenseSkOp
    :project: RandBLAS
    :members: 
@@ -37,8 +37,6 @@ TODO: document the DenseSkOp constructor(s) I care about!
 SparseDist and SparseSkOp
 ==============================
 
-TODO: document the SparseSkOp constructors that I actually care about, and hide documentation of the one(s) I don't care about.
-
 .. doxygenstruct:: RandBLAS::SparseDist
    :project: RandBLAS
    :members:
@@ -54,9 +52,6 @@ TODO: document the SparseSkOp constructors that I actually care about, and hide
 Advanced material
 =================
 
-.. doxygenenum:: RandBLAS::DenseDistName
-    :project: RandBLAS
-
 .. doxygenfunction:: RandBLAS::fill_dense(const DenseDist &D, int64_t n_rows, int64_t n_cols, int64_t S_ro, int64_t S_co, T *buff, const RNGState<RNG> &seed)
    :project: RandBLAS
 

rtd/source/index.rst

@@ -21,7 +21,7 @@ All sketches produced by RandBLAS are dense.
 As such, dense data matrices can be sketched with dense or sparse operators, while sparse data matrices can only be sketched with dense operators.
 RandBLAS can be used in distributed environments through its ability to (reproducibly) compute products with *submatrices* of sketching operators.
 
-Learn more by reading the `RandBLAS User Guide <tutorial/index.html>`_ or our `API Reference <api/index.html>`.
+Learn more by reading our `Tutorial <tutorial/index.html>`_ or our `API Reference <api_reference/index.html>`_.
 
 Source Code
 -----------

rtd/source/tutorial/distributions.rst

@@ -30,28 +30,44 @@ How to choose between dense and sparse sketching
 
 Let's say you have an :math:`m \times n` matrix :math:`A` and an integer :math:`d,`
 and you want to compute a sketch of :math:`A` that has rank :math:`\min\{d, \operatorname{rank}(A)\}.`
-Here's a visual aid to help decide whether to use a dense or a sparse sketching operator.
+Here's a chart to help decide whether to use a dense or a sparse sketching operator.
 
   .. raw:: html
       :file: ../assets/sparse_vs_dense_diagram_no_header.html
 
-The chart's first question asks about the representation of :math:`A,`
-and has a plain yes-no answer. 
-It reflects a limitation of RandBLAS that sparse data can only be sketched with dense sketching operators.
+Discussion of the chart's first yes/no branch.
+  RandBLAS doesn't allow applying sparse sketching operators to sparse data.
+  This is because RandBLAS is only intended to produce sketches that are dense.
 
-The chart's second question is more subjective.
-It's getting at whether adding :math:`O(dmn)` flops to a larger randomized algorithm
-has potential to decisively impact that algorithm's performance.
-Some randomized algorithms for dense matrix computations make it easy to answer this question.
+  While 
+  algorithms exist to multiply two sparse matrices and store the
+  result as a dense matrix, we don't know of practical RandNLA
+  algorithms that would benefit from this functionality.
 
-  Subspace iteration methods for low-rank approximation have complexity :math:`\Omega(dmn)`
-  regardless of whether the complexity of computing the initial sketch is :math:`o(dmn)`.
 
-  Sketch-and-precondition methods for least squares need to set :math:`d \geq \min\{m,n\}`.
-  As a result, these methods can't tolerate :math:`O(dmn)` operations for sketching while still providing
-  asymptotically faster runtime than a direct least squares solver.
+Discussion of the chart's second yes/no branch.
+  This gets at whether adding :math:`O(dmn)` flops to a randomized algorithm
+  can decisively impact that algorithm's performance.
+  Some randomized algorithms for dense matrix computations make it easy to answer this question.
+  Consider, for example ...
 
-In other situations, it's not as clear cut. 
+    *Subspace iteration methods for low-rank approximation.* These methods have complexity :math:`\Omega(dmn)`
+    regardless of whether the complexity of computing the initial sketch is :math:`o(dmn)`.
+
+    *Sketch-and-precondition methods for least squares.* These methods need to set :math:`d \geq \min\{m,n\}`.
+    As a result, they can't tolerate :math:`O(dmn)` operations for sketching while still providing
+    asymptotically faster runtime than a direct least squares solver.
+
+  With this in mind, notice that the chart indicates a preference dense sketching over
+  sparse sketching when dense sketching can be afforded.
+  This preference stems from how if the sketching dimension is fixed, then the statistical properties of dense sketching
+  operators will generally be preferable to those of sparse
+  sketching operators.
+
+  .. note::
+    See Wikipedia for the meanings of
+    `big-omega notation <https://en.wikipedia.org/wiki/Big_O_notation#Big_Omega_notation>`_ and 
+    `little-o notation <https://en.wikipedia.org/wiki/Big_O_notation#Little-o_notation>`_.
 
 
 Distribution parameters

rtd/source/tutorial/sampling_skops.rst

@@ -1,7 +1,7 @@
 .. toctree::
   :maxdepth: 3
 
-Note to self: I can first describe CBRNGs mathematically. Then I get to implementation details.
+.. Note to self: I can first describe CBRNGs mathematically. Then I get to implementation details.
 
 ******************************************************************************
 Sampling a sketching operator

rtd/source/tutorial/temp.rst

@@ -43,3 +43,26 @@
 .. have the same capabilities as GEMM.
 
 
+
+.. ******************************************************************************
+.. Implementation notes
+.. ******************************************************************************
+
+.. RNGState
+.. ========
+
+.. TODO: Implementation details. Things like the counter and key being arrays. You shouldn't need to interact with the APIs
+.. of these arrays. But, to address any curiosity, one of their nice features is an ``ctr.incr(val)`` method that effectively
+.. encodes addition in a way that correctly handles overflow from one entry of ``ctr`` to the next.
+
+.. Every RNGState has an associated template parameter, RNG.
+.. The default value of the RNG template parameter is :math:`\texttt{Philox4x32}`.
+.. An RNG template parameter with name :math:`\texttt{GeneratorNxW}` will represent
+.. the counter and key by an array of (at most) :math:`\texttt{N}` unsiged :math:`\texttt{W}`-bit integers.
+
+.. DenseSkOp
+.. ===================================
+
+
+.. SparseSkOp
+.. ===================================