commonMain.space.kscience.kmath.linear.MatrixFeatures.kt Maven / Gradle / Ivy

Go to download
package space.kscience.kmath.linear

/**
 * A marker interface representing some properties of matrices or additional transformations of them. Features are used
 * to optimize matrix operations performance in some cases or retrieve the APIs.
 */
public interface MatrixFeature

/**
 * Matrices with this feature are considered to have only diagonal non-null elements.
 */
public interface DiagonalFeature : MatrixFeature {
    public companion object : DiagonalFeature
}

/**
 * Matrices with this feature have all zero elements.
 */
public object ZeroFeature : DiagonalFeature

/**
 * Matrices with this feature have unit elements on diagonal and zero elements in all other places.
 */
public object UnitFeature : DiagonalFeature

/**
 * Matrices with this feature can be inverted: [inverse] = `a`^-1 where `a` is the owning matrix.
 *
 * @param T the type of matrices' items.
 */
public interface InverseMatrixFeature : MatrixFeature {
    /**
     * The inverse matrix of the matrix that owns this feature.
     */
    public val inverse: Matrix
}

/**
 * Matrices with this feature can compute their determinant.
 *
 * @param T the type of matrices' items.
 */
public interface DeterminantFeature : MatrixFeature {
    /**
     * The determinant of the matrix that owns this feature.
     */
    public val determinant: T
}

/**
 * Produces a [DeterminantFeature] where the [DeterminantFeature.determinant] is [determinant].
 *
 * @param determinant the value of determinant.
 * @return a new [DeterminantFeature].
 */
@Suppress("FunctionName")
public fun  DeterminantFeature(determinant: T): DeterminantFeature = object : DeterminantFeature {
    override val determinant: T = determinant
}

/**
 * Matrices with this feature are lower triangular ones.
 */
public object LFeature : MatrixFeature

/**
 * Matrices with this feature are upper triangular ones.
 */
public object UFeature : MatrixFeature

/**
 * Matrices with this feature support LU factorization with partial pivoting: *[p] · a = [l] · [u]* where
 * *a* is the owning matrix.
 *
 * @param T the type of matrices' items.
 */
public interface LupDecompositionFeature : MatrixFeature {
    /**
     * The lower triangular matrix in this decomposition. It may have [LFeature].
     */
    public val l: Matrix

    /**
     * The upper triangular matrix in this decomposition. It may have [UFeature].
     */
    public val u: Matrix

    /**
     * The permutation matrix in this decomposition.
     */
    public val p: Matrix
}

/**
 * Matrices with this feature are orthogonal ones: *a · a^T = u* where *a* is the owning matrix, *u*
 * is the unit matrix ([UnitFeature]).
 */
public object OrthogonalFeature : MatrixFeature

/**
 * Matrices with this feature support QR factorization: *a = [q] · [r]* where *a* is the owning matrix.
 *
 * @param T the type of matrices' items.
 */
public interface QRDecompositionFeature : MatrixFeature {
    /**
     * The orthogonal matrix in this decomposition. It may have [OrthogonalFeature].
     */
    public val q: Matrix

    /**
     * The upper triangular matrix in this decomposition. It may have [UFeature].
     */
    public val r: Matrix
}

/**
 * Matrices with this feature support Cholesky factorization: *a = [l] · [l]^H* where *a* is the
 * owning matrix.
 *
 * @param T the type of matrices' items.
 */
public interface CholeskyDecompositionFeature : MatrixFeature {
    /**
     * The triangular matrix in this decomposition. It may have either [UFeature] or [LFeature].
     */
    public val l: Matrix
}

/**
 * Matrices with this feature support SVD: *a = [u] · [s] · [v]^H* where *a* is the owning
 * matrix.
 *
 * @param T the type of matrices' items.
 */
public interface SingularValueDecompositionFeature : MatrixFeature {
    /**
     * The matrix in this decomposition. It is unitary, and it consists from left singular vectors.
     */
    public val u: Matrix

    /**
     * The matrix in this decomposition. Its main diagonal elements are singular values.
     */
    public val s: Matrix

    /**
     * The matrix in this decomposition. It is unitary, and it consists from right singular vectors.
     */
    public val v: Matrix

    /**
     * The buffer of singular values of this SVD.
     */
    public val singularValues: Point
}

//TODO add sparse matrix feature