add some kdocs

Author: devcrocod

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/CreateNDArray.kt

@@ -47,6 +47,9 @@ public fun <T, D : Dimension> Multik.empty(dims: IntArray, dtype: DataType): NDA
     return NDArray(data, shape = dims, dim = dim)
 }
 
+/**
+ * Returns a new zero array of type [T] with the specified shape.
+ */
 public inline fun <reified T : Any> Multik.zeros(dim1: Int): D1Array<T> =
     zeros(intArrayOf(dim1), DataType.ofKClass(T::class))
 
@@ -72,6 +75,9 @@ public fun <T, D : Dimension> Multik.zeros(dims: IntArray, dtype: DataType): NDA
     return NDArray(data, shape = dims, dim = dim)
 }
 
+/**
+ * Returns a new ones array of type [T] with the specified shape.
+ */
 public inline fun <reified T : Any> Multik.ones(dim1: Int): D1Array<T> =
     zeros(intArrayOf(dim1), DataType.ofKClass(T::class))
 
@@ -1518,21 +1524,39 @@ public fun <T : Number> Iterable<T>.toNDArray(): D1Array<T> = this.toCommonNDArr
 @JvmName("toComplexNDArray")
 public fun <T : Complex> Iterable<T>.toNDArray(): D1Array<T> = this.toCommonNDArray()
 
+/**
+ * Returns [D2Array] containing all elements.
+ */
 @JvmName("List2DToNDArrayNumber")
 public inline fun <reified T : Number> List<List<T>>.toNDArray(): D2Array<T> = Multik.ndarray(this)
 
+/**
+ * Returns [D2Array] containing all elements.
+ */
 @JvmName("List2DToNDArrayComplex")
 public inline fun <reified T : Complex> List<List<T>>.toNDArray(): D2Array<T> = Multik.ndarray(this)
 
+/**
+ * Returns [D3Array] containing all elements.
+ */
 @JvmName("List3DToNDArrayNumber")
 public inline fun <reified T : Number> List<List<List<T>>>.toNDArray(): D3Array<T> = Multik.ndarray(this)
 
+/**
+ * Returns [D3Array] containing all elements.
+ */
 @JvmName("List3DToNDArrayComplex")
 public inline fun <reified T : Complex> List<List<List<T>>>.toNDArray(): D3Array<T> = Multik.ndarray(this)
 
+/**
+ * Returns [D4Array] containing all elements.
+ */
 @JvmName("List4DToNDArrayNumber")
 public inline fun <reified T : Number> List<List<List<List<T>>>>.toNDArray(): D4Array<T> = Multik.ndarray(this)
 
+/**
+ * Returns [D4Array] containing all elements.
+ */
 @JvmName("List4DToNDArrayComplex")
 public inline fun <reified T : Complex> List<List<List<List<T>>>>.toNDArray(): D4Array<T> = Multik.ndarray(this)
 

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/io/csv.kt

