From 4d160b81b9620c6ab47e244f727db62355948479 Mon Sep 17 00:00:00 2001 From: Iaroslav Postovalov Date: Tue, 23 Mar 2021 19:48:12 +0700 Subject: [PATCH] Improve KDoc comments for kmath-functions --- .../kscience/kmath/functions/Polynomial.kt | 24 +++++++++++++---- .../kscience/kmath/integration/Integrator.kt | 6 ++--- .../kmath/integration/UnivariateIntegrand.kt | 2 +- .../kmath/interpolation/SplineInterpolator.kt | 7 +++-- .../kmath/interpolation/XYPointSet.kt | 27 +++++++++++++++++++ 5 files changed, 55 insertions(+), 11 deletions(-) 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 9f4e21991..550785812 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 @@ -10,8 +10,9 @@ import kotlin.math.max import kotlin.math.pow /** - * Polynomial coefficients without fixation on specific context they are applied to - * @param coefficients constant is the leftmost coefficient + * Polynomial coefficients model without fixation on specific context they are applied to. + * + * @param coefficients constant is the leftmost coefficient. */ public inline class Polynomial(public val coefficients: List) @@ -21,8 +22,14 @@ public inline class Polynomial(public val coefficients: List) @Suppress("FunctionName") public fun Polynomial(vararg coefficients: T): Polynomial = Polynomial(coefficients.toList()) +/** + * Evaluates the value of the given double polynomial for given double argument. + */ public fun Polynomial.value(): Double = coefficients.reduceIndexed { index, acc, d -> acc + d.pow(index) } +/** + * Evaluates the value of the given polynomial for given argument. + */ public fun > Polynomial.value(ring: C, arg: T): T = ring { if (coefficients.isEmpty()) return@ring zero var res = coefficients.first() @@ -38,19 +45,23 @@ public fun > Polynomial.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 > Polynomial.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( private val ring: C, ) : Group>, ScaleOperations> where C : Ring, C : ScaleOperations { public override val zero: Polynomial = Polynomial(emptyList()) - override fun Polynomial.unaryMinus(): Polynomial = with(ring) { + override fun Polynomial.unaryMinus(): Polynomial = ring { Polynomial(coefficients.map { -it }) } @@ -67,6 +78,9 @@ public class PolynomialSpace( public override fun scale(a: Polynomial, value: Double): Polynomial = ring { Polynomial(List(a.coefficients.size) { index -> a.coefficients[index] * value }) } + /** + * Evaluates the polynomial for the given value [arg]. + */ public operator fun Polynomial.invoke(arg: T): T = value(ring, arg) } diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/Integrator.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/Integrator.kt index ebc53ad2e..e421fb680 100644 --- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/Integrator.kt +++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/Integrator.kt @@ -1,11 +1,11 @@ package space.kscience.kmath.integration /** - * A general interface for all integrators + * A general interface for all integrators. */ public interface Integrator { /** - * 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 -} \ No newline at end of file +} diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/UnivariateIntegrand.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/UnivariateIntegrand.kt index 9389318e8..ca4bbf6b8 100644 --- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/UnivariateIntegrand.kt +++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/UnivariateIntegrand.kt @@ -61,4 +61,4 @@ public fun UnivariateIntegrator.integrate( return integrate( UnivariateIntegrand(function, *features.toTypedArray()) ).value ?: error("Unexpected: no value after integration.") -} \ No newline at end of file +} diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/SplineInterpolator.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/SplineInterpolator.kt index ddbe743f0..ef75a1ef8 100644 --- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/SplineInterpolator.kt +++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/SplineInterpolator.kt @@ -8,8 +8,11 @@ import space.kscience.kmath.operations.invoke import space.kscience.kmath.structures.MutableBufferFactory /** - * Generic spline interpolator. Not recommended for performance critical places, use platform-specific and type specific ones. - * Based on https://github.com/apache/commons-math/blob/eb57d6d457002a0bb5336d789a3381a24599affe/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java + * Generic spline interpolator. Not recommended for performance critical places, use platform-specific and type + * 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>( public override val algebra: Field, diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/XYPointSet.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/XYPointSet.kt index 1ff7b6351..2b1312c0f 100644 --- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/XYPointSet.kt +++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/XYPointSet.kt @@ -3,13 +3,40 @@ package space.kscience.kmath.interpolation import space.kscience.kmath.nd.Structure2D 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 { + /** + * The size of all the involved buffers. + */ public val size: Int + + /** + * The buffer of X values. + */ public val x: Buffer + + /** + * The buffer of Y values. + */ public val y: Buffer } +/** + * 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 : XYPointSet { + /** + * The buffer of Z values. + */ public val z: Buffer }