Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.math.complex
Class ComplexUtils

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

public class ComplexUtils
extends Object

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

Reference:

- Multiple Precision Complex Arithmetic and Functions

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: 349387 $ $Date: 2005-11-27 23:15:46 -0700 (Sun, 27 Nov 2005) $

Method Summary
`static Complex` | `acos(Complex z)` Compute the inverse cosine for the given complex argument.
`static Complex` | `asin(Complex z)` Compute the inverse sine for the given complex argument.
`static Complex` | `atan(Complex z)` Compute the inverse tangent for the given complex argument.
`static Complex` | `cos(Complex z)` Compute the cosine for the given complex argument.
`static Complex` | `cosh(Complex z)` Compute the hyperbolic cosine for the given complex argument.
`static Complex` | `exp(Complex z)` Compute the exponential function for the given complex argument.
`static Complex` | `log(Complex z)` Compute the natural logarithm for the given complex argument.
`static Complex` | `polar2Complex(double r, double theta)` Creates a complex number from the given polar representation.
`static Complex` | `pow(Complex y, Complex x)` Returns of value of `y` raised to the power of `x`.
`static Complex` | `sin(Complex z)` Compute the sine for the given complex argument.
`static Complex` | `sinh(Complex z)` Compute the hyperbolic sine for the given complex argument.
`static Complex` | `sqrt(Complex z)` Compute the square root for the given complex argument.
`static Complex` | `sqrt1z(Complex z)` Compute the square root of 1 - `z`2 for the given complex argument.
`static Complex` | `tan(Complex z)` Compute the tangent for the given complex argument.
`static Complex` | `tanh(Complex z)` Compute the hyperbolic tangent for the given complex argument.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### acos

    public static Complex acos(Complex z)

  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:
    `NullPointerException` - if `z` is null

### asin

    public static Complex asin(Complex z)

  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:
    `NullPointerException` - if `z` is null

### atan

    public static Complex atan(Complex z)

  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:
    `NullPointerException` - if `z` is null

### cos

    public static Complex cos(Complex z)

  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:
    `NullPointerException` - if `z` is null

### cosh

    public static Complex cosh(Complex z)

  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)

  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:
    e`z`

### log

    public static Complex log(Complex z)

  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:
    `IllegalArgumentException` - if r is negative
  Since:
    1.1

### pow

    public static Complex pow(Complex y,
                              Complex 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:
    `y``x`
  Throws:
    `NullPointerException` - if either x or y is null

### sin

    public static Complex sin(Complex z)

  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)

  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:
    `NullPointerException` - if `z` is null

### sqrt

    public static Complex sqrt(Complex z)

  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
  - `|a| = `Math.abs(double)`(a)`
  - `|a + bi| = `Complex.abs()`(a + bi)`
  - `sign(b) = `MathUtils.indicator(byte)`(b)`

  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:
    `NullPointerException` - if `z` is null

### sqrt1z

    public static Complex sqrt1z(Complex z)

  Compute the square root of 1 - `z`2 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 - `z`2
  Throws:
    `NullPointerException` - if `z` is null

### tan

    public static Complex tan(Complex z)

  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(±&pi/2 + 0 i) = ±INFINITY + NaN i

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

### tanh

    public static Complex tanh(Complex z)

  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 + (&pi/2)i) = NaN + INFINITY i

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2005 The Apache Software Foundation. All Rights Reserved.