diff options
Diffstat (limited to 'src/main/java/org/apache/commons/math3/complex/Complex.java')
| -rw-r--r-- | src/main/java/org/apache/commons/math3/complex/Complex.java | 1219 |
1 files changed, 1219 insertions, 0 deletions
diff --git a/src/main/java/org/apache/commons/math3/complex/Complex.java b/src/main/java/org/apache/commons/math3/complex/Complex.java new file mode 100644 index 0000000..cd8d794 --- /dev/null +++ b/src/main/java/org/apache/commons/math3/complex/Complex.java @@ -0,0 +1,1219 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.math3.complex; + +import org.apache.commons.math3.FieldElement; +import org.apache.commons.math3.exception.NotPositiveException; +import org.apache.commons.math3.exception.NullArgumentException; +import org.apache.commons.math3.exception.util.LocalizedFormats; +import org.apache.commons.math3.util.FastMath; +import org.apache.commons.math3.util.MathUtils; +import org.apache.commons.math3.util.Precision; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * Representation of a Complex number, i.e. a number which has both a real and imaginary part. + * + * <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 a {@code NaN} in either real or imaginary part, e.g. the following are + * considered equal: + * + * <ul> + * <li>{@code 1 + NaNi} + * <li>{@code NaN + i} + * <li>{@code NaN + NaNi} + * </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. + */ +public class Complex implements FieldElement<Complex>, Serializable { + /** The square root of -1. A number representing "0.0 + 1.0i" */ + public static final Complex I = new Complex(0.0, 1.0); + + // CHECKSTYLE: stop ConstantName + /** A complex number representing "NaN + NaNi" */ + public static final Complex NaN = new Complex(Double.NaN, Double.NaN); + + // CHECKSTYLE: resume ConstantName + /** A complex number representing "+INF + INFi" */ + public static final Complex INF = + new Complex(Double.POSITIVE_INFINITY, Double.POSITIVE_INFINITY); + + /** A complex number representing "1.0 + 0.0i" */ + public static final Complex ONE = new Complex(1.0, 0.0); + + /** A complex number representing "0.0 + 0.0i" */ + public static final Complex ZERO = new Complex(0.0, 0.0); + + /** Serializable version identifier */ + private static final long serialVersionUID = -6195664516687396620L; + + /** The imaginary part. */ + private final double imaginary; + + /** The real part. */ + private final double real; + + /** Record whether this complex number is equal to NaN. */ + private final transient boolean isNaN; + + /** Record whether this complex number is infinite. */ + private final transient boolean isInfinite; + + /** + * Create a complex number given only the real part. + * + * @param real Real part. + */ + public Complex(double real) { + this(real, 0.0); + } + + /** + * Create a complex number given the real and imaginary parts. + * + * @param real Real part. + * @param imaginary Imaginary part. + */ + public Complex(double real, double imaginary) { + this.real = real; + this.imaginary = imaginary; + + isNaN = Double.isNaN(real) || Double.isNaN(imaginary); + isInfinite = !isNaN && (Double.isInfinite(real) || Double.isInfinite(imaginary)); + } + + /** + * Return the absolute value of this complex number. Returns {@code NaN} if either real or + * imaginary part is {@code NaN} and {@code Double.POSITIVE_INFINITY} if neither part is {@code + * NaN}, but at least one part is infinite. + * + * @return the absolute value. + */ + public double abs() { + if (isNaN) { + return Double.NaN; + } + if (isInfinite()) { + return Double.POSITIVE_INFINITY; + } + if (FastMath.abs(real) < FastMath.abs(imaginary)) { + if (imaginary == 0.0) { + return FastMath.abs(real); + } + double q = real / imaginary; + return FastMath.abs(imaginary) * FastMath.sqrt(1 + q * q); + } else { + if (real == 0.0) { + return FastMath.abs(imaginary); + } + double q = imaginary / real; + return FastMath.abs(real) * FastMath.sqrt(1 + q * q); + } + } + + /** + * Returns a {@code Complex} whose value is {@code (this + addend)}. Uses the definitional + * formula + * + * <p>{@code (a + bi) + (c + di) = (a+c) + (b+d)i} 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 according to the rules for {@link + * java.lang.Double} arithmetic. + * + * @param addend Value to be added to this {@code Complex}. + * @return {@code this + addend}. + * @throws NullArgumentException if {@code addend} is {@code null}. + */ + public Complex add(Complex addend) throws NullArgumentException { + MathUtils.checkNotNull(addend); + if (isNaN || addend.isNaN) { + return NaN; + } + + return createComplex(real + addend.getReal(), imaginary + addend.getImaginary()); + } + + /** + * Returns a {@code Complex} whose value is {@code (this + addend)}, with {@code addend} + * interpreted as a real number. + * + * @param addend Value to be added to this {@code Complex}. + * @return {@code this + addend}. + * @see #add(Complex) + */ + public Complex add(double addend) { + if (isNaN || Double.isNaN(addend)) { + return NaN; + } + + return createComplex(real + addend, imaginary); + } + + /** + * Returns the conjugate of this complex number. The conjugate of {@code a + bi} is {@code a - + * bi}. + * + * <p>{@link #NaN} is returned if either the real or imaginary part of this Complex number + * equals {@code Double.NaN}. + * + * <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}. + * + * @return the conjugate of this Complex object. + */ + public Complex conjugate() { + if (isNaN) { + return NaN; + } + + return createComplex(real, -imaginary); + } + + /** + * Returns a {@code Complex} whose value is {@code (this / divisor)}. Implements the + * definitional formula + * + * <pre> + * <code> + * a + bi ac + bd + (bc - ad)i + * ----------- = ------------------------- + * c + di c<sup>2</sup> + d<sup>2</sup> + * </code> + * </pre> + * + * but uses <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. + * + * <p>{@code Infinite} and {@code NaN} values are handled according to the following rules, + * applied in the order presented: + * + * <ul> + * <li>If either {@code this} or {@code divisor} has a {@code NaN} value in either part, + * {@link #NaN} is returned. + * <li>If {@code divisor} equals {@link #ZERO}, {@link #NaN} is returned. + * <li>If {@code this} and {@code divisor} are both infinite, {@link #NaN} is returned. + * <li>If {@code this} is finite (i.e., has no {@code Infinite} or {@code NaN} parts) and + * {@code divisor} is infinite (one or both parts infinite), {@link #ZERO} is returned. + * <li>If {@code this} is infinite and {@code divisor} is finite, {@code NaN} values are + * returned in the parts of the result if the {@link java.lang.Double} rules applied to + * the definitional formula force {@code NaN} results. + * </ul> + * + * @param divisor Value by which this {@code Complex} is to be divided. + * @return {@code this / divisor}. + * @throws NullArgumentException if {@code divisor} is {@code null}. + */ + public Complex divide(Complex divisor) throws NullArgumentException { + MathUtils.checkNotNull(divisor); + if (isNaN || divisor.isNaN) { + return NaN; + } + + final double c = divisor.getReal(); + final double d = divisor.getImaginary(); + if (c == 0.0 && d == 0.0) { + return NaN; + } + + if (divisor.isInfinite() && !isInfinite()) { + return ZERO; + } + + if (FastMath.abs(c) < FastMath.abs(d)) { + double q = c / d; + double denominator = c * q + d; + return createComplex( + (real * q + imaginary) / denominator, (imaginary * q - real) / denominator); + } else { + double q = d / c; + double denominator = d * q + c; + return createComplex( + (imaginary * q + real) / denominator, (imaginary - real * q) / denominator); + } + } + + /** + * Returns a {@code Complex} whose value is {@code (this / divisor)}, with {@code divisor} + * interpreted as a real number. + * + * @param divisor Value by which this {@code Complex} is to be divided. + * @return {@code this / divisor}. + * @see #divide(Complex) + */ + public Complex divide(double divisor) { + if (isNaN || Double.isNaN(divisor)) { + return NaN; + } + if (divisor == 0d) { + return NaN; + } + if (Double.isInfinite(divisor)) { + return !isInfinite() ? ZERO : NaN; + } + return createComplex(real / divisor, imaginary / divisor); + } + + /** {@inheritDoc} */ + public Complex reciprocal() { + if (isNaN) { + return NaN; + } + + if (real == 0.0 && imaginary == 0.0) { + return INF; + } + + if (isInfinite) { + return ZERO; + } + + if (FastMath.abs(real) < FastMath.abs(imaginary)) { + double q = real / imaginary; + double scale = 1. / (real * q + imaginary); + return createComplex(scale * q, -scale); + } else { + double q = imaginary / real; + double scale = 1. / (imaginary * q + real); + return createComplex(scale, -scale * q); + } + } + + /** + * Test for equality with another object. If both the real and imaginary parts of two complex + * numbers are exactly the same, and neither is {@code Double.NaN}, the two Complex objects are + * considered to be equal. The behavior is the same as for JDK's {@link Double#equals(Object) + * Double}: + * + * <ul> + * <li>All {@code NaN} values are considered to be equal, i.e, if either (or both) real and + * imaginary parts of the complex number are equal to {@code Double.NaN}, the complex + * number is equal to {@code NaN}. + * <li>Instances constructed with different representations of zero (i.e. either "0" or "-0") + * are <em>not</em> considered to be equal. + * </ul> + * + * @param other Object to test for equality with this instance. + * @return {@code true} if the objects are equal, {@code false} if object is {@code null}, not + * an instance of {@code Complex}, or not equal to this instance. + */ + @Override + public boolean equals(Object other) { + if (this == other) { + return true; + } + if (other instanceof Complex) { + Complex c = (Complex) other; + if (c.isNaN) { + return isNaN; + } else { + return MathUtils.equals(real, c.real) && MathUtils.equals(imaginary, c.imaginary); + } + } + return false; + } + + /** + * Test for the floating-point equality between Complex objects. It returns {@code true} if both + * arguments are equal or within the range of allowed error (inclusive). + * + * @param x First value (cannot be {@code null}). + * @param y Second value (cannot be {@code null}). + * @param maxUlps {@code (maxUlps - 1)} is the number of floating point values between the real + * (resp. imaginary) parts of {@code x} and {@code y}. + * @return {@code true} if there are fewer than {@code maxUlps} floating point values between + * the real (resp. imaginary) parts of {@code x} and {@code y}. + * @see Precision#equals(double,double,int) + * @since 3.3 + */ + public static boolean equals(Complex x, Complex y, int maxUlps) { + return Precision.equals(x.real, y.real, maxUlps) + && Precision.equals(x.imaginary, y.imaginary, maxUlps); + } + + /** + * Returns {@code true} iff the values are equal as defined by {@link + * #equals(Complex,Complex,int) equals(x, y, 1)}. + * + * @param x First value (cannot be {@code null}). + * @param y Second value (cannot be {@code null}). + * @return {@code true} if the values are equal. + * @since 3.3 + */ + public static boolean equals(Complex x, Complex y) { + return equals(x, y, 1); + } + + /** + * 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). 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}). + * @param eps Amount of allowed absolute error. + * @return {@code true} if the values are two adjacent floating point numbers or they are within + * range of each other. + * @see Precision#equals(double,double,double) + * @since 3.3 + */ + public static boolean equals(Complex x, Complex y, double eps) { + return Precision.equals(x.real, y.real, eps) + && Precision.equals(x.imaginary, y.imaginary, eps); + } + + /** + * 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. 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}). + * @param eps Amount of allowed relative error. + * @return {@code true} if the values are two adjacent floating point numbers or they are within + * range of each other. + * @see Precision#equalsWithRelativeTolerance(double,double,double) + * @since 3.3 + */ + public static boolean equalsWithRelativeTolerance(Complex x, Complex y, double eps) { + return Precision.equalsWithRelativeTolerance(x.real, y.real, eps) + && Precision.equalsWithRelativeTolerance(x.imaginary, y.imaginary, eps); + } + + /** + * Get a hashCode for the complex number. Any {@code Double.NaN} value in real or imaginary part + * produces the same hash code {@code 7}. + * + * @return a hash code value for this object. + */ + @Override + public int hashCode() { + if (isNaN) { + return 7; + } + return 37 * (17 * MathUtils.hash(imaginary) + MathUtils.hash(real)); + } + + /** + * Access the imaginary part. + * + * @return the imaginary part. + */ + public double getImaginary() { + return imaginary; + } + + /** + * Access the real part. + * + * @return the real part. + */ + public double getReal() { + return real; + } + + /** + * Checks whether either or both parts of this complex number is {@code NaN}. + * + * @return true if either or both parts of this complex number is {@code NaN}; false otherwise. + */ + public boolean isNaN() { + return isNaN; + } + + /** + * Checks whether either the real or imaginary part of this complex number takes an infinite + * value (either {@code Double.POSITIVE_INFINITY} or {@code Double.NEGATIVE_INFINITY}) and + * neither part is {@code NaN}. + * + * @return true if one or both parts of this complex number are infinite and neither part is + * {@code NaN}. + */ + public boolean isInfinite() { + return isInfinite; + } + + /** + * Returns a {@code Complex} whose value is {@code this * factor}. Implements preliminary checks + * for {@code NaN} and infinity followed by the definitional formula: + * + * <p>{@code (a + bi)(c + di) = (ac - bd) + (ad + bc)i} Returns {@link #NaN} if either {@code + * this} or {@code factor} has one or more {@code NaN} parts. + * + * <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). + * + * <p>Returns finite values in components of the result per the definitional formula in all + * remaining cases. + * + * @param factor value to be multiplied by this {@code Complex}. + * @return {@code this * factor}. + * @throws NullArgumentException if {@code factor} is {@code null}. + */ + public Complex multiply(Complex factor) throws NullArgumentException { + MathUtils.checkNotNull(factor); + if (isNaN || factor.isNaN) { + return NaN; + } + if (Double.isInfinite(real) + || Double.isInfinite(imaginary) + || Double.isInfinite(factor.real) + || Double.isInfinite(factor.imaginary)) { + // we don't use isInfinite() to avoid testing for NaN again + return INF; + } + return createComplex( + real * factor.real - imaginary * factor.imaginary, + real * factor.imaginary + imaginary * factor.real); + } + + /** + * Returns a {@code Complex} whose value is {@code this * factor}, with {@code factor} + * interpreted as a integer number. + * + * @param factor value to be multiplied by this {@code Complex}. + * @return {@code this * factor}. + * @see #multiply(Complex) + */ + public Complex multiply(final int factor) { + if (isNaN) { + return NaN; + } + if (Double.isInfinite(real) || Double.isInfinite(imaginary)) { + return INF; + } + return createComplex(real * factor, imaginary * factor); + } + + /** + * Returns a {@code Complex} whose value is {@code this * factor}, with {@code factor} + * interpreted as a real number. + * + * @param factor value to be multiplied by this {@code Complex}. + * @return {@code this * factor}. + * @see #multiply(Complex) + */ + public Complex multiply(double factor) { + if (isNaN || Double.isNaN(factor)) { + return NaN; + } + if (Double.isInfinite(real) || Double.isInfinite(imaginary) || Double.isInfinite(factor)) { + // we don't use isInfinite() to avoid testing for NaN again + return INF; + } + return createComplex(real * factor, imaginary * factor); + } + + /** + * Returns a {@code Complex} whose value is {@code (-this)}. Returns {@code NaN} if either real + * or imaginary part of this Complex number is {@code Double.NaN}. + * + * @return {@code -this}. + */ + public Complex negate() { + if (isNaN) { + return NaN; + } + + return createComplex(-real, -imaginary); + } + + /** + * Returns a {@code Complex} whose value is {@code (this - subtrahend)}. Uses the definitional + * formula + * + * <p>{@code (a + bi) - (c + di) = (a-c) + (b-d)i} 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 {@link + * java.lang.Double} arithmetic. + * + * @param subtrahend value to be subtracted from this {@code Complex}. + * @return {@code this - subtrahend}. + * @throws NullArgumentException if {@code subtrahend} is {@code null}. + */ + public Complex subtract(Complex subtrahend) throws NullArgumentException { + MathUtils.checkNotNull(subtrahend); + if (isNaN || subtrahend.isNaN) { + return NaN; + } + + return createComplex(real - subtrahend.getReal(), imaginary - subtrahend.getImaginary()); + } + + /** + * Returns a {@code Complex} whose value is {@code (this - subtrahend)}. + * + * @param subtrahend value to be subtracted from this {@code Complex}. + * @return {@code this - subtrahend}. + * @see #subtract(Complex) + */ + public Complex subtract(double subtrahend) { + if (isNaN || Double.isNaN(subtrahend)) { + return NaN; + } + return createComplex(real - subtrahend, imaginary); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/InverseCosine.html" TARGET="_top"> inverse + * cosine</a> of this complex number. Implements the formula: + * + * <p>{@code acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))} Returns {@link Complex#NaN} if + * either real or imaginary part of the input argument is {@code NaN} or infinite. + * + * @return the inverse cosine of this complex number. + * @since 1.2 + */ + public Complex acos() { + if (isNaN) { + return NaN; + } + + return this.add(this.sqrt1z().multiply(I)).log().multiply(I.negate()); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/InverseSine.html" TARGET="_top"> inverse + * sine</a> of this complex number. Implements the formula: + * + * <p>{@code asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz))} + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN} or infinite. + * + * @return the inverse sine of this complex number. + * @since 1.2 + */ + public Complex asin() { + if (isNaN) { + return NaN; + } + + return sqrt1z().add(this.multiply(I)).log().multiply(I.negate()); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/InverseTangent.html" TARGET="_top"> inverse + * tangent</a> of this complex number. Implements the formula: + * + * <p>{@code atan(z) = (i/2) log((i + z)/(i - z))} + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN} or infinite. + * + * @return the inverse tangent of this complex number + * @since 1.2 + */ + public Complex atan() { + if (isNaN) { + return NaN; + } + + return this.add(I) + .divide(I.subtract(this)) + .log() + .multiply(I.divide(createComplex(2.0, 0.0))); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/Cosine.html" TARGET="_top"> cosine</a> of + * this complex number. Implements the formula: + * + * <p>{@code cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i} + * + * <p>where the (real) functions on the right-hand side are {@link FastMath#sin}, {@link + * FastMath#cos}, {@link FastMath#cosh} and {@link FastMath#sinh}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. + * + * <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> + * Examples: + * <code> + * cos(1 ± INFINITY i) = 1 \u2213 INFINITY i + * cos(±INFINITY + i) = NaN + NaN i + * cos(±INFINITY ± INFINITY i) = NaN + NaN i + * </code> + * </pre> + * + * @return the cosine of this complex number. + * @since 1.2 + */ + public Complex cos() { + if (isNaN) { + return NaN; + } + + return createComplex( + FastMath.cos(real) * FastMath.cosh(imaginary), + -FastMath.sin(real) * FastMath.sinh(imaginary)); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/HyperbolicCosine.html" TARGET="_top"> + * hyperbolic cosine</a> of this complex number. Implements the formula: + * + * <pre> + * <code> + * 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}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. Infinite values in real or imaginary parts of the input may result in infinite + * or NaN values returned in parts of the result. + * + * <pre> + * Examples: + * <code> + * cosh(1 ± INFINITY i) = NaN + NaN i + * cosh(±INFINITY + i) = INFINITY ± INFINITY i + * cosh(±INFINITY ± INFINITY i) = NaN + NaN i + * </code> + * </pre> + * + * @return the hyperbolic cosine of this complex number. + * @since 1.2 + */ + public Complex cosh() { + if (isNaN) { + return NaN; + } + + return createComplex( + FastMath.cosh(real) * FastMath.cos(imaginary), + FastMath.sinh(real) * FastMath.sin(imaginary)); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/ExponentialFunction.html" TARGET="_top"> + * exponential function</a> of this complex number. Implements the formula: + * + * <pre> + * <code> + * exp(a + bi) = exp(a)cos(b) + exp(a)sin(b)i + * </code> + * </pre> + * + * where the (real) functions on the right-hand side are {@link FastMath#exp}, {@link + * FastMath#cos}, and {@link FastMath#sin}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. Infinite values in real or imaginary parts of the input may result in infinite + * or NaN values returned in parts of the result. + * + * <pre> + * Examples: + * <code> + * exp(1 ± INFINITY i) = NaN + NaN i + * exp(INFINITY + i) = INFINITY + INFINITY i + * exp(-INFINITY + i) = 0 + 0i + * exp(±INFINITY ± INFINITY i) = NaN + NaN i + * </code> + * </pre> + * + * @return <code><i>e</i><sup>this</sup></code>. + * @since 1.2 + */ + public Complex exp() { + if (isNaN) { + return NaN; + } + + double expReal = FastMath.exp(real); + return createComplex(expReal * FastMath.cos(imaginary), expReal * FastMath.sin(imaginary)); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/NaturalLogarithm.html" TARGET="_top"> + * natural logarithm</a> of this complex number. Implements the formula: + * + * <pre> + * <code> + * log(a + bi) = ln(|a + bi|) + arg(a + bi)i + * </code> + * </pre> + * + * 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). + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. 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> + * Examples: + * <code> + * log(1 ± INFINITY i) = INFINITY ± (π/2)i + * log(INFINITY + i) = INFINITY + 0i + * log(-INFINITY + i) = INFINITY + πi + * log(INFINITY ± INFINITY i) = INFINITY ± (π/4)i + * log(-INFINITY ± INFINITY i) = INFINITY ± (3π/4)i + * log(0 + 0i) = -INFINITY + 0i + * </code> + * </pre> + * + * @return the value <code>ln this</code>, the natural logarithm of {@code this}. + * @since 1.2 + */ + public Complex log() { + if (isNaN) { + return NaN; + } + + return createComplex(FastMath.log(abs()), FastMath.atan2(imaginary, real)); + } + + /** + * Returns of value of this complex number raised to the power of {@code x}. Implements the + * formula: + * + * <pre> + * <code> + * y<sup>x</sup> = exp(x·log(y)) + * </code> + * </pre> + * + * where {@code exp} and {@code log} are {@link #exp} and {@link #log}, respectively. + * + * <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}. + * + * @param x exponent to which this {@code Complex} is to be raised. + * @return <code> this<sup>x</sup></code>. + * @throws NullArgumentException if x is {@code null}. + * @since 1.2 + */ + public Complex pow(Complex x) throws NullArgumentException { + MathUtils.checkNotNull(x); + return this.log().multiply(x).exp(); + } + + /** + * Returns of value of this complex number raised to the power of {@code x}. + * + * @param x exponent to which this {@code Complex} is to be raised. + * @return <code>this<sup>x</sup></code>. + * @see #pow(Complex) + */ + public Complex pow(double x) { + return this.log().multiply(x).exp(); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/Sine.html" TARGET="_top"> sine</a> of this + * complex number. Implements the formula: + * + * <pre> + * <code> + * sin(a + bi) = sin(a)cosh(b) - cos(a)sinh(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}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. + * + * <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> + * Examples: + * <code> + * sin(1 ± INFINITY i) = 1 ± INFINITY i + * sin(±INFINITY + i) = NaN + NaN i + * sin(±INFINITY ± INFINITY i) = NaN + NaN i + * </code> + * </pre> + * + * @return the sine of this complex number. + * @since 1.2 + */ + public Complex sin() { + if (isNaN) { + return NaN; + } + + return createComplex( + FastMath.sin(real) * FastMath.cosh(imaginary), + FastMath.cos(real) * FastMath.sinh(imaginary)); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/HyperbolicSine.html" TARGET="_top"> + * hyperbolic sine</a> of this complex number. Implements the formula: + * + * <pre> + * <code> + * sinh(a + bi) = sinh(a)cos(b)) + cosh(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}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. + * + * <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> + * Examples: + * <code> + * sinh(1 ± INFINITY i) = NaN + NaN i + * sinh(±INFINITY + i) = ± INFINITY + INFINITY i + * sinh(±INFINITY ± INFINITY i) = NaN + NaN i + * </code> + * </pre> + * + * @return the hyperbolic sine of {@code this}. + * @since 1.2 + */ + public Complex sinh() { + if (isNaN) { + return NaN; + } + + return createComplex( + FastMath.sinh(real) * FastMath.cos(imaginary), + FastMath.cosh(real) * FastMath.sin(imaginary)); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/SquareRoot.html" TARGET="_top"> square + * root</a> of this complex number. Implements the following algorithm to compute {@code sqrt(a + * + bi)}: + * + * <ol> + * <li>Let {@code t = sqrt((|a| + |a + bi|) / 2)} + * <li> + * <pre>if {@code a ≥ 0} return {@code t + (b/2t)i} + * else return {@code |b|/2t + sign(b)t i }</pre> + * </ol> + * + * where + * + * <ul> + * <li>{@code |a| = }{@link FastMath#abs}(a) + * <li>{@code |a + bi| = }{@link Complex#abs}(a + bi) + * <li>{@code sign(b) = }{@link FastMath#copySign(double,double) copySign(1d, b)} + * </ul> + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. Infinite values in real or imaginary parts of the input may result in infinite + * or NaN values returned in parts of the result. + * + * <pre> + * Examples: + * <code> + * sqrt(1 ± INFINITY i) = INFINITY + NaN i + * sqrt(INFINITY + i) = INFINITY + 0i + * sqrt(-INFINITY + i) = 0 + INFINITY i + * sqrt(INFINITY ± INFINITY i) = INFINITY + NaN i + * sqrt(-INFINITY ± INFINITY i) = NaN ± INFINITY i + * </code> + * </pre> + * + * @return the square root of {@code this}. + * @since 1.2 + */ + public Complex sqrt() { + if (isNaN) { + return NaN; + } + + if (real == 0.0 && imaginary == 0.0) { + return createComplex(0.0, 0.0); + } + + double t = FastMath.sqrt((FastMath.abs(real) + abs()) / 2.0); + if (real >= 0.0) { + return createComplex(t, imaginary / (2.0 * t)); + } else { + return createComplex( + FastMath.abs(imaginary) / (2.0 * t), FastMath.copySign(1d, imaginary) * t); + } + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/SquareRoot.html" TARGET="_top"> square + * root</a> of <code>1 - this<sup>2</sup></code> for this complex number. Computes the result + * directly as {@code sqrt(ONE.subtract(z.multiply(z)))}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. Infinite values in real or imaginary parts of the input may result in infinite + * or NaN values returned in parts of the result. + * + * @return the square root of <code>1 - this<sup>2</sup></code>. + * @since 1.2 + */ + public Complex sqrt1z() { + return createComplex(1.0, 0.0).subtract(this.multiply(this)).sqrt(); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/Tangent.html" TARGET="_top"> tangent</a> of + * this complex number. Implements the formula: + * + * <pre> + * <code> + * tan(a + bi) = sin(2a)/(cos(2a)+cosh(2b)) + [sinh(2b)/(cos(2a)+cosh(2b))]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}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. 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> + * Examples: + * <code> + * tan(a ± INFINITY i) = 0 ± i + * tan(±INFINITY + bi) = NaN + NaN i + * tan(±INFINITY ± INFINITY i) = NaN + NaN i + * tan(±π/2 + 0 i) = ±INFINITY + NaN i + * </code> + * </pre> + * + * @return the tangent of {@code this}. + * @since 1.2 + */ + public Complex tan() { + if (isNaN || Double.isInfinite(real)) { + return NaN; + } + if (imaginary > 20.0) { + return createComplex(0.0, 1.0); + } + if (imaginary < -20.0) { + return createComplex(0.0, -1.0); + } + + double real2 = 2.0 * real; + double imaginary2 = 2.0 * imaginary; + double d = FastMath.cos(real2) + FastMath.cosh(imaginary2); + + return createComplex(FastMath.sin(real2) / d, FastMath.sinh(imaginary2) / d); + } + + /** + * Compute the <a href="http://mathworld.wolfram.com/HyperbolicTangent.html" TARGET="_top"> + * hyperbolic tangent</a> of this complex number. Implements the formula: + * + * <pre> + * <code> + * tan(a + bi) = sinh(2a)/(cosh(2a)+cos(2b)) + [sin(2b)/(cosh(2a)+cos(2b))]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}. + * + * <p>Returns {@link Complex#NaN} if either real or imaginary part of the input argument is + * {@code NaN}. Infinite values in real or imaginary parts of the input may result in infinite + * or NaN values returned in parts of the result. + * + * <pre> + * Examples: + * <code> + * tanh(a ± INFINITY i) = NaN + NaN i + * tanh(±INFINITY + bi) = ±1 + 0 i + * tanh(±INFINITY ± INFINITY i) = NaN + NaN i + * tanh(0 + (π/2)i) = NaN + INFINITY i + * </code> + * </pre> + * + * @return the hyperbolic tangent of {@code this}. + * @since 1.2 + */ + public Complex tanh() { + if (isNaN || Double.isInfinite(imaginary)) { + return NaN; + } + if (real > 20.0) { + return createComplex(1.0, 0.0); + } + if (real < -20.0) { + return createComplex(-1.0, 0.0); + } + double real2 = 2.0 * real; + double imaginary2 = 2.0 * imaginary; + double d = FastMath.cosh(real2) + FastMath.cos(imaginary2); + + return createComplex(FastMath.sinh(real2) / d, FastMath.sin(imaginary2) / d); + } + + /** + * Compute the argument of this complex number. The argument is the angle phi between the + * positive real axis and the point representing this number in the complex plane. The value + * returned is between -PI (not inclusive) 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. Infinite parts are + * handled as {@code Math.atan2} handles them, essentially treating finite parts as zero in the + * presence of an infinite coordinate and returning a multiple of pi/4 depending on the signs of + * the infinite parts. See the javadoc for {@code Math.atan2} for full details. + * + * @return the argument of {@code this}. + */ + public double getArgument() { + return FastMath.atan2(getImaginary(), getReal()); + } + + /** + * Computes the n-th roots of this complex number. The nth roots are defined by the formula: + * + * <pre> + * <code> + * z<sub>k</sub> = abs<sup>1/n</sup> (cos(phi + 2πk/n) + i (sin(phi + 2πk/n)) + * </code> + * </pre> + * + * 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. + * + * <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 of all {@code n}-th roots of {@code this}. + * @throws NotPositiveException if {@code n <= 0}. + * @since 2.0 + */ + public List<Complex> nthRoot(int n) throws NotPositiveException { + + if (n <= 0) { + throw new NotPositiveException( + LocalizedFormats.CANNOT_COMPUTE_NTH_ROOT_FOR_NEGATIVE_N, n); + } + + final List<Complex> result = new ArrayList<Complex>(); + + if (isNaN) { + result.add(NaN); + return result; + } + if (isInfinite()) { + result.add(INF); + return result; + } + + // nth root of abs -- faster / more accurate to use a solver here? + final double nthRootOfAbs = FastMath.pow(abs(), 1.0 / n); + + // Compute nth roots of complex number with k = 0, 1, ... n-1 + final double nthPhi = getArgument() / n; + final double slice = 2 * FastMath.PI / n; + double innerPart = nthPhi; + for (int k = 0; k < n; k++) { + // inner part + final double realPart = nthRootOfAbs * FastMath.cos(innerPart); + final double imaginaryPart = nthRootOfAbs * FastMath.sin(innerPart); + result.add(createComplex(realPart, imaginaryPart)); + innerPart += slice; + } + + return result; + } + + /** + * Create a complex number given the real and imaginary parts. + * + * @param realPart Real part. + * @param imaginaryPart Imaginary part. + * @return a new complex number instance. + * @since 1.2 + * @see #valueOf(double, double) + */ + protected Complex createComplex(double realPart, double imaginaryPart) { + return new Complex(realPart, imaginaryPart); + } + + /** + * Create a complex number given the real and imaginary parts. + * + * @param realPart Real part. + * @param imaginaryPart Imaginary part. + * @return a Complex instance. + */ + public static Complex valueOf(double realPart, double imaginaryPart) { + if (Double.isNaN(realPart) || Double.isNaN(imaginaryPart)) { + return NaN; + } + return new Complex(realPart, imaginaryPart); + } + + /** + * Create a complex number given only the real part. + * + * @param realPart Real part. + * @return a Complex instance. + */ + public static Complex valueOf(double realPart) { + if (Double.isNaN(realPart)) { + return NaN; + } + return new Complex(realPart); + } + + /** + * Resolve the transient fields in a deserialized Complex Object. Subclasses will need to + * override {@link #createComplex} to deserialize properly. + * + * @return A Complex instance with all fields resolved. + * @since 2.0 + */ + protected final Object readResolve() { + return createComplex(real, imaginary); + } + + /** {@inheritDoc} */ + public ComplexField getField() { + return ComplexField.getInstance(); + } + + /** {@inheritDoc} */ + @Override + public String toString() { + return "(" + real + ", " + imaginary + ")"; + } +} |