From 27a252b63700782b5005ac987686641a9f151031 Mon Sep 17 00:00:00 2001
From: Alexander Nozik <altavir@gmail.com>
Date: Sun, 10 Apr 2022 11:31:52 +0300
Subject: [PATCH] Accept changes, Update documentation

---
 .../space/kscience/kmath/domains/HyperSquareDomain.kt | 11 ++++++-----
 .../kscience/kmath/histogram/DoubleHistogramGroup.kt  |  4 ++--
 .../kscience/kmath/histogram/IndexedHistogramGroup.kt |  6 +++---
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/HyperSquareDomain.kt b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/HyperSquareDomain.kt
index 2fac442e7..485416a69 100644
--- a/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/HyperSquareDomain.kt
+++ b/kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains/HyperSquareDomain.kt
@@ -11,16 +11,17 @@ import space.kscience.kmath.structures.DoubleBuffer
 import space.kscience.kmath.structures.indices
 
 /**
- *
- * HyperSquareDomain class.
- *
- * @author Alexander Nozik
+ * A hyper-square (or hyper-cube) real-space domain. It is formed by a [Buffer] of [lower] boundaries
+ * and a [Buffer] of upper boundaries. Upper should be greater or equals than lower.
  */
 @UnstableKMathAPI
 public class HyperSquareDomain(public val lower: Buffer<Double>, public val upper: Buffer<Double>) : DoubleDomain {
     init {
         require(lower.size == upper.size) {
-            "Domain borders size mismatch. Lower borders size is ${lower.size}, but upper borders size is ${upper.size}"
+            "Domain borders size mismatch. Lower borders size is ${lower.size}, but upper borders size is ${upper.size}."
+        }
+        require(lower.indices.all { lower[it] <= upper[it] }) {
+            "Domain borders order mismatch. Lower borders must be less or equals than upper borders."
         }
     }
 
diff --git a/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/DoubleHistogramGroup.kt b/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/DoubleHistogramGroup.kt
index a80ed119c..bb66b5dc5 100644
--- a/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/DoubleHistogramGroup.kt
+++ b/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/DoubleHistogramGroup.kt
@@ -45,7 +45,7 @@ public class DoubleHistogramGroup(
         else -> floor((value - lower[axis]) / binSize[axis]).toInt()
     }
 
-    override fun getIndex(point: Buffer<Double>): IntArray = IntArray(dimension) {
+    override fun getIndexOrNull(point: Buffer<Double>): IntArray = IntArray(dimension) {
         getIndex(it, point[it])
     }
 
@@ -82,7 +82,7 @@ public class DoubleHistogramGroup(
             override val defaultValue: Double get() = 1.0
 
             override fun putValue(point: Point<out Double>, value: Double) {
-                val index = getIndex(point)
+                val index = getIndexOrNull(point)
                 ndCounter[index].add(value)
             }
         }
diff --git a/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/IndexedHistogramGroup.kt b/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/IndexedHistogramGroup.kt
index 6c04f01bf..70913ecfb 100644
--- a/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/IndexedHistogramGroup.kt
+++ b/kmath-histograms/src/commonMain/kotlin/space/kscience/kmath/histogram/IndexedHistogramGroup.kt
@@ -33,7 +33,7 @@ public class IndexedHistogram<T : Comparable<T>, V : Any>(
 ) : Histogram<T, V, DomainBin<T, V>> {
 
     override fun get(point: Point<T>): DomainBin<T, V>? {
-        val index = histogramGroup.getIndex(point) ?: return null
+        val index = histogramGroup.getIndexOrNull(point) ?: return null
         return histogramGroup.produceBin(index, values[index])
     }
 
@@ -54,9 +54,9 @@ public interface IndexedHistogramGroup<T : Comparable<T>, V : Any> : Group<Index
     public val histogramValueAlgebra: FieldND<V, *> //= NDAlgebra.space(valueSpace, Buffer.Companion::boxing, *shape),
 
     /**
-     * Resolve index of the bin including given [point]
+     * Resolve index of the bin including given [point]. Return null if point is outside histogram area
      */
-    public fun getIndex(point: Point<T>): IntArray?
+    public fun getIndexOrNull(point: Point<T>): IntArray?
 
     /**
      * Get a bin domain represented by given index