From e2920ed68390bf29ee0854da85d69efd53c6a5a3 Mon Sep 17 00:00:00 2001 From: Iaroslav Postovalov Date: Sun, 9 May 2021 16:40:10 +0700 Subject: [PATCH] Promote kmath-kotlingrad to experimental alongside minor documentation and API changes --- CHANGELOG.md | 3 +- README.md | 9 +++-- kmath-kotlingrad/README.md | 34 +++++++++++++++++++ kmath-kotlingrad/build.gradle.kts | 20 +++++++++-- kmath-kotlingrad/docs/README-TEMPLATE.md | 7 ++++ .../kotlingrad/DifferentiableMstExpression.kt | 17 +++++----- .../kscience/kmath/kotlingrad/KMathNumber.kt | 25 +++++++++----- .../kmath/kotlingrad/ScalarsAdapters.kt | 26 +++++++------- .../kmath/kotlingrad/AdaptingTests.kt | 6 +--- 9 files changed, 106 insertions(+), 41 deletions(-) create mode 100644 kmath-kotlingrad/README.md create mode 100644 kmath-kotlingrad/docs/README-TEMPLATE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 286511327..4fba361d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,7 @@ - Move MST to core - Separated benchmarks and examples - Rewritten EJML module without ejml-simple +- Stability of kmath-ast and kmath-kotilngrad promoted to EXPERIMENTAL. ### Deprecated @@ -35,7 +36,7 @@ - `contentEquals` from Buffer. It moved to the companion. - MSTExpression - Expression algebra builders -- Comples and Quaternion no longer are elements. +- Complex and Quaternion no longer are elements. ### Fixed - Ring inherits RingOperations, not GroupOperations diff --git a/README.md b/README.md index c8da21b64..3b4387c1b 100644 --- a/README.md +++ b/README.md @@ -207,9 +207,14 @@ One can still use generic algebras though.
* ### [kmath-kotlingrad](kmath-kotlingrad) -> +> Functions, integration and interpolation > -> **Maturity**: PROTOTYPE +> **Maturity**: EXPERIMENTAL +> +> **Features:** +> - [differentiable-mst-expression](kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt) : MST based DifferentiableExpression. +> - [differentiable-mst-expression](kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt) : Conversions between Kotlin∇'s SFun and MST +
* ### [kmath-memory](kmath-memory) diff --git a/kmath-kotlingrad/README.md b/kmath-kotlingrad/README.md new file mode 100644 index 000000000..686df3271 --- /dev/null +++ b/kmath-kotlingrad/README.md @@ -0,0 +1,34 @@ +# Module kmath-kotlingrad + +[Kotlin∇](https://github.com/breandan/kotlingrad) integration module. + + - [differentiable-mst-expression](src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt) : MST based DifferentiableExpression. + - [differentiable-mst-expression](src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt) : Conversions between Kotlin∇'s SFun and MST + + +## Artifact: + +The Maven coordinates of this project are `space.kscience:kmath-kotlingrad:0.3.0-dev-8`. + +**Gradle:** +```gradle +repositories { + maven { url 'https://repo.kotlin.link' } + mavenCentral() +} + +dependencies { + implementation 'space.kscience:kmath-kotlingrad:0.3.0-dev-8' +} +``` +**Gradle Kotlin DSL:** +```kotlin +repositories { + maven("https://repo.kotlin.link") + mavenCentral() +} + +dependencies { + implementation("space.kscience:kmath-kotlingrad:0.3.0-dev-8") +} +``` diff --git a/kmath-kotlingrad/build.gradle.kts b/kmath-kotlingrad/build.gradle.kts index ed5b5bcb4..0e8e49971 100644 --- a/kmath-kotlingrad/build.gradle.kts +++ b/kmath-kotlingrad/build.gradle.kts @@ -4,11 +4,27 @@ plugins { } dependencies { - api("com.github.breandan:kaliningraph:0.1.4") + api("com.github.breandan:kaliningraph:0.1.6") api("com.github.breandan:kotlingrad:0.4.5") api(project(":kmath-ast")) } readme { - maturity = ru.mipt.npm.gradle.Maturity.PROTOTYPE + description = "Functions, integration and interpolation" + maturity = ru.mipt.npm.gradle.Maturity.EXPERIMENTAL + propertyByTemplate("artifact", rootProject.file("docs/templates/ARTIFACT-TEMPLATE.md")) + + feature( + "differentiable-mst-expression", + "src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt", + ) { + "MST based DifferentiableExpression." + } + + feature( + "differentiable-mst-expression", + "src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt", + ) { + "Conversions between Kotlin∇'s SFun and MST" + } } diff --git a/kmath-kotlingrad/docs/README-TEMPLATE.md b/kmath-kotlingrad/docs/README-TEMPLATE.md new file mode 100644 index 000000000..ac38c849b --- /dev/null +++ b/kmath-kotlingrad/docs/README-TEMPLATE.md @@ -0,0 +1,7 @@ +# Module kmath-kotlingrad + +[Kotlin∇](https://www.htmlsymbols.xyz/unicode/U+2207) integration module. + +${features} + +${artifact} diff --git a/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt b/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt index 222145d2d..8c6745c79 100644 --- a/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt +++ b/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt @@ -6,6 +6,7 @@ package space.kscience.kmath.kotlingrad import edu.umontreal.kotlingrad.api.SFun +import edu.umontreal.kotlingrad.api.SVar import space.kscience.kmath.expressions.DifferentiableExpression import space.kscience.kmath.expressions.MST import space.kscience.kmath.expressions.MstAlgebra @@ -14,20 +15,20 @@ import space.kscience.kmath.misc.Symbol import space.kscience.kmath.operations.NumericAlgebra /** - * Represents wrapper of [MstExpression] implementing [DifferentiableExpression]. + * Represents [MST] based [DifferentiableExpression]. * - * The principle of this API is converting the [mst] to an [SFun], differentiating it with Kotlin∇, then converting - * [SFun] back to [MST]. + * The principle of this API is converting the [mst] to an [SFun], differentiating it with + * [Kotlin∇](https://github.com/breandan/kotlingrad), then converting [SFun] back to [MST]. * - * @param T the type of number. - * @param A the [NumericAlgebra] of [T]. - * @property expr the underlying [MstExpression]. + * @param T The type of number. + * @param A The [NumericAlgebra] of [T]. + * @property algebra The [A] instance. + * @property mst The [MST] node. */ public class DifferentiableMstExpression>( public val algebra: A, public val mst: MST, ) : DifferentiableExpression> { - public override fun invoke(arguments: Map): T = mst.interpret(algebra, arguments) public override fun derivativeOrNull(symbols: List): DifferentiableMstExpression = @@ -35,7 +36,7 @@ public class DifferentiableMstExpression>( algebra, symbols.map(Symbol::identity) .map(MstAlgebra::bindSymbol) - .map { it.toSVar>() } + .map>>(MST.Symbolic::toSVar) .fold(mst.toSFun(), SFun>::d) .toMst(), ) diff --git a/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/KMathNumber.kt b/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/KMathNumber.kt index 0c3768dcc..9c9d07b81 100644 --- a/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/KMathNumber.kt +++ b/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/KMathNumber.kt @@ -5,19 +5,26 @@ package space.kscience.kmath.kotlingrad -import edu.umontreal.kotlingrad.api.RealNumber import edu.umontreal.kotlingrad.api.SConst import space.kscience.kmath.operations.NumericAlgebra /** - * Implements [RealNumber] by delegating its functionality to [NumericAlgebra]. + * Implements [SConst] by delegating its functionality to [NumericAlgebra]. * - * @param T the type of number. - * @param A the [NumericAlgebra] of [T]. - * @property algebra the algebra. - * @param value the value of this number. + * @param T The type of number. + * @param A The [NumericAlgebra] over [T]. + * @property algebra The algebra. + * @property value The value of this number. */ -public class KMathNumber(public val algebra: A, value: T) : - RealNumber, T>(value) where T : Number, A : NumericAlgebra { - public override fun wrap(number: Number): SConst> = SConst(algebra.number(number)) +public class KMathNumber(public val algebra: A, public override val value: T) : + SConst>(value) where T : Number, A : NumericAlgebra { + /** + * Returns a string representation of the [value]. + */ + public override fun toString(): String = value.toString() + + /** + * Wraps [Number] to [KMathNumber]. + */ + public override fun wrap(number: Number): KMathNumber = KMathNumber(algebra, algebra.number(number)) } diff --git a/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/ScalarsAdapters.kt b/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/ScalarsAdapters.kt index f65d2948d..bee2c9e3e 100644 --- a/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/ScalarsAdapters.kt +++ b/kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/ScalarsAdapters.kt @@ -15,16 +15,16 @@ import space.kscience.kmath.operations.* /** * Maps [SVar] to [MST.Symbolic] directly. * - * @receiver the variable. - * @return a node. + * @receiver The variable. + * @returnAa node. */ public fun > SVar.toMst(): MST.Symbolic = MstAlgebra.bindSymbol(name) /** * Maps [SVar] to [MST.Numeric] directly. * - * @receiver the constant. - * @return a node. + * @receiver The constant. + * @return A node. */ public fun > SConst.toMst(): MST.Numeric = MstAlgebra.number(doubleValue) @@ -49,8 +49,8 @@ public fun > SConst.toMst(): MST.Numeric = MstAlgebra.number(doub * - [VSumAll] is requested to be evaluated; * - [Derivative] is requested to be evaluated. * - * @receiver the scalar function. - * @return a node. + * @receiver The scalar function. + * @return A node. */ public fun > SFun.toMst(): MST = MstExtendedField { when (this@toMst) { @@ -74,17 +74,16 @@ public fun > SFun.toMst(): MST = MstExtendedField { /** * Maps [MST.Numeric] to [SConst] directly. * - * @receiver the node. - * @return a new constant. + * @receiver The node. + * @return A new constant. */ public fun > MST.Numeric.toSConst(): SConst = SConst(value) /** * Maps [MST.Symbolic] to [SVar] directly. * - * @receiver the node. - * @param proto the prototype instance. - * @return a new variable. + * @receiver The node. + * @return A new variable. */ internal fun > MST.Symbolic.toSVar(): SVar = SVar(value) @@ -98,9 +97,8 @@ internal fun > MST.Symbolic.toSVar(): SVar = SVar(value) * - [MST.Unary] -> [Negative], [Sine], [Cosine], [Tangent], [Power], [Log]; * - [MST.Binary] -> [Sum], [Prod], [Power]. * - * @receiver the node. - * @param proto the prototype instance. - * @return a scalar function. + * @receiver The node. + * @return A scalar function. */ public fun > MST.toSFun(): SFun = when (this) { is MST.Numeric -> toSConst() diff --git a/kmath-kotlingrad/src/test/kotlin/space/kscience/kmath/kotlingrad/AdaptingTests.kt b/kmath-kotlingrad/src/test/kotlin/space/kscience/kmath/kotlingrad/AdaptingTests.kt index 3ed73451d..85c964c58 100644 --- a/kmath-kotlingrad/src/test/kotlin/space/kscience/kmath/kotlingrad/AdaptingTests.kt +++ b/kmath-kotlingrad/src/test/kotlin/space/kscience/kmath/kotlingrad/AdaptingTests.kt @@ -10,7 +10,7 @@ import space.kscience.kmath.asm.compileToExpression import space.kscience.kmath.ast.parseMath import space.kscience.kmath.expressions.MstAlgebra import space.kscience.kmath.expressions.invoke -import space.kscience.kmath.misc.symbol +import space.kscience.kmath.misc.Symbol.Companion.x import space.kscience.kmath.operations.DoubleField import kotlin.test.Test import kotlin.test.assertEquals @@ -65,8 +65,4 @@ internal class AdaptingTests { assertEquals(actualDerivative(x to 0.1), expectedDerivative(x to 0.1)) } - - private companion object { - private val x by symbol - } }