Add transposeConjugate function for Complex and Double (conjugate values are not cached). Minor refactoring of MatrixContext and API reference changes

kmath-core/src/commonMain/kotlin/kscience/kmath/linear/FeaturedMatrix.kt

@@ -1,6 +1,8 @@
 package kscience.kmath.linear
 
+import kscience.kmath.operations.Complex
 import kscience.kmath.operations.Ring
+import kscience.kmath.operations.conjugate
 import kscience.kmath.structures.Matrix
 import kscience.kmath.structures.Structure2D
 import kscience.kmath.structures.asBuffer
@@ -70,7 +72,7 @@ public fun <T : Any, R : Ring<T>> GenericMatrixContext<T, R, *>.one(rows: Int, c
 
 
 /**
- * A virtual matrix of zeroes
+ * Returns virtual matrix of zeroes.
  */
 public fun <T : Any, R : Ring<T>> GenericMatrixContext<T, R, *>.zero(rows: Int, columns: Int): FeaturedMatrix<T> =
     VirtualMatrix(rows, columns) { _, _ -> elementContext.zero }
@@ -78,12 +80,27 @@ public fun <T : Any, R : Ring<T>> GenericMatrixContext<T, R, *>.zero(rows: Int,
 public class TransposedFeature<T : Any>(public val original: Matrix<T>) : MatrixFeature
 
 /**
- * Create a virtual transposed matrix without copying anything. `A.transpose().transpose() === A`
+ * Create a virtual transposed matrix without copying anything. `A.transpose().transpose() === A`.
  */
-public fun <T : Any> Matrix<T>.transpose(): Matrix<T> {
-    return getFeature<TransposedFeature<T>>()?.original ?: VirtualMatrix(
-        colNum,
-        rowNum,
-        setOf(TransposedFeature(this))
-    ) { i, j -> get(j, i) }
-}
+public fun <T : Any> Matrix<T>.transpose(): Matrix<T> = getFeature<TransposedFeature<T>>()?.original ?: VirtualMatrix(
+    colNum,
+    rowNum,
+    setOf(TransposedFeature(this)),
+) { i, j -> get(j, i) }
+
+/**
+ * Returns Hermitian conjugate of this matrix (i.e., just transposes it).
+ *
+ *
+ */
+public fun Matrix<Double>.transposeConjugate(): Matrix<Double> = transpose()
+
+/**
+ * Returns Hermitian conjugate of this matrix (i.e., transposes it and replaces each element with its conjugate).
+ *
+ * @return the Hermitian conjugate of this matrix.
+ */
+public fun Matrix<Complex>.transposeConjugate(): Matrix<Complex> {
+    val t = transpose()
+    return VirtualMatrix(t.rowNum, t.colNum) { i, j -> t[i,j].conjugate }
+}

kmath-core/src/commonMain/kotlin/kscience/kmath/linear/MatrixContext.kt

@@ -10,7 +10,10 @@ import kscience.kmath.structures.Matrix
 import kscience.kmath.structures.asSequence
 
 /**
- * Basic operations on matrices. Operates on [Matrix]
+ * Basic operations on matrices. Operates on [Matrix].
+ *
+ * @param T the type of items in the matrices.
+ * @param M the type of operated matrices.
  */
 public interface MatrixContext<T : Any, out M : Matrix<T>> : SpaceOperations<Matrix<T>> {
     /**
@@ -84,9 +87,16 @@ public interface MatrixContext<T : Any, out M : Matrix<T>> : SpaceOperations<Mat
     }
 }
 
+/**
+ * Partial implementation of [MatrixContext] for matrices of [Ring].
+ *
+ * @param T the type of items in the matrices.
+ * @param R the type of ring of matrix elements.
+ * @param M the type of operated matrices.
+ */
 public interface GenericMatrixContext<T : Any, R : Ring<T>, out M : Matrix<T>> : MatrixContext<T, M> {
     /**
-     * The ring context for matrix elements
+     * The ring over matrix elements.
      */
     public val elementContext: R
 
@@ -133,8 +143,6 @@ public interface GenericMatrixContext<T : Any, R : Ring<T>, out M : Matrix<T>> :
     public override fun multiply(a: Matrix<T>, k: Number): M =
         produce(a.rowNum, a.colNum) { i, j -> elementContext { a[i, j] * k } }
 
-    public operator fun Number.times(matrix: FeaturedMatrix<T>): M = multiply(matrix, this)
-
     public override operator fun Matrix<T>.times(value: T): M =
         produce(rowNum, colNum) { i, j -> elementContext { get(i, j) * value } }
 }

kmath-core/src/commonMain/kotlin/kscience/kmath/linear/VirtualMatrix.kt

@@ -2,17 +2,22 @@ package kscience.kmath.linear
 
 import kscience.kmath.structures.Matrix
 
+/**
+ * The matrix where each element is evaluated each time when is being accessed.
+ *
+ * @property generator the function that provides elements.
+ */
 public class VirtualMatrix<T : Any>(
     override val rowNum: Int,
     override val colNum: Int,
     override val features: Set<MatrixFeature> = emptySet(),
-    public val generator: (i: Int, j: Int) -> T
+    public val generator: (i: Int, j: Int) -> T,
 ) : FeaturedMatrix<T> {
     public constructor(
         rowNum: Int,
         colNum: Int,
         vararg features: MatrixFeature,
-        generator: (i: Int, j: Int) -> T
+        generator: (i: Int, j: Int) -> T,
     ) : this(
         rowNum,
         colNum,

kmath-core/src/commonMain/kotlin/kscience/kmath/structures/Structure2D.kt

@@ -72,6 +72,6 @@ else
 /**
  * Alias for [Structure2D] with more familiar name.
  *
- * @param T the type of items.
+ * @param T the type of items in the matrix.
  */
 public typealias Matrix<T> = Structure2D<T>