From 6375cb5fd8cd0e50d6f236707e5f5818e104de64 Mon Sep 17 00:00:00 2001 From: Iaroslav Postovalov Date: Wed, 17 Mar 2021 23:11:26 +0700 Subject: [PATCH] Some adjustments to the EJML module --- README.md | 12 ++-- kmath-ast/README.md | 2 +- kmath-core/README.md | 4 +- kmath-ejml/README.md | 43 ++++++++++++++ kmath-ejml/build.gradle.kts | 29 ++++++++-- kmath-ejml/docs/README-TEMPLATE.md | 7 +++ .../kscience/kmath/ejml/EjmlLinearSpace.kt | 56 ++++++++++++------- .../space/kscience/kmath/ejml/EjmlMatrix.kt | 2 +- .../space/kscience/kmath/ejml/EjmlVector.kt | 2 +- 9 files changed, 122 insertions(+), 35 deletions(-) create mode 100644 kmath-ejml/README.md create mode 100644 kmath-ejml/docs/README-TEMPLATE.md diff --git a/README.md b/README.md index 2aaeb3150..cc9439d27 100644 --- a/README.md +++ b/README.md @@ -120,10 +120,10 @@ KMath is a modular library. Different modules provide different features with di > > **Features:** > - [algebras](kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Algebraic structures like rings, spaces and fields. -> - [nd](kmath-core/src/commonMain/kotlin/space/kscience/kmath/nd/StructureND.kt) : Many-dimensional structures and operations on them. +> - [nd](kmath-core/src/commonMain/kotlin/space/kscience/kmath/structures/StructureND.kt) : Many-dimensional structures and operations on them. > - [linear](kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Basic linear algebra operations (sums, products, etc.), backed by the `Space` API. Advanced linear algebra operations like matrix inversion and LU decomposition. -> - [buffers](kmath-core/src/commonMain/kotlin/space/kscience/kmath/structures/Buffer.kt) : One-dimensional structure -> - [expressions](kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions) : By writing a single mathematical expression once, users will be able to apply different types of +> - [buffers](kmath-core/src/commonMain/kotlin/space/kscience/kmath/structures/Buffers.kt) : One-dimensional structure +> - [expressions](kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions) : By writing a single mathematical expression once, users will be able to apply different types of objects to the expression by providing a context. Expressions can be used for a wide variety of purposes from high performance calculations to code generation. > - [domains](kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains) : Domains @@ -206,9 +206,9 @@ One can still use generic algebras though. > **Maturity**: EXPERIMENTAL > > **Features:** -> - [nd4jarraystructure](kmath-nd4j/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : NDStructure wrapper for INDArray -> - [nd4jarrayrings](kmath-nd4j/src/commonMain/kotlin/space/kscience/kmath/structures/NDStructure.kt) : Rings over Nd4jArrayStructure of Int and Long -> - [nd4jarrayfields](kmath-nd4j/src/commonMain/kotlin/space/kscience/kmath/structures/Buffers.kt) : Fields over Nd4jArrayStructure of Float and Double +> - [nd4jarraystructure](kmath-nd4j/#) : NDStructure wrapper for INDArray +> - [nd4jarrayrings](kmath-nd4j/#) : Rings over Nd4jArrayStructure of Int and Long +> - [nd4jarrayfields](kmath-nd4j/#) : Fields over Nd4jArrayStructure of Float and Double
diff --git a/kmath-ast/README.md b/kmath-ast/README.md index 4c79b5b36..ee14604d2 100644 --- a/kmath-ast/README.md +++ b/kmath-ast/README.md @@ -58,7 +58,7 @@ For example, the following builder: DoubleField.mstInField { symbol("x") + 2 }.compile() ``` -… leads to generation of bytecode, which can be decompiled to the following Java class: +… leads to generation of bytecode, which can be decompiled to the following Java class: ```java package space.kscience.kmath.asm.generated; diff --git a/kmath-core/README.md b/kmath-core/README.md index dd54b7aeb..4e4b5273d 100644 --- a/kmath-core/README.md +++ b/kmath-core/README.md @@ -3,10 +3,10 @@ The core features of KMath: - [algebras](src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Algebraic structures like rings, spaces and fields. - - [nd](src/commonMain/kotlin/space/kscience/kmath/structures/NDStructure.kt) : Many-dimensional structures and operations on them. + - [nd](src/commonMain/kotlin/space/kscience/kmath/structures/StructureND.kt) : Many-dimensional structures and operations on them. - [linear](src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Basic linear algebra operations (sums, products, etc.), backed by the `Space` API. Advanced linear algebra operations like matrix inversion and LU decomposition. - [buffers](src/commonMain/kotlin/space/kscience/kmath/structures/Buffers.kt) : One-dimensional structure - - [expressions](src/commonMain/kotlin/space/kscience/kmath/expressions) : By writing a single mathematical expression once, users will be able to apply different types of + - [expressions](src/commonMain/kotlin/space/kscience/kmath/expressions) : By writing a single mathematical expression once, users will be able to apply different types of objects to the expression by providing a context. Expressions can be used for a wide variety of purposes from high performance calculations to code generation. - [domains](src/commonMain/kotlin/space/kscience/kmath/domains) : Domains diff --git a/kmath-ejml/README.md b/kmath-ejml/README.md new file mode 100644 index 000000000..1081b2b7f --- /dev/null +++ b/kmath-ejml/README.md @@ -0,0 +1,43 @@ +# ejml-simple support (`kmath-ejml`) + +This subproject implements the following features: + + - [ejml-vector](src/main/kotlin/space/kscience/kmath/ejml/EjmlVector.kt) : The Point implementation using SimpleMatrix. + - [ejml-matrix](src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt) : The Matrix implementation using SimpleMatrix. + - [ejml-linear-space](src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt) : The LinearSpace implementation using SimpleMatrix. + + +> #### Artifact: +> +> This module artifact: `space.kscience:kmath-ejml:0.3.0-dev-3`. +> +> Bintray release version: [ ![Download](https://api.bintray.com/packages/mipt-npm/kscience/kmath-ejml/images/download.svg) ](https://bintray.com/mipt-npm/kscience/kmath-ejml/_latestVersion) +> +> Bintray development version: [ ![Download](https://api.bintray.com/packages/mipt-npm/dev/kmath-ejml/images/download.svg) ](https://bintray.com/mipt-npm/dev/kmath-ejml/_latestVersion) +> +> **Gradle:** +> +> ```gradle +> repositories { +> maven { url 'https://repo.kotlin.link' } +> maven { url 'https://dl.bintray.com/hotkeytlt/maven' } +> maven { url "https://dl.bintray.com/kotlin/kotlin-eap" } // include for builds based on kotlin-eap +> } +> +> dependencies { +> implementation 'space.kscience:kmath-ejml:0.3.0-dev-3' +> } +> ``` +> **Gradle Kotlin DSL:** +> +> ```kotlin +> repositories { +> maven("https://repo.kotlin.link") +> maven("https://dl.bintray.com/kotlin/kotlin-eap") // include for builds based on kotlin-eap +> maven("https://dl.bintray.com/hotkeytlt/maven") // required for a +> } +> +> dependencies { +> implementation("space.kscience:kmath-ejml:0.3.0-dev-3") +> } +> ``` diff --git a/kmath-ejml/build.gradle.kts b/kmath-ejml/build.gradle.kts index 1ce2291c4..5091139ac 100644 --- a/kmath-ejml/build.gradle.kts +++ b/kmath-ejml/build.gradle.kts @@ -1,12 +1,33 @@ +import ru.mipt.npm.gradle.Maturity + plugins { id("ru.mipt.npm.gradle.jvm") } dependencies { - implementation("org.ejml:ejml-simple:0.39") - implementation(project(":kmath-core")) + api("org.ejml:ejml-simple:0.40") + api(project(":kmath-core")) } readme { - maturity = ru.mipt.npm.gradle.Maturity.PROTOTYPE -} \ No newline at end of file + maturity = Maturity.PROTOTYPE + propertyByTemplate("artifact", rootProject.file("docs/templates/ARTIFACT-TEMPLATE.md")) + + feature( + id = "ejml-vector", + description = "The Point implementation using SimpleMatrix.", + ref = "src/main/kotlin/space/kscience/kmath/ejml/EjmlVector.kt" + ) + + feature( + id = "ejml-matrix", + description = "The Matrix implementation using SimpleMatrix.", + ref = "src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt" + ) + + feature( + id = "ejml-linear-space", + description = "The LinearSpace implementation using SimpleMatrix.", + ref = "src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt" + ) +} diff --git a/kmath-ejml/docs/README-TEMPLATE.md b/kmath-ejml/docs/README-TEMPLATE.md new file mode 100644 index 000000000..c53f4a81c --- /dev/null +++ b/kmath-ejml/docs/README-TEMPLATE.md @@ -0,0 +1,7 @@ +# ejml-simple support (`kmath-ejml`) + +This subproject implements the following features: + +${features} + +${artifact} diff --git a/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt b/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt index a82fe933e..6fc0a049c 100644 --- a/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt +++ b/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt @@ -14,10 +14,13 @@ import kotlin.reflect.cast * Represents context of basic operations operating with [EjmlMatrix]. * * @author Iaroslav Postovalov + * @author Alexander Nozik */ public object EjmlLinearSpace : LinearSpace { - - override val elementAlgebra: DoubleField get() = DoubleField + /** + * The [DoubleField] reference. + */ + public override val elementAlgebra: DoubleField get() = DoubleField /** * Converts this matrix to EJML one. @@ -38,14 +41,17 @@ public object EjmlLinearSpace : LinearSpace { }) } - override fun buildMatrix(rows: Int, columns: Int, initializer: DoubleField.(i: Int, j: Int) -> Double): EjmlMatrix = - EjmlMatrix(SimpleMatrix(rows, columns).also { - (0 until rows).forEach { row -> - (0 until columns).forEach { col -> it[row, col] = DoubleField.initializer(row, col) } - } - }) + public override fun buildMatrix( + rows: Int, + columns: Int, + initializer: DoubleField.(i: Int, j: Int) -> Double, + ): EjmlMatrix = EjmlMatrix(SimpleMatrix(rows, columns).also { + (0 until rows).forEach { row -> + (0 until columns).forEach { col -> it[row, col] = DoubleField.initializer(row, col) } + } + }) - override fun buildVector(size: Int, initializer: DoubleField.(Int) -> Double): Point = + public override fun buildVector(size: Int, initializer: DoubleField.(Int) -> Double): Point = EjmlVector(SimpleMatrix(size, 1).also { (0 until it.numRows()).forEach { row -> it[row, 0] = DoubleField.initializer(row) } }) @@ -53,7 +59,7 @@ public object EjmlLinearSpace : LinearSpace { private fun SimpleMatrix.wrapMatrix() = EjmlMatrix(this) private fun SimpleMatrix.wrapVector() = EjmlVector(this) - override fun Matrix.unaryMinus(): Matrix = this * (-1.0) + public override fun Matrix.unaryMinus(): Matrix = this * (-1.0) public override fun Matrix.dot(other: Matrix): EjmlMatrix = EjmlMatrix(toEjml().origin.mult(other.toEjml().origin)) @@ -67,29 +73,29 @@ public object EjmlLinearSpace : LinearSpace { public override operator fun Matrix.times(value: Double): EjmlMatrix = toEjml().origin.scale(value).wrapMatrix() - override fun Point.unaryMinus(): EjmlVector = + public override fun Point.unaryMinus(): EjmlVector = toEjml().origin.negative().wrapVector() - override fun Matrix.plus(other: Matrix): EjmlMatrix = + public override fun Matrix.plus(other: Matrix): EjmlMatrix = (toEjml().origin + other.toEjml().origin).wrapMatrix() - override fun Point.plus(other: Point): EjmlVector = + public override fun Point.plus(other: Point): EjmlVector = (toEjml().origin + other.toEjml().origin).wrapVector() - override fun Point.minus(other: Point): EjmlVector = + public override fun Point.minus(other: Point): EjmlVector = (toEjml().origin - other.toEjml().origin).wrapVector() - override fun Double.times(m: Matrix): EjmlMatrix = + public override fun Double.times(m: Matrix): EjmlMatrix = m.toEjml().origin.scale(this).wrapMatrix() - override fun Point.times(value: Double): EjmlVector = + public override fun Point.times(value: Double): EjmlVector = toEjml().origin.scale(value).wrapVector() - override fun Double.times(v: Point): EjmlVector = + public override fun Double.times(v: Point): EjmlVector = v.toEjml().origin.scale(this).wrapVector() @UnstableKMathAPI - override fun getFeature(structure: Matrix, type: KClass): F? { + public override fun getFeature(structure: Matrix, type: KClass): F? { //Return the feature if it is intrinsic to the structure structure.getFeature(type)?.let { return it } @@ -160,7 +166,7 @@ public object EjmlLinearSpace : LinearSpace { } /** - * Solves for X in the following equation: x = a^-1*b, where 'a' is base matrix and 'b' is an n by p matrix. + * Solves for *x* in the following equation: *x = [a] -1 · [b]*. * * @param a the base matrix. * @param b n by p matrix. @@ -171,7 +177,7 @@ public fun EjmlLinearSpace.solve(a: Matrix, b: Matrix): EjmlMatr EjmlMatrix(a.toEjml().origin.solve(b.toEjml().origin)) /** - * Solves for X in the following equation: x = a^(-1)*b, where 'a' is base matrix and 'b' is an n by p matrix. + * Solves for *x* in the following equation: *x = [a] -1 · [b]*. * * @param a the base matrix. * @param b n by p vector. @@ -181,7 +187,17 @@ public fun EjmlLinearSpace.solve(a: Matrix, b: Matrix): EjmlMatr public fun EjmlLinearSpace.solve(a: Matrix, b: Point): EjmlVector = EjmlVector(a.toEjml().origin.solve(b.toEjml().origin)) +/** + * Inverts this matrix. + * + * @author Alexander Nozik + */ @OptIn(UnstableKMathAPI::class) public fun EjmlMatrix.inverted(): EjmlMatrix = getFeature>()!!.inverse as EjmlMatrix +/** + * Inverts the given matrix. + * + * @author Alexander Nozik + */ public fun EjmlLinearSpace.inverse(matrix: Matrix): Matrix = matrix.toEjml().inverted() \ No newline at end of file diff --git a/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt b/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt index 712c2a42c..10afd6ec2 100644 --- a/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt +++ b/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt @@ -4,7 +4,7 @@ import org.ejml.simple.SimpleMatrix import space.kscience.kmath.linear.Matrix /** - * Represents featured matrix over EJML [SimpleMatrix]. + * The matrix implementation over EJML [SimpleMatrix]. * * @property origin the underlying [SimpleMatrix]. * @author Iaroslav Postovalov diff --git a/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlVector.kt b/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlVector.kt index c7f87675d..2c8d2edd4 100644 --- a/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlVector.kt +++ b/kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlVector.kt @@ -9,7 +9,7 @@ import space.kscience.kmath.linear.Point * @property origin the underlying [SimpleMatrix]. * @author Iaroslav Postovalov */ -public class EjmlVector internal constructor(public val origin: SimpleMatrix) : Point { +public inline class EjmlVector internal constructor(public val origin: SimpleMatrix) : Point { public override val size: Int get() = origin.numRows() -- 2.34.1