From 36ad1fcf589e0f8e9b4701f463360d7d66c80c41 Mon Sep 17 00:00:00 2001
From: Iaroslav <postovalovya@gmail.com>
Date: Sat, 13 Jun 2020 15:44:54 +0700
Subject: [PATCH] Minor refactor and document

---
 .../scientifik/kmath/asm/AsmExpressions.kt    | 101 +++++++++++++-----
 .../kmath/asm/AsmGenerationContext.kt         |  12 ++-
 .../expressions/FunctionalExpressions.kt      |  84 ++++++++++-----
 3 files changed, 141 insertions(+), 56 deletions(-)

diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmExpressions.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmExpressions.kt
index 75b5f26d0..ef579278a 100644
--- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmExpressions.kt
+++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmExpressions.kt
@@ -142,7 +142,8 @@ internal class AsmConstProductExpression<T>(
     }
 }
 
-internal class AsmNumberExpression<T>(private val context: NumericAlgebra<T>, private val value: Number) : AsmExpression<T> {
+internal class AsmNumberExpression<T>(private val context: NumericAlgebra<T>, private val value: Number) :
+    AsmExpression<T> {
     override fun tryEvaluate(): T? = context.number(value)
 
     override fun invoke(gen: AsmGenerationContext<T>): Unit = gen.visitNumberConstant(value)
@@ -155,75 +156,121 @@ internal abstract class FunctionalCompiledExpression<T> internal constructor(
     abstract override fun invoke(arguments: Map<String, T>): T
 }
 
+/**
+ * A context class for [AsmExpression] construction.
+ */
 interface AsmExpressionAlgebra<T, A : NumericAlgebra<T>> : NumericAlgebra<AsmExpression<T>>,
     ExpressionAlgebra<T, AsmExpression<T>> {
+    /**
+     * The algebra to provide for AsmExpressions built.
+     */
     val algebra: A
+
+    /**
+     * Builds an AsmExpression to wrap a number.
+     */
+    override fun number(value: Number): AsmExpression<T> = AsmNumberExpression(algebra, value)
+
+    /**
+     * Builds an AsmExpression of constant expression which does not depend on arguments.
+     */
+    override fun const(value: T): AsmExpression<T> = AsmConstantExpression(value)
+
+    /**
+     * Builds an AsmExpression to access a variable.
+     */
+    override fun variable(name: String, default: T?): AsmExpression<T> = AsmVariableExpression(name, default)
+
+    /**
+     * Builds an AsmExpression of dynamic call of binary operation [operation] on [left] and [right].
+     */
     override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
         AsmBinaryOperation(algebra, operation, left, right)
 
+    /**
+     * Builds an AsmExpression of dynamic call of unary operation with name [operation] on [arg].
+     */
     override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
         AsmUnaryOperation(algebra, operation, arg)
-
-    override fun number(value: Number): AsmExpression<T> = AsmNumberExpression(algebra, value)
-    override fun const(value: T): AsmExpression<T> = AsmConstantExpression(value)
-    override fun variable(name: String, default: T?): AsmExpression<T> = AsmVariableExpression(name, default)
 }
 
+/**
+ * A context class for [AsmExpression] construction for [Space] algebras.
+ */
 open class AsmExpressionSpace<T, A>(override val algebra: A) : AsmExpressionAlgebra<T, A>,
     Space<AsmExpression<T>> where  A : Space<T>, A : NumericAlgebra<T> {
     override val zero: AsmExpression<T>
         get() = const(algebra.zero)
 
-    override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
-        AsmBinaryOperation(algebra, operation, left, right)
-
-    override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
-        AsmUnaryOperation(algebra, operation, arg)
-
+    /**
+     * Builds an AsmExpression of addition of two another expressions.
+     */
     override fun add(a: AsmExpression<T>, b: AsmExpression<T>): AsmExpression<T> =
         AsmBinaryOperation(algebra, SpaceOperations.PLUS_OPERATION, a, b)
 
+    /**
+     * Builds an AsmExpression of multiplication of expression by number.
+     */
     override fun multiply(a: AsmExpression<T>, k: Number): AsmExpression<T> = AsmConstProductExpression(algebra, a, k)
+
     operator fun AsmExpression<T>.plus(arg: T): AsmExpression<T> = this + const(arg)
     operator fun AsmExpression<T>.minus(arg: T): AsmExpression<T> = this - const(arg)
     operator fun T.plus(arg: AsmExpression<T>): AsmExpression<T> = arg + this
     operator fun T.minus(arg: AsmExpression<T>): AsmExpression<T> = arg - this
+
+    override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
+        super<AsmExpressionAlgebra>.unaryOperation(operation, arg)
+
+    override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
+        super<AsmExpressionAlgebra>.binaryOperation(operation, left, right)
 }
 
+/**
+ * A context class for [AsmExpression] construction for [Ring] algebras.
+ */
 open class AsmExpressionRing<T, A>(override val algebra: A) : AsmExpressionSpace<T, A>(algebra),
     Ring<AsmExpression<T>> where  A : Ring<T>, A : NumericAlgebra<T> {
     override val one: AsmExpression<T>
         get() = const(algebra.one)
 
-    override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
-        AsmUnaryOperation(algebra, operation, arg)
-
-    override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
-        AsmBinaryOperation(algebra, operation, left, right)
-
-    override fun number(value: Number): AsmExpression<T> = const(algebra { one * value })
-
+    /**
+     * Builds an AsmExpression of multiplication of two expressions.
+     */
     override fun multiply(a: AsmExpression<T>, b: AsmExpression<T>): AsmExpression<T> =
         AsmBinaryOperation(algebra, RingOperations.TIMES_OPERATION, a, b)
 
     operator fun AsmExpression<T>.times(arg: T): AsmExpression<T> = this * const(arg)
     operator fun T.times(arg: AsmExpression<T>): AsmExpression<T> = arg * this
+
+    override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
+        super<AsmExpressionSpace>.unaryOperation(operation, arg)
+
+    override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
+        super<AsmExpressionSpace>.binaryOperation(operation, left, right)
+
+    override fun number(value: Number): AsmExpression<T> = super<AsmExpressionSpace>.number(value)
 }
 
+/**
+ * A context class for [AsmExpression] construction for [Field] algebras.
+ */
 open class AsmExpressionField<T, A>(override val algebra: A) :
     AsmExpressionRing<T, A>(algebra),
     Field<AsmExpression<T>> where A : Field<T>, A : NumericAlgebra<T> {
-
-    override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
-        AsmUnaryOperation(algebra, operation, arg)
-
-    override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
-        AsmBinaryOperation(algebra, operation, left, right)
-
+    /**
+     * Builds an AsmExpression of division an expression by another one.
+     */
     override fun divide(a: AsmExpression<T>, b: AsmExpression<T>): AsmExpression<T> =
         AsmBinaryOperation(algebra, FieldOperations.DIV_OPERATION, a, b)
 
     operator fun AsmExpression<T>.div(arg: T): AsmExpression<T> = this / const(arg)
     operator fun T.div(arg: AsmExpression<T>): AsmExpression<T> = arg / this
-}
 
+    override fun unaryOperation(operation: String, arg: AsmExpression<T>): AsmExpression<T> =
+        super<AsmExpressionRing>.unaryOperation(operation, arg)
+
+    override fun binaryOperation(operation: String, left: AsmExpression<T>, right: AsmExpression<T>): AsmExpression<T> =
+        super<AsmExpressionRing>.binaryOperation(operation, left, right)
+
+    override fun number(value: Number): AsmExpression<T> = super<AsmExpressionRing>.number(value)
+}
diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmGenerationContext.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmGenerationContext.kt
index d9dba746d..69a2b6c85 100644
--- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmGenerationContext.kt
+++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/AsmGenerationContext.kt
@@ -6,6 +6,15 @@ import org.objectweb.asm.MethodVisitor
 import org.objectweb.asm.Opcodes
 import scientifik.kmath.operations.Algebra
 
+/**
+ * AsmGenerationContext is a structure that abstracts building a class that unwraps [AsmExpression] to plain Java
+ * expression. This class uses [ClassLoader] for loading the generated class, then it is able to instantiate the new
+ * class.
+ *
+ * @param T the type of AsmExpression to unwrap.
+ * @param algebra the algebra the applied AsmExpressions use.
+ * @param className the unique class name of new loaded class.
+ */
 class AsmGenerationContext<T>(
     classOfT: Class<*>,
     private val algebra: Algebra<T>,
@@ -29,8 +38,7 @@ class AsmGenerationContext<T>(
     private val invokeArgumentsVar: Int = 1
     private var maxStack: Int = 0
     private val constants: MutableList<Any> = mutableListOf()
-    private val asmCompiledClassWriter: ClassWriter =
-        ClassWriter(0)
+    private val asmCompiledClassWriter: ClassWriter = ClassWriter(0)
     private val invokeMethodVisitor: MethodVisitor
     private val invokeL0: Label
     private lateinit var invokeL1: Label
diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/expressions/FunctionalExpressions.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/expressions/FunctionalExpressions.kt
index 88d8c87b7..c3f36a814 100644
--- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/expressions/FunctionalExpressions.kt
+++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/expressions/FunctionalExpressions.kt
@@ -28,40 +28,61 @@ internal class FunctionalConstantExpression<T>(val value: T) : Expression<T> {
 
 internal class FunctionalConstProductExpression<T>(
     val context: Space<T>,
-    val expr: Expression<T>,
+    private val expr: Expression<T>,
     val const: Number
-) :
-    Expression<T> {
+) : Expression<T> {
     override fun invoke(arguments: Map<String, T>): T = context.multiply(expr.invoke(arguments), const)
 }
 
+/**
+ * A context class for [Expression] construction.
+ */
 interface FunctionalExpressionAlgebra<T, A : Algebra<T>> : ExpressionAlgebra<T, Expression<T>> {
+    /**
+     * The algebra to provide for Expressions built.
+     */
     val algebra: A
 
+    /**
+     * Builds an Expression of constant expression which does not depend on arguments.
+     */
+    override fun const(value: T): Expression<T> = FunctionalConstantExpression(value)
+
+    /**
+     * Builds an Expression to access a variable.
+     */
+    override fun variable(name: String, default: T?): Expression<T> = FunctionalVariableExpression(name, default)
+
+    /**
+     * Builds an Expression of dynamic call of binary operation [operation] on [left] and [right].
+     */
     override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
         FunctionalBinaryOperation(algebra, operation, left, right)
 
+    /**
+     * Builds an Expression of dynamic call of unary operation with name [operation] on [arg].
+     */
     override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
         FunctionalUnaryOperation(algebra, operation, arg)
-
-    override fun const(value: T): Expression<T> = FunctionalConstantExpression(value)
-    override fun variable(name: String, default: T?): Expression<T> = FunctionalVariableExpression(name, default)
 }
 
+/**
+ * A context class for [Expression] construction for [Space] algebras.
+ */
 open class FunctionalExpressionSpace<T, A>(override val algebra: A) : FunctionalExpressionAlgebra<T, A>,
     Space<Expression<T>> where  A : Space<T> {
     override val zero: Expression<T>
         get() = const(algebra.zero)
 
-    override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
-        FunctionalBinaryOperation(algebra, operation, left, right)
-
-    override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
-        FunctionalUnaryOperation(algebra, operation, arg)
-
+    /**
+     * Builds an Expression of addition of two another expressions.
+     */
     override fun add(a: Expression<T>, b: Expression<T>): Expression<T> =
         FunctionalBinaryOperation(algebra, SpaceOperations.PLUS_OPERATION, a, b)
 
+    /**
+     * Builds an Expression of multiplication of expression by number.
+     */
     override fun multiply(a: Expression<T>, k: Number): Expression<T> =
         FunctionalConstProductExpression(algebra, a, k)
 
@@ -69,6 +90,12 @@ open class FunctionalExpressionSpace<T, A>(override val algebra: A) : Functional
     operator fun Expression<T>.minus(arg: T): Expression<T> = this - const(arg)
     operator fun T.plus(arg: Expression<T>): Expression<T> = arg + this
     operator fun T.minus(arg: Expression<T>): Expression<T> = arg - this
+
+    override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
+        super<FunctionalExpressionAlgebra>.unaryOperation(operation, arg)
+
+    override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
+        super<FunctionalExpressionAlgebra>.binaryOperation(operation, left, right)
 }
 
 open class FunctionalExpressionRing<T, A>(override val algebra: A) : FunctionalExpressionSpace<T, A>(algebra),
@@ -76,34 +103,37 @@ open class FunctionalExpressionRing<T, A>(override val algebra: A) : FunctionalE
     override val one: Expression<T>
         get() = const(algebra.one)
 
-    override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
-        FunctionalUnaryOperation(algebra, operation, arg)
-
-    override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
-        FunctionalBinaryOperation(algebra, operation, left, right)
-
-    override fun number(value: Number): Expression<T> = const(algebra { one * value })
-
+    /**
+     * Builds an Expression of multiplication of two expressions.
+     */
     override fun multiply(a: Expression<T>, b: Expression<T>): Expression<T> =
         FunctionalBinaryOperation(algebra, RingOperations.TIMES_OPERATION, a, b)
 
     operator fun Expression<T>.times(arg: T): Expression<T> = this * const(arg)
     operator fun T.times(arg: Expression<T>): Expression<T> = arg * this
+
+    override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
+        super<FunctionalExpressionSpace>.unaryOperation(operation, arg)
+
+    override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
+        super<FunctionalExpressionSpace>.binaryOperation(operation, left, right)
 }
 
 open class FunctionalExpressionField<T, A>(override val algebra: A) :
     FunctionalExpressionRing<T, A>(algebra),
     Field<Expression<T>> where A : Field<T>, A : NumericAlgebra<T> {
-
-    override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
-        FunctionalUnaryOperation(algebra, operation, arg)
-
-    override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
-        FunctionalBinaryOperation(algebra, operation, left, right)
-
+    /**
+     * Builds an Expression of division an expression by another one.
+     */
     override fun divide(a: Expression<T>, b: Expression<T>): Expression<T> =
         FunctionalBinaryOperation(algebra, FieldOperations.DIV_OPERATION, a, b)
 
     operator fun Expression<T>.div(arg: T): Expression<T> = this / const(arg)
     operator fun T.div(arg: Expression<T>): Expression<T> = arg / this
+
+    override fun unaryOperation(operation: String, arg: Expression<T>): Expression<T> =
+        super<FunctionalExpressionRing>.unaryOperation(operation, arg)
+
+    override fun binaryOperation(operation: String, left: Expression<T>, right: Expression<T>): Expression<T> =
+        super<FunctionalExpressionRing>.binaryOperation(operation, left, right)
 }