You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2023/01/19 12:52:58 UTC
[commons-numbers] branch master updated (e5c51120 -> 16d76d01)
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/commons-numbers.git
from e5c51120 Fix spelling
new 1b1b7b1e Correct reference link
new 496740c6 NUMBERS-192: Add subtract method to Sum
new 16d76d01 Update NOTICE to 2023
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
NOTICE | 2 +-
commons-numbers-angle/NOTICE | 2 +-
commons-numbers-arrays/NOTICE | 2 +-
commons-numbers-bom/NOTICE | 2 +-
commons-numbers-combinatorics/NOTICE | 2 +-
commons-numbers-complex-streams/NOTICE | 2 +-
commons-numbers-complex/NOTICE | 2 +-
commons-numbers-core/NOTICE | 2 +-
.../java/org/apache/commons/numbers/core/Sum.java | 30 ++++++++++++++++++----
.../org/apache/commons/numbers/core/SumTest.java | 29 +++++++++++++++++++++
.../apache/commons/numbers/core/UserGuideTest.java | 11 ++++++++
commons-numbers-examples/NOTICE | 2 +-
commons-numbers-examples/examples-jmh/NOTICE | 2 +-
commons-numbers-field/NOTICE | 2 +-
commons-numbers-fraction/NOTICE | 2 +-
commons-numbers-gamma/NOTICE | 2 +-
commons-numbers-quaternion/NOTICE | 2 +-
commons-numbers-rootfinder/NOTICE | 2 +-
src/changes/changes.xml | 3 +++
src/site/apt/userguide/index.apt | 25 ++++++++++++++++--
20 files changed, 106 insertions(+), 22 deletions(-)
[commons-numbers] 01/03: Correct reference link
Posted by ah...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-numbers.git
commit 1b1b7b1ec903425bd7be13973097fe6cef931cde
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Thu Jan 19 11:57:36 2023 +0000
Correct reference link
---
.../src/main/java/org/apache/commons/numbers/core/Sum.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java b/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java
index 9dc084b2..cc5e7791 100644
--- a/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java
+++ b/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java
@@ -69,7 +69,7 @@ import java.util.function.DoubleSupplier;
*
* <p><strong>Implementation Notes</strong>
* <p>This class internally uses the <em>Sum2S</em> and <em>Dot2S</em> algorithms described in
- * <a href="https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.2.1547">
+ * <a href="https://doi.org/10.1137/030601818">
* Accurate Sum and Dot Product</a> by Takeshi Ogita, Siegfried M. Rump,
* and Shin'ichi Oishi (<em>SIAM J. Sci. Comput</em>, 2005). These are compensated
* summation and multiplication algorithms chosen here for their good
[commons-numbers] 02/03: NUMBERS-192: Add subtract method to Sum
Posted by ah...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-numbers.git
commit 496740c6be6925c173c8860982ec9de238c40f2f
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Thu Jan 19 12:51:24 2023 +0000
NUMBERS-192: Add subtract method to Sum
Updated user guide with subtract example and more usage details.
---
.../java/org/apache/commons/numbers/core/Sum.java | 28 ++++++++++++++++++---
.../org/apache/commons/numbers/core/SumTest.java | 29 ++++++++++++++++++++++
.../apache/commons/numbers/core/UserGuideTest.java | 11 ++++++++
src/changes/changes.xml | 3 +++
src/site/apt/userguide/index.apt | 25 +++++++++++++++++--
5 files changed, 90 insertions(+), 6 deletions(-)
diff --git a/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java b/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java
index cc5e7791..8953efd1 100644
--- a/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java
+++ b/commons-numbers-core/src/main/java/org/apache/commons/numbers/core/Sum.java
@@ -177,11 +177,31 @@ public final class Sum
* @return this instance.
*/
public Sum add(final Sum other) {
- // Pull both values first to ensure there are
- // no issues when adding a sum to itself.
- final double s = other.sum;
- final double c = other.comp;
+ return add(other.sum, other.comp);
+ }
+
+ /**
+ * Subtracts another sum from this sum.
+ *
+ * @param other Sum to subtract.
+ * @return this instance.
+ */
+ public Sum subtract(final Sum other) {
+ return add(-other.sum, -other.comp);
+ }
+ /**
+ * Adds the sum and compensation to this sum.
+ *
+ * <p>This is a utility method to extract both values from a sum
+ * before addition to ensure there are no issues when adding a sum
+ * to itself.
+ *
+ * @param s Sum.
+ * @param c Compensation.
+ * @return this instance.
+ */
+ private Sum add(double s, double c) {
return add(s).add(c);
}
diff --git a/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/SumTest.java b/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/SumTest.java
index f358ba36..5e42a727 100644
--- a/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/SumTest.java
+++ b/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/SumTest.java
@@ -102,6 +102,35 @@ class SumTest {
Assertions.assertEquals(exactSum(a, b, a, b), s.add(s).getAsDouble());
}
+ @Test
+ void testSubtract_sumInstance() {
+ // arrange
+ final double a = Math.PI;
+ final double b = Math.scalb(a, -53);
+ final double c = Math.scalb(a, -53);
+ final double d = Math.scalb(a, -27);
+ final double e = Math.scalb(a, -27);
+ final double f = Math.scalb(a, -50);
+
+ // act/assert
+ // add(-sum) == subtract(sum)
+ Assertions.assertEquals(
+ Sum.of(a, b, c, d).add(Sum.create()).getAsDouble(),
+ Sum.of(a, b, c, d).subtract(Sum.create()).getAsDouble());
+ Assertions.assertEquals(
+ Sum.of(a, b, c, d).add(Sum.of(-e, -f)).getAsDouble(),
+ Sum.of(a, b, c, d).subtract(Sum.of(e, f)).getAsDouble());
+ Assertions.assertEquals(
+ Sum.of(a, b).add(Sum.of(-a, -c).add(Sum.of(-d, -e, -f))).getAsDouble(),
+ Sum.of(a, b).subtract(Sum.of(a, c)).subtract(Sum.of(d, e, f)).getAsDouble());
+ Assertions.assertEquals(
+ Sum.of(a, b).add(Sum.of(-a, c).add(Sum.of(-d, e, -f))).getAsDouble(),
+ Sum.of(a, b).subtract(Sum.of(a, -c)).subtract(Sum.of(d, -e, f)).getAsDouble());
+
+ final Sum s = Sum.of(a, b);
+ Assertions.assertEquals(0, s.subtract(s).getAsDouble());
+ }
+
@Test
void testSumOfProducts_dimensionMismatch() {
// act/assert
diff --git a/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/UserGuideTest.java b/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/UserGuideTest.java
index 537c1a92..10f4d6e2 100644
--- a/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/UserGuideTest.java
+++ b/commons-numbers-core/src/test/java/org/apache/commons/numbers/core/UserGuideTest.java
@@ -64,6 +64,17 @@ class UserGuideTest {
Assertions.assertEquals(-1.0, x2);
}
+ @Test
+ void testSum3() {
+ double x1 = 1e100 + 1 - 2 - 1e100;
+ Sum s1 = Sum.of(1e100, 1);
+ Sum s2 = Sum.of(2, 1e100);
+ double x2 = s1.subtract(s2).getAsDouble();
+ Assertions.assertEquals(0.0, x1);
+ Assertions.assertEquals(-1.0, x2);
+ }
+
+
@Test
void testPrecision1() {
// Default allows no numbers between
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 569fdc6b..914b4af3 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -56,6 +56,9 @@ If the output is not quite correct, check for invisible trailing spaces!
<release version="1.2" date="TBD" description="
New features, updates and bug fixes.
">
+ <action dev="aherbert" type="add" issue="NUMBERS-192">
+ "Sum": Add subtract(Sum) method.
+ </action>
<action dev="aherbert" type="add" issue="NUMBERS-191">
"Stirling": Compute Stirling numbers of the first kind.
</action>
diff --git a/src/site/apt/userguide/index.apt b/src/site/apt/userguide/index.apt
index f140f894..8cf82a4d 100644
--- a/src/site/apt/userguide/index.apt
+++ b/src/site/apt/userguide/index.apt
@@ -411,7 +411,7 @@ Sum.of(1, 2, Double.NaN).getAsDouble() // NaN
Sum.of(1, 2, Double.NEGATIVE_INFINITY).getAsDouble() // -inf
+------------------------------------------+
- The implementation provides an effective 106 bit floating point significand. However the
+ The implementation provides up to a 106 bit floating point significand. However the
significand is split into two <<<double>>> values which may be separated by more than <<<2^53>>>
by using the exponent of the second <<<double>>>.
This provides protection against cancellation in situations that would not be handled by an
@@ -422,14 +422,35 @@ double x1 = 1e100 + 1 - 2 - 1e100;
double x2 = Sum.of(1e100, 1, -2, -1e100).getAsDouble();
// x1 == 0.0
// x2 == -1.0
++------------------------------------------+
+
+ Note that the first part of the sum is maintained as the IEEE754 result. The <<<Sum>>>
+ is therefore not a full <<<double-double>>> implementation, which would maintain the sum
+ as the current total and a round-off term. This difference makes the <<<Sum>>> class faster
+ at the cost of some accuracy during addition of terms that cancel.
+
+ If the terms to be subtracted are known then the summation can be split into the positive
+ and negative terms, summed in two parts and the result computed by a final subtraction of
+ the <<<Sum>>> of negative parts.
+
++------------------------------------------+
+double x1 = 1e100 + 1 - 2 - 1e100;
+Sum s1 = Sum.of(1e100, 1);
+Sum s2 = Sum.of(2, 1e100);
+double x2 = s1.subtract(s2).getAsDouble();
+// x1 == 0.0
+// x2 == -1.0
+------------------------------------------+
The class can be used to:
+ * Provide accurate summation of numbers with the same sign irrespective of input order;
+
* Reduce cancellation effects that occur when large magnitude numbers
with opposite signs are summed together with relatively small values;
- * Provide accurate summation of numbers with the same sign irrespective of input order.
+ * Compute using two sums the terms of the same sign and the final result by combining
+ the sums (using add or subtract).
[]
[commons-numbers] 03/03: Update NOTICE to 2023
Posted by ah...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-numbers.git
commit 16d76d01c0be321093485bb10c06740de6307d09
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Thu Jan 19 12:52:47 2023 +0000
Update NOTICE to 2023
---
NOTICE | 2 +-
commons-numbers-angle/NOTICE | 2 +-
commons-numbers-arrays/NOTICE | 2 +-
commons-numbers-bom/NOTICE | 2 +-
commons-numbers-combinatorics/NOTICE | 2 +-
commons-numbers-complex-streams/NOTICE | 2 +-
commons-numbers-complex/NOTICE | 2 +-
commons-numbers-core/NOTICE | 2 +-
commons-numbers-examples/NOTICE | 2 +-
commons-numbers-examples/examples-jmh/NOTICE | 2 +-
commons-numbers-field/NOTICE | 2 +-
commons-numbers-fraction/NOTICE | 2 +-
commons-numbers-gamma/NOTICE | 2 +-
commons-numbers-quaternion/NOTICE | 2 +-
commons-numbers-rootfinder/NOTICE | 2 +-
15 files changed, 15 insertions(+), 15 deletions(-)
diff --git a/NOTICE b/NOTICE
index 257c15e9..45fc9620 100644
--- a/NOTICE
+++ b/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-angle/NOTICE b/commons-numbers-angle/NOTICE
index 96cf7a70..8a58364b 100644
--- a/commons-numbers-angle/NOTICE
+++ b/commons-numbers-angle/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-arrays/NOTICE b/commons-numbers-arrays/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-arrays/NOTICE
+++ b/commons-numbers-arrays/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-bom/NOTICE b/commons-numbers-bom/NOTICE
index 96cf7a70..8a58364b 100644
--- a/commons-numbers-bom/NOTICE
+++ b/commons-numbers-bom/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-combinatorics/NOTICE b/commons-numbers-combinatorics/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-combinatorics/NOTICE
+++ b/commons-numbers-combinatorics/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-complex-streams/NOTICE b/commons-numbers-complex-streams/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-complex-streams/NOTICE
+++ b/commons-numbers-complex-streams/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-complex/NOTICE b/commons-numbers-complex/NOTICE
index af7539f7..165f5eec 100644
--- a/commons-numbers-complex/NOTICE
+++ b/commons-numbers-complex/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-core/NOTICE b/commons-numbers-core/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-core/NOTICE
+++ b/commons-numbers-core/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-examples/NOTICE b/commons-numbers-examples/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-examples/NOTICE
+++ b/commons-numbers-examples/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-examples/examples-jmh/NOTICE b/commons-numbers-examples/examples-jmh/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-examples/examples-jmh/NOTICE
+++ b/commons-numbers-examples/examples-jmh/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-field/NOTICE b/commons-numbers-field/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-field/NOTICE
+++ b/commons-numbers-field/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-fraction/NOTICE b/commons-numbers-fraction/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-fraction/NOTICE
+++ b/commons-numbers-fraction/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-gamma/NOTICE b/commons-numbers-gamma/NOTICE
index 1c3f3885..c9420527 100644
--- a/commons-numbers-gamma/NOTICE
+++ b/commons-numbers-gamma/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-quaternion/NOTICE b/commons-numbers-quaternion/NOTICE
index 38f902eb..179baf5a 100644
--- a/commons-numbers-quaternion/NOTICE
+++ b/commons-numbers-quaternion/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).
diff --git a/commons-numbers-rootfinder/NOTICE b/commons-numbers-rootfinder/NOTICE
index 96cf7a70..8a58364b 100644
--- a/commons-numbers-rootfinder/NOTICE
+++ b/commons-numbers-rootfinder/NOTICE
@@ -1,5 +1,5 @@
Apache Commons Numbers
-Copyright 2001-2022 The Apache Software Foundation
+Copyright 2001-2023 The Apache Software Foundation
This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).