org.apache.commons.math.complex
Class Complex

java.lang.Object
  extended by org.apache.commons.math.complex.Complex
All Implemented Interfaces:
Serializable, FieldElement<Complex>

public class Complex
extends Object
implements FieldElement<Complex>, Serializable

Representation of a Complex number - 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 arithmetic, applying definitional formulas and returning NaN or infinite values in real or imaginary parts as these arise in computation. See individual method javadocs for details.

equals(java.lang.Object) identifies all values with NaN in either real or imaginary part - e.g.,

 1 + NaNi  == NaN + i == NaN + NaNi.

implements Serializable since 2.0

Version:
$Revision: 990655 $ $Date: 2010-08-29 23:49:40 +0200 (dim. 29 août 2010) $
See Also:
Serialized Form

Field Summary
static Complex I
          The square root of -1.
static Complex INF
          A complex number representing "+INF + INFi"
static Complex NaN
          A complex number representing "NaN + NaNi"
static Complex ONE
          A complex number representing "1.0 + 0.0i"
static Complex ZERO
          A complex number representing "0.0 + 0.0i"
 
Constructor Summary
Complex(double real, double imaginary)
          Create a complex number given the real and imaginary parts.
 
Method Summary
 double abs()
          Return the absolute value of this complex number.
 Complex acos()
          Compute the inverse cosine of this complex number.
 Complex add(Complex rhs)
          Return the sum of this complex number and the given complex number.
 Complex asin()
          Compute the inverse sine of this complex number.
 Complex atan()
          Compute the inverse tangent of this complex number.
 Complex conjugate()
          Return 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.
protected  Complex createComplex(double realPart, double imaginaryPart)
          Create a complex number given the real and imaginary parts.
 Complex divide(Complex rhs)
          Return the quotient of this complex number and the given complex number.
 boolean equals(Object other)
          Test for the equality of two Complex objects.
 Complex exp()
          Compute the exponential function of this complex number.
 double getArgument()
          Compute the argument of this complex number.
 ComplexField getField()
          Get the Field to which the instance belongs.
 double getImaginary()
          Access the imaginary part.
 double getReal()
          Access the real part.
 int hashCode()
          Get a hashCode for the complex number.
 boolean isInfinite()
          Returns true if either the real or imaginary part of this complex number takes an infinite value (either Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY) and neither part is NaN.
 boolean isNaN()
          Returns true if either or both parts of this complex number is NaN; false otherwise
 Complex log()
          Compute the natural logarithm of this complex number.
 Complex multiply(Complex rhs)
          Return the product of this complex number and the given complex number.
 Complex multiply(double rhs)
          Return the product of this complex number and the given scalar number.
 Complex negate()
          Return the additive inverse of this complex number.
 List<Complex> nthRoot(int n)
          Computes the n-th roots of this complex number.
 Complex pow(Complex x)
          Returns of value of this complex number raised to the power of x.
protected  Object readResolve()
          Resolve the transient fields in a deserialized Complex Object.
 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 sqrt1z()
          Compute the square root of 1 - this2 for this complex number.
 Complex subtract(Complex rhs)
          Return the difference between this complex number and the given complex number.
 Complex tan()
          Compute the tangent of this complex number.
 Complex tanh()
          Compute the hyperbolic tangent of this complex number.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

I

public static final Complex I
The square root of -1. A number representing "0.0 + 1.0i"


NaN

public static final Complex NaN
A complex number representing "NaN + NaNi"


INF

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


ONE

public static final Complex ONE
A complex number representing "1.0 + 0.0i"


ZERO

public static final Complex ZERO
A complex number representing "0.0 + 0.0i"

Constructor Detail

Complex

public Complex(double real,
               double imaginary)
Create a complex number given the real and imaginary parts.

Parameters:
real - the real part
imaginary - the imaginary part
Method Detail

abs

public double abs()
Return the absolute value of this complex number.

Returns NaN if either real or imaginary part is NaN and Double.POSITIVE_INFINITY if neither part is NaN, but at least one part takes an infinite value.

Returns:
the absolute value

add

public Complex add(Complex rhs)
Return the sum of this complex number and the given complex number.

Uses the definitional formula

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

If either this or rhs has a NaN value in either part, NaN is returned; otherwise Inifinite and NaN values are returned in the parts of the result according to the rules for Double arithmetic.

Specified by:
add in interface FieldElement<Complex>
Parameters:
rhs - the other complex number
Returns:
the complex number sum
Throws:
NullPointerException - if rhs is null

conjugate

public Complex conjugate()
Return the conjugate of this complex number. The conjugate of "A + Bi" is "A - Bi".

NaN is returned if either the real or imaginary part of this Complex number equals Double.NaN.

