Merge pull request #258 from mipt-npm/commandertvis/doc

KDoc API reference updates
This commit is contained in:
Alexander Nozik 2021-03-23 15:55:51 +03:00 committed by GitHub
commit 570642e56d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 116 additions and 31 deletions

View File

@ -24,7 +24,6 @@ import space.kscience.kmath.misc.UnstableKMathAPI
*/ */
@UnstableKMathAPI @UnstableKMathAPI
public interface DoubleDomain : Domain<Double> { public interface DoubleDomain : Domain<Double> {
/** /**
* Global lower edge * Global lower edge
* @param num axis number * @param num axis number

View File

@ -3,7 +3,10 @@ package space.kscience.kmath.linear
import space.kscience.kmath.nd.as1D 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 <sup>-1</sup> &middot; B*, where *A* and *B* are matrices or
* vectors.
*
* @param T the type of items.
*/ */
public interface LinearSolver<T : Any> { public interface LinearSolver<T : Any> {
/** /**
@ -23,7 +26,7 @@ public interface LinearSolver<T : Any> {
} }
/** /**
* Convert matrix to vector if it is possible * Convert matrix to vector if it is possible.
*/ */
public fun <T : Any> Matrix<T>.asVector(): Point<T> = public fun <T : Any> Matrix<T>.asVector(): Point<T> =
if (this.colNum == 1) if (this.colNum == 1)
@ -31,4 +34,11 @@ public fun <T : Any> Matrix<T>.asVector(): Point<T> =
else else
error("Can't convert matrix with more than one column to vector") error("Can't convert matrix with more than one column to vector")
/**
* Creates an n &times; 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 <T : Any> Point<T>.asMatrix(): VirtualMatrix<T> = VirtualMatrix(size, 1) { i, _ -> get(i) } public fun <T : Any> Point<T>.asMatrix(): VirtualMatrix<T> = VirtualMatrix(size, 1) { i, _ -> get(i) }

View File

@ -17,6 +17,8 @@ public typealias Matrix<T> = Structure2D<T>
/** /**
* Alias or using [Buffer] as a point/vector in a many-dimensional space. * 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<T> = Buffer<T> public typealias Point<T> = Buffer<T>

View File

@ -100,8 +100,8 @@ public fun <T : Any> Algebra<T>.bindSymbol(symbol: Symbol): T = bindSymbol(symbo
public inline operator fun <A : Algebra<*>, R> A.invoke(block: A.() -> R): R = run(block) public inline operator fun <A : Algebra<*>, R> A.invoke(block: A.() -> R): R = run(block)
/** /**
* Represents linear space without neutral element, i.e. algebraic structure with associative, binary operation [add] * Represents group without neutral element (also known as inverse semigroup), i.e. algebraic structure with
* and scalar multiplication [multiply]. * associative, binary operation [add].
* *
* @param T the type of element of this semispace. * @param T the type of element of this semispace.
*/ */
@ -177,7 +177,7 @@ public interface GroupOperations<T> : Algebra<T> {
} }
/** /**
* 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. * @param T the type of element of this semispace.
*/ */
@ -189,8 +189,8 @@ public interface Group<T> : GroupOperations<T> {
} }
/** /**
* Represents rng, i.e. algebraic structure with associative, binary, commutative operation [add] and associative, * Represents ring without multiplicative and additive identities, i.e. algebraic structure with
* operation [multiply] distributive over [add]. * associative, binary, commutative operation [add] and associative, operation [multiply] distributive over [add].
* *
* @param T the type of element of this semiring. * @param T the type of element of this semiring.
*/ */
@ -238,7 +238,7 @@ public interface Ring<T> : Group<T>, RingOperations<T> {
} }
/** /**
* 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. * [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. * @param T the type of element of this semifield.
@ -276,10 +276,11 @@ public interface FieldOperations<T> : RingOperations<T> {
} }
/** /**
* Represents field, i.e. algebraic structure with three operations: associative "addition" and "multiplication", * Represents field, i.e. algebraic structure with three operations: associative, commutative addition and
* and "division" and their neutral elements. * 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<T> : Ring<T>, FieldOperations<T>, ScaleOperations<T>, NumericAlgebra<T> { public interface Field<T> : Ring<T>, FieldOperations<T>, ScaleOperations<T>, NumericAlgebra<T> {
override fun number(value: Number): T = scale(one, value.toDouble()) override fun number(value: Number): T = scale(one, value.toDouble())

View File

@ -12,8 +12,8 @@ import kotlin.math.max
import kotlin.math.min import kotlin.math.min
import kotlin.math.sign import kotlin.math.sign
public typealias Magnitude = UIntArray private typealias Magnitude = UIntArray
public typealias TBase = ULong private typealias TBase = ULong
/** /**
* Kotlin Multiplatform implementation of Big Integer numbers (KBigInteger). * Kotlin Multiplatform implementation of Big Integer numbers (KBigInteger).
@ -358,6 +358,9 @@ private fun stripLeadingZeros(mag: Magnitude): Magnitude {
return mag.sliceArray(IntRange(0, resSize)) return mag.sliceArray(IntRange(0, resSize))
} }
/**
* Returns the absolute value of the given value [x].
*/
public fun abs(x: BigInt): BigInt = x.abs() public fun abs(x: BigInt): BigInt = x.abs()
/** /**

View File

@ -2,14 +2,28 @@ package space.kscience.kmath.functions
import space.kscience.kmath.operations.Ring 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<T, R> { public fun interface Piecewise<T, R> {
/**
* Returns the appropriate sub-function for given piece key.
*/
public fun findPiece(arg: T): R? public fun findPiece(arg: T): R?
} }
/**
* Represents piecewise-defined function where all the sub-functions are polynomials.
*/
public fun interface PiecewisePolynomial<T : Any> : Piecewise<T, Polynomial<T>> public fun interface PiecewisePolynomial<T : Any> : Piecewise<T, Polynomial<T>>
/** /**
* 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<T : Comparable<T>>(delimiter: T) : public class OrderedPiecewisePolynomial<T : Comparable<T>>(delimiter: T) :
PiecewisePolynomial<T> { PiecewisePolynomial<T> {
@ -17,8 +31,10 @@ public class OrderedPiecewisePolynomial<T : Comparable<T>>(delimiter: T) :
private val pieces: MutableList<Polynomial<T>> = arrayListOf() private val pieces: MutableList<Polynomial<T>> = arrayListOf()
/** /**
* Dynamically add a piece to the "right" side (beyond maximum argument value of previous piece) * 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, a error is thrown. *
* @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<T>) { public fun putRight(right: T, piece: Polynomial<T>) {
require(right > delimiters.last()) { "New delimiter should be to the right of old one" } require(right > delimiters.last()) { "New delimiter should be to the right of old one" }
@ -26,13 +42,19 @@ public class OrderedPiecewisePolynomial<T : Comparable<T>>(delimiter: T) :
pieces.add(piece) 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<T>) { public fun putLeft(left: T, piece: Polynomial<T>) {
require(left < delimiters.first()) { "New delimiter should be to the left of old one" } require(left < delimiters.first()) { "New delimiter should be to the left of old one" }
delimiters.add(0, left) delimiters.add(0, left)
pieces.add(0, piece) pieces.add(0, piece)
} }
override fun findPiece(arg: T): Polynomial<T>? { public override fun findPiece(arg: T): Polynomial<T>? {
if (arg < delimiters.first() || arg >= delimiters.last()) if (arg < delimiters.first() || arg >= delimiters.last())
return null return null
else { else {
@ -46,9 +68,10 @@ public class OrderedPiecewisePolynomial<T : Comparable<T>>(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 <T : Comparable<T>, C : Ring<T>> PiecewisePolynomial<T>.value(ring: C, arg: T): T? = public fun <T : Comparable<T>, C : Ring<T>> PiecewisePolynomial<T>.value(ring: C, arg: T): T? =
findPiece(arg)?.value(ring, arg) findPiece(arg)?.value(ring, arg)
public fun <T : Comparable<T>, C : Ring<T>> PiecewisePolynomial<T>.asFunction(ring: C): (T) -> T? = { value(ring, it) } public fun <T : Comparable<T>, C : Ring<T>> PiecewisePolynomial<T>.asFunction(ring: C): (T) -> T? = { value(ring, it) }

View File

@ -10,16 +10,26 @@ import kotlin.math.max
import kotlin.math.pow import kotlin.math.pow
/** /**
* Polynomial coefficients without fixation on specific context they are applied to * Polynomial coefficients model without fixation on specific context they are applied to.
* @param coefficients constant is the leftmost coefficient *
* @param coefficients constant is the leftmost coefficient.
*/ */
public inline class Polynomial<T : Any>(public val coefficients: List<T>) public inline class Polynomial<T : Any>(public val coefficients: List<T>)
/**
* Returns a [Polynomial] instance with given [coefficients].
*/
@Suppress("FunctionName") @Suppress("FunctionName")
public fun <T : Any> Polynomial(vararg coefficients: T): Polynomial<T> = Polynomial(coefficients.toList()) public fun <T : Any> Polynomial(vararg coefficients: T): Polynomial<T> = Polynomial(coefficients.toList())
/**
* Evaluates the value of the given double polynomial for given double argument.
*/
public fun Polynomial<Double>.value(): Double = coefficients.reduceIndexed { index, acc, d -> acc + d.pow(index) } public fun Polynomial<Double>.value(): Double = coefficients.reduceIndexed { index, acc, d -> acc + d.pow(index) }
/**
* Evaluates the value of the given polynomial for given argument.
*/
public fun <T : Any, C : Ring<T>> Polynomial<T>.value(ring: C, arg: T): T = ring { public fun <T : Any, C : Ring<T>> Polynomial<T>.value(ring: C, arg: T): T = ring {
if (coefficients.isEmpty()) return@ring zero if (coefficients.isEmpty()) return@ring zero
var res = coefficients.first() var res = coefficients.first()
@ -35,19 +45,23 @@ public fun <T : Any, C : Ring<T>> Polynomial<T>.value(ring: C, arg: T): T = ring
} }
/** /**
* Represent the polynomial as a regular context-less function * Represent the polynomial as a regular context-less function.
*/ */
public fun <T : Any, C : Ring<T>> Polynomial<T>.asFunction(ring: C): (T) -> T = { value(ring, it) } public fun <T : Any, C : Ring<T>> Polynomial<T>.asFunction(ring: C): (T) -> T = { value(ring, it) }
/** /**
* An algebra for polynomials * Space of polynomials.
*
* @param T the type of operated polynomials.
* @param C the intersection of [Ring] of [T] and [ScaleOperations] of [T].
* @param ring the [C] instance.
*/ */
public class PolynomialSpace<T : Any, C>( public class PolynomialSpace<T : Any, C>(
private val ring: C, private val ring: C,
) : Group<Polynomial<T>>, ScaleOperations<Polynomial<T>> where C : Ring<T>, C : ScaleOperations<T> { ) : Group<Polynomial<T>>, ScaleOperations<Polynomial<T>> where C : Ring<T>, C : ScaleOperations<T> {
public override val zero: Polynomial<T> = Polynomial(emptyList()) public override val zero: Polynomial<T> = Polynomial(emptyList())
override fun Polynomial<T>.unaryMinus(): Polynomial<T> = with(ring) { override fun Polynomial<T>.unaryMinus(): Polynomial<T> = ring {
Polynomial(coefficients.map { -it }) Polynomial(coefficients.map { -it })
} }
@ -64,6 +78,9 @@ public class PolynomialSpace<T : Any, C>(
public override fun scale(a: Polynomial<T>, value: Double): Polynomial<T> = public override fun scale(a: Polynomial<T>, value: Double): Polynomial<T> =
ring { Polynomial(List(a.coefficients.size) { index -> a.coefficients[index] * value }) } ring { Polynomial(List(a.coefficients.size) { index -> a.coefficients[index] * value }) }
/**
* Evaluates the polynomial for the given value [arg].
*/
public operator fun Polynomial<T>.invoke(arg: T): T = value(ring, arg) public operator fun Polynomial<T>.invoke(arg: T): T = value(ring, arg)
} }

View File

@ -1,11 +1,11 @@
package space.kscience.kmath.integration package space.kscience.kmath.integration
/** /**
* A general interface for all integrators * A general interface for all integrators.
*/ */
public interface Integrator<I : Integrand> { public interface Integrator<I : Integrand> {
/** /**
* Run one integration pass and return a new [Integrand] with a new set of features * Runs one integration pass and return a new [Integrand] with a new set of features.
*/ */
public fun integrate(integrand: I): I public fun integrate(integrand: I): I
} }

View File

@ -61,4 +61,4 @@ public fun UnivariateIntegrator<Double>.integrate(
return integrate( return integrate(
UnivariateIntegrand(function, *features.toTypedArray()) UnivariateIntegrand(function, *features.toTypedArray())
).value ?: error("Unexpected: no value after integration.") ).value ?: error("Unexpected: no value after integration.")
} }

