/*
 * 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 &plusmn; INFINITY i) = 1 \u2213 INFINITY i
     *   cos(&plusmn;INFINITY + i) = NaN + NaN i
     *   cos(&plusmn;INFINITY &plusmn; 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 &plusmn; INFINITY i) = NaN + NaN i
     *   cosh(&plusmn;INFINITY + i) = INFINITY &plusmn; INFINITY i
     *   cosh(&plusmn;INFINITY &plusmn; 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 &plusmn; INFINITY i) = NaN + NaN i
     *   exp(INFINITY + i) = INFINITY + INFINITY i
     *   exp(-INFINITY + i) = 0 + 0i
     *   exp(&plusmn;INFINITY &plusmn; 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 &plusmn; INFINITY i) = INFINITY &plusmn; (&pi;/2)i
     *   log(INFINITY + i) = INFINITY + 0i
     *   log(-INFINITY + i) = INFINITY + &pi;i
     *   log(INFINITY &plusmn; INFINITY i) = INFINITY &plusmn; (&pi;/4)i
     *   log(-INFINITY &plusmn; INFINITY i) = INFINITY &plusmn; (3&pi;/4)i
     *   log(0 + 0i) = -INFINITY + 0i
     *  </code>
     * </pre>
     *
     * @return the value <code>ln &nbsp; 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&middot;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 &plusmn; INFINITY i) = 1 &plusmn; INFINITY i
     *   sin(&plusmn;INFINITY + i) = NaN + NaN i
     *   sin(&plusmn;INFINITY &plusmn; 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 &plusmn; INFINITY i) = NaN + NaN i
     *   sinh(&plusmn;INFINITY + i) = &plusmn; INFINITY + INFINITY i
     *   sinh(&plusmn;INFINITY &plusmn; 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 &#8805; 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 &plusmn; INFINITY i) = INFINITY + NaN i
     *   sqrt(INFINITY + i) = INFINITY + 0i
     *   sqrt(-INFINITY + i) = 0 + INFINITY i
     *   sqrt(INFINITY &plusmn; INFINITY i) = INFINITY + NaN i
     *   sqrt(-INFINITY &plusmn; INFINITY i) = NaN &plusmn; 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 &plusmn; INFINITY i) = 0 &plusmn; i
     *   tan(&plusmn;INFINITY + bi) = NaN + NaN i
     *   tan(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
     *   tan(&plusmn;&pi;/2 + 0 i) = &plusmn;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 &plusmn; INFINITY i) = NaN + NaN i
     *   tanh(&plusmn;INFINITY + bi) = &plusmn;1 + 0 i
     *   tanh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
     *   tanh(0 + (&pi;/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&pi;k/n) + i (sin(phi + 2&pi;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 + ")";
    }
}