kmath-tensors/README.md

@@ -1,12 +1,15 @@
 # Module kmath-tensors
 
-Common linear algebra operations on tensors.
-
- - [tensor algebra](src/commonMain/kotlin/space/kscience/kmath/tensors/api/TensorAlgebra.kt) : Basic linear algebra operations on tensors (plus, dot, etc.)
- - [tensor algebra with broadcasting](src/commonMain/kotlin/space/kscience/kmath/tensors/core/algebras/BroadcastDoubleTensorAlgebra.kt) : Basic linear algebra operations implemented with broadcasting.
- - [linear algebra operations](src/commonMain/kotlin/space/kscience/kmath/tensors/api/LinearOpsTensorAlgebra.kt) : Advanced linear algebra operations like LU decomposition, SVD, etc.
+Common operations on tensors, the API consists of:
 
+ - [TensorAlgebra](src/commonMain/kotlin/space/kscience/kmath/tensors/api/TensorAlgebra.kt) : Basic algebra operations on tensors (plus, dot, etc.)
+ - [TensorPartialDivisionAlgebra](src/commonMain/kotlin/space/kscience/kmath/tensors/api/TensorPartialDivisionAlgebra.kt) : Emulates an algebra over a field
+ - [LinearOpsTensorAlgebra](src/commonMain/kotlin/space/kscience/kmath/tensors/api/LinearOpsTensorAlgebra.kt) : Linear algebra operations including LU, QR, Cholesky LL and SVD decompositions
+ - [AnalyticTensorAlgebra](src/commonMain/kotlin/space/kscience/kmath/tensors/api/AnalyticTensorAlgebra.kt) : Element-wise analytic operations
 
+The library offers a multiplatform implementation for this interface over the `Double`'s. As the highlight, the user can find:
+ - [BroadcastDoubleTensorAlgebra](src/commonMain/kotlin/space/kscience/kmath/tensors/core/algebras/BroadcastDoubleTensorAlgebra.kt) : Basic algebra operations implemented with broadcasting.
+ - [DoubleLinearOpsTensorAlgebra](src/commonMain/kotlin/space/kscience/kmath/tensors/core/algebras/DoubleLinearOpsTensorAlgebra.kt) : Includes the power method for SVD and the spectrum of symmetric matrices.
 ## Artifact:
 
 The Maven coordinates of this project are `space.kscience:kmath-tensors:0.3.0-dev-7`.

kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/api/AnalyticTensorAlgebra.kt

@@ -5,59 +5,63 @@
 
 package space.kscience.kmath.tensors.api
 
