commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aherb...@apache.org
Subject [commons-numbers] 01/08: Update Complex javadoc.
Date Wed, 01 Apr 2020 10:58:55 GMT
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 728d6566425902784d9d9842d9929984e16cdce1
Author: aherbert <aherbert@apache.org>
AuthorDate: Wed Apr 1 09:16:48 2020 +0100

    Update Complex javadoc.
    
    Fix typos.
    
    Fix bad MathJax.
    
    Ensure consistency access methods.
---
 .../apache/commons/numbers/complex/Complex.java    | 95 ++++++++++++----------
 1 file changed, 51 insertions(+), 44 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 7cae634..dcb4cff 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
@@ -30,13 +30,13 @@ import java.util.List;
  *
  * <p>Arithmetic in this class conforms to the C99 standard for complex numbers
  * defined in ISO/IEC 9899, Annex G. Methods have been named using the equivalent
- * method in ISO C99. The behaviorfor special cases is listed as defined in C99.</p>
+ * method in ISO C99. The behavior for special cases is listed as defined in C99.</p>
  *
  * <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>For functions that are either odd, \( f(z) = -f(-z) \), or 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>
  *
@@ -46,7 +46,8 @@ import java.util.List;
  * <a href="https://en.cppreference.com/w/c/numeric/fenv/FE_exceptions">floating-point
  * exceptions</a> return the documented value without an explicit mechanism to notify
  * of the exception case, that is no exceptions are thrown during computations in-line with
- * the convention of the corresponding single-valued functions in {@link java.lang.Math}.
+ * the convention of the corresponding single-valued functions in
+ * {@link java.lang.Math java.lang.Math}.
  * These cases are documented in the method special cases as "invalid" or "divide-by-zero"
  * floating-point operation.
  * Note: Invalid floating-point exception cases will result in a complex number where the
@@ -289,8 +290,8 @@ public final class Complex implements Serializable  {
      *    y = \rho \sin(\theta) \]
      *
      * <p>Requires that {@code rho} is non-negative and non-NaN and {@code theta} is
finite;
-     * otherwise returns a complex with NaN real and imaginary parts. A value of {@code -0.0}
is
-     * considered negative and an invalid modulus.
+     * otherwise returns a complex with NaN real and imaginary parts. A {@code rho} value
of
+     * {@code -0.0} is considered negative and an invalid modulus.
      *
      * <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
