Merge pull request #134 from rchillyard/cats

Cats with a few other non-cats issues fixed (although these didn't have Issue numbers)

Author: rchillyard

build.sbt

@@ -2,7 +2,7 @@ organization := "com.phasmidsoftware"
 
 name := "Number"
 
-version := "1.2.10"
+version := "1.2.11"
 
 scalaVersion := "2.13.16"
 
@@ -13,14 +13,22 @@ scalacOptions ++= Seq("-encoding", "UTF-8", "-unchecked", "-deprecation", "-Ywar
 val scalaTestVersion = "3.2.19"
 
 libraryDependencies ++= Seq(
-  "com.phasmidsoftware" %% "flog" % "1.0.10",
-  "com.phasmidsoftware" %% "matchers" % "1.0.11",
-  "org.apache.commons" % "commons-math3" % "3.6.1",
-  "org.scala-lang.modules" %% "scala-parser-combinators" % "2.4.0",
-  "com.novocode" % "junit-interface" % "0.11" % "test", // NOTE vulnerability here
-  "org.scalatest" %% "scalatest" % scalaTestVersion % "test",
-  "ch.qos.logback" % "logback-classic" % "1.5.19" % "test",
-  "org.scalacheck" %% "scalacheck" % "1.19.0" % "test" // This is used for testing Rational
+
+    "com.phasmidsoftware" %% "flog" % "1.0.10",
+    "com.phasmidsoftware" %% "matchers" % "1.0.11",
+    "org.apache.commons" % "commons-math3" % "3.6.1",
+    "com.novocode" % "junit-interface" % "0.11" % "test", // NOTE vulnerability here
+    "org.scalatest" %% "scalatest" % scalaTestVersion % "test",
+    "org.scala-lang.modules" %% "scala-parser-combinators" % "2.4.0",
+    "ch.qos.logback" % "logback-classic" % "1.5.19" % "test",
+    "org.scalacheck" %% "scalacheck" % "1.19.0" % "test", // This is used for testing Rational
+    "org.typelevel" %% "cats-laws" % "2.10.0" % "test",
+    "org.typelevel" %% "discipline-scalatest" % "2.3.0" % "test",
+    "org.typelevel" %% "spire" % "0.18.0",
+    "org.typelevel" %% "cats-kernel" % "2.10.0",
+    "org.typelevel" %% "cats-core" % "2.10.0"
+
+
 )
 
 resolvers += "Typesafe Repository" at "https://repo.typesafe.com/typesafe/releases/"

publish.sbt

@@ -16,7 +16,7 @@ ThisBuild / publishMavenStyle := true
 ThisBuild / credentials += Credentials(Path.userHome / ".sbt" / "sonatype_credentials")
 
 // Required POM metadata for Maven Central
-ThisBuild / licenses := List("MIT" -> url("http://opensource.org/licenses/MIT"))
+ThisBuild / licenses := List("MIT" -> url("https://opensource.org/licenses/MIT"))
 ThisBuild / scmInfo := Some(
   ScmInfo(
     url("https://github.com/rchillyard/Number"),

src/it/scala/com/phasmidsoftware/number/cats/ErrorCommutativeMonoidFuncSpec.scala

@@ -0,0 +1,139 @@
+/*
+ * Copyright (c) 2025. Phasmid Software
+ */
+
+package com.phasmidsoftware.number.cats
+
+import com.phasmidsoftware.number.cats.ErrorCommutativeMonoid._
+import com.phasmidsoftware.number.core.inner.{PureNumber, Value}
+import com.phasmidsoftware.number.core.{AbsoluteFuzz, FuzzyNumber, Gaussian, Number, RelativeFuzz}
+
+/**
+  * Usage-focused examples for the error metric Monoid instances.
+  *
+  * These tests are intentionally lightweight demonstrations rather than law checks.
+  */
+class ErrorCommutativeMonoidFuncSpec extends AnyFlatSpec with Matchers {
+
+  behavior of "Abstracting advocacy communication into lawful scalar folding"
+
+  
+
+  it should "match decoupled parallel error folding with direct Number addition (all addition)" in {
+    implicit val ec: ExecutionContext = ExecutionContext.global
+
+    // Build many fuzzy addends: same nominal 1.2 with absolute Gaussian sigma 0.05
+    val terms: List[Number] = List.fill(2000) {
+      FuzzyNumber(Value.fromDouble(Some(1.2)), PureNumber, Some(AbsoluteFuzz(0.05, Gaussian)))
+    }
+
+    // 1) Traditional: add fuzzy Numbers directly (measure time)
+    val (accumulated: Number, tSeqMs) = 1.times {
+      terms.tail.foldLeft(terms.head)(_ doAdd _)
+    }
+
+    val actualNominal = accumulated.toNominalDouble.getOrElse(Double.NaN)
+    val actualAbs = accumulated match {
+      case f: FuzzyNumber => f.fuzz.collect { case AbsoluteFuzz(m: Double, Gaussian) => m }.getOrElse(Double.NaN)
+      case _ => Double.NaN
+    }
+
+    // 2) Decoupled parallel: nominal sum and sigma folding run independently
+    val ((decoupledNominal, decoupledSigma), tParMs) = 1.times {
+      val fNominal: Future[Double] = Future { terms.flatMap(_.toNominalDouble).sum }
+      val fSigma: Future[Double] = Future {
+        val sigmas = terms.map {
+          case f: FuzzyNumber => f.fuzz.collect { case AbsoluteFuzz(m: Double, Gaussian) => m }.getOrElse(0.0)
+          case _ => 0.0
+        }
+        sigmas.foldLeft(AbsSigma.zero)(_ |+| AbsSigma(_)).value
+      }
+      val a = Await.result(fNominal, 5.seconds)
+      val b = Await.result(fSigma, 5.seconds)
+      (a, b)
+    }
+
+    val decoupled: Number = FuzzyNumber(Value.fromDouble(Some(decoupledNominal)), PureNumber, Some(AbsoluteFuzz(decoupledSigma, Gaussian)))
+
+    val decoupledAbs = decoupled match {
+      case f: FuzzyNumber => f.fuzz.collect { case AbsoluteFuzz(m: Double, Gaussian) => m }.getOrElse(Double.NaN)
+      case _ => Double.NaN
+    }
+
+    // Compare nominal and absolute sigma
+    actualNominal shouldBe decoupledNominal +- 1e-9
+    actualAbs shouldBe decoupledAbs +- 1e-9
+
+    // And new method should be faster (or equal) than traditional
+    // NOTE: simple wall-clock comparison; if flaky in CI, relax or increase data size
+    // tParMs: 72.449458, tSeqMs: 194.883
+    println(s"tParMs: $tParMs, tSeqMs: $tSeqMs")
+    assert(tParMs <= tSeqMs, s"decoupled parallel folding should be faster: par=${tParMs}ms vs seq=${tSeqMs}ms")
+  }
+
+  // CONSIDER this test is slow. We might want to tag it as Slow (or perhaps try to speed it up)
+  it should "match decoupled parallel error folding with direct Number multiplication (all multiplication)" in {
+    implicit val ec: ExecutionContext = ExecutionContext.global
+
+    // Build many fuzzy addends: same nominal 1.2 with absolute Gaussian sigma 0.05
+    val terms: List[Number] = List.fill(2000) {
+      FuzzyNumber(Value.fromDouble(Some(1.1)), PureNumber, Some(RelativeFuzz(0.05, Gaussian)))
+    }
+
+    // 1) Traditional: multiply fuzzy Numbers directly (measure time)
+    val (accumulated: Number, tSeqMs) = 1.times {
+      terms.tail.foldLeft(terms.head)(_ doMultiply _)
+    }
+
+    val actualNominal = accumulated.toNominalDouble.getOrElse(Double.NaN)
+    val actualRel = accumulated match {
+      case f: FuzzyNumber => f.fuzz.collect { case RelativeFuzz(m: Double, Gaussian) => m }.getOrElse(Double.NaN)
+      case _ => Double.NaN
+    }
+
+    // 2) Decoupled parallel: nominal product and sigma folding run independently
+    val ((decoupledNominal, decoupledSigma), tParMs) = 1.times {
+      val fNominal: Future[Double] = Future {
+        val headNominal = terms.headOption.flatMap(_.toNominalDouble).getOrElse(Double.NaN)
+        terms.tail.foldLeft(headNominal) { (acc, n) =>
+          acc * n.toNominalDouble.getOrElse(1.0)
+        }
+      }
+      val fSigma: Future[Double] = Future {
+        // Sequential combination, relative basis propagation: r_xy^2 = r_x^2 + r_y^2 + r_x r_y
+        def combineRel(r1: Double, r2: Double): Double = {
+          val a = r1; val b = r2
+          math.sqrt(a * a + b * b + a * b)
+        }
+        val sigmas = terms.map {
+          case f: FuzzyNumber => f.fuzz.collect { case RelativeFuzz(m: Double, Gaussian) => m }.getOrElse(0.0)
+          case _ => 0.0
+        }
+        sigmas.foldLeft(0.0)(combineRel)
+      }
+      val a = Await.result(fNominal, 5.seconds)
+      val b = Await.result(fSigma, 5.seconds)
+      (a, b)
+    }
+
+    val decoupled: Number = FuzzyNumber(Value.fromDouble(Some(decoupledNominal)), PureNumber, Some(RelativeFuzz(decoupledSigma, Gaussian)))
+
+    val decoupledRel = decoupled match {
+      case f: FuzzyNumber => f.fuzz.collect { case RelativeFuzz(m: Double, Gaussian) => m }.getOrElse(Double.NaN)
+      case _ => Double.NaN
+    }
+
+    // Compare nominal and relative sigma
+    math.abs(actualNominal - decoupledNominal) / math.abs(actualNominal) should be < 1e-12
+    actualRel shouldBe decoupledRel +- 1e-1
+
+    // And new method should be faster (or equal) than traditional
+    // NOTE: simple wall-clock comparison; if flaky in CI, relax or increase data size
+    // tParMs: 5.240125, tSeqMs: 7731.776417
+    println(s"tParMs: $tParMs, tSeqMs: $tSeqMs")
+    assert(tParMs <= tSeqMs, s"decoupled parallel folding should be faster: par=${tParMs}ms vs seq=${tSeqMs}ms")
+  }
+
+}
+
+

src/it/scala/com/phasmidsoftware/number/core/PrimesFuncSpec.scala

@@ -4,8 +4,8 @@ import org.scalatest.flatspec.AnyFlatSpec
 import org.scalatest.matchers.should
 
 /**
- * CONSIDER moving this to an integration testing directory since it is a bit slow.
- */
+  * CONSIDER moving this to an integration testing directory since it is a bit slow.
+  */
 class PrimesFuncSpec extends AnyFlatSpec with should.Matchers {
 
   behavior of "Prime"

src/it/scala/com/phasmidsoftware/number/core/SeriesFuncSpec.scala

@@ -9,7 +9,7 @@ import org.scalatest.flatspec.AnyFlatSpec
 import org.scalatest.matchers.should.Matchers
 import scala.util.Random
 
-class SeriesFuncSpec extends AnyFlatSpec with Matchers with FuzzyEquality{
+class SeriesFuncSpec extends AnyFlatSpec with Matchers with FuzzyEquality {
   behavior of "Basel Problem"
 
   val basel: InfiniteSeries[Number] = InfiniteSeries(LazyList.from(1).map(x => Rational(x).invert.square))

src/main/java/com/phasmidsoftware/number/core/BigNumber.java

@@ -92,7 +92,7 @@ public static BigNumber value(final Rational x) {
      * TESTME
      *
      * @param whole    a non-negative long.
-     * @param decimals a non-negative long, for example 14 for a 3.14 valued result.
+     * @param decimals a non-negative long, for example, 14 for a 3.14 valued result.
      * @param sign     true if the result should be positive.
      * @return a new BigNumber.
      */
@@ -115,7 +115,7 @@ public static BigNumber value(final long whole, final long decimals, final boole
      * TESTME
      *
      * @param whole    a non-negative long.
-     * @param decimals a non-negative long, for example 14 for a 3.14 valued result.
+     * @param decimals a non-negative long, for example, 14 for a 3.14 valued result.
      * @return a new BigNumber.
      */
     public static BigNumber value(final long whole, final long decimals) {
@@ -275,7 +275,6 @@ public BigNumber add(final BigNumber that) {
         final boolean subtract = !that.sign;
         for (int i = resultLength - 1; i >= 0; i--) {
             int sum = carry;
-            borrow = false;
             if (i < thisLength) sum += decimals[i];
             if (i < thatLength) sum += subtract ? -that.decimals[i] : that.decimals[i];
             if (sum < 0) {
@@ -303,23 +302,22 @@ public BigNumber add(final BigNumber that) {
      * @return a negative, zero, or positive int.
      */
     public int compareTo(final BigNumber that) {
-        if (this.equals(that)) {
+        if (this.equals(that))
             return 0;
-        } else {
+        else {
             int wholeComparison = this.whole.compareTo(that.whole);
-            if (wholeComparison != 0) {
+            if (wholeComparison != 0)
                 return this.sign ? wholeComparison : -wholeComparison;
-            } else {
+            else {
                 final int[] thisDecimals = this.decimals;
                 final int[] thatDecimals = that.decimals;
                 final int maxLength = Math.max(thisDecimals.length, thatDecimals.length);
                 for (int i = 0; i < maxLength; i++) {
                     int thisNumber = (i < thisDecimals.length) ? thisDecimals[i] : 0;
                     int thatNumber = (i < thatDecimals.length) ? thatDecimals[i] : 0;
-                    if (thisNumber != thatNumber) {
+                    if (thisNumber != thatNumber)
                         return this.sign ? Integer.compare(thisNumber, thatNumber)
                                 : Integer.compare(thatNumber, thisNumber);
-                    }
                 }
                 return 0;
             }
@@ -374,10 +372,10 @@ public BigNumber multiplyWithKaratsuba(final BigNumber other) {
      * Multiplies two integer arrays representing numerical values and returns the result in an array.
      * TESTME
      *
-     * @param arr1 the first integer array representing a number
-     * @param arr2 the second integer array representing a number
-     * @param start the starting index for the portion of the arrays to be considered
-     * @param end the ending index for the portion of the arrays to be considered
+     * @param arr1       the first integer array representing a number
+     * @param arr2       the second integer array representing a number
+     * @param start      the starting index for the portion of the arrays to be considered
+     * @param end        the ending index for the portion of the arrays to be considered
      * @param resultSize the size of the resulting array
      * @return an integer array representing the result of the multiplication
      */
@@ -410,10 +408,10 @@ private int[] multiplyArrays(final int[] arr1, final int[] arr2, final int start
      * efficient computation of the product.
      * TESTME
      *
-     * @param first The first integer array, where each element represents part of a larger number.
-     * @param second The second integer array, where each element represents part of a larger number.
-     * @param start The starting index for the relevant segment of the arrays to be considered for multiplication.
-     * @param end The ending index for the relevant segment of the arrays to be considered for multiplication.
+     * @param first   The first integer array, where each element represents part of a larger number.
+     * @param second  The second integer array, where each element represents part of a larger number.
+     * @param start   The starting index for the relevant segment of the arrays to be considered for multiplication.
+     * @param end     The ending index for the relevant segment of the arrays to be considered for multiplication.
      * @param resSize The size of the result array to store the product of the two arrays.
      * @return An array representing the product of the two numbers, with the result properly sized as per resSize.
      */
@@ -460,7 +458,7 @@ private int[] recursiveKarat(final int[] first, final int[] second, final int st
      * Zeros are appended to the end of the array to maintain the original length.
      * TESTME
      *
-     * @param arr the array of integers to be shifted; must not be null
+     * @param arr    the array of integers to be shifted; must not be null
      * @param offset the number of positions to shift the elements to the left; must be non-negative
      */
     private void leftShift(final int[] arr, final int offset) {
@@ -479,10 +477,10 @@ private void leftShift(final int[] arr, final int offset) {
      * and stores the result in a new array of specified size.
      * TESTME
      *
-     * @param first the input array from which elements are added
-     * @param start the starting index of the first part in the array
-     * @param middle the ending index of the first part in the array
-     * @param end the ending index of the second part in the array
+     * @param first   the input array from which elements are added
+     * @param start   the starting index of the first part in the array
+     * @param middle  the ending index of the first part in the array
+     * @param end     the ending index of the second part in the array
      * @param resSize the size of the resulting array
      * @return an array containing the result of the addition with carry
      */
@@ -516,8 +514,8 @@ private int[] add(final int[] first, final int start, final int middle, final in
      * Handles carry values appropriately during addition.
      * TESTME
      *
-     * @param first the array representing the first number. Must be large enough
-     *              to accommodate the result of the addition.
+     * @param first  the array representing the first number. Must be large enough
+     *               to accommodate the result of the addition.
      * @param second the array representing the second number. Its digits will be
      *               added to the corresponding digits of the first array.
      */
@@ -646,14 +644,13 @@ public BigNumber divide(final long x) {
      *
      * @param o the object to be compared for equality with this BigNumber
      * @return true if the specified object is a BigNumber, has the same whole part,
-     *         sign, and decimals as this BigNumber; otherwise, false
+     * sign, and decimals as this BigNumber; otherwise, false
      */
     @Override
     public boolean equals(final Object o) {
         if (this == o) return true;
         // NOTE That if you replace this as recommended, you must ensure that Java is compiling on CircleCI with the correct compiler (Java 16).
-        if ( !(o instanceof BigNumber ) ) return false;
-        final BigNumber bigNumber = (BigNumber) o;
+        if (!(o instanceof BigNumber bigNumber)) return false;
         return whole.equals(bigNumber.whole) && sign == bigNumber.sign && Arrays.equals(decimals, bigNumber.decimals);
     }
 
@@ -703,7 +700,7 @@ public BigNumber(final BigInteger whole) {
     }
 
     /**
-     * Secondary constructor to creat a BigNumber which has no decimal part.
+     * Secondary constructor to create a BigNumber which has no decimal part.
      *
      * @param whole any BigInteger value (positive or negative).
      */
@@ -731,7 +728,7 @@ private static int[] trim(final int[] array) {
      *          if positive, retrieves the corresponding decimal index;
      *          if negative, returns 0.
      * @return the element value as a long; the whole number if the index is 0,
-     *         the decimal value if the index is positive, or 0 if the index is negative.
+     * the decimal value if the index is positive, or 0 if the index is negative.
      */
     private long element(final int i) {
         if (i == 0) return whole.longValueExact();
@@ -768,15 +765,15 @@ public static void main(final String[] args) {
     /**
      * Measures and compares the performance of two multiplication algorithms (standard and Karatsuba) for large numbers.
      * TESTME
-     *
+     * <p>
      * The method performs the following steps:
      * 1. Initializes a large constant string representing a seed value and extracts a portion for computation.
      * 2. Parses the seed string into a `BigNumber` object for arithmetic operations.
      * 3. Uses a loop to measure the time taken to execute multiplication using the standard multiplication method.
      * 4. Computes the average execution time for the standard multiplication method.
      * 5. Repeats the process for the Karatsuba multiplication method, measuring and calculating average execution time.
-     * 6. Prints the execution times for both methods, and computes the percentage improvement offered by the Karatsuba method.
-     *
+     * 6. Prints the execution times for both methods and computes the percentage improvement offered by the Karatsuba method.
+     * <p>
      * Notes:
      * - Considers the potential use of performance measurement utilities such as `StopWatch` or `Timer`.
      * - Ensures timing accuracy by iterating over each method multiple times and averaging the results.