refactor: common; docs for matrix

Author: artemiipatov

src/GraphBLAS-sharp.Backend/Algorithms/Algorithms.fs

@@ -5,4 +5,5 @@ open GraphBLAS.FSharp.Backend.Algorithms
 
 [<RequireQualifiedAccess>]
 module Algorithms =
-    let singleSourceBFS = BFS.singleSource
+    module BFS =
+        let singleSource = BFS.singleSource

src/GraphBLAS-sharp.Backend/Common/Common.fs

@@ -5,55 +5,56 @@ open Microsoft.FSharp.Quotations
 open GraphBLAS.FSharp.Backend.Common
 
 module Common =
-    module Bitonic =
-        /// <summary>
-        /// Sorts in-place input array of values by their 2d indices,
-        /// which are stored in two given arrays of keys: rows and columns.
-        /// When comparing, it first looks at rows, then columns.
-        /// </summary>
-        /// <example>
-        /// <code>
-        /// let rows = [| 0; 0; 3; 2; 1; 0; 5 |]
-        /// let columns = [| 0; 2; 1; 2; 0; 3; 5; |]
-        /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
-        /// sortKeyValuesInplace clContext 32 processor rows columns values
-        /// ...
-        /// > val rows = [| 0; 0; 0; 1; 2; 3; 5 |]
-        /// > let columns = [| 0; 2; 3; 0; 2; 1; 5; |]
-        /// > val values = [| 1.9; 2.8; 6.4; 5.5; 4.6; 3.7; 7.3 |]
-        /// </code>
-        /// </example>
-        let sortKeyValuesInplace<'n, 'a when 'n: comparison> =
-            Sort.Bitonic.sortKeyValuesInplace<'n, 'a>
+    module Sort =
+        module Bitonic =
+            /// <summary>
+            /// Sorts in-place input array of values by their 2d indices,
+            /// which are stored in two given arrays of keys: rows and columns.
+            /// When comparing, it first looks at rows, then columns.
+            /// </summary>
+            /// <example>
+            /// <code>
+            /// let rows = [| 0; 0; 3; 2; 1; 0; 5 |]
+            /// let columns = [| 0; 2; 1; 2; 0; 3; 5; |]
+            /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
+            /// sortKeyValuesInplace clContext 32 processor rows columns values
+            /// ...
+            /// > val rows = [| 0; 0; 0; 1; 2; 3; 5 |]
+            /// > let columns = [| 0; 2; 3; 0; 2; 1; 5; |]
+            /// > val values = [| 1.9; 2.8; 6.4; 5.5; 4.6; 3.7; 7.3 |]
+            /// </code>
+            /// </example>
+            let sortKeyValuesInplace<'n, 'a when 'n: comparison> =
+                Sort.Bitonic.sortKeyValuesInplace<'n, 'a>
 
-    module Radix =
-        /// <summary>
-        /// Sorts stable input array of values by given integer keys.
-        /// </summary>
-        /// <example>
-        /// <code>
-        /// let keys = [| 0; 4; 3; 1; 2; 6; 5 |]
-        /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
-        /// runByKeysStandard clContext 32 processor keys values
-        /// ...
-        /// > val keys = [| 0; 1; 2; 3; 4; 5; 6 |]
-        /// > val values = [| 1.9; 4.6; 5.5; 3.7; 2.8; 7.3; 6.4 |]
-        /// </code>
-        /// </example>
-        let runByKeysStandard = Sort.Radix.runByKeysStandard
+        module Radix =
+            /// <summary>
+            /// Sorts stable input array of values by given integer keys.
+            /// </summary>
+            /// <example>
+            /// <code>
+            /// let keys = [| 0; 4; 3; 1; 2; 6; 5 |]
+            /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
+            /// runByKeysStandard clContext 32 processor keys values
+            /// ...
+            /// > val keys = [| 0; 1; 2; 3; 4; 5; 6 |]
+            /// > val values = [| 1.9; 4.6; 5.5; 3.7; 2.8; 7.3; 6.4 |]
+            /// </code>
+            /// </example>
+            let runByKeysStandard = Sort.Radix.runByKeysStandard
 
-        /// <summary>
-        /// Sorts stable input array of integer keys.
-        /// </summary>
-        /// <example>
-        /// <code>
-        /// let keys = [| 0; 4; 3; 1; 2; 6; 5 |]
-        /// standardRunKeysOnly clContext 32 processor keys
-        /// ...
-        /// > val keys = [| 0; 1; 2; 3; 4; 5; 6 |]
-        /// </code>
-        /// </example>
-        let standardRunKeysOnly = Sort.Radix.standardRunKeysOnly
+            /// <summary>
+            /// Sorts stable input array of integer keys.
+            /// </summary>
+            /// <example>
+            /// <code>
+            /// let keys = [| 0; 4; 3; 1; 2; 6; 5 |]
+            /// standardRunKeysOnly clContext 32 processor keys
+            /// ...
+            /// > val keys = [| 0; 1; 2; 3; 4; 5; 6 |]
+            /// </code>
+            /// </example>
+            let standardRunKeysOnly = Sort.Radix.standardRunKeysOnly
 
     module Gather =
         /// <summary>
