Repository: commons-math Updated Branches: refs/heads/master a614e8520 -> 8a8ca83f2
Javadoc fixes; added tests to confirm NaN behavior. Project: http://git-wip-us.apache.org/repos/asf/commons-math/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-math/commit/8a8ca83f Tree: http://git-wip-us.apache.org/repos/asf/commons-math/tree/8a8ca83f Diff: http://git-wip-us.apache.org/repos/asf/commons-math/diff/8a8ca83f Branch: refs/heads/master Commit: 8a8ca83f25bffb9927f67469f2230ed0067d1256 Parents: a614e85 Author: Phil Steitz <phil.ste...@gmail.com> Authored: Fri Jan 1 15:17:08 2016 -0700 Committer: Phil Steitz <phil.ste...@gmail.com> Committed: Fri Jan 1 15:17:08 2016 -0700 ---------------------------------------------------------------------- .../apache/commons/math4/complex/Complex.java | 154 ++++++++----------- .../apache/commons/math4/util/Precision.java | 39 +++-- .../commons/math4/complex/ComplexTest.java | 18 +++ 3 files changed, 108 insertions(+), 103 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-math/blob/8a8ca83f/src/main/java/org/apache/commons/math4/complex/Complex.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math4/complex/Complex.java b/src/main/java/org/apache/commons/math4/complex/Complex.java index fa8397c..5a073c7 100644 --- a/src/main/java/org/apache/commons/math4/complex/Complex.java +++ b/src/main/java/org/apache/commons/math4/complex/Complex.java @@ -32,7 +32,7 @@ import org.apache.commons.math4.util.Precision; /** * Representation of a Complex number, i.e. a number which has both a * real and imaginary part. - * <br/> + * <p> * Implementations of arithmetic operations handle {@code NaN} and * infinite values according to the rules for {@link java.lang.Double}, i.e. * {@link #equals} is an equivalence relation for all instances that have @@ -42,16 +42,14 @@ import org.apache.commons.math4.util.Precision; * <li>{@code 1 + NaNi}</li> * <li>{@code NaN + i}</li> * <li>{@code NaN + NaNi}</li> - * </ul> - * Note that this is in contradiction with the IEEE-754 standard for floating + * </ul><p> + * Note that this contradicts the IEEE-754 standard for floating * point numbers (according to which the test {@code x == x} must fail if * {@code x} is {@code NaN}). The method * {@link org.apache.commons.math4.util.Precision#equals(double,double,int) * equals for primitive double} in {@link org.apache.commons.math4.util.Precision} * conforms with IEEE-754 while this class conforms with the standard behavior - * for Java object types. - * <br/> - * Implements Serializable since 2.0 + * for Java object types.</p> * */ public class Complex implements FieldElement<Complex>, Serializable { @@ -138,12 +136,9 @@ public class Complex implements FieldElement<Complex>, Serializable { * Returns a {@code Complex} whose value is * {@code (this + addend)}. * Uses the definitional formula - * <pre> - * <code> - * (a + bi) + (c + di) = (a+c) + (b+d)i - * </code> - * </pre> - * <br/> + * <p> + * {@code (a + bi) + (c + di) = (a+c) + (b+d)i} + * </p> * If either {@code this} or {@code addend} has a {@code NaN} value in * either part, {@link #NaN} is returned; otherwise {@code Infinite} * and {@code NaN} values are returned in the parts of the result @@ -181,17 +176,17 @@ public class Complex implements FieldElement<Complex>, Serializable { } /** - * Return the conjugate of this complex number. + * Returns the conjugate of this complex number. * The conjugate of {@code a + bi} is {@code a - bi}. - * <br/> + * <p> * {@link #NaN} is returned if either the real or imaginary * part of this Complex number equals {@code Double.NaN}. - * <br/> + * </p><p> * If the imaginary part is infinite, and the real part is not * {@code NaN}, the returned value has infinite imaginary part * of the opposite sign, e.g. the conjugate of * {@code 1 + POSITIVE_INFINITY i} is {@code 1 - NEGATIVE_INFINITY i}. - * + * </p> * @return the conjugate of this Complex object. */ public Complex conjugate() { @@ -217,7 +212,7 @@ public class Complex implements FieldElement<Complex>, Serializable { * <a href="http://doi.acm.org/10.1145/1039813.1039814";> * prescaling of operands</a> to limit the effects of overflows and * underflows in the computation. - * <br/> + * <p> * {@code Infinite} and {@code NaN} values are handled according to the * following rules, applied in the order presented: * <ul> @@ -404,7 +399,7 @@ public class Complex implements FieldElement<Complex>, Serializable { * Returns {@code true} if, both for the real part and for the imaginary * part, there is no double value strictly between the arguments or the * difference between them is within the range of allowed error - * (inclusive). + * (inclusive). Returns {@code false} if either of the arguments is NaN. * * @param x First value (cannot be {@code null}). * @param y Second value (cannot be {@code null}). @@ -424,7 +419,7 @@ public class Complex implements FieldElement<Complex>, Serializable { * Returns {@code true} if, both for the real part and for the imaginary * part, there is no double value strictly between the arguments or the * relative difference between them is smaller or equal to the given - * tolerance. + * tolerance. Returns {@code false} if either of the arguments is NaN. * * @param x First value (cannot be {@code null}). * @param y Second value (cannot be {@code null}). @@ -503,21 +498,19 @@ public class Complex implements FieldElement<Complex>, Serializable { * Returns a {@code Complex} whose value is {@code this * factor}. * Implements preliminary checks for {@code NaN} and infinity followed by * the definitional formula: - * <pre> - * <code> - * (a + bi)(c + di) = (ac - bd) + (ad + bc)i - * </code> - * </pre> + * <p> + * {@code (a + bi)(c + di) = (ac - bd) + (ad + bc)i} + * </p> * Returns {@link #NaN} if either {@code this} or {@code factor} has one or * more {@code NaN} parts. - * <br/> + * <p> * Returns {@link #INF} if neither {@code this} nor {@code factor} has one * or more {@code NaN} parts and if either {@code this} or {@code factor} * has one or more infinite parts (same result is returned regardless of * the sign of the components). - * <br/> + * </p><p> * Returns finite values in components of the result per the definitional - * formula in all remaining cases. + * formula in all remaining cases.</p> * * @param factor value to be multiplied by this {@code Complex}. * @return {@code this * factor}. @@ -585,7 +578,7 @@ public class Complex implements FieldElement<Complex>, Serializable { /** * Returns a {@code Complex} whose value is {@code (-this)}. * Returns {@code NaN} if either real or imaginary - * part of this Complex number equals {@code Double.NaN}. + * part of this Complex number is {@code Double.NaN}. * * @return {@code -this}. */ @@ -602,11 +595,9 @@ public class Complex implements FieldElement<Complex>, Serializable { * Returns a {@code Complex} whose value is * {@code (this - subtrahend)}. * Uses the definitional formula - * <pre> - * <code> - * (a + bi) - (c + di) = (a-c) + (b-d)i - * </code> - * </pre> + * <p> + * {@code (a + bi) - (c + di) = (a-c) + (b-d)i} + * </p> * If either {@code this} or {@code subtrahend} has a {@code NaN]} value in either part, * {@link #NaN} is returned; otherwise infinite and {@code NaN} values are * returned in the parts of the result according to the rules for @@ -648,11 +639,9 @@ public class Complex implements FieldElement<Complex>, Serializable { * <a href="http://mathworld.wolfram.com/InverseCosine.html"; TARGET="_top"> * inverse cosine</a> of this complex number. * Implements the formula: - * <pre> - * <code> - * acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>)))) - * </code> - * </pre> + * <p> + * {@code acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))} + * </p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN} or infinite. * @@ -672,13 +661,11 @@ public class Complex implements FieldElement<Complex>, Serializable { * <a href="http://mathworld.wolfram.com/InverseSine.html"; TARGET="_top"> * inverse sine</a> of this complex number. * Implements the formula: - * <pre> - * <code> - * asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz)) - * </code> - * </pre> + * <p> + * {@code asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz))} + * </p><p> * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN} or infinite. + * input argument is {@code NaN} or infinite.</p> * * @return the inverse sine of this complex number. * @since 1.2 @@ -696,13 +683,11 @@ public class Complex implements FieldElement<Complex>, Serializable { * <a href="http://mathworld.wolfram.com/InverseTangent.html"; TARGET="_top"> * inverse tangent</a> of this complex number. * Implements the formula: - * <pre> - * <code> - * atan(z) = (i/2) log((i + z)/(i - z)) - * </code> - * </pre> + * <p> + * {@code atan(z) = (i/2) log((i + z)/(i - z))} + * </p><p> * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN} or infinite. + * input argument is {@code NaN} or infinite.</p> * * @return the inverse tangent of this complex number * @since 1.2 @@ -719,27 +704,24 @@ public class Complex implements FieldElement<Complex>, Serializable { /** * Compute the * <a href="http://mathworld.wolfram.com/Cosine.html"; TARGET="_top"> - * cosine</a> - * of this complex number. + * cosine</a> of this complex number. * Implements the formula: - * <pre> - * <code> - * cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i - * </code> - * </pre> + * <p> + * {@code cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i} + * </p><p> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. - * <br/> + * </p><p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p><p> * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. + * infinite or NaN values returned in parts of the result.</p> * <pre> * Examples: * <code> - * cos(1 ± INFINITY i) = 1 ∓ INFINITY i + * cos(1 ± INFINITY i) = 1 \u2213 INFINITY i * cos(±INFINITY + i) = NaN + NaN i * cos(±INFINITY ± INFINITY i) = NaN + NaN i * </code> @@ -764,16 +746,16 @@ public class Complex implements FieldElement<Complex>, Serializable { * Implements the formula: * <pre> * <code> - * cosh(a + bi) = cosh(a)cos(b) + sinh(a)sin(b)i} + * cosh(a + bi) = cosh(a)cos(b) + sinh(a)sin(b)i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> @@ -810,10 +792,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * where the (real) functions on the right-hand side are * {@link FastMath#exp}, {@link FastMath#cos}, and * {@link FastMath#sin}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> @@ -852,10 +834,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * where ln on the right hand side is {@link FastMath#log}, * {@code |a + bi|} is the modulus, {@link Complex#abs}, and * {@code arg(a + bi) = }{@link FastMath#atan2}(b, a). - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite (or critical) values in real or imaginary parts of the input may * result in infinite or NaN values returned in parts of the result. * <pre> @@ -893,13 +875,13 @@ public class Complex implements FieldElement<Complex>, Serializable { * </pre> * where {@code exp} and {@code log} are {@link #exp} and * {@link #log}, respectively. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN} or infinite, or if {@code y} - * equals {@link Complex#ZERO}. + * equals {@link Complex#ZERO}.</p> * * @param x exponent to which this {@code Complex} is to be raised. - * @return <code> this<sup>{@code x}</sup></code>. + * @return <code> this<sup>x</sup></code>. * @throws NullArgumentException if x is {@code null}. * @since 1.2 */ @@ -934,10 +916,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p><p> * Infinite values in real or imaginary parts of the input may result in * infinite or {@code NaN} values returned in parts of the result. * <pre> @@ -974,10 +956,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p><p> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> @@ -1015,10 +997,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * <li>{@code |a + bi| = }{@link Complex#abs}(a + bi)</li> * <li>{@code sign(b) = }{@link FastMath#copySign(double,double) copySign(1d, b)} * </ul> - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> @@ -1060,10 +1042,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * number. * Computes the result directly as * {@code sqrt(ONE.subtract(z.multiply(z)))}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * @@ -1087,10 +1069,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, {@link FastMath#cosh} and * {@link FastMath#sinh}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite (or critical) values in real or imaginary parts of the input may * result in infinite or NaN values returned in parts of the result. * <pre> @@ -1138,10 +1120,10 @@ public class Complex implements FieldElement<Complex>, Serializable { * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, {@link FastMath#cosh} and * {@link FastMath#sinh}. - * <br/> + * <p> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. - * <br/> + * </p> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> @@ -1184,7 +1166,7 @@ public class Complex implements FieldElement<Complex>, Serializable { * The value returned is between -PI (not inclusive) * and PI (inclusive), with negative values returned for numbers with * negative imaginary parts. - * <br/> + * <p> * If either real or imaginary part (or both) is NaN, NaN is returned. * Infinite parts are handled as {@code Math.atan2} handles them, * essentially treating finite parts as zero in the presence of an @@ -1209,14 +1191,14 @@ public class Complex implements FieldElement<Complex>, Serializable { * for <i>{@code k=0, 1, ..., n-1}</i>, where {@code abs} and {@code phi} * are respectively the {@link #abs() modulus} and * {@link #getArgument() argument} of this complex number. - * <br/> + * <p> * If one or both parts of this complex number is NaN, a list with just * one element, {@link #NaN} is returned. * if neither part is NaN, but at least one part is infinite, the result * is a one-element list containing {@link #INF}. * * @param n Degree of root. - * @return a List<Complex> of all {@code n}-th roots of {@code this}. + * @return a List of all {@code n}-th roots of {@code this}. * @throws NotPositiveException if {@code n <= 0}. * @since 2.0 */ http://git-wip-us.apache.org/repos/asf/commons-math/blob/8a8ca83f/src/main/java/org/apache/commons/math4/util/Precision.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math4/util/Precision.java b/src/main/java/org/apache/commons/math4/util/Precision.java index e2d0cc9..91b0cb7 100644 --- a/src/main/java/org/apache/commons/math4/util/Precision.java +++ b/src/main/java/org/apache/commons/math4/util/Precision.java @@ -99,7 +99,8 @@ public class Precision { * @param eps the amount of error to allow when checking for equality * @return <ul><li>0 if {@link #equals(double, double, double) equals(x, y, eps)}</li> * <li>< 0 if !{@link #equals(double, double, double) equals(x, y, eps)} && x < y</li> - * <li>> 0 if !{@link #equals(double, double, double) equals(x, y, eps)} && x > y</li></ul> + * <li>> 0 if !{@link #equals(double, double, double) equals(x, y, eps)} && x > y or + * either argument is NaN</li></ul> */ public static int compareTo(double x, double y, double eps) { if (equals(x, y, eps)) { @@ -117,7 +118,7 @@ public class Precision { * point numbers are considered equal. * Adapted from <a * href="http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/";> - * Bruce Dawson</a> + * Bruce Dawson</a>. Returns {@code false} if either of the arguments is NaN. * * @param x first value * @param y second value @@ -125,7 +126,8 @@ public class Precision { * values between {@code x} and {@code y}. * @return <ul><li>0 if {@link #equals(double, double, int) equals(x, y, maxUlps)}</li> * <li>< 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} && x < y</li> - * <li>> 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} && x > y</li></ul> + * <li>> 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} && x > y + * or either argument is NaN</li></ul> */ public static int compareTo(final double x, final double y, final int maxUlps) { if (equals(x, y, maxUlps)) { @@ -149,7 +151,7 @@ public class Precision { } /** - * Returns true if both arguments are NaN or neither is NaN and they are + * Returns true if both arguments are NaN or they are * equal as defined by {@link #equals(float,float) equals(x, y, 1)}. * * @param x first value @@ -162,8 +164,9 @@ public class Precision { } /** - * Returns true if both arguments are equal or within the range of allowed - * error (inclusive). + * Returns true if the arguments are equal or within the range of allowed + * error (inclusive). Returns {@code false} if either of the arguments + * is NaN. * * @param x first value * @param y second value @@ -176,7 +179,7 @@ public class Precision { } /** - * Returns true if both arguments are NaN or are equal or within the range + * Returns true if the arguments are both NaN, are equal, or are within the range * of allowed error (inclusive). * * @param x first value @@ -191,14 +194,14 @@ public class Precision { } /** - * Returns true if both arguments are equal or within the range of allowed + * Returns true if the arguments are equal or within the range of allowed * error (inclusive). * Two float numbers are considered equal if there are {@code (maxUlps - 1)} * (or fewer) floating point numbers between them, i.e. two adjacent floating * point numbers are considered equal. * Adapted from <a * href="http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/";> - * Bruce Dawson</a> + * Bruce Dawson</a>. Returns {@code false} if either of the arguments is NaN. * * @param x first value * @param y second value @@ -242,7 +245,7 @@ public class Precision { } /** - * Returns true if both arguments are NaN or if they are equal as defined + * Returns true if the arguments are both NaN or if they are equal as defined * by {@link #equals(float,float,int) equals(x, y, maxUlps)}. * * @param x first value @@ -270,7 +273,7 @@ public class Precision { } /** - * Returns true if both arguments are NaN or neither is NaN and they are + * Returns true if the arguments are both NaN or they are * equal as defined by {@link #equals(double,double) equals(x, y, 1)}. * * @param x first value @@ -285,7 +288,8 @@ public class Precision { /** * Returns {@code true} if there is no double value strictly between the * arguments or the difference between them is within the range of allowed - * error (inclusive). + * error (inclusive). Returns {@code false} if either of the arguments + * is NaN. * * @param x First value. * @param y Second value. @@ -299,8 +303,9 @@ public class Precision { /** * Returns {@code true} if there is no double value strictly between the - * arguments or the relative difference between them is smaller or equal - * to the given tolerance. + * arguments or the relative difference between them is less than or equal + * to the given tolerance. Returns {@code false} if either of the arguments + * is NaN. * * @param x First value. * @param y Second value. @@ -321,7 +326,7 @@ public class Precision { } /** - * Returns true if both arguments are NaN or are equal or within the range + * Returns true if the arguments are both NaN, are equal or are within the range * of allowed error (inclusive). * * @param x first value @@ -336,7 +341,7 @@ public class Precision { } /** - * Returns true if both arguments are equal or within the range of allowed + * Returns true if the arguments are equal or within the range of allowed * error (inclusive). * <p> * Two float numbers are considered equal if there are {@code (maxUlps - 1)} @@ -346,7 +351,7 @@ public class Precision { * <p> * Adapted from <a * href="http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/";> - * Bruce Dawson</a> + * Bruce Dawson</a>. Returns {@code false} if either of the arguments is NaN. * </p> * * @param x first value http://git-wip-us.apache.org/repos/asf/commons-math/blob/8a8ca83f/src/test/java/org/apache/commons/math4/complex/ComplexTest.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/math4/complex/ComplexTest.java b/src/test/java/org/apache/commons/math4/complex/ComplexTest.java index 6694dd6..9032692 100644 --- a/src/test/java/org/apache/commons/math4/complex/ComplexTest.java +++ b/src/test/java/org/apache/commons/math4/complex/ComplexTest.java @@ -568,6 +568,15 @@ public class ComplexTest { } @Test + public void testFloatingPointEqualsWithAllowedDeltaNaN() { + final Complex x = new Complex(0, Double.NaN); + final Complex y = new Complex(Double.NaN, 0); + Assert.assertFalse(Complex.equals(x, Complex.ZERO, 0.1)); + Assert.assertFalse(Complex.equals(x, x, 0.1)); + Assert.assertFalse(Complex.equals(x, y, 0.1)); + } + + @Test public void testFloatingPointEqualsWithRelativeTolerance() { final double tol = 1e-4; final double re = 1; @@ -580,6 +589,15 @@ public class ComplexTest { } @Test + public void testFloatingPointEqualsWithRelativeToleranceNaN() { + final Complex x = new Complex(0, Double.NaN); + final Complex y = new Complex(Double.NaN, 0); + Assert.assertFalse(Complex.equalsWithRelativeTolerance(x, Complex.ZERO, 0.1)); + Assert.assertFalse(Complex.equalsWithRelativeTolerance(x, x, 0.1)); + Assert.assertFalse(Complex.equalsWithRelativeTolerance(x, y, 0.1)); + } + + @Test public void testEqualsTrue() { Complex x = new Complex(3.0, 4.0); Complex y = new Complex(3.0, 4.0);