@@ -14,10 +14,27 @@ import java.io.*
 import java.nio.charset.Charset
 import java.util.zip.GZIPInputStream
 
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param fileName file path including file name and extensions
+ * @param delimiter separator between elements
+ * @param charset character encoding, by default is UTF_8
+ */
 public inline fun <reified T : Any, reified D : Dim2> Multik.read(
     fileName: String, delimiter: Char = ',', charset: Charset = Charsets.UTF_8
 ): NDArray<T, D> = read(fileName, DataType.ofKClass(T::class), dimensionClassOf<D>(), delimiter, charset)
 
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param fileName file path including file name and extensions
+ * @param dtype NDArray element type
+ * @param delimiter separator between elements
+ * @param charset character encoding, by default is UTF_8
+ */
 public fun <T, D : Dim2> Multik.read(
     fileName: String, dtype: DataType, dim: Dim2,
     delimiter: Char = ',', charset: Charset = Charsets.UTF_8
@@ -27,6 +44,14 @@ public fun <T, D : Dim2> Multik.read(
     return read(file, dtype, dim, delimiter, charset)
 }
 
+/**
+ * Returns a raw array of dimension 2. The type casts to either [Double] or [ComplexDouble].
+ * @param fileName file path including file name and extensions
+ * @param dtype NDArray element type
+ * @param dim dimension of NDArray
+ * @param delimiter separator between elements
+ * @param charset character encoding, by default is UTF_8
+ */
 public fun Multik.readRaw(
     fileName: String, dtype: DataType? = null, dim: Dim2? = null,
     delimiter: Char = ',', charset: Charset = Charsets.UTF_8
@@ -36,23 +61,57 @@ public fun Multik.readRaw(
     return readRaw(file, dtype, dim, delimiter, charset)
 }
 
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param file csv file
+ * @param delimiter separator between elements
+ * @param charset character encoding, by default is UTF_8
+ */
 public inline fun <reified T : Any, reified D : Dim2> Multik.read(
     file: File, delimiter: Char = ',', charset: Charset = Charsets.UTF_8
 ): NDArray<T, D> = read(file, DataType.ofKClass(T::class), dimensionClassOf<D>(), delimiter, charset)
 
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param dtype NDArray element type
+ * @param file csv file
+ * @param delimiter separator between elements
+ * @param charset character encoding, by default is UTF_8
+ */
 public fun <T, D : Dim2> Multik.read(
     file: File, dtype: DataType, dim: Dim2,
     delimiter: Char = ',', charset: Charset = Charsets.UTF_8
 ): NDArray<T, D> =
     readDelim(FileInputStream(file), dtype, dim, delimiter, charset, isCompressed(file))
 
+/**
+ * Returns a raw array of dimension 2. The type casts to either [Double] or [ComplexDouble].
+ * @param file csv file
+ * @param dtype NDArray element type
+ * @param dim dimension of NDArray
+ * @param delimiter separator between elements
+ * @param charset character encoding, by default is UTF_8
+ */
 public fun Multik.readRaw(
     file: File, dtype: DataType? = null, dim: Dim2? = null,
     delimiter: Char = ',', charset: Charset = Charsets.UTF_8
 ): NDArray<*, D2> =
     readDelim<Any, D2>(FileInputStream(file), dtype, dim, delimiter, charset, isCompressed(file))
 
-
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param inStream data input stream from file
+ * @param dtype NDArray element type
+ * @param dim dimension of NDArray
+ * @param delimiter separator between elements
+ * @param isCompressed shows whether the data is compressed, by default is false
+ */
 public fun <T, D : Dim2> Multik.readDelim(
     inStream: InputStream, dtype: DataType?, dim: Dim2?,
     delimiter: Char = ',', charset: Charset, isCompressed: Boolean = false
@@ -65,6 +124,15 @@ public fun <T, D : Dim2> Multik.readDelim(
         readDelim(this, CSVFormat.Builder.create(CSVFormat.DEFAULT).setDelimiter(delimiter).build(), dtype, dim)
     }
 
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param reader reading character-input streams
+ * @param format csv format from apache
+ * @param dtype NDArray element type
+ * @param dim dimension of NDArray
+ */
 public fun <T, D : Dim2> Multik.readDelim(
     reader: Reader, format: CSVFormat = CSVFormat.DEFAULT,
     dtype: DataType?, dim: Dim2?
@@ -134,12 +202,34 @@ private fun String.toComplexFloat(): ComplexFloat {
 
 private fun isCompressed(file: File) = listOf("gz", "zip").contains(file.extension)
 
+/**
+ * Writes an NDArray to csv file. The NDArray must be up to the second dimension.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param file file where the data will be written, if the file does not exist, it will be created
+ * @param delimiter separator between elements
+ */
 public fun <T, D : Dim2> Multik.write(file: File, ndarray: NDArray<T, D>, delimiter: Char = ','): Unit =
     writeCSV(FileWriter(file), ndarray, CSVFormat.Builder.create(CSVFormat.DEFAULT).setDelimiter(delimiter).build())
 
+/**
+ * Writes an NDArray to csv file. The NDArray must be up to the second dimension.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param path file path where the data will be written
+ * @param delimiter separator between elements
+ */
 public fun <T, D : Dim2> Multik.write(path: String, ndarray: NDArray<T, D>, delimiter: Char = ','): Unit =
     writeCSV(FileWriter(path), ndarray, CSVFormat.Builder.create(CSVFormat.DEFAULT).setDelimiter(delimiter).build())
 
+/**
+ * Returns an NDArray of type [T] and [D] dimension read from csv file.
+ * @param T NDArray element type
+ * @param D dimension of NDArray. It can be 1 or 2
+ * @param writer
+ * @param ndarray array of data
+ * @param format csv format from apache
+ */
 public fun <T, D : Dim2> Multik.writeCSV(
     writer: Appendable,
     ndarray: NDArray<T, D>,

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/LinAlgEx.kt

@@ -9,6 +9,9 @@ import org.jetbrains.kotlinx.multik.ndarray.complex.ComplexDouble
 import org.jetbrains.kotlinx.multik.ndarray.complex.ComplexFloat
 import org.jetbrains.kotlinx.multik.ndarray.data.*
 
+/**
+ * Extension interface for [LinAlg] for improved type support.
+ */
 public interface LinAlgEx {
     public fun <T : Number> inv(mat: MultiArray<T, D2>): NDArray<Double, D2>
     public fun invF(mat: MultiArray<Float, D2>): NDArray<Float, D2>

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/dot.kt

@@ -11,28 +11,37 @@ import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 import org.jetbrains.kotlinx.multik.ndarray.data.NDArray
 
 /**
- * Dot products of two arrays. Matrix product.
+ * Dot products of two number matrices.
  */
 @JvmName("dotMMNumber")
 public fun <T : Number> LinAlg.dot(a: MultiArray<T, D2>, b: MultiArray<T, D2>): NDArray<T, D2> = this.linAlgEx.dotMM(a, b)
 
+/**
+ * Dot products of two complex matrices.
+ */
 @JvmName("dotMMComplex")
 public fun <T : Complex> LinAlg.dot(a: MultiArray<T, D2>, b: MultiArray<T, D2>): NDArray<T, D2> = this.linAlgEx.dotMMComplex(a, b)
 
 /**
- * Dot products of two arrays. Matrix product.
+ * Dot products of number matrix and number vector.
  */
 @JvmName("dotMVNumber")
 public fun <T : Number> LinAlg.dot(a: MultiArray<T, D2>, b: MultiArray<T, D1>): NDArray<T, D1> = this.linAlgEx.dotMV(a, b)
 
+/**
+ * Dot products of complex matrix and complex vector.
+ */
 @JvmName("dotMVComplex")
 public fun <T : Complex> LinAlg.dot(a: MultiArray<T, D2>, b: MultiArray<T, D1>): NDArray<T, D1> = this.linAlgEx.dotMVComplex(a, b)
 
 /**
- * Dot products of two one-dimensional arrays. Scalar product.
+ * Dot products of two number vectors. Scalar product.
  */
 @JvmName("dotVVNumber")
 public fun <T : Number> LinAlg.dot(a: MultiArray<T, D1>, b: MultiArray<T, D1>): T = this.linAlgEx.dotVV(a, b)
 
+/**
+ * Dot products of two complex vectors. Scalar product.
+ */
 @JvmName("dotVVComplex")
 public fun <T : Complex> LinAlg.dot(a: MultiArray<T, D1>, b: MultiArray<T, D1>): T = this.linAlgEx.dotVVComplex(a, b)

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/eigvals.kt

@@ -12,23 +12,47 @@ import org.jetbrains.kotlinx.multik.ndarray.data.D2
 import org.jetbrains.kotlinx.multik.ndarray.data.D2Array
 import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 
+/**
+ * Calculates the eigenvalues and eigenvectors of a float matrix
+ * @return a pair of a vector of eigenvalues and a matrix of eigenvectors
+ */
 @JvmName("eigF")
 public fun LinAlg.eig(mat: MultiArray<Float, D2>): Pair<D1Array<ComplexFloat>, D2Array<ComplexFloat>> =
     this.linAlgEx.eigF(mat)
 
+/**
+ * Calculates the eigenvalues and eigenvectors of a numeric matrix
+ * @return a pair of a vector of eigenvalues and a matrix of eigenvectors
+ */
 @JvmName("eig")
 public fun <T : Number> LinAlg.eig(mat: MultiArray<T, D2>): Pair<D1Array<ComplexDouble>, D2Array<ComplexDouble>> =
     this.linAlgEx.eig(mat)
 
+/**
+ * Calculates the eigenvalues and eigenvectors of a complex matrix
+ * @return a pair of a vector of eigenvalues and a matrix of eigenvectors
+ */
 @JvmName("eigC")
 public fun <T : Complex> LinAlg.eig(mat: MultiArray<T, D2>): Pair<D1Array<T>, D2Array<T>> =
     this.linAlgEx.eigC(mat)
 
+/**
+ * Calculates the eigenvalues of a float matrix
+ * @return [ComplexFloat] vector
+ */
 @JvmName("eigValsF")
 public fun LinAlg.eigVals(mat: MultiArray<Float, D2>): D1Array<ComplexFloat> = this.linAlgEx.eigValsF(mat)
 
+/**
+ * Calculates the eigenvalues of a numeric matrix.
+ * @return [ComplexDouble] vector
+ */
 @JvmName("eigVals")
 public fun <T : Number> LinAlg.eigVals(mat: MultiArray<T, D2>): D1Array<ComplexDouble> = this.linAlgEx.eigVals(mat)
 
+/**
+ * Calculates the eigenvalues of a float matrix
+ * @return complex vector
+ */
 @JvmName("eigValsC")
 public fun <T : Complex> LinAlg.eigVals(mat: MultiArray<T, D2>): D1Array<T> = this.linAlgEx.eigValsC(mat)

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/inverse.kt

@@ -9,11 +9,20 @@ import org.jetbrains.kotlinx.multik.ndarray.data.D2
 import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 import org.jetbrains.kotlinx.multik.ndarray.data.NDArray
 
+/**
+ * Returns inverse float matrix
+ */
 @JvmName("invF")
 public fun LinAlg.inv(mat: MultiArray<Float, D2>): NDArray<Float, D2> = this.linAlgEx.invF(mat)
 
+/**
+ * Returns inverse of a double matrix from numeric matrix
+ */
 @JvmName("invD")
 public fun <T : Number> LinAlg.inv(mat: MultiArray<T, D2>): NDArray<Double, D2> = this.linAlgEx.inv(mat)
 
+/**
+ * Returns inverse complex matrix
+ */
 @JvmName("invC")
 public fun <T : Complex> LinAlg.inv(mat: MultiArray<T, D2>): NDArray<T, D2> = this.linAlgEx.invC(mat)

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/plu.kt

@@ -9,11 +9,20 @@ import org.jetbrains.kotlinx.multik.ndarray.data.D2
 import org.jetbrains.kotlinx.multik.ndarray.data.D2Array
 import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 
+/**
+ * Returns PLU decomposition of the float matrix
+ */
 @JvmName("pluF")
 public fun LinAlg.plu(mat: MultiArray<Float, D2>): Triple<D2Array<Float>, D2Array<Float>, D2Array<Float>> = this.linAlgEx.pluF(mat)
 
+/**
+ * Returns PLU decomposition of the numeric matrix
+ */
 @JvmName("pluD")
 public fun <T : Number> LinAlg.plu(mat: MultiArray<T, D2>): Triple<D2Array<Double>, D2Array<Double>, D2Array<Double>> = this.linAlgEx.plu(mat)
 
+/**
+ * Returns PLU decomposition of the complex matrix
+ */
 @JvmName("pluC")
 public fun <T : Complex> LinAlg.plu(mat: MultiArray<T, D2>): Triple<D2Array<T>, D2Array<T>, D2Array<T>> = this.linAlgEx.pluC(mat)

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/qr.kt

@@ -9,11 +9,20 @@ import org.jetbrains.kotlinx.multik.ndarray.data.D2
 import org.jetbrains.kotlinx.multik.ndarray.data.D2Array
 import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 
+/**
+ * Returns QR decomposition of the float matrix
+ */
 @JvmName("qrF")
 public fun LinAlg.qr(mat: MultiArray<Float, D2>): Pair<D2Array<Float>, D2Array<Float>> = this.linAlgEx.qrF(mat)
 
+/**
+ * Returns QR decomposition of the numeric matrix
+ */
 @JvmName("qrD")
 public fun <T : Number> LinAlg.qr(mat: MultiArray<T, D2>): Pair<D2Array<Double>, D2Array<Double>> = this.linAlgEx.qr(mat)
 
+/**
+ * Returns QR decomposition of the complex matrix
+ */
 @JvmName("qrC")
 public fun <T : Complex> LinAlg.qr(mat: MultiArray<T, D2>): Pair<D2Array<T>, D2Array<T>> = this.linAlgEx.qrC(mat)

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/linalg/solve.kt

@@ -10,6 +10,9 @@ import org.jetbrains.kotlinx.multik.ndarray.data.Dim2
 import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 import org.jetbrains.kotlinx.multik.ndarray.data.NDArray
 
+/**
+ * Returns the solution to a system of linear equations
+ */
 @JvmName("solveF")
 public fun <D : Dim2> LinAlg.solve(a: MultiArray<Float, D2>, b: MultiArray<Float, D>): NDArray<Float, D> = this.linAlgEx.solveF(a, b)
 

multik-api/src/main/kotlin/org/jetbrains/kotlinx/multik/api/math/MathEx.kt

@@ -10,6 +10,9 @@ import org.jetbrains.kotlinx.multik.ndarray.data.Dimension
 import org.jetbrains.kotlinx.multik.ndarray.data.MultiArray
 import org.jetbrains.kotlinx.multik.ndarray.data.NDArray
 
+/**
+ * Extension interface for [Math] for improved type support.
+ */
 public interface MathEx {
     public fun <T : Number, D : Dimension> exp(a: MultiArray<T, D>): NDArray<Double, D>
     public fun <D : Dimension> expF(a: MultiArray<Float, D>): NDArray<Float, D>