If the imaginary part is infinite, and the real part is not NaN, the returned value has infinite imaginary part of the opposite sign - e.g. the conjugate of 1 + POSITIVE_INFINITY i is 1 - NEGATIVE_INFINITY i

Returns:
the conjugate of this Complex object

divide

public Complex divide(Complex rhs)
Return the quotient of this complex number and the given complex number.

Implements the definitional formula


    a + bi          ac + bd + (bc - ad)i
    ----------- = -------------------------
    c + di         c2 + d2
 
but uses prescaling of operands to limit the effects of overflows and underflows in the computation.

Infinite and NaN values are handled / returned according to the following rules, applied in the order presented:

Specified by:
divide in interface FieldElement<Complex>
Parameters:
rhs - the other complex number
Returns:
the complex number quotient
Throws:
NullPointerException - if rhs is null

equals

public boolean equals(Object other)
Test for the equality of two Complex objects.

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.

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 Complex.NaN.

Overrides:
equals in class Object
Parameters:
other - Object to test for equality to this
Returns:
true if two Complex objects are equal, false if object is null, not an instance of Complex, or not equal to this Complex instance

hashCode

public int hashCode()
Get a hashCode for the complex number.

All NaN values have the same hash code.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object

getImaginary

public double getImaginary()
Access the imaginary part.

Returns:
the imaginary part

getReal

public double getReal()
Access the real part.

Returns:
the real part

isNaN

public boolean isNaN()
Returns true if either or both parts of this complex number is NaN; false otherwise

Returns:
true if either or both parts of this complex number is NaN; false otherwise

isInfinite

public boolean isInfinite()
Returns true if either the real or imaginary part of this complex number takes an infinite value (either Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY) and neither part is NaN.

Returns:
true if one or both parts of this complex number are infinite and neither part is NaN

multiply

public Complex multiply(Complex rhs)
Return the product of this complex number and the given complex number.

Implements preliminary checks for NaN and infinity followed by the definitional formula:


 (a + bi)(c + di) = (ac - bd) + (ad + bc)i
 

Returns NaN if either this or rhs has one or more NaN parts.

Returns INF if neither this nor rhs has one or more NaN parts and if either this or rhs has one or more infinite parts (same result is returned regardless of the sign of the components).

Returns finite values in components of the result per the definitional formula in all remaining cases.

Specified by:
multiply in interface FieldElement<Complex>
Parameters:
rhs - the other complex number
Returns:
the complex number product
Throws:
NullPointerException - if rhs is null

multiply

public Complex multiply(double rhs)
Return the product of this complex number and the given scalar number.

Implements preliminary checks for NaN and infinity followed by the definitional formula:


 c(a + bi) = (ca) + (cb)i
 

Returns NaN if either this or rhs has one or more NaN parts.

Returns INF if neither this nor rhs has one or more NaN parts and if either this or rhs has one or more infinite parts (same result is returned regardless of the sign of the components).

Returns finite values in components of the result per the definitional formula in all remaining cases.

Parameters:
rhs - the scalar number
Returns:
the complex number product

negate

public Complex negate()
Return the additive inverse of this complex number.

Returns Complex.NaN if either real or imaginary part of this Complex number equals Double.NaN.

Returns:
the negation of this complex number

subtract

public Complex subtract(Complex rhs)
Return the difference between this complex number and the given complex number.

Uses the definitional formula

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

If either this or rhs has a NaN value in either part, NaN is returned; otherwise inifinite and NaN values are returned in the parts of the result according to the rules for Double arithmetic.

Specified by:
subtract in interface FieldElement<Complex>
Parameters:
rhs - the other complex number
Returns:
the complex number difference
Throws:
NullPointerException - if rhs is null

acos

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

Implements the formula:

  acos(z) = -i (log(z + i (sqrt(1 - z2))))

Returns NaN if either real or imaginary part of the input argument is NaN or infinite.

Returns:
the inverse cosine of this complex number
Since:
1.2

asin

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

Implements the formula:

  asin(z) = -i (log(sqrt(1 - z2) + iz)) 

Returns NaN if either real or imaginary part of the input argument is NaN or infinite.

Returns:
the inverse sine of this complex number.
Since:
1.2

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 NaN if either real or imaginary part of the input argument is NaN or infinite.

Returns:
the inverse tangent of this complex number
Since:
1.2

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), MathUtils.cosh(double) and MathUtils.sinh(double).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 cos(1 ± INFINITY i) = 1 ∓ INFINITY i
 cos(±INFINITY + i) = NaN + NaN i
 cos(±INFINITY ± INFINITY i) = NaN + NaN i

Returns:
the cosine of this complex number
Since:
1.2

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), MathUtils.cosh(double) and MathUtils.sinh(double).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 cosh(1 ± INFINITY i) = NaN + NaN i
 cosh(±INFINITY + i) = INFINITY ± INFINITY i
 cosh(±INFINITY ± INFINITY i) = NaN + NaN i

