Added norm method that is part of the C++ standard for complex.
This returns the same value as squared abs().
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 @@
* @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 @@
}
/**
+ * 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 @@
}
@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);
