Package org.apache.commons.numbers.complex

Class Complex

java.lang.Object
org.apache.commons.numbers.complex.Complex
All Implemented Interfaces:
java.io.Serializable
public final class Complex
extends java.lang.Object
implements java.io.Serializable
Representation of a Complex number, i.e. a number which has both a real and imaginary part.

Implementations of arithmetic operations handle NaN and infinite values according to the rules for Double, i.e. equals(java.lang.Object) is an equivalence relation for all instances that have a NaN in either real or imaginary part, e.g. the following are considered equal:

  • 1 + NaNi
  • NaN + i
  • NaN + NaNi

Note that this contradicts the IEEE-754 standard for floating point numbers (according to which the test x == x must fail if x is NaN). The method equals for primitive double in class Precision conforms with IEEE-754 while this class conforms with the standard behavior for Java object types.

See Also:
Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static Complex I
    The square root of -1, a.k.a.
    static Complex INF
    A complex number representing "+INF + INF i"
    static Complex ONE
    A complex number representing one.
    static Complex ZERO
    A complex number representing zero.

  • Method Summary

    Modifier and Type Method Description
    double abs()
    Return the absolute value of this complex number.
    Complex acos()
    Compute the inverse cosine of this complex number.
    Complex acosh()
    Compute 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).
    double arg()
    Compute the argument of this complex number.
    Complex asin()
    Compute the inverse sine of this complex number.
    Complex asinh()
    Compute the inverse hyperbolic sine of this complex number.
    Complex atan()
    Compute the inverse tangent of this complex number.
    Complex atanh()
    Compute the inverse hyperbolic tangent of this complex number.
    Complex conj()
    Returns the conjugate of this complex number.
    Complex conjugate()
    Returns the conjugate of this complex number.
    Complex cos()
    Compute the cosine of this complex number.
    Complex cosh()
    Compute the hyperbolic cosine of this complex number.
    Complex divide​(double divisor)
    Returns a Complex whose value is (this / divisor), with divisor interpreted as a real number.
    Complex divide​(Complex divisor)
    Returns a Complex whose value is (this / divisor).
    boolean equals​(java.lang.Object other)
    Test for equality with another object.
    static boolean equals​(Complex x, Complex y)
    Returns true iff the values are equal as defined by equals(x, y, 1).
    static boolean equals​(Complex x, Complex y, double eps)
    Returns true if, both for the real part and for the imaginary part, there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
    static boolean equals​(Complex x, Complex y, int maxUlps)
    Test for the floating-point equality between Complex objects.
    static boolean equalsWithRelativeTolerance​(Complex x, Complex y, double eps)
    Returns true if, both for the real part and for the imaginary part, there is no double value strictly between the arguments or the relative difference between them is smaller or equal to the given tolerance.
    Complex exp()
    Compute the exponential function of this complex number.
    double getArgument()
    Compute the argument of this complex number.
    double getImaginary()
    Access the imaginary part.
    double getReal()
    Access the real part.
    int hashCode()
    Get a hash code for the complex number.
    double imag()
    Access the imaginary part (C++ grammar)
    boolean isInfinite()
    Returns true if either real or imaginary component of the Complex is Infinite
    boolean isNaN()
    Returns true if either real or imaginary component of the Complex is NaN
    Complex log()
    Compute the natural logarithm of this complex number.
    Complex log10()
    Compute the base 10 or 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.
    Complex multiply​(int factor)
    Returns a Complex whose value is this * factor, with factor interpreted as a integer number.
    Complex multiply​(Complex factor)
    Returns a Complex whose value is this * factor.
    Complex negate()
    Returns a Complex whose value is (-this).
    java.util.List<Complex> nthRoot​(int n)
    Computes 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)
    For a real constructor argument x, returns a new Complex object c where c = cos(x) + i sin (x)
    static Complex ofPolar​(double r, double theta)
    Creates a Complex from its polar representation.
    static Complex ofReal​(double real)
    Create a complex number given the real part.
    static Complex parse​(java.lang.String s)
    Parses a string that would be produced by toString() and instantiates the corresponding object.
    Complex pow​(double x)
    Returns of value of this complex number raised to the power of x.
    Complex pow​(Complex x)
    Returns of value of this complex number raised to the power of x.
    Complex proj()
    Returns projection of this complex number onto the Riemann sphere, i.e.
    double real()
    Access the real part (C++ grammar)
    Complex reciprocal()
    Returns the multiplicative inverse of this instance.
    Complex sin()
    Compute the sine of this complex number.
    Complex sinh()
    Compute the hyperbolic sine of this complex number.
    Complex sqrt()
    Compute the square root of this complex number.
    Complex square()
    Compute the square of this complex number.
    Complex subtract​(double subtrahend)
    Returns a Complex whose value is (this - subtrahend).
    Complex subtract​(Complex subtrahend)
    Returns a Complex whose value is (this - subtrahend).
    Complex tan()
    Compute the tangent of this complex number.
    Complex tanh()
    Compute the hyperbolic tangent of this complex number.
    java.lang.String toString()

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • I

      public static final Complex I
      The square root of -1, a.k.a. "i".

    • INF

      public static final Complex INF
      A complex number representing "+INF + INF i"

    • ONE

      public static final Complex ONE
      A complex number representing one.

    • ZERO

      public static final Complex ZERO
      A complex number representing zero.

  • Method Details

    • 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 object

    • ofReal

      public static Complex ofReal​(double real)
      Create a complex number given the real part.
      Parameters:
      real - Real part.
      Returns:
      Complex object

    • ofPolar

      public static Complex ofPolar​(double r, double theta)
      Creates a Complex from its polar representation. If r is infinite and theta is finite, infinite or NaN values may be returned in parts of the result, following the rules for double arithmetic. 
       Examples:
 
 polar2Complex(INFINITY, \(\pi\)) = INFINITY + INFINITY i
 polar2Complex(INFINITY, 0) = INFINITY + NaN i
 polar2Complex(INFINITY, \(-\frac{\pi}{4}\)) = INFINITY - INFINITY i
 polar2Complex(INFINITY, \(5\frac{\pi}{4}\)) = -INFINITY - INFINITY i
      Parameters:
      r - the modulus of the complex number to create
      theta - the argument of the complex number to create
      Returns:
      Complex

    • ofCis

      public static Complex ofCis​(double x)
      For a real constructor argument x, returns a new Complex object c where c = cos(x) + i sin (x)
      Parameters:
      x - double to build the cis number
      Returns:
      Complex

    • parse

      public static Complex parse​(java.lang.String s)
      Parses a string that would be produced by toString() and instantiates the corresponding object.
      Parameters:
      s - String representation.
      Returns:
      an instance.
      Throws:
      java.lang.IllegalArgumentException - if the string does not conform to the specification.

    • isNaN

      public boolean isNaN()
      Returns true if either real or imaginary component of the Complex is NaN
      Returns:
      boolean

    • isInfinite

      public boolean isInfinite()
      Returns true if either real or imaginary component of the Complex is Infinite
      Returns:
      boolean

    • proj

      public Complex proj()
      Returns projection of this complex number onto the Riemann sphere, i.e. all infinities (including those with an NaN component) project onto real infinity, as described in the IEEE and ISO C standards.

      Returns:
      Complex projected onto the Riemann sphere.

    • abs

      public double abs()
      Return the absolute value of this complex number. This code follows the ISO C Standard, Annex G, in calculating the returned value (i.e. the hypot(x,y) method) and in handling of NaNs.
      Returns:
      the absolute value.

    • add

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

      (a + bi) + (c + di) = (a+c) + (b+d)i

      Parameters:
      addend - Value to be added to this Complex.
      Returns:
      this + addend.

    • add

      public Complex add​(double addend)
      Returns a Complex whose value is (this + addend), with addend interpreted as a real number.
      Parameters:
      addend - Value to be added to this Complex.
      Returns:
      this + addend.
      See Also:
      add(Complex)

    • conjugate

      public Complex conjugate()
      Returns the conjugate of this complex number. The conjugate of a + bi is a - bi.
      Returns:
      the conjugate of this complex object.

    • conj

      public Complex conj()
      Returns the conjugate of this complex number. C++11 grammar.
      Returns:
      the conjugate of this complex object.

    • divide

      public Complex divide​(Complex divisor)
      Returns a Complex whose value is (this / divisor). Implements the definitional formula 
        
    a + bi          ac + bd + (bc - ad)i
    ----------- = -------------------------
    c + di         c2 + d2
      Recalculates to recover infinities as specified in C.99 standard G.5.1. Method is fully in accordance with C++11 standards for complex numbers.
      Parameters:
      divisor - Value by which this Complex is to be divided.
      Returns:
      this / divisor.

    • divide

      public Complex divide​(double divisor)
      Returns a Complex whose value is (this / divisor), with divisor interpreted as a real number.
      Parameters:
      divisor - Value by which this Complex is to be divided.
      Returns:
      this / divisor.
      See Also:
      divide(Complex)

    • reciprocal

      public Complex reciprocal()
      Returns the multiplicative inverse of this instance.
      Returns:
      1 / this.
      See Also:
      divide(Complex)

    • equals

      public boolean equals​(java.lang.Object other)
      Test for equality with another object. If both the real and imaginary parts of two complex numbers are exactly the same, and neither is Double.NaN, the two Complex objects are considered to be equal. The behavior is the same as for JDK's Double:
      • All NaN values are considered to be equal, i.e, if either (or both) real and imaginary parts of the complex number are equal to Double.NaN, the complex number is equal to NaN.
      • Instances constructed with different representations of zero (i.e. either "0" or "-0") are not considered to be equal.
      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.

    • equals

      public static boolean equals​(Complex x, Complex y, int maxUlps)
      Test for the floating-point equality between Complex objects. It returns true if both arguments are equal or within the range of allowed error (inclusive).
      Parameters:
      x - First value (cannot be null).
      y - Second value (cannot be null).
      maxUlps - (maxUlps - 1) is the number of floating point values between the real (resp. imaginary) parts of x and y.
      Returns:
      true if there are fewer than maxUlps floating point values between the real (resp. imaginary) parts of x and y.
      See Also:
      Precision.equals(double,double,int)

    • equals

      public static boolean equals​(Complex x, Complex y)
      Returns true iff the values are equal as defined by equals(x, y, 1).
      Parameters:
      x - First value (cannot be null).
      y - Second value (cannot be null).
      Returns:
      true if the values are equal.

    • equals

      public static boolean equals​(Complex x, Complex y, double eps)
      Returns true if, both for the real part and for the imaginary part, there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive). Returns false if either of the arguments is NaN.
      Parameters:
      x - First value (cannot be null).
      y - Second value (cannot be null).
      eps - Amount of allowed absolute error.
      Returns:
      true if the values are two adjacent floating point numbers or they are within range of each other.
      See Also:
      Precision.equals(double,double,double)

    • equalsWithRelativeTolerance

      public static boolean equalsWithRelativeTolerance​(Complex x, Complex y, double eps)
      Returns true if, both for the real part and for the imaginary part, there is no double value strictly between the arguments or the relative difference between them is smaller or equal to the given tolerance. Returns false if either of the arguments is NaN.
      Parameters:
      x - First value (cannot be null).
      y - Second value (cannot be null).
      eps - Amount of allowed relative error.
      Returns:
      true if the values are two adjacent floating point numbers or they are within range of each other.
      See Also:
      Precision.equalsWithRelativeTolerance(double,double,double)

    • hashCode

      public int hashCode()
      Get a hash code for the complex number. Any Double.NaN value in real or imaginary part produces the same hash code 7.
      Overrides:
      hashCode in class java.lang.Object
      Returns:
      a hash code value for this object.

    • getImaginary

      public double getImaginary()
      Access the imaginary part.
      Returns:
      the imaginary part.

    • imag

      public double imag()
      Access the imaginary part (C++ grammar)
      Returns:
      the imaginary part.

    • getReal

      public double getReal()
      Access the real part.
      Returns:
      the real part.

    • real

      public double real()
      Access the real part (C++ grammar)
      Returns:
      the real part.

    • multiply

      public Complex multiply​(Complex factor)
      Returns a Complex whose value is this * factor. Implements the definitional formula: (a + bi)(c + di) = (ac - bd) + (ad + bc)i Recalculates to recover infinities as specified in C.99 standard G.5.1. Method is fully in accordance with C++11 standards for complex numbers.
      Parameters:
      factor - value to be multiplied by this Complex.
      Returns:
      this * factor.

    • multiply

      public Complex multiply​(int factor)
      Returns a Complex whose value is this * factor, with factor interpreted as a integer number.
      Parameters:
      factor - value to be multiplied by this Complex.
      Returns:
      this * factor.
      See Also:
      multiply(Complex)

    • multiply

      public Complex multiply​(double factor)
      Returns a Complex whose value is this * factor, with factor interpreted as a real number.
      Parameters:
      factor - value to be multiplied by this Complex.
      Returns:
      this * factor.
      See Also:
      multiply(Complex)

    • negate

      public Complex negate()
      Returns a Complex whose value is (-this).
      Returns:
      -this.

    • subtract

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

      (a + bi) - (c + di) = (a-c) + (b-d)i

      Parameters:
      subtrahend - value to be subtracted from this Complex.
      Returns:
      this - subtrahend.

    • subtract

      public Complex subtract​(double subtrahend)
      Returns a Complex whose value is (this - subtrahend).
      Parameters:
      subtrahend - value to be subtracted from this Complex.
      Returns:
      this - subtrahend.
      See Also:
      subtract(Complex)

    • acos

      public Complex acos()
      Compute the inverse cosine of this complex number. Implements the formula:

      acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))

      Returns:
      the inverse cosine of this complex number.

    • asin

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

      asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz))

      Returns:
      the inverse sine of this complex number

    • atan

      public Complex atan()
      Compute the inverse tangent of this complex number. Implements the formula:

      atan(z) = (i/2) log((i + z)/(i - z))

      Returns:
      the inverse tangent of this complex number

    • asinh

      public Complex asinh()
      Compute the inverse hyperbolic sine of this complex number. Implements the formula:

      asinh(z) = log(z+sqrt(z^2+1))

      Returns:
      the inverse hyperbolic cosine of this complex number

    • atanh

      public Complex atanh()
      Compute the inverse hyperbolic tangent of this complex number. Implements the formula:

      atanh(z) = log((1+z)/(1-z))/2

      Returns:
      the inverse hyperbolic cosine of this complex number

    • acosh

      public Complex acosh()
      Compute the inverse hyperbolic cosine of this complex number. Implements the formula:

      acosh(z) = log(z+sqrt(z^2-1))

      Returns:
      the inverse hyperbolic cosine of this complex number

    • square

      public Complex square()
      Compute the square of this complex number.
      Returns:
      square of this complex number

    • cos

      public Complex cos()
      Compute the cosine of this complex number. Implements the formula:

      cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i

      where the (real) functions on the right-hand side are Math.sin(double), Math.cos(double), Math.cosh(double) and Math.sinh(double).

      Returns:
      the cosine of this complex number.

    • cosh

      public Complex cosh()
      Compute the hyperbolic cosine of this complex number. Implements the formula: 
        
   cosh(a + bi) = cosh(a)cos(b) + sinh(a)sin(b)i
      where the (real) functions on the right-hand side are Math.sin(double), Math.cos(double), Math.cosh(double) and Math.sinh(double).

      Returns:
      the hyperbolic cosine of this complex number.

    • exp

      public Complex exp()
      Compute the exponential function of this complex number. Implements the formula: 
        
   exp(a + bi) = exp(a)cos(b) + exp(a)sin(b)i
      where the (real) functions on the right-hand side are Math.exp(double), Math.cos(double), and Math.sin(double).
      Returns:
      ethis.

    • log

      public Complex log()
      Compute the natural logarithm of this complex number. Implements the formula: 
        
   log(a + bi) = ln(|a + bi|) + arg(a + bi)i
      where ln on the right hand side is Math.log(double), |a + bi| is the modulus, abs(), and arg(a + bi) = Math.atan2(double, double)(b, a).
      Returns:
      the value ln   this, the natural logarithm of this.

    • log10

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

    • pow

      public Complex pow​(Complex x)
      Returns of value of this complex number raised to the power of x. Implements the formula: 
        
   yx = exp(x·log(y))
      where exp and log are exp() and log(), respectively.
      Parameters:
      x - exponent to which this Complex is to be raised.
      Returns:
      thisx.

    • pow

      public Complex pow​(double x)
      Returns of value of this complex number raised to the power of x.
      Parameters:
      x - exponent to which this Complex is to be raised.
      Returns:
      thisx.
      See Also:
      pow(Complex)

    • sin

      public Complex sin()
      Compute the sine of this complex number. Implements the formula: 
        
   sin(a + bi) = sin(a)cosh(b) - cos(a)sinh(b)i
      where the (real) functions on the right-hand side are Math.sin(double), Math.cos(double), Math.cosh(double) and Math.sinh(double).
      Returns:
      the sine of this complex number.

    • sinh

      public Complex sinh()
      Compute the hyperbolic sine of this complex number. Implements the formula: 
        
   sinh(a + bi) = sinh(a)cos(b)) + cosh(a)sin(b)i
      where the (real) functions on the right-hand side are Math.sin(double), Math.cos(double), Math.cosh(double) and Math.sinh(double).
      Returns:
      the hyperbolic sine of this.

    • sqrt

      public Complex sqrt()
      Compute the square root of this complex number. Implements the following algorithm to compute sqrt(a + bi):
      1. Let t = sqrt((|a| + |a + bi|) / 2)
      2. if  a &#8805; 0 return t + (b/2t)i
  else return |b|/2t + sign(b)t i
      where
      • |a| = Math.abs(int)(a)
      • |a + bi| = abs()(a + bi)
      • sign(b) = copySign(1d, b)
      Returns:
      the square root of this.

    • tan

      public Complex tan()
      Compute the tangent of this complex number. Implements the formula: 
        
   tan(a + bi) = sin(2a)/(cos(2a)+cosh(2b)) + [sinh(2b)/(cos(2a)+cosh(2b))]i
      where the (real) functions on the right-hand side are Math.sin(double), Math.cos(double), Math.cosh(double) and Math.sinh(double).
      Returns:
      the tangent of this.

    • tanh

      public Complex tanh()
      Compute the hyperbolic tangent of this complex number. Implements the formula: 
        
   tan(a + bi) = sinh(2a)/(cosh(2a)+cos(2b)) + [sin(2b)/(cosh(2a)+cos(2b))]i
      where the (real) functions on the right-hand side are Math.sin(double), Math.cos(double), Math.cosh(double) and Math.sinh(double).
      Returns:
      the hyperbolic tangent of this.

    • getArgument

      public double getArgument()
      Compute the argument of this complex number. The argument is the angle phi between the positive real axis and the point representing this number in the complex plane. The value returned is between -PI (not inclusive) and PI (inclusive), with negative values returned for numbers with negative imaginary parts.

      If either real or imaginary part (or both) is NaN, NaN is returned. Infinite parts are handled as Math.atan2 handles them, essentially treating finite parts as zero in the presence of an infinite coordinate and returning a multiple of pi/4 depending on the signs of the infinite parts. See the javadoc for Math.atan2 for full details.

      Returns:
      the argument of this.

    • arg

      public double arg()
      Compute the argument of this complex number. C++11 syntax
      Returns:
      the argument of this.

    • nthRoot

      public java.util.List<Complex> nthRoot​(int n)
      Computes the n-th roots of this complex number. The nth roots are defined by the formula: 
        
   zk = abs1/n (cos(phi + 2πk/n) + i (sin(phi + 2πk/n))
      for k=0, 1, ..., n-1, where abs 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 just one element, NaN + NaN i is returned. if neither part is NaN, but at least one part is infinite, the result is a one-element list containing INF.

      Parameters:
      n - Degree of root.
      Returns:
      a List of all n-th roots of this.

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object