@@ -212,28 +213,28 @@ module Common =
         /// > val sum = [| 4 |]
         /// </code>
         /// </example>
+        /// <param name="plus">Associative binary operation.</param>
         /// <param name="clContext">ClContext.</param>
         /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
-        /// <param name="plus">Associative binary operation.</param>
         /// <param name="zero">Zero element for binary operation.</param>
         let runIncludeInPlace plus = PrefixSum.runIncludeInPlace plus
 
         /// <summary>
         /// Exclude in-place prefix sum. Array is scanned starting from the end.
         /// </summary>
+        /// <param name="plus">Associative binary operation.</param>
         /// <param name="clContext">ClContext.</param>
         /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
-        /// <param name="plus">Associative binary operation.</param>
         /// <param name="zero">Zero element for binary operation.</param>
         let runBackwardsExcludeInPlace plus =
             PrefixSum.runBackwardsExcludeInPlace plus
 
         /// <summary>
         /// Include in-place prefix sum. Array is scanned starting from the end.
         /// </summary>
+        /// <param name="plus">Associative binary operation.</param>
         /// <param name="clContext">ClContext.</param>
         /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
-        /// <param name="plus">Associative binary operation.</param>
         /// <param name="zero">Zero element for binary operation.</param>
         let runBackwardsIncludeInPlace plus =
             PrefixSum.runBackwardsIncludeInPlace plus

src/GraphBLAS-sharp.Backend/Common/Gather.fs

@@ -2,7 +2,23 @@ namespace GraphBLAS.FSharp.Backend.Common
 
 open Brahma.FSharp
 
-module internal Gather =
+module Gather =
+    /// <summary>
+    /// Fills the given output array using the given value array and a function. The function maps old position
+    /// of each element of the value array to its position in the output array.
+    /// </summary>
+    /// <remarks>
+    /// If index is out of bounds, the value will be ignored.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// let positions = [| 1; 0; 2; 6; 4; 3; 5 |]
+    /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
+    /// run clContext 32 processor positions values result
+    /// ...
+    /// > val result = [| 2.8; 1.9; 3.7; 7.3; 5.5; 4.6; 6.4 |]
+    /// </code>
+    /// </example>
     let runInit positionMap (clContext: ClContext) workGroupSize =
 
         let gather =
@@ -29,6 +45,22 @@ module internal Gather =
 
             processor.Post(Msg.CreateRunMsg<_, _>(kernel))
 
+    /// <summary>
+    /// Fills the given output array using the given value and position arrays. Array of positions indicates
+    /// which element from the value array should be in each position of the output array.
+    /// </summary>
+    /// <remarks>
+    /// If index is out of bounds, the value will be ignored.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// let positions = [| 1; 0; 2; 6; 4; 3; 5 |]
+    /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
+    /// run clContext 32 processor positions values result
+    /// ...
+    /// > val result = [| 2.8; 1.9; 3.7; 7.3; 5.5; 4.6; 6.4 |]
+    /// </code>
+    /// </example>
     let run (clContext: ClContext) workGroupSize =
 
         let gather =

src/GraphBLAS-sharp.Backend/Common/PrefixSum.fs

@@ -6,7 +6,7 @@ open GraphBLAS.FSharp.Backend.Quotes
 open GraphBLAS.FSharp.Objects.ArraysExtensions
 open GraphBLAS.FSharp.Objects.ClCellExtensions
 
