Add reference to Commons Math implementation of InternalErf, fix markdown issues, rename prob package in examples to stat

2020-11-29 22:02:06 +07:00 · 2020-11-29 22:02:06 +07:00 · 5a3fccb455
commit 5a3fccb455
parent 12758d589e
15 changed files with 21 additions and 16 deletions
--- a/examples/src/main/kotlin/kscience/kmath/commons/prob/DistributionBenchmark.kt
+++ b/examples/src/main/kotlin/kscience/kmath/commons/prob/DistributionBenchmark.kt
@ -1,11 +1,8 @@
-package kscience.kmath.commons.prob
+package kscience.kmath.stat

 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.async
 import kotlinx.coroutines.runBlocking
-import kscience.kmath.stat.RandomGenerator
-import kscience.kmath.stat.blocking
-import kscience.kmath.stat.fromSource
 import kscience.kmath.stat.samplers.GaussianSampler
 import org.apache.commons.rng.simple.RandomSource
 import java.time.Duration
--- a/examples/src/main/kotlin/kscience/kmath/commons/prob/DistributionDemo.kt
+++ b/examples/src/main/kotlin/kscience/kmath/commons/prob/DistributionDemo.kt
@ -1,4 +1,4 @@
-package kscience.kmath.commons.prob
+package kscience.kmath.stat

 import kotlinx.coroutines.runBlocking
 import kscience.kmath.chains.Chain
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/distributions/NormalDistribution.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/distributions/NormalDistribution.kt
@ -9,6 +9,9 @@ import kscience.kmath.stat.samplers.NormalizedGaussianSampler
 import kscience.kmath.stat.samplers.ZigguratNormalizedGaussianSampler
 import kotlin.math.*

+/**
+ * Implements [UnivariateDistribution] for the normal (gaussian) distribution.
+ */
 public inline class NormalDistribution(public val sampler: GaussianSampler) : UnivariateDistribution<Double> {
    public constructor(
        mean: Double,
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/internal/InternalErf.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/internal/InternalErf.kt
@ -2,6 +2,10 @@ package kscience.kmath.stat.internal

 import kotlin.math.abs

+/**
+ * Based on Commons Math implementation.
+ * See [https://commons.apache.org/proper/commons-math/javadocs/api-3.3/org/apache/commons/math3/special/Erf.html].
+ */
 internal object InternalErf {
    fun erfc(x: Double): Double {
        if (abs(x) > 40) return if (x > 0) 0.0 else 2.0
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/AhrensDieterExponentialSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/AhrensDieterExponentialSampler.kt
@ -12,7 +12,7 @@ import kotlin.math.pow
 * Sampling from an [exponential distribution](http://mathworld.wolfram.com/ExponentialDistribution.html).
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/AhrensDieterExponentialSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/AhrensDieterExponentialSampler.html].
 */
 public class AhrensDieterExponentialSampler private constructor(public val mean: Double) : Sampler<Double> {
    public override fun sample(generator: RandomGenerator): Chain<Double> = generator.chain {
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/AhrensDieterMarsagliaTsangGammaSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/AhrensDieterMarsagliaTsangGammaSampler.kt
@ -15,7 +15,8 @@ import kotlin.math.*
 *    Marsaglia and Tsang, A Simple Method for Generating Gamma Variables. ACM Transactions on Mathematical Software, Volume 26 Issue 3, September, 2000.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/AhrensDieterMarsagliaTsangGammaSampler.html
+ *
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/AhrensDieterMarsagliaTsangGammaSampler.html].
 */
 public class AhrensDieterMarsagliaTsangGammaSampler private constructor(
    alpha: Double,
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/AliasMethodDiscreteSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/AliasMethodDiscreteSampler.kt
@ -34,7 +34,7 @@ import kotlin.math.min
 * that exploit the power of 2.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/AliasMethodDiscreteSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/AliasMethodDiscreteSampler.html].
 */
 public open class AliasMethodDiscreteSampler private constructor(
    // Deliberate direct storage of input arrays
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/BoxMullerNormalizedGaussianSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/BoxMullerNormalizedGaussianSampler.kt
@ -11,7 +11,7 @@ import kotlin.math.*
 * distribution.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.html].
 */
 public class BoxMullerNormalizedGaussianSampler private constructor() : NormalizedGaussianSampler, Sampler<Double> {
    private var nextGaussian: Double = Double.NaN
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/GaussianSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/GaussianSampler.kt
@ -9,7 +9,7 @@ import kscience.kmath.stat.Sampler
 * Sampling from a Gaussian distribution with given mean and standard deviation.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/GaussianSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/GaussianSampler.html].
 *
 * @property mean the mean of the distribution.
 * @property standardDeviation the variance of the distribution.
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/KempSmallMeanPoissonSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/KempSmallMeanPoissonSampler.kt
@ -16,7 +16,7 @@ import kotlin.math.exp
 * Sampling uses 1 call to UniformRandomProvider.nextDouble(). This method provides an alternative to the SmallMeanPoissonSampler for slow generators of double.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/KempSmallMeanPoissonSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/KempSmallMeanPoissonSampler.html].
 */
 public class KempSmallMeanPoissonSampler private constructor(
    private val p0: Double,
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/LargeMeanPoissonSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/LargeMeanPoissonSampler.kt
@ -18,7 +18,7 @@ import kotlin.math.*
 * This sampler is suitable for mean >= 40.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/LargeMeanPoissonSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/LargeMeanPoissonSampler.html].
 */
 public class LargeMeanPoissonSampler private constructor(public val mean: Double) : Sampler<Int> {
    private val exponential: Sampler<Double> = AhrensDieterExponentialSampler.of(1.0)
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/MarsagliaNormalizedGaussianSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/MarsagliaNormalizedGaussianSampler.kt
@ -13,7 +13,7 @@ import kotlin.math.sqrt
 * [BoxMullerNormalizedGaussianSampler].
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.html]
 */
 public class MarsagliaNormalizedGaussianSampler private constructor() : NormalizedGaussianSampler, Sampler<Double> {
    private var nextGaussian = Double.NaN
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/PoissonSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/PoissonSampler.kt
@ -14,7 +14,7 @@ import kscience.kmath.stat.Sampler
 *   Devroye, Luc. (1981). The Computer Generation of Poisson Random Variables Computing vol. 26 pp. 197-207.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/PoissonSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/PoissonSampler.html].
 */
 public class PoissonSampler private constructor(mean: Double) : Sampler<Int> {
    private val poissonSamplerDelegate: Sampler<Int> = of(mean)
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/SmallMeanPoissonSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/SmallMeanPoissonSampler.kt
@ -17,7 +17,7 @@ import kotlin.math.exp
 *
 * Based on Commons RNG implementation.
 *
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/SmallMeanPoissonSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/SmallMeanPoissonSampler.html].
 */
 public class SmallMeanPoissonSampler private constructor(mean: Double) : Sampler<Int> {
    private val p0: Double = exp(-mean)
--- a/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/ZigguratNormalizedGaussianSampler.kt
+++ b/kmath-stat/src/commonMain/kotlin/kscience/kmath/stat/samplers/ZigguratNormalizedGaussianSampler.kt
@ -12,7 +12,7 @@ import kotlin.math.*
 * implementation has been adapted from the C code provided therein.
 *
 * Based on Commons RNG implementation.
- * See https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.html
+ * See [https://commons.apache.org/proper/commons-rng/commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.html].
 */
 public class ZigguratNormalizedGaussianSampler private constructor() :
    NormalizedGaussianSampler, Sampler<Double> {