Returns:
the hyperbolic cosine of this complex number.
Since:
1.2

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 NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 exp(1 ± INFINITY i) = NaN + NaN i
 exp(INFINITY + i) = INFINITY + INFINITY i
 exp(-INFINITY + i) = 0 + 0i
 exp(±INFINITY ± INFINITY i) = NaN + NaN i

Returns:
ethis
Since:
1.2

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 NaN if either real or imaginary part of the input argument is NaN.

Infinite (or critical) values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 log(1 ± INFINITY i) = INFINITY ± (π/2)i
 log(INFINITY + i) = INFINITY + 0i
 log(-INFINITY + i) = INFINITY + πi
 log(INFINITY ± INFINITY i) = INFINITY ± (π/4)i
 log(-INFINITY ± INFINITY i) = INFINITY ± (3π/4)i
 log(0 + 0i) = -INFINITY + 0i
 

Returns:
ln of this complex number.
Since:
1.2

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.

Returns NaN if either real or imaginary part of the input argument is NaN or infinite, or if y equals ZERO.

Parameters:
x - the exponent.
Returns:
thisx
Throws:
NullPointerException - if x is null
Since:
1.2

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), MathUtils.cosh(double) and MathUtils.sinh(double).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 sin(1 ± INFINITY i) = 1 ± INFINITY i
 sin(±INFINITY + i) = NaN + NaN i
 sin(±INFINITY ± INFINITY i) = NaN + NaN i

Returns:
the sine of this complex number.
Since:
1.2

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), MathUtils.cosh(double) and MathUtils.sinh(double).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 sinh(1 ± INFINITY i) = NaN + NaN i
 sinh(±INFINITY + i) = ± INFINITY + INFINITY i
 sinh(±INFINITY ± INFINITY i) = NaN + NaN i

Returns:
the hyperbolic sine of this complex number
Since:
1.2

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 ≥ 0 return t + (b/2t)i
      else return |b|/2t + sign(b)t i 
where

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 sqrt(1 ± INFINITY i) = INFINITY + NaN i
 sqrt(INFINITY + i) = INFINITY + 0i
 sqrt(-INFINITY + i) = 0 + INFINITY i
 sqrt(INFINITY ± INFINITY i) = INFINITY + NaN i
 sqrt(-INFINITY ± INFINITY i) = NaN ± INFINITY i
 

Returns:
the square root of this complex number
Since:
1.2

sqrt1z

public Complex sqrt1z()
Compute the square root of 1 - this2 for this complex number.

Computes the result directly as sqrt(Complex.ONE.subtract(z.multiply(z))).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

Returns:
the square root of 1 - this2
Since:
1.2

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), MathUtils.cosh(double) and MathUtils.sinh(double).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite (or critical) values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 tan(1 ± INFINITY i) = 0 + NaN i
 tan(±INFINITY + i) = NaN + NaN i
 tan(±INFINITY ± INFINITY i) = NaN + NaN i
 tan(±π/2 + 0 i) = ±INFINITY + NaN i

Returns:
the tangent of this complex number
Since:
1.2

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), MathUtils.cosh(double) and MathUtils.sinh(double).

Returns NaN if either real or imaginary part of the input argument is NaN.

Infinite values in real or imaginary parts of the input may result in infinite or NaN values returned in parts of the result.

 Examples:
 
 tanh(1 ± INFINITY i) = NaN + NaN i
 tanh(±INFINITY + i) = NaN + 0 i
 tanh(±INFINITY ± INFINITY i) = NaN + NaN i
 tanh(0 + (π/2)i) = NaN + INFINITY i

Returns:
the hyperbolic tangent of this complex number
Since:
1.2

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 java.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 java.Math.atan2 for full details.

Returns:
the argument of this complex number

nthRoot

public List<Complex> nthRoot(int n)
                      throws IllegalArgumentException

Computes the n-th roots of this complex number.

The nth roots are defined by the formula:

  zk = abs 1/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 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:
List all nth roots of this complex number
Throws:
IllegalArgumentException - if parameter n is less than or equal to 0
Since:
2.0

createComplex

protected Complex createComplex(double realPart,
                                double imaginaryPart)
Create a complex number given the real and imaginary parts.

Parameters:
realPart - the real part
imaginaryPart - the imaginary part
Returns:
a new complex number instance
Since:
1.2

readResolve

protected final Object readResolve()

Resolve the transient fields in a deserialized Complex Object.

Subclasses will need to override createComplex(double, double) to deserialize properly

Returns:
A Complex instance with all fields resolved.
Since:
2.0

getField

public ComplexField getField()
Get the Field to which the instance belongs.

Specified by:
getField in interface FieldElement<Complex>
Returns:
Field to which the instance belongs


Copyright © 2003-2011 Apache Software Foundation. All Rights Reserved.