From 67aa173927c3f50dcea398d201236c54ad5fe4e0 Mon Sep 17 00:00:00 2001 From: Iaroslav Postovalov Date: Mon, 22 Mar 2021 16:11:54 +0700 Subject: [PATCH] Some documentation updates --- .../kscience/kmath/domains/DoubleDomain.kt | 1 - .../kscience/kmath/linear/LinearSolver.kt | 14 ++++++-- .../kscience/kmath/linear/LinearSpace.kt | 2 ++ .../kscience/kmath/operations/Algebra.kt | 19 +++++----- .../space/kscience/kmath/operations/BigInt.kt | 7 ++-- .../kscience/kmath/functions/Piecewise.kt | 35 +++++++++++++++---- .../kscience/kmath/functions/Polynomial.kt | 3 ++ 7 files changed, 61 insertions(+), 20 deletions(-) diff --git a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/DoubleDomain.kt b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/DoubleDomain.kt index 057a4a344..154763159 100644 --- a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/DoubleDomain.kt +++ b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/DoubleDomain.kt @@ -24,7 +24,6 @@ import space.kscience.kmath.misc.UnstableKMathAPI */ @UnstableKMathAPI public interface DoubleDomain : Domain { - /** * Global lower edge * @param num axis number diff --git a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSolver.kt b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSolver.kt index af136c552..3e2dbee3f 100644 --- a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSolver.kt +++ b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSolver.kt @@ -3,7 +3,10 @@ package space.kscience.kmath.linear import space.kscience.kmath.nd.as1D /** - * A group of methods to resolve equation A dot X = B, where A and B are matrices or vectors + * A group of methods to solve for *X* in equation *X = A -1 · B*, where *A* and *B* are matrices or + * vectors. + * + * @param T the type of items. */ public interface LinearSolver { /** @@ -23,7 +26,7 @@ public interface LinearSolver { } /** - * Convert matrix to vector if it is possible + * Convert matrix to vector if it is possible. */ public fun Matrix.asVector(): Point = if (this.colNum == 1) @@ -31,4 +34,11 @@ public fun Matrix.asVector(): Point = else error("Can't convert matrix with more than one column to vector") +/** + * Creates an n × 1 [VirtualMatrix], where n is the size of the given buffer. + * + * @param T the type of elements contained in the buffer. + * @receiver a buffer. + * @return the new matrix. + */ public fun Point.asMatrix(): VirtualMatrix = VirtualMatrix(size, 1) { i, _ -> get(i) } diff --git a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSpace.kt b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSpace.kt index 6a587270b..921f4c79c 100644 --- a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSpace.kt +++ b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/linear/LinearSpace.kt @@ -17,6 +17,8 @@ public typealias Matrix = Structure2D /** * Alias or using [Buffer] as a point/vector in a many-dimensional space. + * + * @param T the type of elements contained in the buffer. */ public typealias Point = Buffer diff --git a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt index 9f57bc4c1..960b7581c 100644 --- a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt +++ b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt @@ -100,8 +100,8 @@ public fun Algebra.bindSymbol(symbol: Symbol): T = bindSymbol(symbo public inline operator fun , R> A.invoke(block: A.() -> R): R = run(block) /** - * Represents linear space without neutral element, i.e. algebraic structure with associative, binary operation [add] - * and scalar multiplication [multiply]. + * Represents group without neutral element (also known as inverse semigroup), i.e. algebraic structure with + * associative, binary operation [add]. * * @param T the type of element of this semispace. */ @@ -177,7 +177,7 @@ public interface GroupOperations : Algebra { } /** - * Represents linear space with neutral element, i.e. algebraic structure with associative, binary operation [add]. + * Represents group, i.e. algebraic structure with associative, binary operation [add]. * * @param T the type of element of this semispace. */ @@ -189,8 +189,8 @@ public interface Group : GroupOperations { } /** - * Represents rng, i.e. algebraic structure with associative, binary, commutative operation [add] and associative, - * operation [multiply] distributive over [add]. + * Represents ring without multiplicative and additive identities, i.e. algebraic structure with + * associative, binary, commutative operation [add] and associative, operation [multiply] distributive over [add]. * * @param T the type of element of this semiring. */ @@ -238,7 +238,7 @@ public interface Ring : Group, RingOperations { } /** - * Represents field without identity elements, i.e. algebraic structure with associative, binary, commutative operations + * Represents field without without multiplicative and additive identities, i.e. algebraic structure with associative, binary, commutative operations * [add] and [multiply]; binary operation [divide] as multiplication of left operand by reciprocal of right one. * * @param T the type of element of this semifield. @@ -276,10 +276,11 @@ public interface FieldOperations : RingOperations { } /** - * Represents field, i.e. algebraic structure with three operations: associative "addition" and "multiplication", - * and "division" and their neutral elements. + * Represents field, i.e. algebraic structure with three operations: associative, commutative addition and + * multiplication, and division. **This interface differs from the eponymous mathematical definition: fields in KMath + * also support associative multiplication by scalar.** * - * @param T the type of element of this semifield. + * @param T the type of element of this field. */ public interface Field : Ring, FieldOperations, ScaleOperations, NumericAlgebra { override fun number(value: Number): T = scale(one, value.toDouble()) diff --git a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/BigInt.kt b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/BigInt.kt index 55bb68850..b5e27575b 100644 --- a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/BigInt.kt +++ b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/BigInt.kt @@ -12,8 +12,8 @@ import kotlin.math.max import kotlin.math.min import kotlin.math.sign -public typealias Magnitude = UIntArray -public typealias TBase = ULong +private typealias Magnitude = UIntArray +private typealias TBase = ULong /** * Kotlin Multiplatform implementation of Big Integer numbers (KBigInteger). @@ -358,6 +358,9 @@ private fun stripLeadingZeros(mag: Magnitude): Magnitude { return mag.sliceArray(IntRange(0, resSize)) } +/** + * Returns the absolute value of the given value [x]. + */ public fun abs(x: BigInt): BigInt = x.abs() /** diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Piecewise.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Piecewise.kt index d2470a4b4..3510973be 100644 --- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Piecewise.kt +++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Piecewise.kt @@ -2,14 +2,28 @@ package space.kscience.kmath.functions import space.kscience.kmath.operations.Ring +/** + * Represents piecewise-defined function. + * + * @param T the piece key type. + * @param R the sub-function type. + */ public fun interface Piecewise { + /** + * Returns the appropriate sub-function for given piece key. + */ public fun findPiece(arg: T): R? } +/** + * Represents piecewise-defined function where all the sub-functions are polynomials. + */ public fun interface PiecewisePolynomial : Piecewise> /** - * Ordered list of pieces in piecewise function + * Basic [Piecewise] implementation where all the pieces are ordered by the [Comparable] type instances. + * + * @param T the comparable piece key type. */ public class OrderedPiecewisePolynomial>(delimiter: T) : PiecewisePolynomial { @@ -17,8 +31,10 @@ public class OrderedPiecewisePolynomial>(delimiter: T) : private val pieces: MutableList> = arrayListOf() /** - * Dynamically add a piece to the "right" side (beyond maximum argument value of previous piece) - * @param right new rightmost position. If is less then current rightmost position, a error is thrown. + * Dynamically adds a piece to the right side (beyond maximum argument value of previous piece) + * + * @param right new rightmost position. If is less then current rightmost position, an error is thrown. + * @param piece the sub-function. */ public fun putRight(right: T, piece: Polynomial) { require(right > delimiters.last()) { "New delimiter should be to the right of old one" } @@ -26,13 +42,19 @@ public class OrderedPiecewisePolynomial>(delimiter: T) : pieces.add(piece) } + /** + * Dynamically adds a piece to the left side (beyond maximum argument value of previous piece) + * + * @param left the new leftmost position. If is less then current rightmost position, an error is thrown. + * @param piece the sub-function. + */ public fun putLeft(left: T, piece: Polynomial) { require(left < delimiters.first()) { "New delimiter should be to the left of old one" } delimiters.add(0, left) pieces.add(0, piece) } - override fun findPiece(arg: T): Polynomial? { + public override fun findPiece(arg: T): Polynomial? { if (arg < delimiters.first() || arg >= delimiters.last()) return null else { @@ -46,9 +68,10 @@ public class OrderedPiecewisePolynomial>(delimiter: T) : } /** - * Return a value of polynomial function with given [ring] an given [arg] or null if argument is outside of piecewise definition. + * Return a value of polynomial function with given [ring] an given [arg] or null if argument is outside of piecewise + * definition. */ public fun , C : Ring> PiecewisePolynomial.value(ring: C, arg: T): T? = findPiece(arg)?.value(ring, arg) -public fun , C : Ring> PiecewisePolynomial.asFunction(ring: C): (T) -> T? = { value(ring, it) } \ No newline at end of file +public fun , C : Ring> PiecewisePolynomial.asFunction(ring: C): (T) -> T? = { value(ring, it) } diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Polynomial.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Polynomial.kt index 049909fe1..9f4e21991 100644 --- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Polynomial.kt +++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Polynomial.kt @@ -15,6 +15,9 @@ import kotlin.math.pow */ public inline class Polynomial(public val coefficients: List) +/** + * Returns a [Polynomial] instance with given [coefficients]. + */ @Suppress("FunctionName") public fun Polynomial(vararg coefficients: T): Polynomial = Polynomial(coefficients.toList())