@@ -362,7 +363,7 @@ public final class Complex implements Serializable  {
      * "(0,0)"             = Complex.ofCartesian(0, 0)
      * "(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)
+     * "(-1.23, 4.56)"     = Complex.ofCartesian(-1.23, 4.56)
      * "(1e300,-1.1e-2)"   = Complex.ofCartesian(1e300, -1.1e-2)</pre>
      *
      * @param s String representation.
@@ -428,7 +429,7 @@ public final class Complex implements Serializable  {
      * Returns {@code true} if either the real <em>or</em> imaginary component
of the complex number is NaN
      * <em>and</em> the complex number is not infinite.
      *
-     * <p>Note that in contrast to {@link Double#isNaN()}:
+     * <p>Note that:
      * <ul>
      *   <li>There is more than one complex number that can return {@code true}.
      *   <li>Different representations of NaN can be distinguished by the
@@ -450,8 +451,8 @@ public final class Complex implements Serializable  {
     /**
      * Returns {@code true} if either real or imaginary component of the complex number is
infinite.
      *
-     * <p>Note: A complex or imaginary value with at least one infinite part is regarded
-     * as an infinity (even if its other part is a NaN).</p>
+     * <p>Note: A complex number with at least one infinite part is regarded
+     * as an infinity (even if its other part is a NaN).
      *
      * @return {@code true} if this instance contains an infinite value.
      * @see Double#isInfinite(double)
@@ -471,7 +472,7 @@ public final class Complex implements Serializable  {
     }
 
     /**
-     * Returns projection of this complex number onto the Riemann sphere.
+     * Returns the projection of this complex number onto the Riemann sphere.
      *
      * <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.
@@ -501,7 +502,7 @@ public final class Complex implements Serializable  {
      * <p>Special cases:
      *
      * <ul>
-     * <li>{@code \text{abs}(x + iy) == \text{abs}(y + ix) == \text{abs}(x - iy)}.
+     * <li>{@code abs(x + iy) == abs(y + ix) == abs(x - iy)}.
      * <li>If {@code z} is ±∞ + iy for any y, returns +∞.
      * <li>If {@code z} is x + iNaN for non-infinite x, returns NaN.
      * <li>If {@code z} is x + i0, returns |x|.
@@ -511,10 +512,12 @@ public final class Complex implements Serializable  {
      * infinity. If either component is NaN and this is not {@link #isInfinite() infinite}
then
      * the result is NaN.
      *
-     * <p>This code follows the
+     * <p>This method follows the
      * <a href="http://www.iso-9899.info/wiki/The_Standard">ISO C Standard</a>,
Annex G,
      * in calculating the returned value without intermediate overflow or underflow.
      *
+     * <p>The computed result will be within 1 ulp of the exact result.
+     *
      * @return The absolute value.
      * @see #isInfinite()
      * @see #isNaN()
@@ -560,9 +563,12 @@ public final class Complex implements Serializable  {
      * <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.
      *
-     * <p>This method will return the square of {@link #abs()}. It can be used as a
faster
-     * alternative for ranking by magnitude although overflow to infinity will create equal
-     * ranking for values that may be still distinguished by {@code abs()}.
+     * <p>Note: This method may not return the same value as the square of {@link #abs()}
as
+     * that method uses an extended precision computation.
+     *
+     * <p>{@code norm()} can be used as a faster alternative than {@code abs()} for
ranking by
+     * magnitude. If used for ranking any overflow to infinity will create an equal ranking
for
+     * values that may be still distinguished by {@code abs()}.
      *
      * @return The square norm value.
      * @see #isInfinite()
@@ -645,8 +651,8 @@ public final class Complex implements Serializable  {
      * <a href="http://mathworld.wolfram.com/ComplexConjugate.html">conjugate</a>
      * \( \overline{z} \) of this complex number \( z \).
      *
-     * <p>\[ z           = x + i y \\
-     *      \overline{z} = x - i y \]
+     * <p>\[ z           = a + i b \\
+     *      \overline{z} = a - i b \]
      *
      * @return The conjugate (\( \overline{z} \)) of this complex number.
      */
@@ -766,7 +772,7 @@ public final class Complex implements Serializable  {
      * <p>Note: This method should be preferred over using
      * {@link #divide(Complex) divide(Complex.ofCartesian(divisor, 0))}. Division
      * can generate signed zeros if {@code this} complex has zeros for the real
-     * and/or imaginary component, or the divisor is infinity. The summation of signed zeros
+     * and/or imaginary component, or the divisor is infinite. The summation of signed zeros
      * in {@link #divide(Complex)} may create zeros in the result that differ in sign
      * from the equivalent call to divide by a real-only number.
      *
@@ -791,7 +797,7 @@ public final class Complex implements Serializable  {
      * <p>Note: This method should be preferred over using
      * {@link #divide(Complex) divide(Complex.ofCartesian(0, divisor))}. Division
      * can generate signed zeros if {@code this} complex has zeros for the real
-     * and/or imaginary component, or the divisor is infinity. The summation of signed zeros
+     * and/or imaginary component, or the divisor is infinite. The summation of signed zeros
      * in {@link #divide(Complex)} may create zeros in the result that differ in sign
      * from the equivalent call to divide by an imaginary-only number.
      *
@@ -801,7 +807,7 @@ public final class Complex implements Serializable  {
      * as dividing by a real-only zero. The output from dividing by imaginary zero will create
      * infinite and NaN values in the same component parts as the output from
      * {@code this.divide(Complex.ZERO).multiplyImaginary(1)}, however the sign
-     * of some infinity values may be negated.
+     * of some infinite values may be negated.
      *
      * @param  divisor Value by which this complex number is to be divided.
      * @return {@code this / divisor}.
@@ -834,7 +840,7 @@ public final class Complex implements Serializable  {
      * <ul>
      *  <li>
      *   Instances that contain {@code NaN} values in the same part
-     *   are considered to be equal for that part, even though {@code Double.NaN==Double.NaN}
+     *   are considered to be equal for that part, even though {@code Double.NaN == Double.NaN}
      *   has the value {@code false}.
      *  </li>
      *  <li>
@@ -843,7 +849,7 @@ public final class Complex implements Serializable  {
      *  </li>
      *  <li>
      *   Instances that contain different representations of zero in the same part
-     *   are <em>not</em> considered to be equal for that part, even though {@code
-0.0==0.0}
+     *   are <em>not</em> considered to be equal for that part, even though {@code
-0.0 == 0.0}
      *   has the value {@code true}.
      *  </li>
      * </ul>
@@ -893,7 +899,7 @@ public final class Complex implements Serializable  {
     }
 
     /**
-     * Gets the imaginary part.
+     * Gets the imaginary part \( b \) of this complex number \( (a + i b) \).
      *
      * @return The imaginary part.
      */
@@ -902,7 +908,9 @@ public final class Complex implements Serializable  {
     }
 
     /**
-     * Gets the imaginary part (C++ grammar).
+     * Gets the imaginary part \( b \) of this complex number \( (a + i b) \).
+     *
+     * <p>This method is the equivalent of the C++ method {@code std::complex::imag}.
      *
      * @return The imaginary part.
      * @see #getImaginary()
@@ -912,7 +920,7 @@ public final class Complex implements Serializable  {
     }
 
     /**
-     * Gets the real part.
+     * Gets the real part \( a \) of this complex number \( (a + i b) \).
      *
      * @return The real part.
      */
@@ -920,8 +928,10 @@ public final class Complex implements Serializable  {
         return real;
     }
 
-     /**
-     * Gets the real part (C++ grammar).
+    /**
+     * Gets the real part \( a \) of this complex number \( (a + i b) \).
+     *
+     * <p>This method is the equivalent of the C++ method {@code std::complex::real}.
      *
      * @return The real part.
      * @see #getReal()
@@ -1101,7 +1111,7 @@ public final class Complex implements Serializable  {
      * <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
+     * by \( i \) using a factor with magnitude 1.0. This should be used in preference to
      * {@link #multiply(Complex) multiply(Complex.I)} with or without {@link #negate() negation}:</p>
      *
      * \[ iz = (-b + i a) \\
@@ -1129,6 +1139,9 @@ public final class Complex implements Serializable  {
      * Returns a {@code Complex} whose value is the negation of both the real and imaginary
parts
      * of complex number \( z \).
      *
+     * <p>\[ z  =  a + i b \\
+     *      -z  = -a - i b \]
+     *
      * @return \( -z \).
      */
     public Complex negate() {
@@ -1197,7 +1210,7 @@ public final class Complex implements Serializable  {
      *
      * <p>Note: This method inverts the sign of the imaginary component \( b \) if
it is {@code 0.0}.
      * The sign would not be inverted if subtracting from \( c + i 0 \) using
-     * {@link #subtract(Complex) Complex.ofCartesian(minuend, 0).subtract(this))} since
+     * {@link #subtract(Complex) Complex.ofCartesian(minuend, 0).subtract(this)} since
      * {@code 0.0 - 0.0 = 0.0}.
      *
      * @param  minuend Value this complex number is to be subtracted from.
@@ -1220,7 +1233,7 @@ public final class Complex implements Serializable  {
      *
      * <p>Note: This method inverts the sign of the real component \( a \) if it is
{@code 0.0}.
      * The sign would not be inverted if subtracting from \( 0 + i d \) using
-     * {@link #subtract(Complex) Complex.ofCartesian(0, minuend).subtract(this))} since
+     * {@link #subtract(Complex) Complex.ofCartesian(0, minuend).subtract(this)} since
      * {@code 0.0 - 0.0 = 0.0}.
      *
      * @param  minuend Value this complex number is to be subtracted from.
@@ -1279,9 +1292,7 @@ public final class Complex implements Serializable  {
      * </blockquote>
      *
      * <p>The code has been adapted from the <a href="https://www.boost.org/">Boost</a>
-     * {@code c++} implementation {@code <boost/math/complex/acos.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>
+     * {@code c++} implementation {@code <boost/math/complex/acos.hpp>}.
      *
      * @return The inverse cosine of this complex number.
      * @see <a href="http://functions.wolfram.com/ElementaryFunctions/ArcCos/">ArcCos</a>
@@ -1294,7 +1305,7 @@ public final class Complex implements Serializable  {
      * Returns the inverse cosine of the complex number.
      *
      * <p>This function exists to allow implementation of the identity
-     * {@code acosh(z) = +-i acos(z)}.<p>
+     * {@code acosh(z) = +-i acos(z)}.
      *
      * @param real Real part.
      * @param imaginary Imaginary part.
@@ -1449,9 +1460,7 @@ public final class Complex implements Serializable  {
      * </blockquote>
      *
      * <p>The code has been adapted from the <a href="https://www.boost.org/">Boost</a>
-     * {@code c++} implementation {@code <boost/math/complex/asin.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>
+     * {@code c++} implementation {@code <boost/math/complex/asin.hpp>}.
      *
      * @return The inverse sine of this complex number.
      * @see <a href="http://functions.wolfram.com/ElementaryFunctions/ArcSin/">ArcSin</a>
@@ -1464,7 +1473,7 @@ public final class Complex implements Serializable  {
      * Returns the inverse sine of the complex number.
      *
      * <p>This function exists to allow implementation of the identity
-     * {@code asinh(z) = -i asin(iz)}.<p>
+     * {@code asinh(z) = -i asin(iz)}.
      *
      * <p>The code has been adapted from the <a href="https://www.boost.org/">Boost</a>
      * {@code c++} implementation {@code <boost/math/complex/asin.hpp>}.</p>
@@ -1703,9 +1712,7 @@ public final class Complex implements Serializable  {
      * correct quadrant is returned from \( \tan^{-1} \left(\frac{2y}{1-x^2-y^2} \right)
\).
      *
      * <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.
+     * {@code c++} implementation {@code <boost/math/complex/atanh.hpp>}.
      *
      * @return The inverse hyperbolic tangent of this complex number.
      * @see <a href="http://functions.wolfram.com/ElementaryFunctions/ArcTanh/">ArcTanh</a>
@@ -1718,7 +1725,7 @@ public final class Complex implements Serializable  {
      * Returns the inverse hyperbolic tangent of this complex number.
      *
      * <p>This function exists to allow implementation of the identity
-     * {@code atan(z) = -i atanh(iz)}.<p>
+     * {@code atan(z) = -i atanh(iz)}.
      *
      * @param real Real part.
      * @param imaginary Imaginary part.
@@ -2160,7 +2167,7 @@ public final class Complex implements Serializable  {
      *
      * <p>\[ \exp(x + iy) = e^x (\cos(y) + i \sin(y)) \]
      *
-     * @return <code>e<sup>this</sup></code>.
+     * @return The exponential of this complex number.
      * @see <a href="http://functions.wolfram.com/ElementaryFunctions/Exp/">Exp</a>
      */
     public Complex exp() {
@@ -3131,7 +3138,7 @@ public final class Complex implements Serializable  {
      * and \( \pi \) (inclusive), with negative values returned for numbers with
      * negative imaginary parts.
      *
-     * <p>If either real or imaginary part (or both) is NaN, NaN is returned.
+     * <p>If either real or imaginary part (or both) is NaN, then the result is NaN.
      * Infinite parts are handled as {@linkplain Math#atan2} handles them,
      * essentially treating finite parts as zero in the presence of an
      * infinite coordinate and returning a multiple of \( \frac{\pi}{4} \) depending on


Mime
View raw message