org.apache.commons.math.complex
Class ComplexUtils

java.lang.Object
  extended by org.apache.commons.math.complex.ComplexUtils

public class ComplexUtils
extends java.lang.Object

Static implementations of common Complex-valued functions. Included are trigonometric, exponential, log, power and square root functions.

Reference:

See individual method javadocs for the computational formulas used. In general, NaN values in either real or imaginary parts of input arguments result in Complex.NaN returned. Otherwise, infinite or NaN values are returned as they arise in computing the real functions specified in the computational formulas. Null arguments result in NullPointerExceptions.

Version:
$Revision: 615734 $ $Date: 2008-01-27 23:10:03 -0700 (Sun, 27 Jan 2008) $

Constructor Summary
private ComplexUtils()
          Default constructor.
 
Method Summary
static Complex acos(Complex z)
          Deprecated. use Complex.acos()
static Complex asin(Complex z)
          Deprecated. use Complex.asin()
static Complex atan(Complex z)
          Deprecated. use Complex.atan()
static Complex cos(Complex z)
          Deprecated. use Complex.cos()
static Complex cosh(Complex z)
          Deprecated. use Complex.cosh()
static Complex exp(Complex z)
          Deprecated. use Complex.exp()
static Complex log(Complex z)
          Deprecated. use Complex.log()
static Complex polar2Complex(double r, double theta)
          Creates a complex number from the given polar representation.
static Complex pow(Complex y, Complex x)
          Deprecated. use Complex.pow(x)
static Complex sin(Complex z)
          Deprecated. use Complex.sin()
static Complex sinh(Complex z)
          Deprecated. use Complex.sinh()
static Complex sqrt(Complex z)
          Deprecated. use Complex.sqrt()
static Complex sqrt1z(Complex z)
          Deprecated. use Complex.sqrt1z()
static Complex tan(Complex z)
          Deprecated. use Complex.tan()
static Complex tanh(Complex z)
          Deprecated. use Complex.tanh()
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ComplexUtils

private ComplexUtils()
Default constructor.

Method Detail

acos

public static Complex acos(Complex z)
Deprecated. use Complex.acos()

Compute the inverse cosine for the given complex argument.

Implements the formula:

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

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

Parameters:
z - the value whose inverse cosine is to be returned
Returns:
the inverse cosine of z
Throws:
java.lang.NullPointerException - if z is null

asin

public static Complex asin(Complex z)
Deprecated. use Complex.asin()

Compute the inverse sine for the given complex argument.

Implements the formula:

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

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

Parameters:
z - the value whose inverse sine is to be returned.
Returns:
the inverse sine of z.
Throws:
java.lang.NullPointerException - if z is null

atan

public static Complex atan(Complex z)
Deprecated. use Complex.atan()

Compute the inverse tangent for the given complex argument.

Implements the formula:

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

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

Parameters:
z - the value whose inverse tangent is to be returned
Returns:
the inverse tangent of z
Throws:
java.lang.NullPointerException - if z is null

cos

public static Complex cos(Complex z)
Deprecated. use Complex.cos()

Compute the cosine for the given complex argument.

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

Parameters:
z - the value whose cosine is to be returned
Returns:
the cosine of z
Throws:
java.lang.NullPointerException - if z is null

cosh

public static Complex cosh(Complex z)
Deprecated. use Complex.cosh()

Compute the hyperbolic cosine for the given complex argument.

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

Throws NullPointerException if z is null.

Parameters:
z - the value whose hyperbolic cosine is to be returned.
Returns:
the hyperbolic cosine of z.

exp

public static Complex exp(Complex z)
Deprecated. use Complex.exp()

Compute the exponential function for the given complex argument.

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

Throws NullPointerException if z is null.

Parameters:
z - the value
Returns:
ez

log

public static Complex log(Complex z)
Deprecated. use Complex.log()

Compute the natural logarithm for the given complex argument.

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, Complex.abs(), and arg(a + bi) = Math.atan2(double, double)(b, a)

Returns Complex.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
 
Throws NullPointerException if z is null.

Parameters:
z - the value.
Returns:
ln z.

polar2Complex

public static Complex polar2Complex(double r,
                                    double theta)
Creates a complex number from the given polar representation.

The value returned is r·ei·theta, computed as r·cos(theta) + r·sin(theta)i

If either r or theta is NaN, or theta is infinite, Complex.NaN is returned.

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, π/4) = INFINITY + INFINITY i
 polar2Complex(INFINITY, 0) = INFINITY + NaN i
 polar2Complex(INFINITY, -π/4) = INFINITY - INFINITY i
 polar2Complex(INFINITY, 5π/4) = -INFINITY - INFINITY i 

Parameters:
r - the modulus of the complex number to create
theta - the argument of the complex number to create
Returns:
r·ei·theta
Throws:
java.lang.IllegalArgumentException - if r is negative
Since:
1.1

pow

public static Complex pow(Complex y,
                          Complex x)
Deprecated. use Complex.pow(x)

Returns of value of y raised to the power of x.

Implements the formula:

  yx = exp(x·log(y))
where exp and log are exp(org.apache.commons.math.complex.Complex) and log(org.apache.commons.math.complex.Complex), respectively.

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

Parameters:
y - the base.
x - the exponent.
Returns:
yx
Throws:
java.lang.NullPointerException - if either x or y is null

sin

public static Complex sin(Complex z)
Deprecated. use Complex.sin()

Compute the sine for the given complex argument.

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 Complex.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
Throws NullPointerException if z is null.

Parameters:
z - the value whose sine is to be returned.
Returns:
the sine of z.

sinh

public static Complex sinh(Complex z)
Deprecated. use Complex.sinh()

Compute the hyperbolic sine for the given complex argument.

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 Complex.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
Parameters:
z - the value whose hyperbolic sine is to be returned
Returns:
the hyperbolic sine of z
Throws:
java.lang.NullPointerException - if z is null

sqrt

public static Complex sqrt(Complex z)
Deprecated. use Complex.sqrt()

Compute the square root for the given complex argument.

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

Parameters:
z - the value whose square root is to be returned
Returns:
the square root of z
Throws:
java.lang.NullPointerException - if z is null

sqrt1z

public static Complex sqrt1z(Complex z)
Deprecated. use Complex.sqrt1z()

Compute the square root of 1 - z2 for the given complex argument.

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

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

Parameters:
z - the value
Returns:
the square root of 1 - z2
Throws:
java.lang.NullPointerException - if z is null

tan

public static Complex tan(Complex z)
Deprecated. use Complex.tan()

Compute the tangent for the given complex argument.

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

Parameters:
z - the value whose tangent is to be returned
Returns:
the tangent of z
Throws:
java.lang.NullPointerException - if z is null

tanh

public static Complex tanh(Complex z)
Deprecated. use Complex.tanh()

Compute the hyperbolic tangent for the given complex argument.

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

Parameters:
z - the value whose hyperbolic tangent is to be returned
Returns:
the hyperbolic tangent of z
Throws:
java.lang.NullPointerException - if z is null