Fwd: JDK 9 RFR of JDK-8030942: Explicitly state floating-point summation requirements on non-finite inputs

[Joe Darcy]

On 07/18/2014 12:00 PM, Georgiy Rakov wrote:
>
> On 18.07.2014 20:14, Joe Darcy wrote:
>> Hello Georgiy,
>>
>> On 07/18/2014 05:29 AM, Georgiy Rakov wrote:
>>> Hello Joe,
>>>
>>> could you please clarify by short example following assertion:
>>>
>>>   154      * If the exact sum is infinite, a properly-signed infinity is
>>>   155      * returned.
>>>
>>> I'm afraid I don't quite understand what you mean here by 'exact sum'.
>>
>> By "exact sum," the sum absent any floating-point rounding, the sum 
>> you would get using infinite precision to operate on the values in 
>> question.
>>
>> The sentence in question is intended to be a short way of saying "If 
>> you have same-signed infinities in your input, the result will be an 
>> infinity of that sign." In particular, this disallows the behavior 
>> that was fixed before JDK 8 GA where having infinities in the input 
>> would cause a NaN to be returned because of how the compensated 
>> summation code manipulated those values.
>>
> Thanks, I see,
> however it seems to me a bit confusing, since the term "infinite exact 
> sum" seems to me not obvious and I believe it needs some definition. 
> I'd like to suggest to use more straightforward approach, that is as 
> you've said: "If you have same-signed infinities in your input, the 
> result will be an infinity of that sign.". I believe it would be more 
> clear for end user (at least for me :)) and from conformance point of 
> view.
>
> Besides it seems to me a bit questionable. For instance "inexact some" 
> looks like more appropriate, since overflowing to infinity occurs when 
> _actual _sum exceeds the limit. By actual sum I mean sum resulted from 
> actual summation with all the rounding happened. There wouldn't be 
> such questions, provided straightforward approach is used.
>
> Thanks,
> Georgiy.
>

In response to previous feedback, I propose this revised change to the 
specification:

--- a/src/share/classes/java/util/DoubleSummaryStatistics.java Sat Jul 
19 11:22:08 2014 +0800
+++ b/src/share/classes/java/util/DoubleSummaryStatistics.java Mon Jul 
21 18:02:54 2014 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -129,9 +129,6 @@
       * Returns the sum of values recorded, or zero if no values have been
       * recorded.
       *
-     * If any recorded value is a NaN or the sum is at any point a NaN
-     * then the sum will be NaN.
-     *
       * <p> The value of a floating-point sum is a function both of the
       * input values as well as the order of addition operations. The
       * order of addition operations of this method is intentionally
@@ -143,6 +140,44 @@
       * numerical sum compared to a simple summation of {@code double}
       * values.
       *
+     * Because of the unspecified order of operations and the
+     * possibility of using differing summation schemes, the output of
+     * this method may vary on the same input values.
+     *
+     * <p>Various conditions can result in a non-finite sum being
+     * computed. This can occur even if the all the recorded values
+     * being summed are finite. If any recorded value is non-finite,
+     * the sum will be non-finite:
+     *
+     * <ul>
+     *
+     * <li>If any recorded value is a NaN, then the final sum will be
+     * NaN.
+     *
+     * <li>If the recorded values contain one or more infinities, the
+     * sum will be infinite or NaN.
+     *
+     * <ul>
+     *
+     * <li>If the recorded values contain infinities of opposite sign,
+     * the sum will be NaN.
+     *
+     * <li>If the recorded values contain infinities of one sign and
+     * an intermediate sum overflows to an infinity of the opposite
+     * sign, the sum may be NaN.
+     *
+     * </ul>
+     *
+     * </ul>
+     *
+     * It is possible for intermediate sums of finite values to
+     * overflow into opposite-signed infinities; if that occurs, the
+     * final sum will be NaN even if the recorded values are all
+     * finite.
+     *
+     * If all the recorded values are zero, the sign of zero is
+     * <em>not</em> guaranteed to be preserved in the final sum.
+     *
       * @apiNote Values sorted by increasing absolute magnitude tend to 
yield
       * more accurate results.
       *
@@ -193,15 +228,9 @@
       * Returns the arithmetic mean of values recorded, or zero if no
       * values have been recorded.
       *
-     * If any recorded value is a NaN or the sum is at any point a NaN
-     * then the average will be code NaN.
-     *
-     * <p>The average returned can vary depending upon the order in
-     * which values are recorded.
-     *
-     * This method may be implemented using compensated summation or
-     * other technique to reduce the error bound in the {@link #getSum
-     * numerical sum} used to compute the average.
+     * <p> The computed average can vary numerically and have the
+     * special case behavior as computing the sum; see {@link #getSum}
+     * for details.
       *
       * @apiNote Values sorted by increasing absolute magnitude tend to 
yield
       * more accurate results.

(With analogous changes in java/util/stream/DoubleStream.java.)

Thanks,

-Joe