Class Complex

  • All Implemented Interfaces:
    java.io.Serializable

    public final class Complex
    extends java.lang.Object
    implements java.io.Serializable
    Cartesian representation of a complex number. The complex number is expressed in the form \( a + ib \) where \( a \) and \( b \) are real numbers and \( i \) is the imaginary unit which satisfies the equation \( i^2 = -1 \). For the complex number \( a + ib \), \( a \) is called the real part and \( b \) is called the imaginary part.

    This class is immutable. All arithmetic will create a new instance for the result.

    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 behavior for special cases is listed as defined in C99.

    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.

    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.

    Special cases of branch cuts for multivalued functions adopt the principle value convention from C99. Specials cases from C99 that raise the "invalid" or "divide-by-zero" floating-point exceptions 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 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 cardinality of NaN component parts has increased as a real or imaginary part could not be computed and is set to NaN.

    See Also:
    ISO/IEC 9899 - Programming languages - C, Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static interface  Complex.ComplexConstructor
      Define a constructor for a Complex.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static double A_CROSSOVER
      Crossover point to switch computation for asin/acos factor A.
      private static double B_CROSSOVER
      Crossover point to switch computation for asin/acos factor B.
      private static int BEFORE_SEP
      The minimum number of characters before the separator.
      private static double EPSILON
      Largest double-precision floating-point number such that 1 + EPSILON is numerically equal to 1.
      private static int EXP_1024
      Represents an exponent of 1024 in unbiased form (infinite or nan) shifted 20-bits to align with the upper 32-bits of a double.
      private static int EXP_500
      Represents an exponent of 500 in unbiased form shifted 20-bits to align with the upper 32-bits of a double.
      private static int EXP_54
      54 shifted 20-bits to align with the exponent of the upper 32-bits of a double.
      private static double EXP_M
      The value of Math.exp(SAFE_EXP): e^708.
      private static int EXP_NEG_500
      Represents an exponent of -500 in unbiased form shifted 20-bits to align with the upper 32-bits of a double.
      private static int EXPONENT_OFFSET
      Exponent offset in IEEE754 representation.
      private static char FORMAT_END
      private static int FORMAT_MIN_LEN
      The minimum number of characters in the format.
      private static char FORMAT_SEP
      private static char FORMAT_START
      private static double HALF
      1/2.
      static Complex I
      A complex number representing \( i \), the square root of \( -1 \).
      private double imaginary
      The imaginary part.
      private static double LN_2
      Natural logarithm of 2 (ln(2)).
      private static double LOG_10E_O_2
      Base 10 logarithm of 10 divided by 2 (log10(e)/2).
      private static double LOG10_2
      Base 10 logarithm of 2 (log10(2)).
      private static long MANTISSA_MASK
      Mask to extract the 52-bit mantissa from a long representation of a double.
      private static double MULTIPLIER
      The multiplier used to split the double value into hi and low parts.
      private static Complex NAN
      A complex number representing NaN + i NaN.
      private static long NEGATIVE_ZERO_LONG_BITS
      The bit representation of -0.0.
      static Complex ONE
      A complex number representing one.
      private static double ONE_OVER_ROOT2
      1.0 / sqrt(2).
      private static double PI_OVER_2
      π/2.
      private static double PI_OVER_4
      π/4.
      private double real
      The real part.
      private static double ROOT2
      sqrt(2).
      private static double SAFE_EXP
      A safe maximum double value m where e^m is not infinite.
      private static double SAFE_LOWER
      The safe minimum double value x to avoid loss of precision/underflow in atanh.
      private static double SAFE_MAX
      The safe maximum double value x to avoid loss of precision in asin/acos.
      private static double SAFE_MIN
      The safe minimum double value x to avoid loss of precision/underflow in asin/acos.
      private static double SAFE_UPPER
      The safe maximum double value x to avoid loss of precision in atanh.
      private static long serialVersionUID
      Serializable version identifier.
      private static double SQRT_SAFE_UPPER
      The safe maximum double value x to avoid overflow in sqrt.
      private static int TO_STRING_SIZE
      The size of the buffer for toString().
      private static double TWO_POW_600
      2^600.
      private static double TWO_POW_NEG_600
      2^-600.
      private static long UNSIGN_MASK
      Mask to remove the sign bit from a long.
      static Complex ZERO
      A complex number representing zero.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Complex​(double real, double imaginary)
      Private default constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      double abs()
      Returns the absolute value of this complex number.
      private static double abs​(double real, double imaginary)
      Returns the absolute value of the complex number.
      Complex acos()
      Returns the inverse cosine of this complex number.
      private static Complex acos​(double real, double imaginary, Complex.ComplexConstructor constructor)
      Returns the inverse cosine of the complex number.
      Complex acosh()
      Returns the inverse hyperbolic cosine of this complex number.
      Complex add​(double addend)
      Returns a Complex whose value is (this + addend), with addend interpreted as a real number.
      Complex add​(Complex addend)
      Returns a Complex whose value is (this + addend).
      Complex addImaginary​(double addend)
      Returns a Complex whose value is (this + addend), with addend interpreted as an imaginary number.
      double arg()
      Returns the argument of this complex number.
      Complex asin()
      Returns the inverse sine of this complex number.
      private static Complex asin​(double real, double imaginary, Complex.ComplexConstructor constructor)
      Returns the inverse sine of the complex number.
      Complex asinh()
      Returns the inverse hyperbolic sine of this complex number.
      Complex atan()
      Returns the inverse tangent of this complex number.
      Complex atanh()
      Returns the inverse hyperbolic tangent of this complex number.
      private static Complex atanh​(double real, double imaginary, Complex.ComplexConstructor constructor)
      Returns the inverse hyperbolic tangent of this complex number.
      private static double boxInfinity​(double component)
      Box values for the real or imaginary component of an infinite complex number.
      private static double changeNaNtoZero​(double value)
      Change NaN to zero preserving the sign; otherwise return the value.
      private static double changeSign​(double magnitude, double signedValue)
      Change the sign of the magnitude based on the signed value.
      Complex conj()
      Returns the conjugate \( \overline{z} \) of this complex number \( z \).
      Complex cos()
      Returns the cosine of this complex number.
      Complex cosh()
      Returns the hyperbolic cosine of this complex number.
      private static Complex cosh​(double real, double imaginary, Complex.ComplexConstructor constructor)
      Returns the hyperbolic cosine of the complex number.
      private static Complex coshsinh​(double x, double real, double imaginary, boolean sinh, Complex.ComplexConstructor constructor)
      Compute cosh or sinh when the absolute real component |x| is large.
      Complex divide​(double divisor)
      Returns a Complex whose value is (this / divisor), with divisor interpreted as a real number.
      private static Complex divide​(double re1, double im1, double re2, double im2)
      Returns a Complex whose value is:
      Complex divide​(Complex divisor)
      Returns a Complex whose value is (this / divisor).
      Complex divideImaginary​(double divisor)
      Returns a Complex whose value is (this / divisor), with divisor interpreted as an imaginary number.
      private static boolean equals​(double x, double y)
      Returns true if the values are equal according to semantics of Double.equals(Object).
      boolean equals​(java.lang.Object other)
      Test for equality with another object.
      Complex exp()
      Returns the exponential function of this complex number.
      private static double fastSumLow​(double a, double b, double x)
      Compute the round-off from the sum of two numbers a and b using Dekker's two-sum algorithm.
      double getImaginary()
      Gets the imaginary part \( b \) of this complex number \( (a + i b) \).
      private static int getMaxExponent​(double a, double b)
      Returns the largest unbiased exponent used in the representation of the two numbers.
      double getReal()
      Gets the real part \( a \) of this complex number \( (a + i b) \).
      private static int getScale​(double a, double b)
      Returns a scale suitable for use with Math.scalb(double, int) to normalise the number to the interval [1, 2).
      int hashCode()
      Gets a hash code for the complex number.
      private static double hypot​(double x, double y)
      Returns sqrt(x^2 + y^2) without intermediate overflow or underflow.
      double imag()
      Gets the imaginary part \( b \) of this complex number \( (a + i b) \).
      private static boolean inRegion​(double x, double y, double min, double max)
      Checks if both x and y are in the region defined by the minimum and maximum.
      boolean isFinite()
      Returns true if both real and imaginary component of the complex number are finite.
      boolean isInfinite()
      Returns true if either real or imaginary component of the complex number is infinite.
      boolean isNaN()
      Returns true if either the real or imaginary component of the complex number is NaN and the complex number is not infinite.
      private static boolean isNotZero​(double real, double imaginary)
      Checks if the complex number is not zero.
      private static boolean isPosFinite​(double d)
      Check that an absolute value is finite.
      private static boolean isPosInfinite​(double d)
      Check that a value is positive infinity.
      Complex log()
      Returns the natural logarithm of this complex number.
      private Complex log​(java.util.function.DoubleUnaryOperator log, double logOfeOver2, double logOf2, Complex.ComplexConstructor constructor)
      Returns the logarithm of this complex number using the provided function.
      Complex log10()
      Returns the base 10 common logarithm of this complex number.
      Complex multiply​(double factor)
      Returns a Complex whose value is this * factor, with factor interpreted as a real number.
      private static Complex multiply​(double re1, double im1, double re2, double im2)
      Returns a Complex whose value is:
      Complex multiply​(Complex factor)
      Returns a Complex whose value is this * factor.
      Complex multiplyImaginary​(double factor)
      Returns a Complex whose value is this * factor, with factor interpreted as an imaginary number.
      private static Complex multiplyNegativeI​(double real, double imaginary)
      Create a complex number given the real and imaginary parts, then multiply by -i.
      Complex negate()
      Returns a Complex whose value is the negation of both the real and imaginary parts of complex number \( z \).
      private static boolean negative​(double d)
      Check that a value is negative.
      double norm()
      Returns the squared norm value of this complex number.
      java.util.List<Complex> nthRoot​(int n)
      Returns the n-th roots of this complex number.
      static Complex ofCartesian​(double real, double imaginary)
      Create a complex number given the real and imaginary parts.
      static Complex ofCis​(double x)
      Create a complex cis number.
      static Complex ofPolar​(double rho, double theta)
      Creates a complex number from its polar representation using modulus rho (\( \rho \)) and phase angle theta (\( \theta \)).
      static Complex parse​(java.lang.String s)
      Returns a Complex instance representing the specified string s.
      private static java.lang.String parsingExceptionMsg​(java.lang.String message, java.lang.Object error, java.lang.String s)
      Creates an exception message.
      Complex pow​(double x)
      Returns the complex power of this complex number raised to the power of x, with x interpreted as a real number.
      Complex pow​(Complex x)
      Returns the complex power of this complex number raised to the power of x.
      Complex proj()
      Returns the projection of this complex number onto the Riemann sphere.
      double real()
      Gets the real part \( a \) of this complex number \( (a + i b) \).
      Complex sin()
      Returns the sine of this complex number.
      Complex sinh()
      Returns the hyperbolic sine of this complex number.
      private static Complex sinh​(double real, double imaginary, Complex.ComplexConstructor constructor)
      Returns the hyperbolic sine of the complex number.
      private static double splitHigh​(double a)
      Implement Dekker's method to split a value into two parts.
      Complex sqrt()
      Returns the square root of this complex number.
      private static Complex sqrt​(double real, double imaginary)
      Returns the square root of the complex number sqrt(x + i y).
      private static double squareLow​(double low, double high, double square)
      Compute the round-off from the square of a split number with low and high components.
      Complex subtract​(double subtrahend)
      Returns a Complex whose value is (this - subtrahend), with subtrahend interpreted as a real number.
      Complex subtract​(Complex subtrahend)
      Returns a Complex whose value is (this - subtrahend).
      Complex subtractFrom​(double minuend)
      Returns a Complex whose value is (minuend - this), with minuend interpreted as a real number.
      Complex subtractFromImaginary​(double minuend)
      Returns a Complex whose value is (this - subtrahend), with minuend interpreted as an imaginary number.
      Complex subtractImaginary​(double subtrahend)
      Returns a Complex whose value is (this - subtrahend), with subtrahend interpreted as an imaginary number.
      private static double sumLow​(double a, double b, double x)
      Compute the round-off from the sum of two numbers a and b using Knuth's two-sum algorithm.
      private static double sumx2y2m1​(double x2High, double x2Low, double y2High, double y2Low)
      Sum x^2 + y^2 - 1.
      Complex tan()
      Returns the tangent of this complex number.
      Complex tanh()
      Returns the hyperbolic tangent of this complex number.
      private static Complex tanh​(double real, double imaginary, Complex.ComplexConstructor constructor)
      Returns the hyperbolic tangent of this complex number.
      java.lang.String toString()
      Returns a string representation of the complex number.
      private static double x2y2​(double x, double y)
      Return x^2 + y^2 with high accuracy.
      private static double x2y2m1​(double x, double y)
      Compute x^2 + y^2 - 1 in high precision.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • I

        public static final Complex I
        A complex number representing \( i \), the square root of \( -1 \).

        \( (0 + i 1) \).

      • ONE

        public static final Complex ONE
        A complex number representing one.

        \( (1 + i 0) \).

      • ZERO

        public static final Complex ZERO
        A complex number representing zero.

        \( (0 + i 0) \).

      • NAN

        private static final Complex NAN
        A complex number representing NaN + i NaN.
      • LN_2

        private static final double LN_2
        Natural logarithm of 2 (ln(2)).
      • LOG_10E_O_2

        private static final double LOG_10E_O_2
        Base 10 logarithm of 10 divided by 2 (log10(e)/2).
      • LOG10_2

        private static final double LOG10_2
        Base 10 logarithm of 2 (log10(2)).
      • ONE_OVER_ROOT2

        private static final double ONE_OVER_ROOT2
        1.0 / sqrt(2). This is pre-computed to the closest double from the exact result. It is 1 ULP different from 1.0 / Math.sqrt(2) but equal to Math.sqrt(2) / 2.
        See Also:
        Constant Field Values
      • NEGATIVE_ZERO_LONG_BITS

        private static final long NEGATIVE_ZERO_LONG_BITS
        The bit representation of -0.0.
      • EXPONENT_OFFSET

        private static final int EXPONENT_OFFSET
        Exponent offset in IEEE754 representation.
        See Also:
        Constant Field Values
      • EPSILON

        private static final double EPSILON
        Largest double-precision floating-point number such that 1 + EPSILON is numerically equal to 1. This value is an upper bound on the relative error due to rounding real numbers to double precision floating-point numbers.

        In IEEE 754 arithmetic, this is 2-53. Copied from o.a.c.numbers.Precision.

        See Also:
        Machine epsilon
      • UNSIGN_MASK

        private static final long UNSIGN_MASK
        Mask to remove the sign bit from a long.
        See Also:
        Constant Field Values
      • MANTISSA_MASK

        private static final long MANTISSA_MASK
        Mask to extract the 52-bit mantissa from a long representation of a double.
        See Also:
        Constant Field Values
      • MULTIPLIER

        private static final double MULTIPLIER
        The multiplier used to split the double value into hi and low parts. This must be odd and a value of 2^s + 1 in the range p/2 <= s <= p-1 where p is the number of bits of precision of the floating point number. Here s = 27.
        See Also:
        Constant Field Values
      • A_CROSSOVER

        private static final double A_CROSSOVER
        Crossover point to switch computation for asin/acos factor A. This has been updated from the 1.5 value used by Hull et al to 10 as used in boost::math::complex.
        See Also:
        Boost ticket 7290, Constant Field Values
      • B_CROSSOVER

        private static final double B_CROSSOVER
        Crossover point to switch computation for asin/acos factor B.
        See Also:
        Constant Field Values
      • SAFE_MAX

        private static final double SAFE_MAX
        The safe maximum double value x to avoid loss of precision in asin/acos. Equal to sqrt(M) / 8 in Hull, et al (1997) with M the largest normalised floating-point value.
      • SAFE_MIN

        private static final double SAFE_MIN
        The safe minimum double value x to avoid loss of precision/underflow in asin/acos. Equal to sqrt(u) * 4 in Hull, et al (1997) with u the smallest normalised floating-point value.
      • SAFE_UPPER

        private static final double SAFE_UPPER
        The safe maximum double value x to avoid loss of precision in atanh. Equal to sqrt(M) / 2 with M the largest normalised floating-point value.
      • SAFE_LOWER

        private static final double SAFE_LOWER
        The safe minimum double value x to avoid loss of precision/underflow in atanh. Equal to sqrt(u) * 2 with u the smallest normalised floating-point value.
      • SQRT_SAFE_UPPER

        private static final double SQRT_SAFE_UPPER
        The safe maximum double value x to avoid overflow in sqrt.
        See Also:
        Constant Field Values
      • SAFE_EXP

        private static final double SAFE_EXP
        A safe maximum double value m where e^m is not infinite. This can be used when functions require approximations of sinh(x) or cosh(x) when x is large using exp(x):
         sinh(x) = (e^x - e^-x) / 2 = sign(x) * e^|x| / 2
         cosh(x) = (e^x + e^-x) / 2 = e^|x| / 2 

        This value can be used to approximate e^x using a product:

         e^x = product_n (e^m) * e^(x-nm)
         n = (int) x/m
         e.g. e^2000 = e^m * e^m * e^(2000 - 2m) 

        The value should be below ln(max_value) ~ 709.783. The value m is set to an integer for less error when subtracting m and chosen as even (m=708) as it is used as a threshold in tanh with m/2.

        The value is used to compute e^x multiplied by a small number avoiding overflow (sinh/cosh) or a small number divided by e^x without underflow due to infinite e^x (tanh). The following conditions are used:

         0.5 * e^m * Double.MIN_VALUE * e^m * e^m = Infinity
         2.0 / e^m / e^m = 0.0 
        See Also:
        Constant Field Values
      • EXP_M

        private static final double EXP_M
        The value of Math.exp(SAFE_EXP): e^708. To be used in overflow/underflow safe products of e^m to approximate e^x where x > m.
      • EXP_54

        private static final int EXP_54
        54 shifted 20-bits to align with the exponent of the upper 32-bits of a double.
        See Also:
        Constant Field Values
      • EXP_500

        private static final int EXP_500
        Represents an exponent of 500 in unbiased form shifted 20-bits to align with the upper 32-bits of a double.
        See Also:
        Constant Field Values
      • EXP_1024

        private static final int EXP_1024
        Represents an exponent of 1024 in unbiased form (infinite or nan) shifted 20-bits to align with the upper 32-bits of a double.
        See Also:
        Constant Field Values
      • EXP_NEG_500

        private static final int EXP_NEG_500
        Represents an exponent of -500 in unbiased form shifted 20-bits to align with the upper 32-bits of a double.
        See Also:
        Constant Field Values
      • serialVersionUID

        private static final long serialVersionUID
        Serializable version identifier.
        See Also:
        Constant Field Values
      • TO_STRING_SIZE

        private static final int TO_STRING_SIZE
        The size of the buffer for toString().

        The longest double will require a sign, a maximum of 17 digits, the decimal place and the exponent, e.g. for max value this is 24 chars: -1.7976931348623157e+308. Set the buffer size to twice this and round up to a power of 2 thus allowing for formatting characters. The size is 64.

        See Also:
        Constant Field Values
      • FORMAT_MIN_LEN

        private static final int FORMAT_MIN_LEN
        The minimum number of characters in the format. This is 5, e.g. "(0,0)".
        See Also:
        Constant Field Values
      • BEFORE_SEP

        private static final int BEFORE_SEP
        The minimum number of characters before the separator. This is 2, e.g. "(0".
        See Also:
        Constant Field Values
      • imaginary

        private final double imaginary
        The imaginary part.
      • real

        private final double real
        The real part.
    • Constructor Detail

      • Complex

        private Complex​(double real,
                        double imaginary)
        Private default constructor.
        Parameters:
        real - Real part.
        imaginary - Imaginary part.
    • Method Detail

      • ofCartesian

        public static Complex ofCartesian​(double real,
                                          double imaginary)
        Create a complex number given the real and imaginary parts.
        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        Returns:
        Complex number.
      • ofPolar

        public static Complex ofPolar​(double rho,
                                      double theta)
        Creates a complex number from its polar representation using modulus rho (\( \rho \)) and phase angle theta (\( \theta \)). \[ \begin{aligned} x &= \rho \cos(\theta) \\ y &= \rho \sin(\theta) \end{aligned} \]

        Requires that rho is non-negative and non-NaN and theta is finite; otherwise returns a complex with NaN real and imaginary parts. A rho value of -0.0 is considered negative and an invalid modulus.

        A non-NaN complex number constructed using this method will satisfy the following to within floating-point error when theta is in the range \( -\pi\ \lt \theta \leq \pi \):

          Complex.ofPolar(rho, theta).abs() == rho
          Complex.ofPolar(rho, theta).arg() == theta

        If rho is infinite then the resulting parts may be infinite or NaN following the rules for double arithmetic, for example:

        • ofPolar(\( -0.0 \), \( 0 \)) = \( \text{NaN} + i \text{NaN} \)
        • ofPolar(\( 0.0 \), \( 0 \)) = \( 0 + i 0 \)
        • ofPolar(\( 1 \), \( 0 \)) = \( 1 + i 0 \)
        • ofPolar(\( 1 \), \( \pi \)) = \( -1 + i \sin(\pi) \)
        • ofPolar(\( \infty \), \( \pi \)) = \( -\infty + i \infty \)
        • ofPolar(\( \infty \), \( 0 \)) = \( -\infty + i \text{NaN} \)
        • ofPolar(\( \infty \), \( -\frac{\pi}{4} \)) = \( \infty - i \infty \)
        • ofPolar(\( \infty \), \( 5\frac{\pi}{4} \)) = \( -\infty - i \infty \)

        This method is the functional equivalent of the C++ method std::polar.

        Parameters:
        rho - The modulus of the complex number.
        theta - The argument of the complex number.
        Returns:
        Complex number.
        See Also:
        Polar Coordinates
      • ofCis

        public static Complex ofCis​(double x)
        Create a complex cis number. This is also known as the complex exponential: \[ \text{cis}(x) = e^{ix} = \cos(x) + i \sin(x) \]
        Parameters:
        x - double to build the cis number.
        Returns:
        Complex cis number.
        See Also:
        Cis
      • parse

        public static Complex parse​(java.lang.String s)
        Returns a Complex instance representing the specified string s.

        If s is null, then a NullPointerException is thrown.

        The string must be in a format compatible with that produced by Complex.toString(). The format expects a start and end parentheses surrounding two numeric parts split by a separator. Leading and trailing spaces are allowed around each numeric part. Each numeric part is parsed using Double.parseDouble(String). The parts are interpreted as the real and imaginary parts of the complex number.

        Examples of valid strings and the equivalent Complex are shown below:

         "(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(-1.23, 4.56)
         "(1e300,-1.1e-2)"   = Complex.ofCartesian(1e300, -1.1e-2)
        Parameters:
        s - String representation.
        Returns:
        Complex number.
        Throws:
        java.lang.NullPointerException - if the string is null.
        java.lang.NumberFormatException - if the string does not contain a parsable complex number.
        See Also:
        Double.parseDouble(String), toString()
      • parsingExceptionMsg

        private static java.lang.String parsingExceptionMsg​(java.lang.String message,
                                                            java.lang.Object error,
                                                            java.lang.String s)
        Creates an exception message.
        Parameters:
        message - Message prefix.
        error - Input that caused the error.
        s - String representation.
        Returns:
        A message.
      • getReal

        public double getReal()
        Gets the real part \( a \) of this complex number \( (a + i b) \).
        Returns:
        The real part.
      • real

        public double real()
        Gets the real part \( a \) of this complex number \( (a + i b) \).

        This method is the equivalent of the C++ method std::complex::real.

        Returns:
        The real part.
        See Also:
        getReal()
      • getImaginary

        public double getImaginary()
        Gets the imaginary part \( b \) of this complex number \( (a + i b) \).
        Returns:
        The imaginary part.
      • imag

        public double imag()
        Gets the imaginary part \( b \) of this complex number \( (a + i b) \).

        This method is the equivalent of the C++ method std::complex::imag.

        Returns:
        The imaginary part.
        See Also:
        getImaginary()
      • abs

        public double abs()
        Returns the absolute value of this complex number. This is also called complex norm, modulus, or magnitude.

        \[ \text{abs}(x + i y) = \sqrt{(x^2 + y^2)} \]

        Special cases:

        • abs(x + iy) == abs(y + ix) == abs(x - iy).
        • If z is ±∞ + iy for any y, returns +∞.
        • If z is x + iNaN for non-infinite x, returns NaN.
        • If z is x + i0, returns |x|.

        The cases ensure that if either component is infinite then the result is positive infinity. If either component is NaN and this is not infinite then the result is NaN.

        This method follows the ISO C Standard, Annex G, in calculating the returned value without intermediate overflow or underflow.

        The computed result will be within 1 ulp of the exact result.

        Returns:
        The absolute value.
        See Also:
        isInfinite(), isNaN(), Complex modulus
      • abs

        private static double abs​(double real,
                                  double imaginary)
        Returns the absolute value of the complex number.
        abs(x + i y) = sqrt(x^2 + y^2)

        This should satisfy the special cases of the hypot function in ISO C99 F.9.4.3: "The hypot functions compute the square root of the sum of the squares of x and y, without undue overflow or underflow."

        • hypot(x, y), hypot(y, x), and hypot(x, −y) are equivalent.
        • hypot(x, ±0) is equivalent to |x|.
        • hypot(±∞, y) returns +∞, even if y is a NaN.

        This method is called by all methods that require the absolute value of the complex number, e.g. abs(), sqrt() and log().

        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        Returns:
        The absolute value.
      • arg

        public double arg()
        Returns 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.

        If either real or imaginary part (or both) is NaN, then the result is NaN. Infinite parts are handled as Math.atan2(double, double) 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 the signs of the infinite parts.

        This code follows the ISO C Standard, Annex G, in calculating the returned value using the atan2(y, x) method for complex \( x + iy \).

        Returns:
        The argument of this complex number.
        See Also:
        Math.atan2(double, double)
      • norm

        public double norm()
        Returns the squared norm value of this complex number. This is also called the absolute square.

        \[ \text{norm}(x + i y) = x^2 + y^2 \]

        If either component is infinite then the result is positive infinity. If either component is NaN and this is not infinite then the result is NaN.

        Note: This method may not return the same value as the square of abs() as that method uses an extended precision computation.

        norm() can be used as a faster alternative than 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 abs().

        Returns:
        The square norm value.
        See Also:
        isInfinite(), isNaN(), abs(), Absolute square
      • isNaN

        public boolean isNaN()
        Returns true if either the real or imaginary component of the complex number is NaN and the complex number is not infinite.

        Note that:

        • There is more than one complex number that can return true.
        • Different representations of NaN can be distinguished by the Complex.equals(Object) method.
        Returns:
        true if this instance contains NaN and no infinite parts.
        See Also:
        Double.isNaN(double), isInfinite(), Complex.equals(Object)
      • isInfinite

        public boolean isInfinite()
        Returns true if either real or imaginary component of the complex number is infinite.

        Note: A complex number with at least one infinite part is regarded as an infinity (even if its other part is a NaN).

        Returns:
        true if this instance contains an infinite value.
        See Also:
        Double.isInfinite(double)
      • isFinite

        public boolean isFinite()
        Returns true if both real and imaginary component of the complex number are finite.
        Returns:
        true if this instance contains finite values.
        See Also:
        Double.isFinite(double)
      • conj

        public Complex conj()
        Returns the conjugate \( \overline{z} \) of this complex number \( z \).

        \[ \begin{aligned} z &= a + i b \\ \overline{z} &= a - i b \end{aligned}\]

        Returns:
        The conjugate (\( \overline{z} \)) of this complex number.
      • negate

        public Complex negate()
        Returns a Complex whose value is the negation of both the real and imaginary parts of complex number \( z \).

        \[ \begin{aligned} z &= a + i b \\ -z &= -a - i b \end{aligned} \]

        Returns:
        \( -z \).
      • proj

        public Complex proj()
        Returns the projection of this complex number onto the Riemann sphere.

        \( 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. If \( z \) has an infinite part, then z.proj() shall be equivalent to:

        return Complex.ofCartesian(Double.POSITIVE_INFINITY, Math.copySign(0.0, z.imag());
        Returns:
        \( z \) projected onto the Riemann sphere.
        See Also:
        isInfinite(), IEEE and ISO C standards: cproj
      • add

        public Complex add​(Complex addend)
        Returns a Complex whose value is (this + addend). Implements the formula:

        \[ (a + i b) + (c + i d) = (a + c) + i (b + d) \]

        Parameters:
        addend - Value to be added to this complex number.
        Returns:
        this + addend.
        See Also:
        Complex Addition
      • add

        public Complex add​(double addend)
        Returns a Complex whose value is (this + addend), with addend interpreted as a real number. Implements the formula:

        \[ (a + i b) + c = (a + c) + i b \]

        This method is included for compatibility with ISO C99 which defines arithmetic between real-only and complex numbers.

        Note: This method preserves the sign of the imaginary component \( b \) if it is -0.0. The sign would be lost if adding \( (c + i 0) \) using add(Complex.ofCartesian(addend, 0)) since -0.0 + 0.0 = 0.0.

        Parameters:
        addend - Value to be added to this complex number.
        Returns:
        this + addend.
        See Also:
        add(Complex), ofCartesian(double, double)
      • addImaginary

        public Complex addImaginary​(double addend)
        Returns a Complex whose value is (this + addend), with addend interpreted as an imaginary number. Implements the formula:

        \[ (a + i b) + i d = a + i (b + d) \]

        This method is included for compatibility with ISO C99 which defines arithmetic between imaginary-only and complex numbers.

        Note: This method preserves the sign of the real component \( a \) if it is -0.0. The sign would be lost if adding \( (0 + i d) \) using add(Complex.ofCartesian(0, addend)) since -0.0 + 0.0 = 0.0.

        Parameters:
        addend - Value to be added to this complex number.
        Returns:
        this + addend.
        See Also:
        add(Complex), ofCartesian(double, double)
      • subtract

        public Complex subtract​(Complex subtrahend)
        Returns a Complex whose value is (this - subtrahend). Implements the formula:

        \[ (a + i b) - (c + i d) = (a - c) + i (b - d) \]

        Parameters:
        subtrahend - Value to be subtracted from this complex number.
        Returns:
        this - subtrahend.
        See Also:
        Complex Subtraction
      • subtract

        public Complex subtract​(double subtrahend)
        Returns a Complex whose value is (this - subtrahend), with subtrahend interpreted as a real number. Implements the formula:

        \[ (a + i b) - c = (a - c) + i b \]

        This method is included for compatibility with ISO C99 which defines arithmetic between real-only and complex numbers.

        Parameters:
        subtrahend - Value to be subtracted from this complex number.
        Returns:
        this - subtrahend.
        See Also:
        subtract(Complex)
      • subtractImaginary

        public Complex subtractImaginary​(double subtrahend)
        Returns a Complex whose value is (this - subtrahend), with subtrahend interpreted as an imaginary number. Implements the formula:

        \[ (a + i b) - i d = a + i (b - d) \]

        This method is included for compatibility with ISO C99 which defines arithmetic between imaginary-only and complex numbers.

        Parameters:
        subtrahend - Value to be subtracted from this complex number.
        Returns:
        this - subtrahend.
        See Also:
        subtract(Complex)
      • subtractFrom

        public Complex subtractFrom​(double minuend)
        Returns a Complex whose value is (minuend - this), with minuend interpreted as a real number. Implements the formula: \[ c - (a + i b) = (c - a) - i b \]

        This method is included for compatibility with ISO C99 which defines arithmetic between real-only and complex numbers.

        Note: This method inverts the sign of the imaginary component \( b \) if it is 0.0. The sign would not be inverted if subtracting from \( c + i 0 \) using Complex.ofCartesian(minuend, 0).subtract(this) since 0.0 - 0.0 = 0.0.

        Parameters:
        minuend - Value this complex number is to be subtracted from.
        Returns:
        minuend - this.
        See Also:
        subtract(Complex), ofCartesian(double, double)
      • subtractFromImaginary

        public Complex subtractFromImaginary​(double minuend)
        Returns a Complex whose value is (this - subtrahend), with minuend interpreted as an imaginary number. Implements the formula: \[ i d - (a + i b) = -a + i (d - b) \]

        This method is included for compatibility with ISO C99 which defines arithmetic between imaginary-only and complex numbers.

        Note: This method inverts the sign of the real component \( a \) if it is 0.0. The sign would not be inverted if subtracting from \( 0 + i d \) using Complex.ofCartesian(0, minuend).subtract(this) since 0.0 - 0.0 = 0.0.

        Parameters:
        minuend - Value this complex number is to be subtracted from.
        Returns:
        this - subtrahend.
        See Also:
        subtract(Complex), ofCartesian(double, double)
      • multiply

        public Complex multiply​(Complex factor)
        Returns a Complex whose value is this * factor. Implements the formula:

        \[ (a + i b)(c + i d) = (ac - bd) + i (ad + bc) \]

        Recalculates to recover infinities as specified in C99 standard G.5.1.

        Parameters:
        factor - Value to be multiplied by this complex number.
        Returns:
        this * factor.
        See Also:
        Complex Muliplication
      • multiply

        private static Complex multiply​(double re1,
                                        double im1,
                                        double re2,
                                        double im2)
        Returns a Complex whose value is:
          (a + i b)(c + i d) = (ac - bd) + i (ad + bc)

        Recalculates to recover infinities as specified in C99 standard G.5.1.

        Parameters:
        re1 - Real component of first number.
        im1 - Imaginary component of first number.
        re2 - Real component of second number.
        im2 - Imaginary component of second number.
        Returns:
        (a + b i)(c + d i).
      • boxInfinity

        private static double boxInfinity​(double component)
        Box values for the real or imaginary component of an infinite complex number. Any infinite value will be returned as one. Non-infinite values will be returned as zero. The sign is maintained.
          inf  =  1
         -inf  = -1
          x    =  0
         -x    = -0
         
        Parameters:
        component - the component
        Returns:
        The boxed value
      • isNotZero

        private static boolean isNotZero​(double real,
                                         double imaginary)
        Checks if the complex number is not zero.
        Parameters:
        real - the real component
        imaginary - the imaginary component
        Returns:
        true if the complex is not zero
      • changeNaNtoZero

        private static double changeNaNtoZero​(double value)
        Change NaN to zero preserving the sign; otherwise return the value.
        Parameters:
        value - the value
        Returns:
        The new value
      • multiply

        public Complex multiply​(double factor)
        Returns a Complex whose value is this * factor, with factor interpreted as a real number. Implements the formula:

        \[ (a + i b) c = (ac) + i (bc) \]

        This method is included for compatibility with ISO C99 which defines arithmetic between real-only and complex numbers.

        Note: This method should be preferred over using multiply(Complex.ofCartesian(factor, 0)). Multiplication can generate signed zeros if either this complex has zeros for the real and/or imaginary component, or if the factor is zero. The summation of signed zeros in multiply(Complex) may create zeros in the result that differ in sign from the equivalent call to multiply by a real-only number.

        Parameters:
        factor - Value to be multiplied by this complex number.
        Returns:
        this * factor.
        See Also:
        multiply(Complex)
      • multiplyImaginary

        public Complex multiplyImaginary​(double factor)
        Returns a Complex whose value is this * factor, with factor interpreted as an imaginary number. Implements the formula:

        \[ (a + i b) id = (-bd) + i (ad) \]

        This method can be used to compute the multiplication of this complex number \( z \) by \( i \) using a factor with magnitude 1.0. This should be used in preference to multiply(Complex.I) with or without negation:

        \[ \begin{aligned} iz &= (-b + i a) \\ -iz &= (b - i a) \end{aligned} \]

        This method is included for compatibility with ISO C99 which defines arithmetic between imaginary-only and complex numbers.

        Note: This method should be preferred over using multiply(Complex.ofCartesian(0, factor)). Multiplication can generate signed zeros if either this complex has zeros for the real and/or imaginary component, or if the factor is zero. The summation of signed zeros in multiply(Complex) may create zeros in the result that differ in sign from the equivalent call to multiply by an imaginary-only number.

        Parameters:
        factor - Value to be multiplied by this complex number.
        Returns:
        this * factor.
        See Also:
        multiply(Complex)
      • divide

        public Complex divide​(Complex divisor)
        Returns a Complex whose value is (this / divisor). Implements the formula:

        \[ \frac{a + i b}{c + i d} = \frac{(ac + bd) + i (bc - ad)}{c^2+d^2} \]

        Re-calculates NaN result values to recover infinities as specified in C99 standard G.5.1.

        Parameters:
        divisor - Value by which this complex number is to be divided.
        Returns:
        this / divisor.
        See Also:
        Complex Division
      • divide

        private static Complex divide​(double re1,
                                      double im1,
                                      double re2,
                                      double im2)
        Returns a Complex whose value is:
         
           a + i b     (ac + bd) + i (bc - ad)
           -------  =  -----------------------
           c + i d            c2 + d2
         
         

        Recalculates to recover infinities as specified in C99 standard G.5.1. Method is fully in accordance with C++11 standards for complex numbers.

        Note: In the event of divide by zero this method produces the same result as dividing by a real-only zero using divide(double).

        Parameters:
        re1 - Real component of first number.
        im1 - Imaginary component of first number.
        re2 - Real component of second number.
        im2 - Imaginary component of second number.
        Returns:
        (a + i b) / (c + i d).
        See Also:
        Complex Division, divide(double)
      • divide

        public Complex divide​(double divisor)
        Returns a Complex whose value is (this / divisor), with divisor interpreted as a real number. Implements the formula:

        \[ \frac{a + i b}{c} = \frac{a}{c} + i \frac{b}{c} \]

        This method is included for compatibility with ISO C99 which defines arithmetic between real-only and complex numbers.

        Note: This method should be preferred over using divide(Complex.ofCartesian(divisor, 0)). Division can generate signed zeros if this complex has zeros for the real and/or imaginary component, or the divisor is infinite. The summation of signed zeros in divide(Complex) may create zeros in the result that differ in sign from the equivalent call to divide by a real-only number.

        Parameters:
        divisor - Value by which this complex number is to be divided.
        Returns:
        this / divisor.
        See Also:
        divide(Complex)
      • divideImaginary

        public Complex divideImaginary​(double divisor)
        Returns a Complex whose value is (this / divisor), with divisor interpreted as an imaginary number. Implements the formula:

        \[ \frac{a + i b}{id} = \frac{b}{d} - i \frac{a}{d} \]

        This method is included for compatibility with ISO C99 which defines arithmetic between imaginary-only and complex numbers.

        Note: This method should be preferred over using divide(Complex.ofCartesian(0, divisor)). Division can generate signed zeros if this complex has zeros for the real and/or imaginary component, or the divisor is infinite. The summation of signed zeros in divide(Complex) may create zeros in the result that differ in sign from the equivalent call to divide by an imaginary-only number.

        Warning: This method will generate a different result from divide(Complex.ofCartesian(0, divisor)) if the divisor is zero. In this case the divide method using a zero-valued Complex will produce the same result 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 this.divide(Complex.ZERO).multiplyImaginary(1), however the sign of some infinite values may be negated.

        Parameters:
        divisor - Value by which this complex number is to be divided.
        Returns:
        this / divisor.
        See Also:
        divide(Complex), divide(double)
      • exp

        public Complex exp()
        Returns the exponential function of this complex number.

        \[ \exp(z) = e^z \]

        The exponential function of \( z \) is an entire function in the complex plane. Special cases:

        • z.conj().exp() == z.exp().conj().
        • If z is ±0 + i0, returns 1 + i0.
        • If z is x + i∞ for finite x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is x + iNaN for finite x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is +∞ + i0, returns +∞ + i0.
        • If z is −∞ + iy for finite y, returns +0 cis(y) (see ofCis(double)).
        • If z is +∞ + iy for finite nonzero y, returns +∞ cis(y).
        • If z is −∞ + i∞, returns ±0 ± i0 (where the signs of the real and imaginary parts of the result are unspecified).
        • If z is +∞ + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified; "invalid" floating-point operation).
        • If z is −∞ + iNaN, returns ±0 ± i0 (where the signs of the real and imaginary parts of the result are unspecified).
        • If z is +∞ + iNaN, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
        • If z is NaN + i0, returns NaN + i0.
        • If z is NaN + iy for all nonzero numbers y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + iNaN, returns NaN + iNaN.

        Implements the formula:

        \[ \exp(x + iy) = e^x (\cos(y) + i \sin(y)) \]

        Returns:
        The exponential of this complex number.
        See Also:
        Exp
      • log

        public Complex log()
        Returns the natural logarithm of this complex number.

        The natural logarithm of \( z \) is unbounded along the real axis and in the range \( [-\pi, \pi] \) along the imaginary axis. The imaginary part of the natural logarithm has a branch cut along the negative real axis \( (-infty,0] \). Special cases:

        • z.conj().log() == z.log().conj().
        • If z is −0 + i0, returns −∞ + iπ ("divide-by-zero" floating-point operation).
        • If z is +0 + i0, returns −∞ + i0 ("divide-by-zero" floating-point operation).
        • If z is x + i∞ for finite x, returns +∞ + iπ/2.
        • If z is x + iNaN for finite x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is −∞ + iy for finite positive-signed y, returns +∞ + iπ.
        • If z is +∞ + iy for finite positive-signed y, returns +∞ + i0.
        • If z is −∞ + i∞, returns +∞ + i3π/4.
        • If z is +∞ + i∞, returns +∞ + iπ/4.
        • If z is ±∞ + iNaN, returns +∞ + iNaN.
        • If z is NaN + iy for finite y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + i∞, returns +∞ + iNaN.
        • If z is NaN + iNaN, returns NaN + iNaN.

        Implements the formula:

        \[ \ln(z) = \ln |z| + i \arg(z) \]

        where \( |z| \) is the absolute and \( \arg(z) \) is the argument.

        The implementation is based on the method described in:

        T E Hull, Thomas F Fairgrieve and Ping Tak Peter Tang (1994) Implementing complex elementary functions using exception handling. ACM Transactions on Mathematical Software, Vol 20, No 2, pp 215-244.
        Returns:
        The natural logarithm of this complex number.
        See Also:
        Math.log(double), abs(), arg(), Log
      • log10

        public Complex log10()
        Returns the base 10 common logarithm of this complex number.

        The common logarithm of \( z \) is unbounded along the real axis and in the range \( [-\pi, \pi] \) along the imaginary axis. The imaginary part of the common logarithm has a branch cut along the negative real axis \( (-infty,0] \). Special cases are as defined in the natural logarithm:

        Implements the formula:

        \[ \log_{10}(z) = \log_{10} |z| + i \arg(z) \]

        where \( |z| \) is the absolute and \( \arg(z) \) is the argument.

        Returns:
        The base 10 logarithm of this complex number.
        See Also:
        Math.log10(double), abs(), arg()
      • log

        private Complex log​(java.util.function.DoubleUnaryOperator log,
                            double logOfeOver2,
                            double logOf2,
                            Complex.ComplexConstructor constructor)
        Returns the logarithm of this complex number using the provided function. Implements the formula:
           log(x + i y) = log(|x + i y|) + i arg(x + i y)

        Warning: The argument logOf2 must be equal to log(2) using the provided log function otherwise scaling using powers of 2 in the case of overflow will be incorrect. This is provided as an internal optimisation.

        Parameters:
        log - Log function.
        logOfeOver2 - The log function applied to e, then divided by 2.
        logOf2 - The log function applied to 2.
        constructor - Constructor for the returned complex.
        Returns:
        The logarithm of this complex number.
        See Also:
        abs(), arg()
      • pow

        public Complex pow​(Complex x)
        Returns the complex power of this complex number raised to the power of x. Implements the formula:

        \[ z^x = e^{x \ln(z)} \]

        If this complex number is zero then this method returns zero if x is positive in the real component and zero in the imaginary component; otherwise it returns NaN + iNaN.

        Parameters:
        x - The exponent to which this complex number is to be raised.
        Returns:
        This complex number raised to the power of x.
        See Also:
        log(), multiply(Complex), exp(), Complex exponentiation, Power
      • pow

        public Complex pow​(double x)
        Returns the complex power of this complex number raised to the power of x, with x interpreted as a real number. Implements the formula:

        \[ z^x = e^{x \ln(z)} \]

        If this complex number is zero then this method returns zero if x is positive; otherwise it returns NaN + iNaN.

        Parameters:
        x - The exponent to which this complex number is to be raised.
        Returns:
        This complex number raised to the power of x.
        See Also:
        log(), multiply(double), exp(), pow(Complex), Power
      • sqrt

        public Complex sqrt()
        Returns the square root of this complex number.

        \[ \sqrt{x + iy} = \frac{1}{2} \sqrt{2} \left( \sqrt{ \sqrt{x^2 + y^2} + x } + i\ \text{sgn}(y) \sqrt{ \sqrt{x^2 + y^2} - x } \right) \]

        The square root of \( z \) is in the range \( [0, +\infty) \) along the real axis and is unbounded along the imaginary axis. The imaginary part of the square root has a branch cut along the negative real axis \( (-infty,0) \). Special cases:

        • z.conj().sqrt() == z.sqrt().conj().
        • If z is ±0 + i0, returns +0 + i0.
        • If z is x + i∞ for all x (including NaN), returns +∞ + i∞.
        • If z is x + iNaN for finite x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is −∞ + iy for finite positive-signed y, returns +0 + i∞.
        • If z is +∞ + iy for finite positive-signed y, returns +∞ + i0.
        • If z is −∞ + iNaN, returns NaN ± i∞ (where the sign of the imaginary part of the result is unspecified).
        • If z is +∞ + iNaN, returns +∞ + iNaN.
        • If z is NaN + iy for finite y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + iNaN, returns NaN + iNaN.

        Implements the following algorithm to compute \( \sqrt{x + iy} \):

        1. Let \( t = \sqrt{2 (|x| + |x + iy|)} \)
        2. if \( x \geq 0 \) return \( \frac{t}{2} + i \frac{y}{t} \)
        3. else return \( \frac{|y|}{t} + i\ \text{sgn}(y) \frac{t}{2} \)
        where:
        • \( |x| =\ \)abs(x)
        • \( |x + y i| =\ \)abs()
        • \( \text{sgn}(y) =\ \)copySign(1.0, y)

        The implementation is overflow and underflow safe based on the method described in:

        T E Hull, Thomas F Fairgrieve and Ping Tak Peter Tang (1994) Implementing complex elementary functions using exception handling. ACM Transactions on Mathematical Software, Vol 20, No 2, pp 215-244.
        Returns:
        The square root of this complex number.
        See Also:
        Sqrt
      • sqrt

        private static Complex sqrt​(double real,
                                    double imaginary)
        Returns the square root of the complex number sqrt(x + i y).
        Parameters:
        real - Real component.
        imaginary - Imaginary component.
        Returns:
        The square root of the complex number.
      • sin

        public Complex sin()
        Returns the sine of this complex number.

        \[ \sin(z) = \frac{1}{2} i \left( e^{-iz} - e^{iz} \right) \]

        This is an odd function: \( \sin(z) = -\sin(-z) \). The sine is an entire function and requires no branch cuts.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \sin(x + iy) = \sin(x)\cosh(y) + i \cos(x)\sinh(y) \]

        As per the C99 standard this function is computed using the trigonomic identity:

        \[ \sin(z) = -i \sinh(iz) \]

        Returns:
        The sine of this complex number.
        See Also:
        Sin
      • cos

        public Complex cos()
        Returns the cosine of this complex number.

        \[ \cos(z) = \frac{1}{2} \left( e^{iz} + e^{-iz} \right) \]

        This is an even function: \( \cos(z) = \cos(-z) \). The cosine is an entire function and requires no branch cuts.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \cos(x + iy) = \cos(x)\cosh(y) - i \sin(x)\sinh(y) \]

        As per the C99 standard this function is computed using the trigonomic identity:

        \[ cos(z) = cosh(iz) \]

        Returns:
        The cosine of this complex number.
        See Also:
        Cos
      • tan

        public Complex tan()
        Returns the tangent of this complex number.

        \[ \tan(z) = \frac{i(e^{-iz} - e^{iz})}{e^{-iz} + e^{iz}} \]

        This is an odd function: \( \tan(z) = -\tan(-z) \). The tangent is an entire function and requires no branch cuts.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \tan(x + iy) = \frac{\sin(2x)}{\cos(2x)+\cosh(2y)} + i \frac{\sinh(2y)}{\cos(2x)+\cosh(2y)} \]

        As per the C99 standard this function is computed using the trigonomic identity:

        \[ \tan(z) = -i \tanh(iz) \]
        Returns:
        The tangent of this complex number.
        See Also:
        Tangent
      • asin

        public Complex asin()
        Returns the inverse sine of this complex number.

        \[ \sin^{-1}(z) = - i \left(\ln{iz + \sqrt{1 - z^2}}\right) \]

        The inverse sine of \( z \) is unbounded along the imaginary axis and in the range \( [-\pi, \pi] \) along the real axis. Special cases are handled as if the operation is implemented using \( \sin^{-1}(z) = -i \sinh^{-1}(iz) \).

        The inverse sine is a multivalued function and requires a branch cut in the complex plane; the cut is conventionally placed at the line segments \( (\infty,-1) \) and \( (1,\infty) \) of the real axis.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \begin{aligned} \sin^{-1}(z) &= \sin^{-1}(B) + i\ \text{sgn}(y)\ln \left(A + \sqrt{A^2-1} \right) \\ A &= \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} + \sqrt{(x-1)^2+y^2} \right] \\ B &= \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} - \sqrt{(x-1)^2+y^2} \right] \end{aligned} \]

        where \( \text{sgn}(y) \) is the sign function implemented using copySign(1.0, y).

        The implementation is based on the method described in:

        T E Hull, Thomas F Fairgrieve and Ping Tak Peter Tang (1997) Implementing the complex Arcsine and Arccosine Functions using Exception Handling. ACM Transactions on Mathematical Software, Vol 23, No 3, pp 299-335.

        The code has been adapted from the Boost c++ implementation <boost/math/complex/asin.hpp>.

        Returns:
        The inverse sine of this complex number.
        See Also:
        ArcSin
      • asin

        private static Complex asin​(double real,
                                    double imaginary,
                                    Complex.ComplexConstructor constructor)
        Returns the inverse sine of the complex number.

        This function exists to allow implementation of the identity asinh(z) = -i asin(iz).

        Adapted from <boost/math/complex/asin.hpp>. This method only (and not invoked methods within) is distributed under the Boost Software License V1.0. The original notice is shown below and the licence is shown in full in LICENSE:

         (C) Copyright John Maddock 2005.
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE or copy at https://www.boost.org/LICENSE_1_0.txt)
         
        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        constructor - Constructor.
        Returns:
        The inverse sine of this complex number.
      • acos

        public Complex acos()
        Returns the inverse cosine of this complex number.

        \[ \cos^{-1}(z) = \frac{\pi}{2} + i \left(\ln{iz + \sqrt{1 - z^2}}\right) \]

        The inverse cosine of \( z \) is in the range \( [0, \pi) \) along the real axis and unbounded along the imaginary axis. Special cases:

        • z.conj().acos() == z.acos().conj().
        • If z is ±0 + i0, returns π/2 − i0.
        • If z is ±0 + iNaN, returns π/2 + iNaN.
        • If z is x + i∞ for finite x, returns π/2 − i∞.
        • If z is x + iNaN, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is −∞ + iy for positive-signed finite y, returns π − i∞.
        • If z is +∞ + iy for positive-signed finite y, returns +0 − i∞.
        • If z is −∞ + i∞, returns 3π/4 − i∞.
        • If z is +∞ + i∞, returns π/4 − i∞.
        • If z is ±∞ + iNaN, returns NaN ± i∞ where the sign of the imaginary part of the result is unspecified.
        • If z is NaN + iy for finite y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + i∞, returns NaN − i∞.
        • If z is NaN + iNaN, returns NaN + iNaN.

        The inverse cosine is a multivalued function and requires a branch cut in the complex plane; the cut is conventionally placed at the line segments \( (-\infty,-1) \) and \( (1,\infty) \) of the real axis.

        This function is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \begin{aligned} \cos^{-1}(z) &= \cos^{-1}(B) - i\ \text{sgn}(y) \ln\left(A + \sqrt{A^2-1}\right) \\ A &= \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} + \sqrt{(x-1)^2+y^2} \right] \\ B &= \frac{1}{2} \left[ \sqrt{(x+1)^2+y^2} - \sqrt{(x-1)^2+y^2} \right] \end{aligned} \]

        where \( \text{sgn}(y) \) is the sign function implemented using copySign(1.0, y).

        The implementation is based on the method described in:

        T E Hull, Thomas F Fairgrieve and Ping Tak Peter Tang (1997) Implementing the complex Arcsine and Arccosine Functions using Exception Handling. ACM Transactions on Mathematical Software, Vol 23, No 3, pp 299-335.

        The code has been adapted from the Boost c++ implementation <boost/math/complex/acos.hpp>.

        Returns:
        The inverse cosine of this complex number.
        See Also:
        ArcCos
      • acos

        private static Complex acos​(double real,
                                    double imaginary,
                                    Complex.ComplexConstructor constructor)
        Returns the inverse cosine of the complex number.

        This function exists to allow implementation of the identity acosh(z) = +-i acos(z).

        Adapted from <boost/math/complex/acos.hpp>. This method only (and not invoked methods within) is distributed under the Boost Software License V1.0. The original notice is shown below and the licence is shown in full in LICENSE:

         (C) Copyright John Maddock 2005.
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE or copy at https://www.boost.org/LICENSE_1_0.txt)
         
        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        constructor - Constructor.
        Returns:
        The inverse cosine of the complex number.
      • atan

        public Complex atan()
        Returns the inverse tangent of this complex number.

        \[ \tan^{-1}(z) = \frac{i}{2} \ln \left( \frac{i + z}{i - z} \right) \]

        The inverse hyperbolic tangent of \( z \) is unbounded along the imaginary axis and in the range \( [-\pi/2, \pi/2] \) along the real axis.

        The inverse tangent is a multivalued function and requires a branch cut in the complex plane; the cut is conventionally placed at the line segments \( (i \infty,-i] \) and \( [i,i \infty) \) of the imaginary axis.

        As per the C99 standard this function is computed using the trigonomic identity: \[ \tan^{-1}(z) = -i \tanh^{-1}(iz) \]

        Returns:
        The inverse tangent of this complex number.
        See Also:
        ArcTan
      • sinh

        public Complex sinh()
        Returns the hyperbolic sine of this complex number.

        \[ \sinh(z) = \frac{1}{2} \left( e^{z} - e^{-z} \right) \]

        The hyperbolic sine of \( z \) is an entire function in the complex plane and is periodic with respect to the imaginary component with period \( 2\pi i \). Special cases:

        • z.conj().sinh() == z.sinh().conj().
        • This is an odd function: \( \sinh(z) = -\sinh(-z) \).
        • If z is +0 + i0, returns +0 + i0.
        • If z is +0 + i∞, returns ±0 + iNaN (where the sign of the real part of the result is unspecified; "invalid" floating-point operation).
        • If z is +0 + iNaN, returns ±0 + iNaN (where the sign of the real part of the result is unspecified).
        • If z is x + i∞ for positive finite x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is x + iNaN for finite nonzero x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is +∞ + i0, returns +∞ + i0.
        • If z is +∞ + iy for positive finite y, returns +∞ cis(y) (see ofCis(double).
        • If z is +∞ + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified; "invalid" floating-point operation).
        • If z is +∞ + iNaN, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
        • If z is NaN + i0, returns NaN + i0.
        • If z is NaN + iy for all nonzero numbers y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + iNaN, returns NaN + iNaN.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \sinh(x + iy) = \sinh(x)\cos(y) + i \cosh(x)\sin(y) \]

        Returns:
        The hyperbolic sine of this complex number.
        See Also:
        Sinh
      • sinh

        private static Complex sinh​(double real,
                                    double imaginary,
                                    Complex.ComplexConstructor constructor)
        Returns the hyperbolic sine of the complex number.

        This function exists to allow implementation of the identity sin(z) = -i sinh(iz).

        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        constructor - Constructor.
        Returns:
        The hyperbolic sine of the complex number.
      • cosh

        public Complex cosh()
        Returns the hyperbolic cosine of this complex number.

        \[ \cosh(z) = \frac{1}{2} \left( e^{z} + e^{-z} \right) \]

        The hyperbolic cosine of \( z \) is an entire function in the complex plane and is periodic with respect to the imaginary component with period \( 2\pi i \). Special cases:

        • z.conj().cosh() == z.cosh().conj().
        • This is an even function: \( \cosh(z) = \cosh(-z) \).
        • If z is +0 + i0, returns 1 + i0.
        • If z is +0 + i∞, returns NaN ± i0 (where the sign of the imaginary part of the result is unspecified; "invalid" floating-point operation).
        • If z is +0 + iNaN, returns NaN ± i0 (where the sign of the imaginary part of the result is unspecified).
        • If z is x + i∞ for finite nonzero x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is x + iNaN for finite nonzero x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is +∞ + i0, returns +∞ + i0.
        • If z is +∞ + iy for finite nonzero y, returns +∞ cis(y) (see ofCis(double)).
        • If z is +∞ + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
        • If z is +∞ + iNaN, returns +∞ + iNaN.
        • If z is NaN + i0, returns NaN ± i0 (where the sign of the imaginary part of the result is unspecified).
        • If z is NaN + iy for all nonzero numbers y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + iNaN, returns NaN + iNaN.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \cosh(x + iy) = \cosh(x)\cos(y) + i \sinh(x)\sin(y) \]

        Returns:
        The hyperbolic cosine of this complex number.
        See Also:
        Cosh
      • cosh

        private static Complex cosh​(double real,
                                    double imaginary,
                                    Complex.ComplexConstructor constructor)
        Returns the hyperbolic cosine of the complex number.

        This function exists to allow implementation of the identity cos(z) = cosh(iz).

        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        constructor - Constructor.
        Returns:
        The hyperbolic cosine of the complex number.
      • coshsinh

        private static Complex coshsinh​(double x,
                                        double real,
                                        double imaginary,
                                        boolean sinh,
                                        Complex.ComplexConstructor constructor)
        Compute cosh or sinh when the absolute real component |x| is large. In this case cosh(x) and sinh(x) can be approximated by exp(|x|) / 2:
         cosh(x+iy) real = (e^|x| / 2) * cos(y)
         cosh(x+iy) imag = (e^|x| / 2) * sin(y) * sign(x)
         sinh(x+iy) real = (e^|x| / 2) * cos(y) * sign(x)
         sinh(x+iy) imag = (e^|x| / 2) * sin(y)
         
        Parameters:
        x - Absolute real component |x|.
        real - Real part (x).
        imaginary - Imaginary part (y).
        sinh - Set to true to compute sinh, otherwise cosh.
        constructor - Constructor.
        Returns:
        The hyperbolic sine/cosine of the complex number.
      • tanh

        public Complex tanh()
        Returns the hyperbolic tangent of this complex number.

        \[ \tanh(z) = \frac{e^z - e^{-z}}{e^z + e^{-z}} \]

        The hyperbolic tangent of \( z \) is an entire function in the complex plane and is periodic with respect to the imaginary component with period \( \pi i \) and has poles of the first order along the imaginary line, at coordinates \( (0, \pi(\frac{1}{2} + n)) \). Note that the double floating-point representation is unable to exactly represent \( \pi/2 \) and there is no value for which a pole error occurs. Special cases:

        • z.conj().tanh() == z.tanh().conj().
        • This is an odd function: \( \tanh(z) = -\tanh(-z) \).
        • If z is +0 + i0, returns +0 + i0.
        • If z is 0 + i∞, returns 0 + iNaN.
        • If z is x + i∞ for finite non-zero x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is 0 + iNaN, returns 0 + iNAN.
        • If z is x + iNaN for finite non-zero x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is +∞ + iy for positive-signed finite y, returns 1 + i0 sin(2y).
        • If z is +∞ + i∞, returns 1 ± i0 (where the sign of the imaginary part of the result is unspecified).
        • If z is +∞ + iNaN, returns 1 ± i0 (where the sign of the imaginary part of the result is unspecified).
        • If z is NaN + i0, returns NaN + i0.
        • If z is NaN + iy for all nonzero numbers y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + iNaN, returns NaN + iNaN.

        Special cases include the technical corrigendum DR 471: Complex math functions cacosh and ctanh.

        This is defined using real \( x \) and imaginary \( y \) parts:

        \[ \tan(x + iy) = \frac{\sinh(2x)}{\cosh(2x)+\cos(2y)} + i \frac{\sin(2y)}{\cosh(2x)+\cos(2y)} \]

        The implementation uses double-angle identities to avoid overflow of 2x and 2y.

        Returns:
        The hyperbolic tangent of this complex number.
        See Also:
        Tanh
      • tanh

        private static Complex tanh​(double real,
                                    double imaginary,
                                    Complex.ComplexConstructor constructor)
        Returns the hyperbolic tangent of this complex number.

        This function exists to allow implementation of the identity tan(z) = -i tanh(iz).

        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        constructor - Constructor.
        Returns:
        The hyperbolic tangent of the complex number.
      • asinh

        public Complex asinh()
        Returns the inverse hyperbolic sine of this complex number.

        \[ \sinh^{-1}(z) = \ln \left(z + \sqrt{1 + z^2} \right) \]

        The inverse hyperbolic sine of \( z \) is unbounded along the real axis and in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:

        • z.conj().asinh() == z.asinh().conj().
        • This is an odd function: \( \sinh^{-1}(z) = -\sinh^{-1}(-z) \).
        • If z is +0 + i0, returns 0 + i0.
        • If z is x + i∞ for positive-signed finite x, returns +∞ + iπ/2.
        • If z is x + iNaN for finite x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is +∞ + iy for positive-signed finite y, returns +∞ + i0.
        • If z is +∞ + i∞, returns +∞ + iπ/4.
        • If z is +∞ + iNaN, returns +∞ + iNaN.
        • If z is NaN + i0, returns NaN + i0.
        • If z is NaN + iy for finite nonzero y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + i∞, returns ±∞ + iNaN (where the sign of the real part of the result is unspecified).
        • If z is NaN + iNaN, returns NaN + iNaN.

        The inverse hyperbolic sine is a multivalued function and requires a branch cut in the complex plane; the cut is conventionally placed at the line segments \( (-i \infty,-i) \) and \( (i,i \infty) \) of the imaginary axis.

        This function is computed using the trigonomic identity:

        \[ \sinh^{-1}(z) = -i \sin^{-1}(iz) \]

        Returns:
        The inverse hyperbolic sine of this complex number.
        See Also:
        ArcSinh
      • acosh

        public Complex acosh()
        Returns the inverse hyperbolic cosine of this complex number.

        \[ \cosh^{-1}(z) = \ln \left(z + \sqrt{z + 1} \sqrt{z - 1} \right) \]

        The inverse hyperbolic cosine of \( z \) is in the range \( [0, \infty) \) along the real axis and in the range \( [-\pi, \pi] \) along the imaginary axis. Special cases:

        • z.conj().acosh() == z.acosh().conj().
        • If z is ±0 + i0, returns +0 + iπ/2.
        • If z is x + i∞ for finite x, returns +∞ + iπ/2.
        • If z is 0 + iNaN, returns NaN + iπ/2 [1].
        • If z is x + iNaN for finite non-zero x, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is −∞ + iy for positive-signed finite y, returns +∞ + iπ.
        • If z is +∞ + iy for positive-signed finite y, returns +∞ + i0.
        • If z is −∞ + i∞, returns +∞ + i3π/4.
        • If z is +∞ + i∞, returns +∞ + iπ/4.
        • If z is ±∞ + iNaN, returns +∞ + iNaN.
        • If z is NaN + iy for finite y, returns NaN + iNaN ("invalid" floating-point operation).
        • If z is NaN + i∞, returns +∞ + iNaN.
        • If z is NaN + iNaN, returns NaN + iNaN.

        Special cases include the technical corrigendum DR 471: Complex math functions cacosh and ctanh.

        The inverse hyperbolic cosine is a multivalued function and requires a branch cut in the complex plane; the cut is conventionally placed at the line segment \( (-\infty,-1) \) of the real axis.

        This function is computed using the trigonomic identity:

        \[ \cosh^{-1}(z) = \pm i \cos^{-1}(z) \]

        The sign of the multiplier is chosen to give z.acosh().real() >= 0 and compatibility with the C99 standard.

        Returns:
        The inverse hyperbolic cosine of this complex number.
        See Also:
        ArcCosh
      • atanh

        public Complex atanh()
        Returns the inverse hyperbolic tangent of this complex number.

        \[ \tanh^{-1}(z) = \frac{1}{2} \ln \left( \frac{1 + z}{1 - z} \right) \]

        The inverse hyperbolic tangent of \( z \) is unbounded along the real axis and in the range \( [-\pi/2, \pi/2] \) along the imaginary axis. Special cases:

        • z.conj().atanh() == z.atanh().conj().
        • This is an odd function: \( \tanh^{-1}(z) = -\tanh^{-1}(-z) \).
        • If z is +0 + i0, returns +0 + i0.
        • If z is +0 + iNaN, returns +0 + iNaN.
        • If z is +1 + i0, returns +∞ + i0 ("divide-by-zero" floating-point operation).
        • If z is x + i∞ for finite positive-signed x, returns +0 + iπ/2.
        • If z is x+iNaN for nonzero finite x, returns NaN+iNaN ("invalid" floating-point operation).
        • If z is +∞ + iy for finite positive-signed y, returns +0 + iπ/2.
        • If z is +∞ + i∞, returns +0 + iπ/2.
        • If z is +∞ + iNaN, returns +0 + iNaN.
        • If z is NaN+iy for finite y, returns NaN+iNaN ("invalid" floating-point operation).
        • If z is NaN + i∞, returns ±0 + iπ/2 (where the sign of the real part of the result is unspecified).
        • If z is NaN + iNaN, returns NaN + iNaN.

        The inverse hyperbolic tangent is a multivalued function and requires a branch cut in the complex plane; the cut is conventionally placed at the line segments \( (\infty,-1] \) and \( [1,\infty) \) of the real axis.

        This is implemented using real \( x \) and imaginary \( y \) parts:

        \[ \tanh^{-1}(z) = \frac{1}{4} \ln \left(1 + \frac{4x}{(1-x)^2+y^2} \right) + \\ i \frac{1}{2} \left( \tan^{-1} \left(\frac{2y}{1-x^2-y^2} \right) + \frac{\pi}{2} \left(\text{sgn}(x^2+y^2-1)+1 \right) \text{sgn}(y) \right) \]

        The imaginary part is computed using Math.atan2(double, double) to ensure the correct quadrant is returned from \( \tan^{-1} \left(\frac{2y}{1-x^2-y^2} \right) \).

        The code has been adapted from the Boost c++ implementation <boost/math/complex/atanh.hpp>.

        Returns:
        The inverse hyperbolic tangent of this complex number.
        See Also:
        ArcTanh
      • atanh

        private static Complex atanh​(double real,
                                     double imaginary,
                                     Complex.ComplexConstructor constructor)
        Returns the inverse hyperbolic tangent of this complex number.

        This function exists to allow implementation of the identity atan(z) = -i atanh(iz).

        Adapted from <boost/math/complex/atanh.hpp>. This method only (and not invoked methods within) is distributed under the Boost Software License V1.0. The original notice is shown below and the licence is shown in full in LICENSE:

         (C) Copyright John Maddock 2005.
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE or copy at https://www.boost.org/LICENSE_1_0.txt)
         
        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        constructor - Constructor.
        Returns:
        The inverse hyperbolic tangent of the complex number.
      • x2y2m1

        private static double x2y2m1​(double x,
                                     double y)
        Compute x^2 + y^2 - 1 in high precision. Assumes that the values x and y can be multiplied without overflow; that x >= y; and both values are positive.
        Parameters:
        x - the x value
        y - the y value
        Returns:
        x^2 + y^2 - 1.
      • splitHigh

        private static double splitHigh​(double a)
        Implement Dekker's method to split a value into two parts. Multiplying by (2^s + 1) create a big value from which to derive the two split parts.
         c = (2^s + 1) * a
         a_big = c - a
         a_hi = c - a_big
         a_lo = a - a_hi
         a = a_hi + a_lo
         

        The multiplicand must be odd allowing a p-bit value to be split into (p-s)-bit value a_hi and a non-overlapping (s-1)-bit value a_lo. Combined they have (p􏰔-1) bits of significand but the sign bit of a_lo contains a bit of information.

        Parameters:
        a - Value.
        Returns:
        the high part of the value.
        See Also:
        Dekker (1971) A floating-point technique for extending the available precision
      • squareLow

        private static double squareLow​(double low,
                                        double high,
                                        double square)
        Compute the round-off from the square of a split number with low and high components. Uses Dekker's algorithm for split multiplication modified for a square product.

        Note: This is candidate to be replaced with Math.fma(x, x, -x * x) to compute the round-off from the square product x * x. This would remove the requirement to compute the split number and make this method redundant. Math.fma requires JDK 9 and FMA hardware support.

        Parameters:
        low - Low part of number.
        high - High part of number.
        square - Square of the number.
        Returns:
        low * low - (((product - high * high) - low * high) - high * low)
        See Also:
        Shewchuk (1997) Theorum 18
      • fastSumLow

        private static double fastSumLow​(double a,
                                         double b,
                                         double x)
        Compute the round-off from the sum of two numbers a and b using Dekker's two-sum algorithm. The values are required to be ordered by magnitude: |a| >= |b|.
        Parameters:
        a - First part of sum.
        b - Second part of sum.
        x - Sum.
        Returns:
        b - (x - a)
        See Also:
        Shewchuk (1997) Theorum 6
      • sumLow

        private static double sumLow​(double a,
                                     double b,
                                     double x)
        Compute the round-off from the sum of two numbers a and b using Knuth's two-sum algorithm. The values are not required to be ordered by magnitude.
        Parameters:
        a - First part of sum.
        b - Second part of sum.
        x - Sum.
        Returns:
        (a - (x - (x - a))) + (b - (x - a))
        See Also:
        Shewchuk (1997) Theorum 7
      • sumx2y2m1

        private static double sumx2y2m1​(double x2High,
                                        double x2Low,
                                        double y2High,
                                        double y2Low)
        Sum x^2 + y^2 - 1. It is assumed that y <= x < 1.

        Implement Shewchuk's expansion-sum algorithm: [x2Low, x2High] + [-1] + [y2Low, y2High].

        Parameters:
        x2High - High part of x^2.
        x2Low - Low part of x^2.
        y2High - High part of y^2.
        y2Low - Low part of y^2.
        Returns:
        x^2 + y^2 - 1
        See Also:
        Shewchuk (1997) Theorum 12
      • nthRoot

        public java.util.List<Complex> nthRoot​(int n)
        Returns the n-th roots of this complex number. The nth roots are defined by the formula:

        \[ z_k = |z|^{\frac{1}{n}} \left( \cos \left(\phi + \frac{2\pi k}{n} \right) + i \sin \left(\phi + \frac{2\pi k}{n} \right) \right) \]

        for \( k=0, 1, \ldots, n-1 \), where \( |z| \) and \( \phi \) are respectively the modulus and argument of this complex number.

        If one or both parts of this complex number is NaN, a list with all all elements set to NaN + i NaN is returned.

        Parameters:
        n - Degree of root.
        Returns:
        A list of all n-th roots of this complex number.
        Throws:
        java.lang.IllegalArgumentException - if n is zero.
        See Also:
        Root
      • equals

        public boolean equals​(java.lang.Object other)
        Test for equality with another object. If the other object is a Complex then a comparison is made of the real and imaginary parts; otherwise false is returned.

        If both the real and imaginary parts of two complex numbers are exactly the same the two Complex objects are considered to be equal. For this purpose, two double values are considered to be the same if and only if the method #doubleToLongBits(double) returns the identical long value when applied to each.

        Note that in most cases, for two instances of class Complex, c1 and c2, the value of c1.equals(c2) is true if and only if

          c1.getReal() == c2.getReal() && c1.getImaginary() == c2.getImaginary()

        also has the value true. However, there are exceptions:

        • Instances that contain NaN values in the same part are considered to be equal for that part, even though Double.NaN == Double.NaN has the value false.
        • Instances that share a NaN value in one part but have different values in the other part are not considered equal.
        • Instances that contain different representations of zero in the same part are not considered to be equal for that part, even though -0.0 == 0.0 has the value true.

        The behavior is the same as if the components of the two complex numbers were passed to Arrays.equals(double[], double[]):

          Arrays.equals(new double[]{c1.getReal(), c1.getImaginary()},
                        new double[]{c2.getReal(), c2.getImaginary()}); 
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - Object to test for equality with this instance.
        Returns:
        true if the objects are equal, false if object is null, not an instance of Complex, or not equal to this instance.
        See Also:
        Double.doubleToLongBits(double), Arrays.equals(double[], double[])
      • hashCode

        public int hashCode()
        Gets a hash code for the complex number.

        The behavior is the same as if the components of the complex number were passed to Arrays.hashCode(double[]):

          Arrays.hashCode(new double[] {getReal(), getImaginary()})
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code value for this object.
        See Also:
        Arrays.hashCode(double[])
      • toString

        public java.lang.String toString()
        Returns a string representation of the complex number.

        The string will represent the numeric values of the real and imaginary parts. The values are split by a separator and surrounded by parentheses. The string can be parsed to obtain an instance with the same value.

        The format for complex number \( x + i y \) is "(x,y)", with \( x \) and \( y \) converted as if using Double.toString(double).

        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of the complex number.
        See Also:
        parse(String), Double.toString(double)
      • equals

        private static boolean equals​(double x,
                                      double y)
        Returns true if the values are equal according to semantics of Double.equals(Object).
        Parameters:
        x - Value
        y - Value
        Returns:
        Double.valueof(x).equals(Double.valueOf(y)).
      • negative

        private static boolean negative​(double d)
        Check that a value is negative. It must meet all the following conditions:
        • it is not NaN,
        • it is negative signed,

        Note: This is true for negative zero.

        Parameters:
        d - Value.
        Returns:
        true if d is negative.
      • isPosInfinite

        private static boolean isPosInfinite​(double d)
        Check that a value is positive infinity. Used to replace Double.isInfinite() when the input value is known to be positive (i.e. in the case where it has been set using Math.abs(double)).
        Parameters:
        d - Value.
        Returns:
        true if d is +inf.
      • isPosFinite

        private static boolean isPosFinite​(double d)
        Check that an absolute value is finite. Used to replace Double.isFinite(double) when the input value is known to be positive (i.e. in the case where it has been set using Math.abs(double)).
        Parameters:
        d - Value.
        Returns:
        true if d is +finite.
      • multiplyNegativeI

        private static Complex multiplyNegativeI​(double real,
                                                 double imaginary)
        Create a complex number given the real and imaginary parts, then multiply by -i. This is used in functions that implement trigonomic identities. It is the functional equivalent of:
          z = new Complex(real, imaginary).multiplyImaginary(-1);
        Parameters:
        real - Real part.
        imaginary - Imaginary part.
        Returns:
        Complex object.
      • changeSign

        private static double changeSign​(double magnitude,
                                         double signedValue)
        Change the sign of the magnitude based on the signed value.

        If the signed value is negative then the result is -magnitude; otherwise return magnitude.

        A signed value of -0.0 is treated as negative. A signed value of NaN is treated as positive.

        This is not the same as Math.copySign(double, double) as this method will change the sign based on the signed value rather than copy the sign.

        Parameters:
        magnitude - the magnitude
        signedValue - the signed value
        Returns:
        magnitude or -magnitude.
        See Also:
        negative(double)
      • getScale

        private static int getScale​(double a,
                                    double b)
        Returns a scale suitable for use with Math.scalb(double, int) to normalise the number to the interval [1, 2).

        The scale is typically the largest unbiased exponent used in the representation of the two numbers. In contrast to Math.getExponent(double) this handles sub-normal numbers by computing the number of leading zeros in the mantissa and shifting the unbiased exponent. The result is that for all finite, non-zero, numbers a, b, the magnitude of scalb(x, -getScale(a, b)) is always in the range [1, 2), where x = max(|a|, |b|).

        This method is a functional equivalent of the c function ilogb(double) adapted for two input arguments.

        The result is to be used to scale a complex number using Math.scalb(double, int). Hence the special case of both zero arguments is handled using the return value for NaN as zero cannot be scaled. This is different from Math.getExponent(double) or getMaxExponent(double, double).

        Special cases:

        • If either argument is NaN or infinite, then the result is Double.MAX_EXPONENT + 1.
        • If both arguments are zero, then the result is Double.MAX_EXPONENT + 1.
        Parameters:
        a - the first value
        b - the second value
        Returns:
        The maximum unbiased exponent of the values to be used for scaling
        See Also:
        Math.getExponent(double), Math.scalb(double, int), ilogb
      • getMaxExponent

        private static int getMaxExponent​(double a,
                                          double b)
        Returns the largest unbiased exponent used in the representation of the two numbers. Special cases:
        • If either argument is NaN or infinite, then the result is Double.MAX_EXPONENT + 1.
        • If both arguments are zero or subnormal, then the result is Double.MIN_EXPONENT -1.

        This is used by divide(double, double, double, double) as a simple detection that a number may overflow if multiplied by a value in the interval [1, 2).

        Parameters:
        a - the first value
        b - the second value
        Returns:
        The maximum unbiased exponent of the values.
        See Also:
        Math.getExponent(double), divide(double, double, double, double)
      • inRegion

        private static boolean inRegion​(double x,
                                        double y,
                                        double min,
                                        double max)
        Checks if both x and y are in the region defined by the minimum and maximum.
        Parameters:
        x - x value.
        y - y value.
        min - the minimum (exclusive).
        max - the maximum (exclusive).
        Returns:
        true if inside the region.
      • hypot

        private static double hypot​(double x,
                                    double y)
        Returns sqrt(x^2 + y^2) without intermediate overflow or underflow.

        Special cases:

        • If either argument is infinite, then the result is positive infinity.
        • If either argument is NaN and neither argument is infinite, then the result is NaN.

        The computed result is expected to be within 1 ulp of the exact result.

        This method is a replacement for Math.hypot(double, double). There will be differences between this method and Math.hypot(double, double) due to the use of a different algorithm to compute the high precision sum of x^2 + y^2. This method has been tested to have a lower maximum error from the exact result; any differences are expected to be 1 ULP indicating a rounding change in the sum.

        JDK9 ported the hypot function to Java for bug JDK-7130085 due to the slow performance of the method as a native function. Benchmarks of the Complex class for functions that use hypot confirm this is slow pre-Java 9. This implementation outperforms the new faster Math.hypot(double, double) on JDK 11 (LTS). See the Commons numbers examples JMH module for benchmarks. Comparisons with alternative implementations indicate performance gains are related to edge case handling and elimination of an unpredictable branch in the computation of x^2 + y^2.

        This port was adapted from the "Freely Distributable Math Library" hypot function. This method only (and not invoked methods within) is distributed under the terms of the original notice as shown below:

         ====================================================
         Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
        
         Developed at SunSoft, a Sun Microsystems, Inc. business.
         Permission to use, copy, modify, and distribute this
         software is freely granted, provided that this notice
         is preserved.
         ====================================================
         

        Note: The fdlibm c code makes use of the language ability to read and write directly to the upper and lower 32-bits of the 64-double. The function performs checking on the upper 32-bits for the magnitude of the two numbers by accessing the exponent and 20 most significant bits of the mantissa. These upper bits are manipulated during scaling and then used to perform extended precision computation of the sum x^2 + y^2 where the high part of the number has 20-bit precision. Manipulation of direct bits has no equivalent in Java other than use of Double.doubleToLongBits(double) and Double.longBitsToDouble(long). To avoid conversion to and from long and double representations this implementation only scales the double representation. The high and low parts of a double for the extended precision computation are extracted using the method of Dekker (1971) to create two 26-bit numbers. This works for sub-normal numbers and reduces the maximum error in comparison to fdlibm hypot which does not use a split number algorithm for sub-normal numbers.

        Parameters:
        x - Value x
        y - Value y
        Returns:
        sqrt(x^2 + y^2)
        See Also:
        Math.hypot(double, double), fdlibm e_hypot.c, JDK-7130085 : Port fdlibm hypot to Java
      • x2y2

        private static double x2y2​(double x,
                                   double y)
        Return x^2 + y^2 with high accuracy.

        It is assumed that 2^500 > |x| >= |y| > 2^-500. Thus there will be no overflow or underflow of the result. The inputs are not assumed to be unsigned.

        The computation is performed using Dekker's method for extended precision multiplication of x and y and then summation of the extended precision squares.

        Parameters:
        x - Value x.
        y - Value y
        Returns:
        x^2 + y^2
        See Also:
        Dekker (1971) A floating-point technique for extending the available precision