From 4cebca51ef6a3c09a0e921f4a171e7a58bf8c560 Mon Sep 17 00:00:00 2001 From: Iaroslav Date: Sun, 20 Sep 2020 19:01:27 +0700 Subject: [PATCH] Add @author annotations, minor KDoc updates --- .../kotlin/scientifik/kmath/ast/MST.kt | 3 ++ .../kotlin/scientifik/kmath/ast/MstAlgebra.kt | 10 +++++ .../scientifik/kmath/ast/MstExpression.kt | 19 ++++++++ .../kotlin/scientifik/kmath/ast/parser.kt | 4 ++ .../kotlin/scientifik/kmath/asm/asm.kt | 15 +++++-- .../kmath/asm/internal/AsmBuilder.kt | 1 + .../scientifik/kmath/asm/internal/MstType.kt | 3 ++ .../kmath/asm/internal/codegenUtils.kt | 43 +++++++++++++++---- .../kmath/asm/internal/mapIntrinsics.kt | 5 +++ .../kmath/operations/AlgebraExtensions.kt | 5 +++ .../kmath/structures/FloatBuffer.kt | 1 + 11 files changed, 97 insertions(+), 12 deletions(-) diff --git a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MST.kt b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MST.kt index 0e8151c04..22b2efcda 100644 --- a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MST.kt +++ b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MST.kt @@ -6,6 +6,8 @@ import scientifik.kmath.operations.RealField /** * A Mathematical Syntax Tree node for mathematical expressions. + * + * @author Alexander Nozik */ sealed class MST { /** @@ -52,6 +54,7 @@ sealed class MST { * @receiver the algebra that provides operations. * @param node the node to evaluate. * @return the value of expression. + * @author Alexander Nozik */ fun Algebra.evaluate(node: MST): T = when (node) { is MST.Numeric -> (this as? NumericAlgebra)?.number(node.value) diff --git a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstAlgebra.kt b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstAlgebra.kt index 23deae24b..ac8765198 100644 --- a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstAlgebra.kt +++ b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstAlgebra.kt @@ -4,6 +4,8 @@ import scientifik.kmath.operations.* /** * [Algebra] over [MST] nodes. + * + * @author Alexander Nozik */ object MstAlgebra : NumericAlgebra { override fun number(value: Number): MST = MST.Numeric(value) @@ -19,6 +21,8 @@ object MstAlgebra : NumericAlgebra { /** * [Space] over [MST] nodes. + * + * @author Alexander Nozik */ object MstSpace : Space, NumericAlgebra { override val zero: MST = number(0.0) @@ -36,6 +40,8 @@ object MstSpace : Space, NumericAlgebra { /** * [Ring] over [MST] nodes. + * + * @author Alexander Nozik */ object MstRing : Ring, NumericAlgebra { override val zero: MST = number(0.0) @@ -57,6 +63,8 @@ object MstRing : Ring, NumericAlgebra { /** * [Field] over [MST] nodes. + * + * @author Alexander Nozik */ object MstField : Field { override val zero: MST = number(0.0) @@ -77,6 +85,8 @@ object MstField : Field { /** * [ExtendedField] over [MST] nodes. + * + * @author Iaroslav Postovalov */ object MstExtendedField : ExtendedField { override val zero: MST = number(0.0) diff --git a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstExpression.kt b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstExpression.kt index 293152cdd..71779ac96 100644 --- a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstExpression.kt +++ b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/MstExpression.kt @@ -11,6 +11,7 @@ import kotlin.contracts.contract * * @property algebra the algebra that provides operations. * @property mst the [MST] node. + * @author Alexander Nozik */ class MstExpression(val algebra: Algebra, val mst: MST) : Expression { private inner class InnerAlgebra(val arguments: Map) : NumericAlgebra { @@ -31,6 +32,8 @@ class MstExpression(val algebra: Algebra, val mst: MST) : Expression { /** * Builds [MstExpression] over [Algebra]. + * + * @author Alexander Nozik */ inline fun , E : Algebra> A.mst( mstAlgebra: E, @@ -39,6 +42,8 @@ inline fun , E : Algebra> A.mst( /** * Builds [MstExpression] over [Space]. + * + * @author Alexander Nozik */ inline fun Space.mstInSpace(block: MstSpace.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -47,6 +52,8 @@ inline fun Space.mstInSpace(block: MstSpace.() -> MST): Mst /** * Builds [MstExpression] over [Ring]. + * + * @author Alexander Nozik */ inline fun Ring.mstInRing(block: MstRing.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -55,6 +62,8 @@ inline fun Ring.mstInRing(block: MstRing.() -> MST): MstExp /** * Builds [MstExpression] over [Field]. + * + * @author Alexander Nozik */ inline fun Field.mstInField(block: MstField.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -63,6 +72,8 @@ inline fun Field.mstInField(block: MstField.() -> MST): Mst /** * Builds [MstExpression] over [ExtendedField]. + * + * @author Iaroslav Postovalov */ inline fun Field.mstInExtendedField(block: MstExtendedField.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -71,6 +82,8 @@ inline fun Field.mstInExtendedField(block: MstExtendedField /** * Builds [MstExpression] over [FunctionalExpressionSpace]. + * + * @author Alexander Nozik */ inline fun > FunctionalExpressionSpace.mstInSpace(block: MstSpace.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -79,6 +92,8 @@ inline fun > FunctionalExpressionSpace.mstIn /** * Builds [MstExpression] over [FunctionalExpressionRing]. + * + * @author Alexander Nozik */ inline fun > FunctionalExpressionRing.mstInRing(block: MstRing.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -87,6 +102,8 @@ inline fun > FunctionalExpressionRing.mstInRi /** * Builds [MstExpression] over [FunctionalExpressionField]. + * + * @author Alexander Nozik */ inline fun > FunctionalExpressionField.mstInField(block: MstField.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -95,6 +112,8 @@ inline fun > FunctionalExpressionField.mstIn /** * Builds [MstExpression] over [FunctionalExpressionExtendedField]. + * + * @author Iaroslav Postovalov */ inline fun > FunctionalExpressionExtendedField.mstInExtendedField(block: MstExtendedField.() -> MST): MstExpression { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } diff --git a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/parser.kt b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/parser.kt index cba335a8d..d83b12486 100644 --- a/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/parser.kt +++ b/kmath-ast/src/commonMain/kotlin/scientifik/kmath/ast/parser.kt @@ -17,6 +17,8 @@ import scientifik.kmath.operations.SpaceOperations /** * TODO move to core + * + * @author Alexander Nozik and Iaroslav Postovalov */ object ArithmeticsEvaluator : Grammar() { // TODO replace with "...".toRegex() when better-parse 0.4.1 is released @@ -85,6 +87,7 @@ object ArithmeticsEvaluator : Grammar() { * * @receiver the string to parse. * @return the [MST] node. + * @author Alexander Nozik */ fun String.tryParseMath(): ParseResult = ArithmeticsEvaluator.tryParseToEnd(this) @@ -93,5 +96,6 @@ fun String.tryParseMath(): ParseResult = ArithmeticsEvaluator.tryParseToEnd * * @receiver the string to parse. * @return the [MST] node. + * @author Alexander Nozik */ fun String.parseMath(): MST = ArithmeticsEvaluator.parseToEnd(this) diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/asm.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/asm.kt index ee0ea15ff..a5da51564 100644 --- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/asm.kt +++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/asm.kt @@ -11,7 +11,12 @@ import scientifik.kmath.operations.Algebra import kotlin.reflect.KClass /** - * Compile given MST to an Expression using AST compiler + * Compiles given MST to an Expression using AST compiler. + * + * @param type the target type. + * @param algebra the target algebra. + * @return the compiled expression. + * @author Alexander Nozik */ fun MST.compileWith(type: KClass, algebra: Algebra): Expression { fun AsmBuilder.visit(node: MST) { @@ -54,11 +59,15 @@ fun MST.compileWith(type: KClass, algebra: Algebra): Expression< } /** - * Compile an [MST] to ASM using given algebra + * Compiles an [MST] to ASM using given algebra. + * + * @author Alexander Nozik. */ inline fun Algebra.expression(mst: MST): Expression = mst.compileWith(T::class, this) /** - * Optimize performance of an [MstExpression] using ASM codegen + * Optimizes performance of an [MstExpression] using ASM codegen. + * + * @author Alexander Nozik. */ inline fun MstExpression.compile(): Expression = mst.compileWith(T::class, algebra) diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/AsmBuilder.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/AsmBuilder.kt index f8c159baf..1cf49a251 100644 --- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/AsmBuilder.kt +++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/AsmBuilder.kt @@ -20,6 +20,7 @@ import kotlin.reflect.KClass * @property algebra the algebra the applied AsmExpressions use. * @property className the unique class name of new loaded class. * @property invokeLabel0Visitor the function to apply to this object when generating invoke method, label 0. + * @author Iaroslav Postovalov */ internal class AsmBuilder internal constructor( private val classOfT: KClass<*>, diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/MstType.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/MstType.kt index bf73d304b..81e6791c1 100644 --- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/MstType.kt +++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/MstType.kt @@ -2,6 +2,9 @@ package scientifik.kmath.asm.internal import scientifik.kmath.ast.MST +/** + * Represents types known in [MST], numbers and general values. + */ internal enum class MstType { GENERAL, NUMBER; diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/codegenUtils.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/codegenUtils.kt index 021c8ae02..ab29d3614 100644 --- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/codegenUtils.kt +++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/codegenUtils.kt @@ -6,6 +6,9 @@ import org.objectweb.asm.commons.InstructionAdapter import scientifik.kmath.ast.MST import scientifik.kmath.expressions.Expression import scientifik.kmath.operations.Algebra +import scientifik.kmath.operations.FieldOperations +import scientifik.kmath.operations.RingOperations +import scientifik.kmath.operations.SpaceOperations import java.lang.reflect.Method import kotlin.contracts.InvocationKind import kotlin.contracts.contract @@ -13,20 +16,27 @@ import kotlin.reflect.KClass private val methodNameAdapters: Map, String> by lazy { hashMapOf( - "+" to 2 to "add", - "*" to 2 to "multiply", - "/" to 2 to "divide", - "+" to 1 to "unaryPlus", - "-" to 1 to "unaryMinus", - "-" to 2 to "minus" + SpaceOperations.PLUS_OPERATION to 2 to "add", + RingOperations.TIMES_OPERATION to 2 to "multiply", + FieldOperations.DIV_OPERATION to 2 to "divide", + SpaceOperations.PLUS_OPERATION to 1 to "unaryPlus", + SpaceOperations.MINUS_OPERATION to 1 to "unaryMinus", + SpaceOperations.MINUS_OPERATION to 2 to "minus" ) } +/** + * Returns ASM [Type] for given [KClass]. + * + * @author Iaroslav Postovalov + */ internal val KClass<*>.asm: Type get() = Type.getType(java) /** * Returns singleton array with this value if the [predicate] is true, returns empty array otherwise. + * + * @author Iaroslav Postovalov */ internal inline fun T.wrapToArrayIf(predicate: (T) -> Boolean): Array { contract { callsInPlace(predicate, InvocationKind.EXACTLY_ONCE) } @@ -35,11 +45,15 @@ internal inline fun T.wrapToArrayIf(predicate: (T) -> Boolean): Arra /** * Creates an [InstructionAdapter] from this [MethodVisitor]. + * + * @author Iaroslav Postovalov */ private fun MethodVisitor.instructionAdapter(): InstructionAdapter = InstructionAdapter(this) /** * Creates an [InstructionAdapter] from this [MethodVisitor] and applies [block] to it. + * + * @author Iaroslav Postovalov */ internal inline fun MethodVisitor.instructionAdapter(block: InstructionAdapter.() -> Unit): InstructionAdapter { contract { callsInPlace(block, InvocationKind.EXACTLY_ONCE) } @@ -48,6 +62,8 @@ internal inline fun MethodVisitor.instructionAdapter(block: InstructionAdapter.( /** * Constructs a [Label], then applies it to this visitor. + * + * @author Iaroslav Postovalov */ internal fun MethodVisitor.label(): Label = Label().also { visitLabel(it) } @@ -56,6 +72,8 @@ internal fun MethodVisitor.label(): Label = Label().also { visitLabel(it) } * * This methods helps to avoid collisions of class name to prevent loading several classes with the same name. If there * is a colliding class, change [collision] parameter or leave it `0` to check existing classes recursively. + * + * @author Iaroslav Postovalov */ internal tailrec fun buildName(mst: MST, collision: Int = 0): String { val name = "scientifik.kmath.asm.generated.AsmCompiledExpression_${mst.hashCode()}_$collision" @@ -75,6 +93,11 @@ internal inline fun ClassWriter(flags: Int, block: ClassWriter.() -> Unit): Clas return ClassWriter(flags).apply(block) } +/** + * Invokes [visitField] and applies [block] to the [FieldVisitor]. + * + * @author Iaroslav Postovalov + */ internal inline fun ClassWriter.visitField( access: Int, name: String, @@ -104,7 +127,7 @@ private fun AsmBuilder.findSpecific(context: Algebra, name: String, pa * Checks if the target [context] for code generation contains a method with needed [name] and arity, also builds * type expectation stack for needed arity. * - * @return `true` if contains, else `false`. + * @author Iaroslav Postovalov */ private fun AsmBuilder.buildExpectationStack( context: Algebra, @@ -136,7 +159,7 @@ private fun AsmBuilder.mapTypes(method: Method, parameterTypes: Array AsmBuilder.tryInvokeSpecific( context: Algebra, @@ -160,7 +183,9 @@ private fun AsmBuilder.tryInvokeSpecific( } /** - * Builds specialized algebra call with option to fallback to generic algebra operation accepting String. + * Builds specialized [context] call with option to fallback to generic algebra operation accepting [String]. + * + * @author Iaroslav Postovalov */ internal inline fun AsmBuilder.buildAlgebraOperationCall( context: Algebra, diff --git a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/mapIntrinsics.kt b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/mapIntrinsics.kt index 80e83c1bf..997dbbfe5 100644 --- a/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/mapIntrinsics.kt +++ b/kmath-ast/src/jvmMain/kotlin/scientifik/kmath/asm/internal/mapIntrinsics.kt @@ -2,6 +2,11 @@ package scientifik.kmath.asm.internal +/** + * Gets value with given [key] or throws [IllegalStateException] whenever it is not present. + * + * @author Iaroslav Postovalov + */ @JvmOverloads internal fun Map.getOrFail(key: K, default: V? = null): V = this[key] ?: default ?: error("Parameter not found: $key") diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt index 00b16dc98..fabfbdb49 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt @@ -24,6 +24,7 @@ fun Space.sum(data: Sequence): T = data.fold(zero) { left, right -> ad * @receiver the algebra that provides addition and division. * @param data the iterable to find average. * @return the average value. + * @author Iaroslav Postovalov */ fun Space.average(data: Iterable): T = sum(data) / data.count() @@ -33,6 +34,7 @@ fun Space.average(data: Iterable): T = sum(data) / data.count() * @receiver the algebra that provides addition and division. * @param data the sequence to find average. * @return the average value. + * @author Iaroslav Postovalov */ fun Space.average(data: Sequence): T = sum(data) / data.count() @@ -60,6 +62,7 @@ fun Sequence.sumWith(space: Space): T = space.sum(this) * @receiver the iterable to find average. * @param space the algebra that provides addition and division. * @return the average value. + * @author Iaroslav Postovalov */ fun Iterable.averageWith(space: Space): T = space.average(this) @@ -69,6 +72,7 @@ fun Iterable.averageWith(space: Space): T = space.average(this) * @receiver the sequence to find average. * @param space the algebra that provides addition and division. * @return the average value. + * @author Iaroslav Postovalov */ fun Sequence.averageWith(space: Space): T = space.average(this) @@ -98,6 +102,7 @@ fun Ring.power(arg: T, power: Int): T { * @param arg the base. * @param power the exponent. * @return the base raised to the power. + * @author Iaroslav Postovalov */ fun Field.power(arg: T, power: Int): T { require(power != 0 || arg != zero) { "The $zero raised to $power is not defined." } diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/FloatBuffer.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/FloatBuffer.kt index 3beb110cf..d1b99685c 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/FloatBuffer.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/FloatBuffer.kt @@ -6,6 +6,7 @@ import kotlin.contracts.contract * Specialized [MutableBuffer] implementation over [FloatArray]. * * @property array the underlying array. + * @author Iaroslav Postovalov */ inline class FloatBuffer(val array: FloatArray) : MutableBuffer { override val size: Int get() = array.size