[commons-numbers] 02/03: Added norm method that is part of the C++ standard for complex.

[aherbert]

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 5fad5e285c6498d3747ebd75f98557b6a9324fcc
Author: Alex Herbert <aherb...@apache.org>
AuthorDate: Sat Dec 21 17:04:21 2019 +0000

    Added norm method that is part of the C++ standard for complex.
    
    This returns the same value as squared abs().
---
 .../apache/commons/numbers/complex/Complex.java    | 26 ++++++++++++++++++++++
 .../commons/numbers/complex/ComplexTest.java       | 19 ++++++++++++++++
 2 files changed, 45 insertions(+)

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 a6f8da4..23c79a4 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
@@ -435,6 +435,7 @@ public final class Complex implements Serializable  {
      * @see #isInfinite()
      * @see #isNaN()
      * @see Math#hypot(double, double)
+     * @see <a href="http://mathworld.wolfram.com/ComplexModulus.html";>Complex 
modulus</a>
      */
     public double abs() {
         // Delegate
@@ -457,6 +458,31 @@ public final class Complex implements Serializable  {
     }
 
     /**
+     * Return the squared norm value of this complex number. This is also 
called the absolute
+     * square.
+     * <pre>norm(a + b i) = a^2 + b^2</pre>
+     *
+     * <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()}.
+     *
+     * @return the square norm value.
+     * @see #isInfinite()
+     * @see #isNaN()
+     * @see #abs()
+     * @see <a 
href="http://mathworld.wolfram.com/AbsoluteSquare.html";>Absolute square</a>
+     */
+    public double norm() {
+        if (isInfinite()) {
+            return Double.POSITIVE_INFINITY;
+        }
+        return real * real + imaginary * imaginary;
+    }
+
+    /**
      * Returns a {@code Complex} whose value is {@code (this + addend)}.
      * Implements the formula:
      * <pre>
diff --git 
a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
 
b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
index 13eb77c..7d6770d 100644
--- 
a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
+++ 
b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexTest.java
@@ -224,6 +224,25 @@ public class ComplexTest {
     }
 
     @Test
+    public void testNorm() {
+        final Complex z = Complex.ofCartesian(3.0, 4.0);
+        Assertions.assertEquals(25.0, z.norm());
+    }
+
+    @Test
+    public void testNormNaN() {
+        // The result is NaN if either argument is NaN and the other is not 
infinite
+        Assertions.assertEquals(nan, NAN.norm());
+        Assertions.assertEquals(nan, Complex.ofCartesian(3.0, nan).norm());
+        Assertions.assertEquals(nan, Complex.ofCartesian(nan, 3.0).norm());
+        // The result is positive infinite if either argument is infinite
+        Assertions.assertEquals(inf, Complex.ofCartesian(inf, nan).norm());
+        Assertions.assertEquals(inf, Complex.ofCartesian(-inf, nan).norm());
+        Assertions.assertEquals(inf, Complex.ofCartesian(nan, inf).norm());
+        Assertions.assertEquals(inf, Complex.ofCartesian(nan, -inf).norm());
+    }
+
+    @Test
     public void testAdd() {
         final Complex x = Complex.ofCartesian(3.0, 4.0);
         final Complex y = Complex.ofCartesian(5.0, 6.0);