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 2020/01/02 15:04:42 UTC
[commons-numbers] branch master updated (fd3e2f1 -> 6361a80)
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 fd3e2f1 Pre-compute bit representation of -0.0.
new b215129 Added C99 special cases to javadoc.
new f1b8cc3 Update C99 standard for acosh and tanh
new f12e04e Remove dependency on numbers-core for the Precision EPSILON.
new 6361a80 Javadoc cleanup of <pre> tags for better rendered layout.
The 4 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:
commons-numbers-complex/pom.xml | 1 +
.../apache/commons/numbers/complex/Complex.java | 479 ++++++++++++++++-----
.../commons/numbers/complex/CStandardTest.java | 17 +-
3 files changed, 379 insertions(+), 118 deletions(-)
[commons-numbers] 01/04: Added C99 special cases to javadoc.
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 b215129a1101b6cf14b36ca33ab0274dff4305c1
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Wed Jan 1 22:12:59 2020 +0000
Added C99 special cases to javadoc.
Improved layout of MathJax to separate paragraphs.
---
.../apache/commons/numbers/complex/Complex.java | 387 ++++++++++++++++-----
1 file changed, 308 insertions(+), 79 deletions(-)
diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
index 967a196..5b710a2 100644
--- a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
+++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
@@ -32,15 +32,15 @@ import org.apache.commons.numbers.core.Precision;
*
* <p>Arithmetic in this class conforms to the C99 standard for complex numbers
* defined in ISO/IEC 9899, Annex G. All methods have been named using the equivalent
- * method in ISO C99.</p>
+ * method in ISO C99. The behaviour for special cases is listed as defined in C99.</p>
*
- * <p>Operations ({@code op}) with no arguments obey the conjugate equality:</p>
- * <pre>z.op().conjugate() == z.conjugate().op()</pre>
+ * <p>For functions \( f \) which obey the conjugate equality \( conj(f(z)) = f(conj(z)) \),
+ * the specifications for the upper half-plane imply the specifications for the lower
+ * half-plane.</p>
*
- * <p>Operations that are odd or even obey the equality:</p>
- *
- * <p>Odd: \( f(z) = -f(-z) \)
- * <p>Even: \( f(z) = f(-z) \)
+ * <p>For functions that are either odd, \( f(z) = -f(-z) \), or even, \( f(z) = f(-z) \)
+ * the specifications for the first quadrant imply the specifications for the other three
+ * quadrants.</p>
*
* @see <a href="http://www.open-std.org/JTC1/SC22/WG14/www/standards">
* ISO/IEC 9899 - Programming languages - C</a>
@@ -415,7 +415,7 @@ public final class Complex implements Serializable {
* Returns the absolute value of this complex number. This is also called complex norm, modulus,
* or magnitude.
*
- * \[ \text{abs}(x + i y) = \sqrt{(x^2 + y^2)} \]
+ * <p>\[ \text{abs}(x + i y) = \sqrt{(x^2 + y^2)} \]
*
* <p>If either component is infinite then the result is positive infinity. If either
* component is NaN and this is not {@link #isInfinite() infinite} then the result is NaN.
@@ -440,7 +440,7 @@ public final class Complex implements Serializable {
* Returns the squared norm value of this complex number. This is also called the absolute
* square.
*
- * \[ \text{norm}(x + i y) = x^2 + y^2 \]
+ * <p>\[ \text{norm}(x + i y) = x^2 + y^2 \]
*
* <p>If either component is infinite then the result is positive infinity. If either
* component is NaN and this is not {@link #isInfinite() infinite} then the result is NaN.
@@ -466,7 +466,7 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code (this + addend)}.
* Implements the formula:
*
- * \[ (a + i b) + (c + i d) = (a + c) + i (b + d) \]
+ * <p>\[ (a + i b) + (c + i d) = (a + c) + i (b + d) \]
*
* @param addend Value to be added to this complex number.
* @return {@code this + addend}.
@@ -482,7 +482,7 @@ public final class Complex implements Serializable {
* with {@code addend} interpreted as a real number.
* Implements the formula:
*
- * \[ (a + i b) + c = (a + c) + i b \]
+ * <p>\[ (a + i b) + c = (a + c) + i b \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* real-only and complex numbers.</p>
@@ -506,7 +506,7 @@ public final class Complex implements Serializable {
* with {@code addend} interpreted as an imaginary number.
* Implements the formula:
*
- * \[ (a + i b) + i d = a + i (b + d) \]
+ * <p>\[ (a + i b) + i d = a + i (b + d) \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* imaginary-only and complex numbers.</p>
@@ -530,8 +530,8 @@ public final class Complex implements Serializable {
* <a href="http://mathworld.wolfram.com/ComplexConjugate.html">conjugate</a>
* \( \overline{z} \) of this complex number \( z \).
*
- * \[ z = x + i y \\
- * \overline{z} = x - i y \]
+ * <p>\[ z = x + i y \\
+ * \overline{z} = x - i y \]
*
* @return The conjugate (\( \overline{z} \)) of this complex number.
*/
@@ -543,7 +543,7 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code (this / divisor)}.
* Implements the formula:
*
- * \[ \frac{a + i b}{c + i d} = \frac{(ac + bd) + i (bc - ad)}{c^2+d^2} \]
+ * <p>\[ \frac{a + i b}{c + i d} = \frac{(ac + bd) + i (bc - ad)}{c^2+d^2} \]
*
* <p>Re-calculates NaN result values to recover infinities as specified in C99 standard G.5.1.
*
@@ -678,7 +678,8 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code (this / divisor)},
* with {@code divisor} interpreted as a real number.
* Implements the formula:
- * \[ \frac{a + i b}{c} = \frac{a}{c} + i \frac{b}{c} \]
+ *
+ * <p>\[ \frac{a + i b}{c} = \frac{a}{c} + i \frac{b}{c} \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* real-only and complex numbers.</p>
@@ -702,7 +703,8 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code (this / divisor)},
* with {@code divisor} interpreted as an imaginary number.
* Implements the formula:
- * \[ \frac{a + i b}{id} = \frac{b}{d} - i \frac{a}{d} \]
+ *
+ * <p>\[ \frac{a + i b}{id} = \frac{b}{d} - i \frac{a}{d} \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* imaginary-only and complex numbers.</p>
@@ -852,7 +854,8 @@ public final class Complex implements Serializable {
/**
* Returns a {@code Complex} whose value is {@code this * factor}.
* Implements the formula:
- * \[ (a + i b)(c + i d) = (ac - bd) + i (ad + bc) \]
+ *
+ * <p>\[ (a + i b)(c + i d) = (ac - bd) + i (ad + bc) \]
*
* <p>Recalculates to recover infinities as specified in C99 standard G.5.1.
*
@@ -992,7 +995,8 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code this * factor}, with {@code factor}
* interpreted as a real number.
* Implements the formula:
- * \[ (a + i b) c = (ac) + i (bc) \]
+ *
+ * <p>\[ (a + i b) c = (ac) + i (bc) \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* real-only and complex numbers.</p>
@@ -1016,7 +1020,8 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code this * factor}, with {@code factor}
* interpreted as an imaginary number.
* Implements the formula:
- * \[ (a + i b) id = (-bd) + i (ad) \]
+ *
+ * <p>\[ (a + i b) id = (-bd) + i (ad) \]
*
* <p>This method can be used to compute the multiplication of this complex number \( z \)
* by \( i \). This should be used in preference to
@@ -1056,7 +1061,8 @@ public final class Complex implements Serializable {
/**
* Returns a {@code Complex} whose value is {@code (this - subtrahend)}.
* Implements the formula:
- * \[ (a + i b) - (c + i d) = (a - c) + i (b - d) \]
+ *
+ * <p>\[ (a + i b) - (c + i d) = (a - c) + i (b - d) \]
*
* @param subtrahend Value to be subtracted from this complex number.
* @return {@code this - subtrahend}.
@@ -1071,7 +1077,8 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code (this - subtrahend)},
* with {@code subtrahend} interpreted as a real number.
* Implements the formula:
- * \[ (a + i b) - c = (a - c) + i b \]
+ *
+ * <p>\[ (a + i b) - c = (a - c) + i b \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* real-only and complex numbers.</p>
@@ -1088,7 +1095,8 @@ public final class Complex implements Serializable {
* Returns a {@code Complex} whose value is {@code (this - subtrahend)},
* with {@code subtrahend} interpreted as an imaginary number.
* Implements the formula:
- * \[ (a + i b) - i d = a + i (b - d) \]
+ *
+ * <p>\[ (a + i b) - i d = a + i (b - d) \]
*
* <p>This method is included for compatibility with ISO C99 which defines arithmetic between
* imaginary-only and complex numbers.</p>
@@ -1151,10 +1159,31 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/InverseCosine.html">
* inverse cosine</a> of this complex number.
- * \[ \cos^{-1}(z) = \frac{\pi}{2} + i \left(\ln{iz + \sqrt{1 - z^2}}\right) \]
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \cos^{-1}(z) = \cos^{-1}(B) - i\ \text{sgn}(y) \ln\left(A + \sqrt{A^2-1}\right) \\
+ * <p>\[ \cos^{-1}(z) = \frac{\pi}{2} + i \left(\ln{iz + \sqrt{1 - z^2}}\right) \]
+ *
+ * <p>The inverse cosine of \( z \) is in the range \( [0, \infty) \) along the real axis and
+ * in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().acos() == z.acos().conj()}.
+ * <li>If {@code z} is ±0 + i0, returns π/2 − i0.
+ * <li>If {@code z} is ±0 + iNaN, returns π/2 + iNaN.
+ * <li>If {@code z} is x + i∞ for finite x, returns π/2 − i∞.
+ * <li>If {@code z} is x + iNaN, returns NaN + iNaN.
+ * <li>If {@code z} is −∞ + iy for positive-signed finite y, returns π − i∞.
+ * <li>If {@code z} is +∞ + iy for positive-signed finite y, returns +0 − i∞.
+ * <li>If {@code z} is −∞ + i∞, returns 3π /4 − i∞.
+ * <li>If {@code z} is +∞ + i∞, returns π /4 − i∞.
+ * <li>If {@code z} is ±∞ + iNaN, returns NaN ± i∞ where the sign of the imaginary part of the result is unspecified.
+ * <li>If {@code z} is NaN + iy for finite y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + i∞, returns NaN − i∞.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>This function is implemented using real \( x \) and imaginary \( y \) parts:
+ *
+ * <p>\[ \cos^{-1}(z) = \cos^{-1}(B) - i\ \text{sgn}(y) \ln\left(A + \sqrt{A^2-1}\right) \\
* A = \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} + \sqrt{(x-1)^2+y^2} \right] \\
* B = \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} - \sqrt{(x-1)^2+y^2} \right] \]
*
@@ -1311,10 +1340,16 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/InverseSine.html">
* inverse sine</a> of this complex number.
- * \[ \sin^{-1}(z) = - i \left(\ln{iz + \sqrt{1 - z^2}}\right) \]
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \sin^{-1}(z) = \sin^{-1}(B) + i\ \text{sgn}(y)\ln \left(A + \sqrt{A^2-1} \right) \\
+ * <p>\[ \sin^{-1}(z) = - i \left(\ln{iz + \sqrt{1 - z^2}}\right) \]
+ *
+ * <p>The inverse sine of \( z \) is unbounded along the imaginary axis and
+ * in the range \( [-\pi, \pi] \) along the real axis. Special cases are handled
+ * as if the operation is implemented using \( \sin^{-1}(z) = -i \sinh^{-1}(iz) \).
+ *
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
+ *
+ * <p>\[ \sin^{-1}(z) = \sin^{-1}(B) + i\ \text{sgn}(y)\ln \left(A + \sqrt{A^2-1} \right) \\
* A = \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} + \sqrt{(x-1)^2+y^2} \right] \\
* B = \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} - \sqrt{(x-1)^2+y^2} \right] \]
*
@@ -1476,7 +1511,8 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/InverseTangent.html">
* inverse tangent</a> of this complex number.
- * \[ \tan^{-1}(z) = \frac{i}{2} \ln \left( \frac{i + z}{i - z} \right) \]
+ *
+ * <p>\[ \tan^{-1}(z) = \frac{i}{2} \ln \left( \frac{i + z}{i - z} \right) \]
*
* <p>As per the C99 standard this function is computed using the trigonomic identity:
* \[ \tan^{-1}(z) = -i \tanh^{-1}(iz) \]
@@ -1495,12 +1531,30 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/InverseHyperbolicSine.html">
* inverse hyperbolic sine</a> of this complex number.
- * \[ \sinh^{-1}(z) = \ln \left(z + \sqrt{1 + z^2} \right) \]
*
- * <p>This is an odd function: \( \sinh^{-1}(z) = -\sinh^{-1}(-z) \).
+ * <p>\[ \sinh^{-1}(z) = \ln \left(z + \sqrt{1 + z^2} \right) \]
+ *
+ * <p>The inverse hyperbolic sine of \( z \) is unbounded along the real axis and
+ * in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().asinh() == z.asinh().conj()}.
+ * <li>This is an odd function: \( \sinh^{-1}(z) = -\sinh^{-1}(-z) \).
+ * <li>If {@code z} is +0 + i0, returns 0 + i0.
+ * <li>If {@code z} is x + i∞ for positive-signed finite x, returns +∞ + iπ/2.
+ * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is +∞ + iy for positive-signed finite y, returns +∞ + i0.
+ * <li>If {@code z} is +∞ + i∞, returns +∞ + iπ/4.
+ * <li>If {@code z} is +∞ + iNaN, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + i0, returns NaN + i0.
+ * <li>If {@code z} is NaN + iy for finite nonzero y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
*
* <p>This function is computed using the trigonomic identity:
- * \[ \sinh^{-1}(z) = -i \sin^{-1}(iz) \]
+ *
+ * <p>\[ \sinh^{-1}(z) = -i \sin^{-1}(iz) \]
*
* @return The inverse hyperbolic sine of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/ArcSinh/">ArcSinh</a>
@@ -1518,13 +1572,32 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/InverseHyperbolicTangent.html">
* inverse hyperbolic tangent</a> of this complex number.
- * \[ \tanh^{-1}(z) = \frac{1}{2} \ln \left( \frac{1 + z}{1 - z} \right) \]
*
- * <p>This is an odd function: \( \tanh^{-1}(z) = -\tanh^{-1}(-z) \).
+ * <p>\[ \tanh^{-1}(z) = \frac{1}{2} \ln \left( \frac{1 + z}{1 - z} \right) \]
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \tanh^{-1}(z) = \frac{1}{4} \ln \left(1 + \frac{4x}{(1-x)^2+y^2} \right) + \\
- * i \frac{1}{2} \left( \tan^{-1} \left(\frac{2y}{1-x^2-y^2} \right) + \frac{\pi}{2} \left(\text{sgn}(x^2+y^2-1)+1 \right) \text{sgn}(y) \right) \]
+ * <p>The inverse hyperbolic tangent of \( z \) is unbounded along the real axis and
+ * in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().atanh() == z.atanh().conj()}.
+ * <li>This is an odd function: \( \tanh^{-1}(z) = -\tanh^{-1}(-z) \).
+ * <li>If {@code z} is +0 + i0, returns +0 + i0.
+ * <li>If {@code z} is +0 + iNaN, returns +0 + iNaN.
+ * <li>If {@code z} is +1 + i0, returns +∞ + i0.
+ * <li>If {@code z} is x + i∞ for finite positive-signed x, returns +0 + iπ /2.
+ * <li>If {@code z} is x+iNaN for nonzero finite x, returns NaN+iNaN.
+ * <li>If {@code z} is +∞ + iy for finite positive-signed y, returns +0 + iπ /2.
+ * <li>If {@code z} is +∞ + i∞, returns +0 + iπ /2.
+ * <li>If {@code z} is +∞ + iNaN, returns +0 + iNaN.
+ * <li>If {@code z} is NaN+iy for finite y, returns NaN+iNaN.
+ * <li>If {@code z} is NaN + i∞, returns ±0 + iπ /2 (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
+ *
+ * <p>\[ \tanh^{-1}(z) = \frac{1}{4} \ln \left(1 + \frac{4x}{(1-x)^2+y^2} \right) + \\
+ * i \frac{1}{2} \left( \tan^{-1} \left(\frac{2y}{1-x^2-y^2} \right) + \frac{\pi}{2} \left(\text{sgn}(x^2+y^2-1)+1 \right) \text{sgn}(y) \right) \]
*
* <p>The imaginary part is computed using {@link Math#atan2(double, double)} to ensure the
* correct quadrant is returned from \( \tan^{-1} \left(\frac{2y}{1-x^2-y^2} \right) \).
@@ -1532,7 +1605,7 @@ public final class Complex implements Serializable {
* <p>The code has been adapted from the <a href="https://www.boost.org/">Boost</a>
* {@code c++} implementation {@code <boost/math/complex/atanh.hpp>}. The function is well
* defined over the entire complex number range, and produces accurate values even at the
- * extremes due to special handling of overflow and underflow conditions.</p>
+ * extremes due to special handling of overflow and underflow conditions.
*
* @return The inverse hyperbolic tangent of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/ArcTanh/">ArcTanh</a>
@@ -1702,13 +1775,33 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/InverseHyperbolicCosine.html">
* inverse hyperbolic cosine</a> of this complex number.
- * \[ \cosh^{-1}(z) = \ln \left(z + \sqrt{z + 1} \sqrt{z - 1} \right) \]
*
- * <p>This function is computed using the trigonomic identity:</p>
- * \[ \cosh^{-1}(z) = \pm i \cos^{-1}(z) \]
+ * <p>\[ \cosh^{-1}(z) = \ln \left(z + \sqrt{z + 1} \sqrt{z - 1} \right) \]
+ *
+ * <p>The inverse hyperbolic cosine of \( z \) is in the range \( [0, \infty) \) along the real axis and
+ * in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().acosh() == z.acosh().conj()}.
+ * <li>If {@code z} is ±0 + i0, returns +0 + iπ/2.
+ * <li>If {@code z} is x + i∞ for finite x, returns +∞ + iπ/2.
+ * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is −∞ + iy for positive-signed finite y, returns +∞ + iπ.
+ * <li>If {@code z} is +∞ + iy for positive-signed finite y, returns +∞ + i0.
+ * <li>If {@code z} is −∞ + i∞, returns +∞ + i3π/4.
+ * <li>If {@code z} is +∞ + i∞, returns +∞ + iπ/4.
+ * <li>If {@code z} is ±∞ + iNaN, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + iy for finite y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + i∞, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>This function is computed using the trigonomic identity:
+ *
+ * <p>\[ \cosh^{-1}(z) = \pm i \cos^{-1}(z) \]
*
* <p>The sign of the multiplier is chosen to give {@code z.acosh().real() >= 0}
- * and compatibility with the C99 standard.</p>
+ * and compatibility with the C99 standard.
*
* @return The inverse hyperbolic cosine of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/ArcCosh/">ArcCosh</a>
@@ -1736,15 +1829,18 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/Cosine.html">
* cosine</a> of this complex number.
- * \[ \cos(z) = \frac{1}{2} \left( e^{iz} + e^{-iz} \right) \]
+ *
+ * <p>\[ \cos(z) = \frac{1}{2} \left( e^{iz} + e^{-iz} \right) \]
*
* <p>This is an even function: \( \cos(z) = \cos(-z) \).
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \cos(x + iy) = \cos(x)\cosh(y) - i \sin(x)\sinh(y) \]
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
*
- * <p>As per the C99 standard this function is computed using the trigonomic identity:</p>
- * \[ cos(z) = cosh(iz) \]
+ * <p>\[ \cos(x + iy) = \cos(x)\cosh(y) - i \sin(x)\sinh(y) \]
+ *
+ * <p>As per the C99 standard this function is computed using the trigonomic identity:
+ *
+ * <p>\[ cos(z) = cosh(iz) \]
*
* @return The cosine of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Cos/">Cos</a>
@@ -1760,12 +1856,32 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/HyperbolicCosine.html">
* hyperbolic cosine</a> of this complex number.
- * \[ \cosh(z) = \frac{1}{2} \left( e^{z} + e^{-z} \right) \]
*
- * <p>This is an even function: \( \cosh(z) = \cosh(-z) \).
+ * <p>\[ \cosh(z) = \frac{1}{2} \left( e^{z} + e^{-z} \right) \]
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \cosh(x + iy) = \cosh(x)\cos(y) + i \sinh(x)\sin(y) \]
+ * <p>The hyperbolic cosine of \( z \) is an entire function in the complex plane.
+ * and is periodic with respect to the imaginary component with period \( 2\pi i \).
+ *
+ * <ul>
+ * <li>{@code z.conj().cosh() == z.cosh().conj()}.
+ * <li>This is an even function: \( \cosh(z) = \cosh(-z) \).
+ * <li>If {@code z} is +0 + i0, returns 1 + i0.
+ * <li>If {@code z} is +0 + i∞, returns NaN ± i0 (where the sign of the imaginary part of the result is unspecified).
+ * <li>If {@code z} is +0 + iNaN, returns NaN ± i0 (where the sign of the imaginary part of the result is unspecified).
+ * <li>If {@code z} is x + i∞ for finite nonzero x, returns NaN + iNaN.
+ * <li>If {@code z} is x + iNaN for finite nonzero x, returns NaN + iNaN.
+ * <li>If {@code z} is +∞ + i0, returns +∞ + i0.
+ * <li>If {@code z} is +∞ + iy for finite nonzero y, returns +∞ cis(y) (see {@link #ofCis(double)}).
+ * <li>If {@code z} is +∞ + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is +∞ + iNaN, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + i0, returns NaN ± i0 (where the sign of the imaginary part of the result is unspecified).
+ * <li>If {@code z} is NaN + iy for all nonzero numbers y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
+ *
+ * <p>\[ \cosh(x + iy) = \cosh(x)\cos(y) + i \sinh(x)\sin(y) \]
*
* @return The hyperbolic cosine of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Cosh/">Cosh</a>
@@ -1808,10 +1924,32 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/ExponentialFunction.html">
* exponential function</a> of this complex number.
- * \[ \exp(z) = e^z \]
+ *
+ * <p>\[ \exp(z) = e^z \]
+ *
+ * <p>The exponential function of \( z \) is an entire function in the complex plane.
+ * Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().exp() == z.exp().conj()}.
+ * <li>If {@code z} is ±0 + i0, returns 1 + i0.
+ * <li>If {@code z} is x + i∞ for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is +∞ + i0, returns +∞ + i0.
+ * <li>If {@code z} is −∞ + iy for finite y, returns +0 cis(y) (see {@link #ofCis(double)}).
+ * <li>If {@code z} is +∞ + iy for finite nonzero y, returns +∞ cis(y).
+ * <li>If {@code z} is −∞ + i∞, returns ±0 ± i0 (where the signs of the real and imaginary parts of the result are unspecified).
+ * <li>If {@code z} is +∞ + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is −∞ + iNaN, returns ±0 ± i0 (where the signs of the real and imaginary parts of the result are unspecified).
+ * <li>If {@code z} is +∞ + iNaN, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is NaN + i0, returns NaN + i0.
+ * <li>If {@code z} is NaN + iy for all nonzero numbers y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
*
* <p>Implements the formula:
- * \[ \exp(x + iy) = e^x (\cos(y) + i \sin(y)) \]
+ *
+ * <p>\[ \exp(x + iy) = e^x (\cos(y) + i \sin(y)) \]
*
* @return <code>e<sup>this</sup></code>.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Exp/">Exp</a>
@@ -1872,8 +2010,29 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/NaturalLogarithm.html">
* natural logarithm</a> of this complex number.
- * Implements the formula:
- * \[ \ln(z) = \ln |z| + i \arg(z) \]
+ *
+ * <p>The natural logarithm of \( z \) is unbounded along the real axis and
+ * in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().log() == z.log().conj()}.
+ * <li>If {@code z} is −0 + i0, returns −∞ + iπ.
+ * <li>If {@code z} is +0 + i0, returns −∞ + i0.
+ * <li>If {@code z} is x + i∞ for finite x, returns +∞ + iπ/2.
+ * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is −∞ + iy for finite positive-signed y, returns +∞ + iπ.
+ * <li>If {@code z} is +∞ + iy for finite positive-signed y, returns +∞ + i0.
+ * <li>If {@code z} is −∞ + i∞, returns +∞ + i3π/4.
+ * <li>If {@code z} is +∞ + i∞, returns +∞ + iπ/4.
+ * <li>If {@code z} is ±∞ + iNaN, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + iy for finite y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + i∞, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>Implements the formula:
+ *
+ * <p>\[ \ln(z) = \ln |z| + i \arg(z) \]
*
* <p>where \( |z| \) is the absolute and \( \arg(z) \) is the argument.
*
@@ -1898,9 +2057,14 @@ public final class Complex implements Serializable {
* Returns the base 10
* <a href="http://mathworld.wolfram.com/CommonLogarithm.html">
* common logarithm</a> of this complex number.
- * Implements the formula:
- * Implements the formula:
- * \[ \log_{10}(z) = \log_{10} |z| + i \arg(z) \]
+ *
+ * <p>The common logarithm of \( z \) is unbounded along the real axis and
+ * in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases are as
+ * defined in the {@link #log() natural logarithm}:
+ *
+ * <p>Implements the formula:
+ *
+ * <p>\[ \log_{10}(z) = \log_{10} |z| + i \arg(z) \]
*
* <p>where \( |z| \) is the absolute and \( \arg(z) \) is the argument.
*
@@ -2055,11 +2219,12 @@ public final class Complex implements Serializable {
/**
* Returns the complex power of this complex number raised to the power of \( x \).
* Implements the formula:
- * \[ z^x = e^{x \ln(z)} \]
+ *
+ * <p>\[ z^x = e^{x \ln(z)} \]
*
* <p>If this complex number is zero then this method returns zero if \( x \) is positive
* in the real component and zero in the imaginary component;
- * otherwise it returns (NaN + i NaN).
+ * otherwise it returns NaN + iNaN.
*
* @param x The exponent to which this complex number is to be raised.
* @return <code>this<sup>x</sup></code>.
@@ -2087,10 +2252,11 @@ public final class Complex implements Serializable {
/**
* Returns the complex power of this complex number raised to the power of \( x \).
* Implements the formula:
- * \[ z^x = e^{x \ln(z)} \]
+ *
+ * <p>\[ z^x = e^{x \ln(z)} \]
*
* <p>If this complex number is zero then this method returns zero if \( x \) is positive;
- * otherwise it returns (NaN + i NaN).
+ * otherwise it returns NaN + iNaN.
*
* @param x The exponent to which this complex number is to be raised.
* @return <code>this<sup>x</sup></code>.
@@ -2118,15 +2284,18 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/Sine.html">
* sine</a> of this complex number.
- * \[ \sin(z) = \frac{1}{2} i \left( e^{-iz} - e^{iz} \right) \]
+ *
+ * <p>\[ \sin(z) = \frac{1}{2} i \left( e^{-iz} - e^{iz} \right) \]
*
* <p>This is an odd function: \( \sin(z) = -\sin(-z) \).
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \sin(x + iy) = \sin(x)\cosh(y) + i \cos(x)\sinh(y) \]
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
*
- * <p>As per the C99 standard this function is computed using the trigonomic identity:</p>
- * \[ \sin(z) = -i \sinh(iz) \]
+ * <p>\[ \sin(x + iy) = \sin(x)\cosh(y) + i \cos(x)\sinh(y) \]
+ *
+ * <p>As per the C99 standard this function is computed using the trigonomic identity:
+ *
+ * <p>\[ \sin(z) = -i \sinh(iz) \]
*
* @return The sine of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Sin/">Sin</a>
@@ -2142,12 +2311,32 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/HyperbolicSine.html">
* hyperbolic sine</a> of this complex number.
- * \[ \sinh(z) = \frac{1}{2} \left( e^{z} - e^{-z} \right) \]
*
- * <p>This is an odd function: \( \sinh(z) = -\sinh(-z) \).
+ * <p>\[ \sinh(z) = \frac{1}{2} \left( e^{z} - e^{-z} \right) \]
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \sinh(x + iy) = \sinh(x)\cos(y) + i \cosh(x)\sin(y) \]
+ * <p>The hyperbolic sine of \( z \) is an entire function in the complex plane.
+ * and is periodic with respect to the imaginary component with period \( 2\pi i \).
+ *
+ * <ul>
+ * <li>{@code z.conj().sinh() == z.sinh().conj()}.
+ * <li>This is an odd function: \( \sinh(z) = -\sinh(-z) \).
+ * <li>If {@code z} is +0 + i0, returns +0 + i0.
+ * <li>If {@code z} is +0 + i∞, returns ±0 + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is +0 + iNaN, returns ±0 + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is x + i∞ for positive finite x, returns NaN + iNaN.
+ * <li>If {@code z} is x + iNaN for finite nonzero x, returns NaN + iNaN.
+ * <li>If {@code z} is +∞ + i0, returns +∞ + i0.
+ * <li>If {@code z} is +∞ + iy for positive finite y, returns +∞ cis(y) (see {@link #ofCis(double)}.
+ * <li>If {@code z} is +∞ + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is +∞ + iNaN, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
+ * <li>If {@code z} is NaN + i0, returns NaN + i0.
+ * <li>If {@code z} is NaN + iy for all nonzero numbers y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
+ *
+ * <p>\[ \sinh(x + iy) = \sinh(x)\cos(y) + i \cosh(x)\sin(y) \]
*
* @return The hyperbolic sine of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Sinh/">Sinh</a>
@@ -2183,7 +2372,24 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/SquareRoot.html">
* square root</a> of this complex number.
- * \[ \sqrt{x + iy} = \frac{1}{2} \sqrt{2} \left( \sqrt{ \sqrt{x^2 + y^2} + x } + i\ \text{sgn}(y) \sqrt{ \sqrt{x^2 + y^2} - x } \right) \]
+ *
+ * <p>\[ \sqrt{x + iy} = \frac{1}{2} \sqrt{2} \left( \sqrt{ \sqrt{x^2 + y^2} + x } + i\ \text{sgn}(y) \sqrt{ \sqrt{x^2 + y^2} - x } \right) \]
+ *
+ * <p>The square root of \( z \) is in the range \( [0, +\infty) \) along the real axis and
+ * is unbounded along the imaginary axis. Special cases:
+ *
+ * <ul>
+ * <li>{@code z.conj().sqrt() == z.sqrt().conj()}.
+ * <li>If {@code z} is ±0 + i0, returns +0 + i0.
+ * <li>If {@code z} is x + i∞ for all x (including NaN), returns +∞ + i∞.
+ * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is −∞ + iy for finite positive-signed y, returns +0 + i∞.
+ * <li>If {@code z} is +∞ + iy for finite positive-signed y, returns +∞ + i0.
+ * <li>If {@code z} is −∞ + iNaN, returns NaN ± i∞ (where the sign of the imaginary part of the result is unspecified).
+ * <li>If {@code z} is +∞ + iNaN, returns +∞ + iNaN.
+ * <li>If {@code z} is NaN + iy for finite y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
*
* <p>Implements the following algorithm to compute \( \sqrt{x + iy} \):
* <ol>
@@ -2290,7 +2496,8 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/Tangent.html">
* tangent</a> of this complex number.
- * \[ \tan(z) = \frac{i(e^{-iz} - e^{iz})}{e^{-iz} + e^{iz}} \]
+ *
+ * <p>\[ \tan(z) = \frac{i(e^{-iz} - e^{iz})}{e^{-iz} + e^{iz}} \]
*
* <p>This is an odd function: \( \tan(z) = -\tan(-z) \).
*
@@ -2314,12 +2521,33 @@ public final class Complex implements Serializable {
* Returns the
* <a href="http://mathworld.wolfram.com/HyperbolicTangent.html">
* hyperbolic tangent</a> of this complex number.
- * \[ \tanh(z) = \frac{e^z - e^{-z}}{e^z + e^{-z}} \]
*
- * <p>This is an odd function: \( \tanh(z) = -\tanh(-z) \).
+ * <p>\[ \tanh(z) = \frac{e^z - e^{-z}}{e^z + e^{-z}} \]
*
- * <p>This is implemented using real \( x \) and imaginary \( y \) parts:</p>
- * \[ \tan(x + iy) = \frac{\sinh(2x)}{\cosh(2x)+\cos(2y)} + i \frac{\sin(2y)}{\cosh(2x)+\cos(2y)} \]
+ * <p>The hyperbolic tangent of \( z \) is an entire function in the complex plane.
+ * and is periodic with respect to the imaginary component with period \( \pi i \)
+ * and has poles of the first order along the imaginary line, at coordinates
+ * \( (0, \pi(\frac{1}{2} + n)) \).
+ * Note that the {@code double} floating-point representation is unable to exactly represent
+ * \( \pi/2 \) and there is no value for which a pole error occurs.
+ *
+ * <ul>
+ * <li>{@code z.conj().tanh() == z.tanh().conj()}.
+ * <li>This is an odd function: \( \tanh(z) = -\tanh(-z) \).
+ * <li>If {@code z} is +0 + i0, returns +0 + i0.
+ * <li>If {@code z} is x + i∞ for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is +∞ + iy for positive-signed finite y, returns 1 + i0 sin(2y).
+ * <li>If {@code z} is +∞ + i∞, returns 1 ± i0 (where the sign of the imaginary part of the result is unspecified).
+ * <li>If {@code z} is +∞ + iNaN, returns 1 ± i0 (where the sign of the imaginary part of the result is unspecified).
+ * <li>If {@code z} is NaN + i0, returns NaN + i0.
+ * <li>If {@code z} is NaN + iy for all nonzero numbers y, returns NaN + iNaN.
+ * <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
+ * </ul>
+ *
+ * <p>This is implemented using real \( x \) and imaginary \( y \) parts:
+ *
+ * <p>\[ \tan(x + iy) = \frac{\sinh(2x)}{\cosh(2x)+\cos(2y)} + i \frac{\sin(2y)}{\cosh(2x)+\cos(2y)} \]
*
* @return The hyperbolic tangent of this complex number.
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Tanh/">Tanh</a>
@@ -2458,7 +2686,8 @@ public final class Complex implements Serializable {
/**
* Returns the n-th roots of this complex number.
* The nth roots are defined by the formula:
- * \[ z_k = |z|^{\frac{1}{n}} \left( \cos \left(\phi + \frac{2\pi k}{n} \right) + i \sin \left(\phi + \frac{2\pi k}{n} \right) \right) \]
+ *
+ * <p>\[ z_k = |z|^{\frac{1}{n}} \left( \cos \left(\phi + \frac{2\pi k}{n} \right) + i \sin \left(\phi + \frac{2\pi k}{n} \right) \right) \]
*
* <p>for \( k=0, 1, \ldots, n-1 \), where \( |z| \) and \( \phi \)
* are respectively the {@link #abs() modulus} and
[commons-numbers] 03/04: Remove dependency on numbers-core for the
Precision EPSILON.
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 f12e04e7e4a5354f2c5a58ee1e493e7e67401694
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Thu Jan 2 13:57:29 2020 +0000
Remove dependency on numbers-core for the Precision EPSILON.
The dependency has been reduced to test scope.
---
commons-numbers-complex/pom.xml | 1 +
.../apache/commons/numbers/complex/Complex.java | 24 ++++++++++++++++------
2 files changed, 19 insertions(+), 6 deletions(-)
diff --git a/commons-numbers-complex/pom.xml b/commons-numbers-complex/pom.xml
index 29b0872..a50beac 100644
--- a/commons-numbers-complex/pom.xml
+++ b/commons-numbers-complex/pom.xml
@@ -46,6 +46,7 @@
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-numbers-core</artifactId>
+ <scope>test</scope>
</dependency>
<dependency>
diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
index 79b2408..bee566b 100644
--- a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
+++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
@@ -21,8 +21,6 @@ import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;
-import org.apache.commons.numbers.core.Precision;
-
/**
* Cartesian representation of a complex number, i.e. a number which has both a
* real and imaginary part.
@@ -87,6 +85,20 @@ public final class Complex implements Serializable {
private static final double PRECISION_1 = 54;
/** The bit representation of {@code -0.0}. */
private static final long NEGATIVE_ZERO_LONG_BITS = Double.doubleToLongBits(-0.0);
+ /** Exponent offset in IEEE754 representation. */
+ private static final long EXPONENT_OFFSET = 1023L;
+ /**
+ * Largest double-precision floating-point number such that
+ * {@code 1 + EPSILON} is numerically equal to 1. This value is an upper
+ * bound on the relative error due to rounding real numbers to double
+ * precision floating-point numbers.
+ *
+ * <p>In IEEE 754 arithmetic, this is 2<sup>-53</sup>.
+ * Copied from o.a.c.numbers.Precision.
+ *
+ * @see <a href="http://en.wikipedia.org/wiki/Machine_epsilon">Machine epsilon</a>
+ */
+ private static final double EPSILON = Double.longBitsToDouble((EXPONENT_OFFSET - 53L) << 52);
/**
* Crossover point to switch computation for asin/acos factor A.
@@ -1292,7 +1304,7 @@ public final class Complex implements Serializable {
}
} else {
// Hull et al: Exception handling code from figure 6
- if (y <= (Precision.EPSILON * Math.abs(xm1))) {
+ if (y <= (EPSILON * Math.abs(xm1))) {
if (x < 1) {
re = Math.acos(x);
im = y / Math.sqrt(xp1 * (1 - x));
@@ -1317,7 +1329,7 @@ public final class Complex implements Serializable {
// u = Double.MIN_NORMAL
re = Math.sqrt(y);
im = Math.sqrt(y);
- } else if (Precision.EPSILON * y - 1 >= x) {
+ } else if (EPSILON * y - 1 >= x) {
re = PI_OVER_2;
im = LN_2 + Math.log(y);
} else if (x > 1) {
@@ -1464,7 +1476,7 @@ public final class Complex implements Serializable {
}
} else {
// Hull et al: Exception handling code from figure 4
- if (y <= (Precision.EPSILON * Math.abs(xm1))) {
+ if (y <= (EPSILON * Math.abs(xm1))) {
if (x < 1) {
re = Math.asin(x);
im = y / Math.sqrt(xp1 * (1 - x));
@@ -1486,7 +1498,7 @@ public final class Complex implements Serializable {
// u = Double.MIN_NORMAL
re = PI_OVER_2 - Math.sqrt(y);
im = Math.sqrt(y);
- } else if (Precision.EPSILON * y - 1 >= x) {
+ } else if (EPSILON * y - 1 >= x) {
// Possible underflow:
re = x / y;
im = LN_2 + Math.log(y);
[commons-numbers] 04/04: Javadoc cleanup of tags for better
rendered layout.
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 6361a80f3910921f8854c15ea5e854f510e208e7
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Thu Jan 2 14:06:19 2020 +0000
Javadoc cleanup of <pre> tags for better rendered layout.
---
.../apache/commons/numbers/complex/Complex.java | 45 +++++++++-------------
1 file changed, 19 insertions(+), 26 deletions(-)
diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
index bee566b..202cc1d 100644
--- a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
+++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
@@ -92,7 +92,7 @@ public final class Complex implements Serializable {
* {@code 1 + EPSILON} is numerically equal to 1. This value is an upper
* bound on the relative error due to rounding real numbers to double
* precision floating-point numbers.
- *
+ *
* <p>In IEEE 754 arithmetic, this is 2<sup>-53</sup>.
* Copied from o.a.c.numbers.Precision.
*
@@ -224,10 +224,11 @@ public final class Complex implements Serializable {
*
* <p>A non-NaN complex number constructed using this method will satisfy the following
* to within floating-point error when {@code theta} is in the range
- * \( -\pi\ \lt \theta \leq \pi \):</p>
+ * \( -\pi\ \lt \theta \leq \pi \):
+ *
* <pre>
* Complex.ofPolar(rho, theta).abs() == rho
- * Complex.ofPolar(rho, theta).arg() == theta </pre>
+ * Complex.ofPolar(rho, theta).arg() == theta</pre>
*
* <p>If {@code rho} is infinite then the resulting parts may be infinite or NaN
* following the rules for double arithmetic, for example:</p>
@@ -292,8 +293,7 @@ public final class Complex implements Serializable {
* "(0.0,0.0)" = Complex.ofCartesian(0, 0)
* "(-0.0, 0.0)" = Complex.ofCartesian(-0.0, 0)
* "(-1.23, 4.56)" = Complex.ofCartesian(-123, 4.56)
- * "(1e300,-1.1e-2)" = Complex.ofCartesian(1e300, -1.1e-2)
- * </pre>
+ * "(1e300,-1.1e-2)" = Complex.ofCartesian(1e300, -1.1e-2)</pre>
*
* @param s String representation.
* @return {@code Complex} number.
@@ -406,10 +406,9 @@ public final class Complex implements Serializable {
* <p>\( z \) projects to \( z \), except that all complex infinities (even those
* with one infinite part and one NaN part) project to positive infinity on the real axis.
*
- * If \( z \) has an infinite part, then {@code z.proj()} shall be equivalent to:</p>
- * <pre>
- * return Complex.ofCartesian(Double.POSITIVE_INFINITY, Math.copySign(0.0, z.imag());
- * </pre>
+ * If \( z \) has an infinite part, then {@code z.proj()} shall be equivalent to:
+ *
+ * <pre>return Complex.ofCartesian(Double.POSITIVE_INFINITY, Math.copySign(0.0, z.imag());</pre>
*
* @return \( z \) projected onto the Riemann sphere.
* @see #isInfinite()
@@ -760,7 +759,7 @@ public final class Complex implements Serializable {
* value of {@code c1.equals(c2)} is {@code true} if and only if
*
* <pre>
- * {@code c1.getReal() == c2.getReal() && c1.getImaginary() == c2.getImaginary()}</pre>
+ * {@code c1.getReal() == c2.getReal() && c1.getImaginary() == c2.getImaginary()}</pre>
*
* <p>also has the value {@code true}. However, there are exceptions:
*
@@ -813,9 +812,9 @@ public final class Complex implements Serializable {
*
* <p>The behavior is the same as if the components of the complex number were passed
* to {@link java.util.Arrays#hashCode(double[]) Arrays.hashCode(double[])}:
+ *
* <pre>
- * {@code Arrays.hashCode(new double[] {getReal(), getImaginary()})}
- * </pre>
+ * {@code Arrays.hashCode(new double[] {getReal(), getImaginary()})}</pre>
*
* @return A hash code value for this object.
* @see java.util.Arrays#hashCode(double[]) Arrays.hashCode(double[])
@@ -882,8 +881,7 @@ public final class Complex implements Serializable {
/**
* Returns a {@code Complex} whose value is:
* <pre>
- * (a + i b)(c + i d) = (ac - bd) + i (ad + bc)
- * </pre>
+ * (a + i b)(c + i d) = (ac - bd) + i (ad + bc)</pre>
*
* <p>Recalculates to recover infinities as specified in C99 standard G.5.1.
*
@@ -2099,9 +2097,9 @@ public final class Complex implements Serializable {
/**
* Returns the logarithm of this complex number using the provided function.
* Implements the formula:
+ *
* <pre>
- * log(x + i y) = log(|x + i y|) + i arg(x + i y)
- * </pre>
+ * log(x + i y) = log(|x + i y|) + i arg(x + i y)</pre>
*
* <p>Warning: The argument {@code logOf2} must be equal to {@code log(2)} using the
* provided log function otherwise scaling using powers of 2 in the case of overflow
@@ -2641,11 +2639,9 @@ public final class Complex implements Serializable {
* Safely compute {@code cos(2*a)} when {@code a} is finite.
* Note that {@link Math#cos(double)} returns NaN when the input is infinite.
* If {@code 2*a} is finite use {@code Math.cos(2*a)}; otherwise use the identity:
+ *
* <pre>
- * <code>
- * cos(2a) = 2 cos<sup>2</sup>(a) - 1
- * </code>
- * </pre>
+ * <code>cos(2a) = 2 cos<sup>2</sup>(a) - 1</code></pre>
*
* @param a Angle a.
* @return The cosine of 2a.
@@ -2664,11 +2660,9 @@ public final class Complex implements Serializable {
* Safely compute {@code sin(2*a)} when {@code a} is finite.
* Note that {@link Math#sin(double)} returns NaN when the input is infinite.
* If {@code 2*a} is finite use {@code Math.sin(2*a)}; otherwise use the identity:
+ *
* <pre>
- * <code>
- * sin(2a) = 2 sin(a) cos(a)
- * </code>
- * </pre>
+ * <code>sin(2a) = 2 sin(a) cos(a)</code></pre>
*
* @param a Angle a.
* @return The sine of 2a.
@@ -2823,8 +2817,7 @@ public final class Complex implements Serializable {
* equivalent of:
*
* <pre>
- * z = new Complex(real, imaginary).multiplyImaginary(-1);
- * </pre>
+ * z = new Complex(real, imaginary).multiplyImaginary(-1);</pre>
*
* @param real Real part.
* @param imaginary Imaginary part.
[commons-numbers] 02/04: Update C99 standard for acosh and tanh
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 f1b8cc31888aa284e39249708787b37164c5d436
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Wed Jan 1 22:49:41 2020 +0000
Update C99 standard for acosh and tanh
See:
http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471
---
.../apache/commons/numbers/complex/Complex.java | 31 ++++++++++++++++------
.../commons/numbers/complex/CStandardTest.java | 17 +++++++++---
2 files changed, 37 insertions(+), 11 deletions(-)
diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
index 5b710a2..79b2408 100644
--- a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
+++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java
@@ -1785,7 +1785,8 @@ public final class Complex implements Serializable {
* <li>{@code z.conj().acosh() == z.acosh().conj()}.
* <li>If {@code z} is ±0 + i0, returns +0 + iπ/2.
* <li>If {@code z} is x + i∞ for finite x, returns +∞ + iπ/2.
- * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is 0 + iNaN, returns NaN + iπ/2 <sup>[1]</sup>.
+ * <li>If {@code z} is x + iNaN for finite non-zero x, returns NaN + iNaN.
* <li>If {@code z} is −∞ + iy for positive-signed finite y, returns +∞ + iπ.
* <li>If {@code z} is +∞ + iy for positive-signed finite y, returns +∞ + i0.
* <li>If {@code z} is −∞ + i∞, returns +∞ + i3π/4.
@@ -1796,6 +1797,10 @@ public final class Complex implements Serializable {
* <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
* </ul>
*
+ * <p>[1] This has been updated as per
+ * <a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471">
+ * DR 471: Complex math functions cacosh and ctanh</a>.
+ *
* <p>This function is computed using the trigonomic identity:
*
* <p>\[ \cosh^{-1}(z) = \pm i \cos^{-1}(z) \]
@@ -1809,11 +1814,13 @@ public final class Complex implements Serializable {
public Complex acosh() {
// Define in terms of acos
// acosh(z) = +-i acos(z)
- // Handle special case:
+ // Note the special case:
// acos(+-0 + iNaN) = π/2 + iNaN
- // acosh(x + iNaN) = NaN + iNaN for all finite x (including zero)
- if (Double.isNaN(imaginary) && Double.isFinite(real)) {
- return NAN;
+ // acosh(0 + iNaN) = NaN + iπ/2
+ // will not appropriately multiply by I to maintain positive imaginary if
+ // acos() imaginary computes as NaN. So do this explicitly.
+ if (Double.isNaN(imaginary) && real == 0) {
+ return new Complex(Double.NaN, PI_OVER_2);
}
return acos(real, imaginary, (re, im) ->
// Set the sign appropriately for real >= 0
@@ -2517,6 +2524,8 @@ public final class Complex implements Serializable {
return tanh(-imaginary, real, Complex::multiplyNegativeI);
}
+ // TODO
+
/**
* Returns the
* <a href="http://mathworld.wolfram.com/HyperbolicTangent.html">
@@ -2535,8 +2544,10 @@ public final class Complex implements Serializable {
* <li>{@code z.conj().tanh() == z.tanh().conj()}.
* <li>This is an odd function: \( \tanh(z) = -\tanh(-z) \).
* <li>If {@code z} is +0 + i0, returns +0 + i0.
- * <li>If {@code z} is x + i∞ for finite x, returns NaN + iNaN.
- * <li>If {@code z} is x + iNaN for finite x, returns NaN + iNaN.
+ * <li>If {@code z} is 0 + i∞, returns 0 + iNaN.
+ * <li>If {@code z} is x + i∞ for finite non-zero x, returns NaN + iNaN.
+ * <li>If {@code z} is 0 + iNaN, returns 0 + iNAN.
+ * <li>If {@code z} is x + iNaN for finite non-zero x, returns NaN + iNaN.
* <li>If {@code z} is +∞ + iy for positive-signed finite y, returns 1 + i0 sin(2y).
* <li>If {@code z} is +∞ + i∞, returns 1 ± i0 (where the sign of the imaginary part of the result is unspecified).
* <li>If {@code z} is +∞ + iNaN, returns 1 ± i0 (where the sign of the imaginary part of the result is unspecified).
@@ -2545,6 +2556,10 @@ public final class Complex implements Serializable {
* <li>If {@code z} is NaN + iNaN, returns NaN + iNaN.
* </ul>
*
+ * <p>[1] This has been updated as per
+ * <a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471">
+ * DR 471: Complex math functions cacosh and ctanh</a>.
+ *
* <p>This is implemented using real \( x \) and imaginary \( y \) parts:
*
* <p>\[ \tan(x + iy) = \frac{\sinh(2x)}{\cosh(2x)+\cos(2y)} + i \frac{\sin(2y)}{\cosh(2x)+\cos(2y)} \]
@@ -2581,7 +2596,7 @@ public final class Complex implements Serializable {
// Identity: sin x / (1 + cos x) = tan(x/2)
return constructor.create(real, Math.tan(imaginary));
}
- return constructor.create(Double.NaN, Double.NaN);
+ return constructor.create(real, Double.NaN);
}
if (imaginary == 0) {
if (Double.isNaN(real)) {
diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java
index b47ec5e..374d565 100644
--- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java
+++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java
@@ -65,6 +65,7 @@ public class CStandardTest {
private static final Complex nanInf = complex(nan, inf);
private static final Complex nanNegInf = complex(nan, negInf);
private static final Complex nanZero = complex(nan, 0);
+ private static final Complex nanPiTwo = complex(nan, piOverTwo);
private static final Complex piTwoNaN = complex(piOverTwo, nan);
private static final Complex piNegInf = complex(Math.PI, negInf);
private static final Complex piTwoNegInf = complex(piOverTwo, negInf);
@@ -819,6 +820,9 @@ public class CStandardTest {
/**
* ISO C Standard G.6.2.1.
+ *
+ * @see <a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471">
+ * Complex math functions cacosh and ctanh</a>
*/
@Test
public void testAcosh() {
@@ -829,7 +833,9 @@ public class CStandardTest {
for (double x : finite) {
assertComplex(complex(x, inf), operation, infPiTwo);
}
- for (double x : finite) {
+ assertComplex(zeroNaN, operation, nanPiTwo);
+ assertComplex(negZeroNaN, operation, nanPiTwo);
+ for (double x : nonZeroFinite) {
assertComplex(complex(x, nan), operation, NAN);
}
for (double y : positiveFinite) {
@@ -974,6 +980,9 @@ public class CStandardTest {
/**
* ISO C Standard G.6.2.6.
+ *
+ * @see <a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471">
+ * Complex math functions cacosh and ctanh</a>
*/
@Test
public void testTanh() {
@@ -982,10 +991,12 @@ public class CStandardTest {
assertConjugateEquality(operation);
assertFunctionType(operation, type);
assertComplex(Complex.ZERO, operation, Complex.ZERO, type);
- for (double x : finite) {
+ assertComplex(zeroInf, operation, zeroNaN, type);
+ for (double x : nonZeroFinite) {
assertComplex(complex(x, inf), operation, NAN, type);
}
- for (double x : finite) {
+ assertComplex(zeroNaN, operation, zeroNaN, type);
+ for (double x : nonZeroFinite) {
assertComplex(complex(x, nan), operation, NAN, type);
}
for (double y : positiveFinite) {