-module internal PrefixSum =
+module PrefixSum =
     let private update (opAdd: Expr<'a -> 'a -> 'a>) (clContext: ClContext) workGroupSize =
 
         let update =

src/GraphBLAS-sharp.Backend/Common/Scatter.fs

@@ -3,7 +3,7 @@ namespace GraphBLAS.FSharp.Backend.Common
 open Brahma.FSharp
 open GraphBLAS.FSharp.Backend.Quotes
 
-module internal Scatter =
+module Scatter =
     let private general<'a> predicate (clContext: ClContext) workGroupSize =
 
         let run =

src/GraphBLAS-sharp.Backend/Common/Sort/Bitonic.fs

@@ -3,7 +3,7 @@ namespace GraphBLAS.FSharp.Backend.Common.Sort
 open Brahma.FSharp
 open GraphBLAS.FSharp.Backend.Common
 
-module internal Bitonic =
+module Bitonic =
     let private localBegin (clContext: ClContext) workGroupSize =
 
         let processedSize = workGroupSize * 2

src/GraphBLAS-sharp.Backend/Common/Sum.fs

@@ -8,7 +8,7 @@ open GraphBLAS.FSharp.Objects.ClContextExtensions
 open GraphBLAS.FSharp.Objects.ArraysExtensions
 open GraphBLAS.FSharp.Objects.ClCellExtensions
 
-module internal Reduce =
+module Reduce =
     /// <summary>
     /// Generalized reduction pattern.
     /// </summary>

src/GraphBLAS-sharp.Backend/GraphBLAS-sharp.Backend.fsproj

@@ -27,8 +27,8 @@
     <Compile Include="Quotes/PreparePositions.fs" />
     <Compile Include="Quotes/Predicates.fs" />
     <Compile Include="Quotes/Map.fs" />
-
     <Compile Include="Quotes/Search.fs" />
+
     <Compile Include="Common/Scatter.fs" />
     <Compile Include="Common/Utils.fs" />
     <Compile Include="Common/PrefixSum.fs" />

src/GraphBLAS-sharp.Backend/Matrix/COO/Matrix.fs

@@ -10,10 +10,40 @@ open GraphBLAS.FSharp.Objects.ClCellExtensions
 open GraphBLAS.FSharp.Objects.ArraysExtensions
 
 module Matrix =
+    /// <summary>
+    /// Builds a new COO matrix whose elements are the results of applying the given function
+    /// to each of the elements of the matrix.
+    /// </summary>
+    /// <param name="op">
+    /// A function to transform values of the input matrix.
+    /// Operand and result types should be optional to distinguish explicit and implicit zeroes
+    /// </param>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let map = Map.run
 
+    /// <summary>
+    /// Builds a new COO matrix whose values are the results of applying the given function
+    /// to the corresponding pairs of values from the two matrices.
+    /// </summary>
+    /// <param name="op">
+    /// A function to transform pairs of values from the input matrices.
+    /// Operands and result types should be optional to distinguish explicit and implicit zeroes
+    /// </param>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let map2 = Map2.run
 
+    /// <summary>
+    /// Builds a new COO matrix whose values are the results of applying the given function
+    /// to the corresponding pairs of values from the two matrices.
+    /// </summary>
+    /// <param name="op">
+    /// A function to transform pairs of values from the input matrices.
+    /// Operation assumption: one of the operands should always be non-zero.
+    /// </param>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let rec map2AtLeastOne<'a, 'b, 'c when 'a: struct and 'b: struct and 'c: struct and 'c: equality>
         (clContext: ClContext)
         (opAdd: Expr<AtLeastOne<'a, 'b> -> 'c option>)
@@ -22,6 +52,11 @@ module Matrix =
 
         Map2.AtLeastOne.run clContext (Convert.atLeastOneToOption opAdd) workGroupSize
 
+    /// <summary>
+    /// Converts <c>COO</c> matrix format to <c>Tuple</c>.
+    /// </summary>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let getTuples (clContext: ClContext) workGroupSize =
 
         let copy = ClArray.copy clContext workGroupSize
@@ -44,6 +79,11 @@ module Matrix =
               ColumnIndices = resultColumns
               Values = resultValues }
 
+    /// <summary>
+    /// Converts rows of given COO matrix to rows in CSR format of the same matrix.
+    /// </summary>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let private compressRows (clContext: ClContext) workGroupSize =
 
         let compressRows =
@@ -81,6 +121,12 @@ module Matrix =
 
             rowPointers
 
+    /// <summary>
+    /// Converts the given COO matrix to CSR format.
+    /// Values and columns are copied and do not depend on input COO matrix anymore.
+    /// </summary>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let toCSR (clContext: ClContext) workGroupSize =
         let prepare = compressRows clContext workGroupSize
 
@@ -105,6 +151,12 @@ module Matrix =
               Columns = cols
               Values = values }
 
+    /// <summary>
+    /// Converts the given COO matrix to CSR format.
+    /// Values and columns are NOT copied and still depend on the input COO matrix.
+    /// </summary>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let toCSRInPlace (clContext: ClContext) workGroupSize =
         let prepare = compressRows clContext workGroupSize
 
@@ -121,10 +173,16 @@ module Matrix =
               Columns = matrix.Columns
               Values = matrix.Values }
 
+    /// <summary>
+    /// Transposes the given matrix and returns result.
+    /// The given matrix should neither be used afterwards nor be disposed.
+    /// </summary>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let transposeInPlace (clContext: ClContext) workGroupSize =
 
         let sort =
-            Common.Bitonic.sortKeyValuesInplace clContext workGroupSize
+            Common.Sort.Bitonic.sortKeyValuesInplace clContext workGroupSize
 
         fun (queue: MailboxProcessor<_>) (matrix: ClMatrix.COO<'a>) ->
             sort queue matrix.Columns matrix.Rows matrix.Values
@@ -136,6 +194,11 @@ module Matrix =
               Columns = matrix.Rows
               Values = matrix.Values }
 
+    /// <summary>
+    /// Transposes the given matrix and returns result as a new matrix.
+    /// </summary>
+    ///<param name="clContext">OpenCL context.</param>
+    ///<param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let transpose (clContext: ClContext) workGroupSize =
 
         let transposeInPlace = transposeInPlace clContext workGroupSize

src/GraphBLAS-sharp.Backend/Matrix/CSR/Map2.fs

@@ -205,7 +205,7 @@ module internal Map2 =
             =
 
             let merge =
-                GraphBLAS.FSharp.Backend.Matrix.CSR.Merge.run clContext workGroupSize
+                Merge.run clContext workGroupSize
 
             let preparePositions =
                 preparePositions opAdd clContext workGroupSize