Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'MATH_3_X' of https://luc@git-wip-us.apache.org/repos/asf/commons-math.git into MATH_3_X

This commit is contained in:
Luc Maisonobe 2016-01-02 10:28:21 +01:00
parent 29649959e2 895e9c1c50
commit c5e6ccb817
3 changed files with 108 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
src/main/java/org/apache/commons/math3/complex/Complex.java
View File

@ -32,7 +32,7 @@ import org.apache.commons.math3.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.math3.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.math3.util.Precision#equals(double,double,int)
* equals for primitive double} in {@link org.apache.commons.math3.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
@ -180,17 +175,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() {
@ -216,7 +211,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>
@ -401,7 +396,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}).
@ -421,7 +416,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}).
@ -500,21 +495,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}.
@ -580,7 +573,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}.
*/
@ -596,11 +589,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
@ -641,11 +632,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.
*
@ -665,13 +654,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
@ -689,13 +676,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
@ -712,27 +697,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 &plusmn; INFINITY i) = 1 &#x2213; INFINITY i
* cos(1 &plusmn; INFINITY i) = 1 \u2213 INFINITY i
* cos(&plusmn;INFINITY + i) = NaN + NaN i
* cos(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
* </code>
@ -757,16 +739,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>
@ -803,10 +785,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>
@ -845,10 +827,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>
@ -886,13 +868,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
*/
@ -927,10 +909,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>
@ -967,10 +949,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>
@ -1008,10 +990,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>
@ -1053,10 +1035,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.
*
@ -1080,10 +1062,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>
@ -1131,10 +1113,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>
@ -1177,7 +1159,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
@ -1202,14 +1184,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
*/

39
src/main/java/org/apache/commons/math3/util/Precision.java
View File

@ -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>&lt; 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; x &lt; y</li>
* <li>> 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; x > y</li></ul>
* <li>> 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; 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>&lt; 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; x &lt; y</li>
* <li>> 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; x > y</li></ul>
* <li>&gt; 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; 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

18
src/test/java/org/apache/commons/math3/complex/ComplexTest.java
View File

@ -564,6 +564,15 @@ public class ComplexTest {
Assert.assertFalse(Complex.equals(x, y, tol2));
}
@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;
@ -576,6 +585,15 @@ public class ComplexTest {
Assert.assertTrue(Complex.equalsWithRelativeTolerance(x, y, tol));
}
@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);