View File

@ -8,8 +8,11 @@ import space.kscience.kmath.operations.invoke
import space.kscience.kmath.structures.MutableBufferFactory import space.kscience.kmath.structures.MutableBufferFactory
/** /**
* Generic spline interpolator. Not recommended for performance critical places, use platform-specific and type specific ones. * Generic spline interpolator. Not recommended for performance critical places, use platform-specific and type
* Based on https://github.com/apache/commons-math/blob/eb57d6d457002a0bb5336d789a3381a24599affe/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java * specific ones.
*
* Based on
* https://github.com/apache/commons-math/blob/eb57d6d457002a0bb5336d789a3381a24599affe/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java
*/ */
public class SplineInterpolator<T : Comparable<T>>( public class SplineInterpolator<T : Comparable<T>>(
public override val algebra: Field<T>, public override val algebra: Field<T>,

View File

@ -3,13 +3,40 @@ package space.kscience.kmath.interpolation
import space.kscience.kmath.nd.Structure2D import space.kscience.kmath.nd.Structure2D
import space.kscience.kmath.structures.Buffer import space.kscience.kmath.structures.Buffer
/**
* Pair of associated buffers for X and Y axes values.
*
* @param X the type of X values.
* @param Y the type of Y values.
*/
public interface XYPointSet<X, Y> { public interface XYPointSet<X, Y> {
/**
* The size of all the involved buffers.
*/
public val size: Int public val size: Int
/**
* The buffer of X values.
*/
public val x: Buffer<X> public val x: Buffer<X>
/**
* The buffer of Y values.
*/
public val y: Buffer<Y> public val y: Buffer<Y>
} }
/**
* Triple of associated buffers for X, Y, and Z axes values.
*
* @param X the type of X values.
* @param Y the type of Y values.
* @param Z the type of Z values.
*/
public interface XYZPointSet<X, Y, Z> : XYPointSet<X, Y> { public interface XYZPointSet<X, Y, Z> : XYPointSet<X, Y> {
/**
* The buffer of Z values.
*/
public val z: Buffer<Z> public val z: Buffer<Z>
} }