Add contracts to some functions, fix multiple style issues

Author: CommanderTvis

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/JafamaBenchmark.kt

@@ -13,6 +13,8 @@ import space.kscience.kmath.jafama.JafamaDoubleField
 import space.kscience.kmath.jafama.StrictJafamaDoubleField
 import space.kscience.kmath.operations.DoubleField
 import space.kscience.kmath.operations.invoke
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 import kotlin.random.Random
 
 @State(Scope.Benchmark)
@@ -31,9 +33,10 @@ internal class JafamaBenchmark {
     fun strictJafama(blackhole: Blackhole) = invokeBenchmarks(blackhole) { x ->
         StrictJafamaDoubleField { x * power(x, 4) * exp(x) / cos(x) + sin(x) }
     }
+}
 
-    private inline fun invokeBenchmarks(blackhole: Blackhole, expr: (Double) -> Double) {
-        val rng = Random(0)
-        repeat(1000000) { blackhole.consume(expr(rng.nextDouble())) }
-    }
+private inline fun invokeBenchmarks(blackhole: Blackhole, expr: (Double) -> Double) {
+    contract { callsInPlace(expr, InvocationKind.AT_LEAST_ONCE) }
+    val rng = Random(0)
+    repeat(1000000) { blackhole.consume(expr(rng.nextDouble())) }
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/MatrixInverseBenchmark.kt

@@ -40,14 +40,14 @@ internal class MatrixInverseBenchmark {
 
     @Benchmark
     fun cmLUPInversion(blackhole: Blackhole) {
-        with(CMLinearSpace) {
+        CMLinearSpace {
             blackhole.consume(inverse(matrix))
         }
     }
 
     @Benchmark
     fun ejmlInverse(blackhole: Blackhole) {
-        with(EjmlLinearSpaceDDRM) {
+        EjmlLinearSpaceDDRM {
             blackhole.consume(matrix.getFeature<InverseMatrixFeature<Double>>()?.inverse)
         }
     }

docs/nd-structure.md

@@ -115,6 +115,8 @@ via extension function.
 Usually it is bad idea to compare the direct numerical operation performance in different languages, but it hard to
 work completely without frame of reference. In this case, simple numpy code:
 ```python
+import numpy as np
+
 res = np.ones((1000,1000))
 for i in range(1000):
     res = res + 1.0

examples/src/main/kotlin/space/kscience/kmath/ast/astRendering.kt

@@ -10,7 +10,7 @@ import space.kscience.kmath.ast.rendering.LatexSyntaxRenderer
 import space.kscience.kmath.ast.rendering.MathMLSyntaxRenderer
 import space.kscience.kmath.ast.rendering.renderWithStringBuilder
 
-public fun main() {
+fun main() {
     val mst = "exp(sqrt(x))-asin(2*x)/(2e10+x^3)/(-12)".parseMath()
     val syntax = FeaturedMathRendererWithPostProcess.Default.render(mst)
     println("MathSyntax:")

kmath-ast/src/commonMain/kotlin/space/kscience/kmath/ast/rendering/features.kt

@@ -13,7 +13,7 @@ import space.kscience.kmath.operations.*
 import kotlin.reflect.KClass
 
 /**
- * Prints any [Symbol] as a [SymbolSyntax] containing the [Symbol.value] of it.
+ * Prints any [Symbol] as a [SymbolSyntax] containing the [Symbol.identity] of it.
  *
  * @author Iaroslav Postovalov
  */

kmath-ast/src/commonTest/kotlin/space/kscience/kmath/ast/TestCompilerConsistencyWithInterpreter.kt

@@ -11,7 +11,6 @@ import space.kscience.kmath.expressions.Symbol.Companion.x
 import space.kscience.kmath.expressions.interpret
 import space.kscience.kmath.operations.DoubleField
 import space.kscience.kmath.operations.IntRing
-import space.kscience.kmath.operations.bindSymbol
 import space.kscience.kmath.operations.invoke
 import kotlin.test.Test
 import kotlin.test.assertEquals

kmath-ast/src/commonTest/kotlin/space/kscience/kmath/ast/TestCompilerVariables.kt

@@ -9,7 +9,6 @@ import space.kscience.kmath.expressions.MstRing
 import space.kscience.kmath.expressions.Symbol.Companion.x
 import space.kscience.kmath.expressions.invoke
 import space.kscience.kmath.operations.IntRing
-import space.kscience.kmath.operations.bindSymbol
 import space.kscience.kmath.operations.invoke
 import kotlin.test.Test
 import kotlin.test.assertEquals

kmath-ast/src/jsMain/kotlin/space/kscience/kmath/internal/estree/estree.kt

@@ -3,6 +3,8 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
+@file:Suppress("ClassName")
+
 package space.kscience.kmath.internal.estree
 
 import kotlin.js.RegExp

kmath-ast/src/jsTest/kotlin/space/kscience/kmath/ast/utils.kt

@@ -10,6 +10,8 @@ import space.kscience.kmath.expressions.MST
 import space.kscience.kmath.expressions.Symbol
 import space.kscience.kmath.operations.DoubleField
 import space.kscience.kmath.operations.IntRing
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 import space.kscience.kmath.estree.compile as estreeCompile
 import space.kscience.kmath.estree.compileToExpression as estreeCompileToExpression
 import space.kscience.kmath.wasm.compile as wasmCompile
@@ -34,6 +36,7 @@ private object ESTreeCompilerTestContext : CompilerTestContext {
 }
 
 internal actual inline fun runCompilerTest(action: CompilerTestContext.() -> Unit) {
+    contract { callsInPlace(action, InvocationKind.AT_LEAST_ONCE) }
     action(WasmCompilerTestContext)
     action(ESTreeCompilerTestContext)
 }

kmath-ast/src/jsTest/kotlin/space/kscience/kmath/wasm/TestWasmSpecific.kt

@@ -11,7 +11,6 @@ import space.kscience.kmath.expressions.invoke
 import space.kscience.kmath.expressions.symbol
 import space.kscience.kmath.operations.DoubleField
 import space.kscience.kmath.operations.IntRing
-import space.kscience.kmath.operations.bindSymbol
 import space.kscience.kmath.operations.invoke
 import kotlin.test.Test
 import kotlin.test.assertEquals

kmath-ast/src/jvmTest/kotlin/space/kscience/kmath/ast/utils.kt

@@ -10,6 +10,8 @@ import space.kscience.kmath.expressions.MST
 import space.kscience.kmath.expressions.Symbol
 import space.kscience.kmath.operations.DoubleField
 import space.kscience.kmath.operations.IntRing
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 import space.kscience.kmath.asm.compile as asmCompile
 import space.kscience.kmath.asm.compileToExpression as asmCompileToExpression
 
@@ -22,4 +24,7 @@ private object AsmCompilerTestContext : CompilerTestContext {
         asmCompile(algebra, arguments)
 }
 
-internal actual inline fun runCompilerTest(action: CompilerTestContext.() -> Unit) = action(AsmCompilerTestContext)
+internal actual inline fun runCompilerTest(action: CompilerTestContext.() -> Unit) {
+    contract { callsInPlace(action, InvocationKind.EXACTLY_ONCE) }
+    action(AsmCompilerTestContext)
+}

kmath-commons/src/main/kotlin/space/kscience/kmath/commons/expressions/DerivativeStructureExpression.kt

@@ -15,7 +15,7 @@ import space.kscience.kmath.operations.NumbersAddOperations
  * A field over commons-math [DerivativeStructure].
  *
  * @property order The derivation order.
- * @property bindings The map of bindings values. All bindings are considered free parameters
+ * @param bindings The map of bindings values. All bindings are considered free parameters
  */
 @OptIn(UnstableKMathAPI::class)
 public class DerivativeStructureField(

kmath-commons/src/main/kotlin/space/kscience/kmath/commons/optimization/CMOptimization.kt

@@ -52,11 +52,11 @@ public class CMOptimization(
 
     public fun exportOptimizationData(): List<OptimizationData> = optimizationData.values.toList()
 
-    public override fun initialGuess(map: Map<Symbol, Double>): Unit {
+    public override fun initialGuess(map: Map<Symbol, Double>) {
         addOptimizationData(InitialGuess(map.toDoubleArray()))
     }
 
-    public override fun function(expression: Expression<Double>): Unit {
+    public override fun function(expression: Expression<Double>) {
         val objectiveFunction = ObjectiveFunction {
             val args = it.toMap()
             expression(args)

kmath-commons/src/main/kotlin/space/kscience/kmath/commons/transform/Transformations.kt

@@ -32,7 +32,7 @@ public object Transformations {
     /**
      * Create a virtual buffer on top of array
      */
-    private fun Array<org.apache.commons.math3.complex.Complex>.asBuffer() = VirtualBuffer<Complex>(size) {
+    private fun Array<org.apache.commons.math3.complex.Complex>.asBuffer() = VirtualBuffer(size) {
         val value = get(it)
         Complex(value.real, value.imaginary)
     }

kmath-commons/src/test/kotlin/space/kscience/kmath/commons/expressions/DerivativeStructureExpressionTest.kt

@@ -16,7 +16,7 @@ internal inline fun diff(
     order: Int,
     vararg parameters: Pair<Symbol, Double>,
     block: DerivativeStructureField.() -> Unit,
-): Unit {
+) {
     contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) }
     DerivativeStructureField(order, mapOf(*parameters)).run(block)
 }

kmath-complex/src/commonMain/kotlin/space/kscience/kmath/complex/Quaternion.kt

@@ -147,7 +147,7 @@ public object QuaternionField : Field<Quaternion>, Norm<Quaternion, Quaternion>,
             return if (arg.w > 0)
                 Quaternion(ln(arg.w), 0, 0, 0)
             else {
-                val l = ComplexField { ComplexField.ln(arg.w.toComplex()) }
+                val l = ComplexField { ln(arg.w.toComplex()) }
                 Quaternion(l.re, l.im, 0, 0)
             }
 

kmath-core/src/commonMain/kotlin/space/kscience/kmath/data/XYColumnarData.kt

@@ -16,7 +16,7 @@ import kotlin.math.max
  * The buffer of X values.
  */
 @UnstableKMathAPI
-public interface XYColumnarData<T, out X : T, out Y : T> : ColumnarData<T> {
+public interface XYColumnarData<out T, out X : T, out Y : T> : ColumnarData<T> {
     /**
      * The buffer of X values
      */

kmath-core/src/commonMain/kotlin/space/kscience/kmath/data/XYZColumnarData.kt

@@ -14,7 +14,7 @@ import space.kscience.kmath.structures.Buffer
  * Inherits [XYColumnarData].
  */
 @UnstableKMathAPI
-public interface XYZColumnarData<T, out X : T, out Y : T, out Z : T> : XYColumnarData<T, X, Y> {
+public interface XYZColumnarData<out T, out X : T, out Y : T, out Z : T> : XYColumnarData<T, X, Y> {
     public val z: Buffer<Z>
 
     override fun get(symbol: Symbol): Buffer<T>? = when (symbol) {
@@ -23,4 +23,4 @@ public interface XYZColumnarData<T, out X : T, out Y : T, out Z : T> : XYColumna
         Symbol.z -> z
         else -> null
     }
-}
+}

kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/Domain.kt

@@ -12,7 +12,7 @@ import space.kscience.kmath.linear.Point
  *
  * @param T the type of element of this domain.
  */
-public interface Domain<T : Any> {
+public interface Domain<in T : Any> {
     /**
      * Checks if the specified point is contained in this domain.
      */

kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions/DifferentiableExpression.kt

@@ -9,7 +9,6 @@ package space.kscience.kmath.expressions
  * Represents expression which structure can be differentiated.
  *
  * @param T the type this expression takes as argument and returns.
- * @param R the type of expression this expression can be differentiated to.
  */
 public interface DifferentiableExpression<T> : Expression<T> {
     /**
@@ -24,16 +23,18 @@ public interface DifferentiableExpression<T> : Expression<T> {
 public fun <T> DifferentiableExpression<T>.derivative(symbols: List<Symbol>): Expression<T> =
     derivativeOrNull(symbols) ?: error("Derivative by symbols $symbols not provided")
 
-public fun <T> DifferentiableExpression<T>.derivative(vararg symbols: Symbol):  Expression<T> =
+public fun <T> DifferentiableExpression<T>.derivative(vararg symbols: Symbol): Expression<T> =
     derivative(symbols.toList())
 
-public fun <T> DifferentiableExpression<T>.derivative(name: String):  Expression<T> =
+public fun <T> DifferentiableExpression<T>.derivative(name: String): Expression<T> =
     derivative(StringSymbol(name))
 
 /**
- * A special type of [DifferentiableExpression] which returns typed expressions as derivatives
+ * A special type of [DifferentiableExpression] which returns typed expressions as derivatives.
+ *
+ * @param R the type of expression this expression can be differentiated to.
  */
-public interface SpecialDifferentiableExpression<T, R: Expression<T>>: DifferentiableExpression<T> {
+public interface SpecialDifferentiableExpression<T, out R : Expression<T>> : DifferentiableExpression<T> {
     override fun derivativeOrNull(symbols: List<Symbol>): R?
 }
 
@@ -53,9 +54,9 @@ public abstract class FirstDerivativeExpression<T> : DifferentiableExpression<T>
     /**
      * Returns first derivative of this expression by given [symbol].
      */
-    public abstract fun derivativeOrNull(symbol: Symbol):  Expression<T>?
+    public abstract fun derivativeOrNull(symbol: Symbol): Expression<T>?
 
-    public final override fun derivativeOrNull(symbols: List<Symbol>):  Expression<T>? {
+    public final override fun derivativeOrNull(symbols: List<Symbol>): Expression<T>? {
         val dSymbol = symbols.firstOrNull() ?: return null
         return derivativeOrNull(dSymbol)
     }
@@ -64,6 +65,6 @@ public abstract class FirstDerivativeExpression<T> : DifferentiableExpression<T>
 /**
  * A factory that converts an expression in autodiff variables to a [DifferentiableExpression]
  */
-public fun interface AutoDiffProcessor<T : Any, I : Any, A : ExpressionAlgebra<T, I>, out R : Expression<T>> {
+public fun interface AutoDiffProcessor<T : Any, I : Any, out A : ExpressionAlgebra<T, I>, out R : Expression<T>> {
     public fun process(function: A.() -> I): DifferentiableExpression<T>
 }

kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions/FunctionalExpressionAlgebra.kt

@@ -6,13 +6,15 @@
 package space.kscience.kmath.expressions
 
 import space.kscience.kmath.operations.*
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
 
 /**
  * A context class for [Expression] construction.
  *
  * @param algebra The algebra to provide for Expressions built.
  */
-public abstract class FunctionalExpressionAlgebra<T, A : Algebra<T>>(
+public abstract class FunctionalExpressionAlgebra<T, out A : Algebra<T>>(
     public val algebra: A,
 ) : ExpressionAlgebra<T, Expression<T>> {
     /**
@@ -29,19 +31,13 @@ public abstract class FunctionalExpressionAlgebra<T, A : Algebra<T>>(
             ?: error("Symbol '$value' is not supported in $this")
     }
 
-    /**
-     * Builds an Expression of dynamic call of binary operation [operation] on [left] and [right].
-     */
     public override fun binaryOperationFunction(operation: String): (left: Expression<T>, right: Expression<T>) -> Expression<T> =
         { left, right ->
             Expression { arguments ->
                 algebra.binaryOperationFunction(operation)(left.invoke(arguments), right.invoke(arguments))
             }
         }
 
-    /**
-     * Builds an Expression of dynamic call of unary operation with name [operation] on [arg].
-     */
     public override fun unaryOperationFunction(operation: String): (arg: Expression<T>) -> Expression<T> = { arg ->
         Expression { arguments -> algebra.unaryOperationFunction(operation)(arg.invoke(arguments)) }
     }
@@ -50,7 +46,7 @@ public abstract class FunctionalExpressionAlgebra<T, A : Algebra<T>>(
 /**
  * A context class for [Expression] construction for [Ring] algebras.
  */
-public open class FunctionalExpressionGroup<T, A : Group<T>>(
+public open class FunctionalExpressionGroup<T, out A : Group<T>>(
     algebra: A,
 ) : FunctionalExpressionAlgebra<T, A>(algebra), Group<Expression<T>> {
     public override val zero: Expression<T> get() = const(algebra.zero)
@@ -84,7 +80,7 @@ public open class FunctionalExpressionGroup<T, A : Group<T>>(
 
 }
 
-public open class FunctionalExpressionRing<T, A : Ring<T>>(
+public open class FunctionalExpressionRing<T, out A : Ring<T>>(
     algebra: A,
 ) : FunctionalExpressionGroup<T, A>(algebra), Ring<Expression<T>> {
     public override val one: Expression<T> get() = const(algebra.one)
@@ -105,7 +101,7 @@ public open class FunctionalExpressionRing<T, A : Ring<T>>(
         super<FunctionalExpressionGroup>.binaryOperationFunction(operation)
 }
 
-public open class FunctionalExpressionField<T, A : Field<T>>(
+public open class FunctionalExpressionField<T, out A : Field<T>>(
     algebra: A,
 ) : FunctionalExpressionRing<T, A>(algebra), Field<Expression<T>>, ScaleOperations<Expression<T>> {
     /**
@@ -131,7 +127,7 @@ public open class FunctionalExpressionField<T, A : Field<T>>(
         super<FunctionalExpressionRing>.bindSymbolOrNull(value)
 }
 
-public open class FunctionalExpressionExtendedField<T, A : ExtendedField<T>>(
+public open class FunctionalExpressionExtendedField<T, out A : ExtendedField<T>>(
     algebra: A,
 ) : FunctionalExpressionField<T, A>(algebra), ExtendedField<Expression<T>> {
     public override fun number(value: Number): Expression<T> = const(algebra.number(value))
@@ -172,14 +168,26 @@ public open class FunctionalExpressionExtendedField<T, A : ExtendedField<T>>(
     public override fun bindSymbol(value: String): Expression<T> = super<FunctionalExpressionField>.bindSymbol(value)
 }
 
-public inline fun <T, A : Ring<T>> A.expressionInSpace(block: FunctionalExpressionGroup<T, A>.() -> Expression<T>): Expression<T> =
-    FunctionalExpressionGroup(this).block()
+public inline fun <T, A : Group<T>> A.expressionInGroup(
+    block: FunctionalExpressionGroup<T, A>.() -> Expression<T>,
+): Expression<T> {
+    contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) }
+    return FunctionalExpressionGroup(this).block()
+}
 
-public inline fun <T, A : Ring<T>> A.expressionInRing(block: FunctionalExpressionRing<T, A>.() -> Expression<T>): Expression<T> =
-    FunctionalExpressionRing(this).block()
+public inline fun <T, A : Ring<T>> A.expressionInRing(
+    block: FunctionalExpressionRing<T, A>.() -> Expression<T>,
+): Expression<T> {
+    contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) }
+    return FunctionalExpressionRing(this).block()
+}
 
-public inline fun <T, A : Field<T>> A.expressionInField(block: FunctionalExpressionField<T, A>.() -> Expression<T>): Expression<T> =
-    FunctionalExpressionField(this).block()
+public inline fun <T, A : Field<T>> A.expressionInField(
+    block: FunctionalExpressionField<T, A>.() -> Expression<T>,
+): Expression<T> {
+    contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) }
+    return FunctionalExpressionField(this).block()
+}
 
 public inline fun <T, A : ExtendedField<T>> A.expressionInExtendedField(
     block: FunctionalExpressionExtendedField<T, A>.() -> Expression<T>,