-
+/**
+ * Element-wise analytic operations on [TensorStructure].
+ *
+ * @param T the type of items closed under analytic functions in the tensors.
+ */
 public interface AnalyticTensorAlgebra<T> :
     TensorPartialDivisionAlgebra<T> {
 
-    //https://pytorch.org/docs/stable/generated/torch.exp.html
+    //For information: https://pytorch.org/docs/stable/generated/torch.exp.html
     public fun TensorStructure<T>.exp(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.log.html
+    //For information: https://pytorch.org/docs/stable/generated/torch.log.html
     public fun TensorStructure<T>.log(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.sqrt.html
+    //For information: https://pytorch.org/docs/stable/generated/torch.sqrt.html
     public fun TensorStructure<T>.sqrt(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.acos.html#torch.cos
+    //For information: https://pytorch.org/docs/stable/generated/torch.acos.html#torch.cos
     public fun TensorStructure<T>.cos(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.acos.html#torch.acos
+    //For information: https://pytorch.org/docs/stable/generated/torch.acos.html#torch.acos
     public fun TensorStructure<T>.acos(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.acosh.html#torch.cosh
+    //For information: https://pytorch.org/docs/stable/generated/torch.acosh.html#torch.cosh
     public fun TensorStructure<T>.cosh(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.acosh.html#torch.acosh
+    //For information: https://pytorch.org/docs/stable/generated/torch.acosh.html#torch.acosh
     public fun TensorStructure<T>.acosh(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.asin.html#torch.sin
+    //For information: https://pytorch.org/docs/stable/generated/torch.asin.html#torch.sin
     public fun TensorStructure<T>.sin(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.asin.html#torch.asin
+    //For information: https://pytorch.org/docs/stable/generated/torch.asin.html#torch.asin
     public fun TensorStructure<T>.asin(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.asin.html#torch.sinh
+    //For information: https://pytorch.org/docs/stable/generated/torch.asin.html#torch.sinh
     public fun TensorStructure<T>.sinh(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.asin.html#torch.asinh
+    //For information: https://pytorch.org/docs/stable/generated/torch.asin.html#torch.asinh
     public fun TensorStructure<T>.asinh(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.atan.html#torch.tan
+    //For information: https://pytorch.org/docs/stable/generated/torch.atan.html#torch.tan
     public fun TensorStructure<T>.tan(): TensorStructure<T>
 
     //https://pytorch.org/docs/stable/generated/torch.atan.html#torch.atan
     public fun TensorStructure<T>.atan(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.atanh.html#torch.tanh
+    //For information: https://pytorch.org/docs/stable/generated/torch.atanh.html#torch.tanh
     public fun TensorStructure<T>.tanh(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.atanh.html#torch.atanh
+    //For information: https://pytorch.org/docs/stable/generated/torch.atanh.html#torch.atanh
     public fun TensorStructure<T>.atanh(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.ceil.html#torch.ceil
+    //For information: https://pytorch.org/docs/stable/generated/torch.ceil.html#torch.ceil
     public fun TensorStructure<T>.ceil(): TensorStructure<T>
 
-    //https://pytorch.org/docs/stable/generated/torch.floor.html#torch.floor
+    //For information: https://pytorch.org/docs/stable/generated/torch.floor.html#torch.floor
     public fun TensorStructure<T>.floor(): TensorStructure<T>
 
 }

kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/api/LinearOpsTensorAlgebra.kt

@@ -8,7 +8,7 @@ package space.kscience.kmath.tensors.api
 /**
  * Common linear algebra operations. Operates on [TensorStructure].
  *
- * @param T the type of items in the tensors.
+ * @param T the type of items closed under division in the tensors.
  */
 public interface LinearOpsTensorAlgebra<T> :
     TensorPartialDivisionAlgebra<T> {

kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/api/TensorAlgebra.kt

@@ -6,7 +6,7 @@
 package space.kscience.kmath.tensors.api
 
 /**
- * Basic linear algebra operations on [TensorStructure].
+ * Algebra over a ring on [TensorStructure].
  * For more information: https://proofwiki.org/wiki/Definition:Algebra_over_Ring
  *
  * @param T the type of items in the tensors.

kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/api/TensorPartialDivisionAlgebra.kt

@@ -5,12 +5,52 @@
 
 package space.kscience.kmath.tensors.api
 
-// https://proofwiki.org/wiki/Definition:Division_Algebra
+/**
+ * Algebra over a field with partial division on [TensorStructure].
+ * For more information: https://proofwiki.org/wiki/Definition:Division_Algebra
+ *
+ * @param T the type of items closed under division in the tensors.
+ */
 public interface TensorPartialDivisionAlgebra<T> :
     TensorAlgebra<T> {
+
+    /**
+     * Each element of the tensor [other] is divided by this value.
+     * The resulting tensor is returned.
+     *
+     * @param other tensor to divide by.
+     * @return the division of this value by the tensor [other].
+     */
     public operator fun T.div(other: TensorStructure<T>): TensorStructure<T>
+
+    /**
+     * Divide by the scalar [value] each element of this tensor returns a new resulting tensor.
+     *
+     * @param value the number to divide by each element of this tensor.
+     * @return the division of this tensor by the [value].
+     */
     public operator fun TensorStructure<T>.div(value: T): TensorStructure<T>
+
+    /**
+     * Each element of the tensor [other] is divided by each element of this tensor.
+     * The resulting tensor is returned.
+     *
+     * @param other tensor to be divided by.
+     * @return the division of this tensor by [other].
+     */
     public operator fun TensorStructure<T>.div(other: TensorStructure<T>): TensorStructure<T>
+
+    /**
+     * Divides by the scalar [value] each element of this tensor.
+     *
+     * @param value the number to divide by each element of this tensor.
+     */
     public operator fun TensorStructure<T>.divAssign(value: T)
+
+    /**
+     * Each element of this tensor is divided by each element of the [other] tensor.
+     *
+     * @param other tensor to be divide by.
+     */
     public operator fun TensorStructure<T>.divAssign(other: TensorStructure<T>)
 }