org.apache.commons.math.complex

## Class Complex

- java.lang.Object
- - 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

Fields
`static Complex` `I` The square root of -1.
`private double` `imaginary` The imaginary part.
`static Complex` `INF` A complex number representing "+INF + INFi"
`private boolean` `isInfinite` Record whether this complex number is infinite.
`private boolean` `isNaN` Record whether this complex number is equal to NaN.
`static Complex` `NaN` A complex number representing "NaN + NaNi"
`static Complex` `ONE` A complex number representing "1.0 + 0.0i"
`private double` `real` The real part.
`private static long` `serialVersionUID` Serializable version identifier
`static Complex` `ZERO` A complex number representing "0.0 + 0.0i"

### Constructor Summary

Constructors
Constructor and Description
`Complex(double real, double imaginary)` Create a complex number given the real and imaginary parts.

### Method Summary

Methods
`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 - `this`2 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"

#### serialVersionUID

    private static final long serialVersionUID

Serializable version identifier

See Also:
  Constant Field Values

#### imaginary

    private final double imaginary

The imaginary part.

#### real

    private final double real

The real part.

#### isNaN

    private final transient boolean isNaN

Record whether this complex number is equal to NaN.

#### isInfinite

    private final transient boolean isInfinite

Record whether this complex number is infinite.

### 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:

- If either this or `rhs` has a NaN value in either part, `NaN` is returned.
- If `rhs` equals `ZERO`, `NaN` is returned.
- If this and `rhs` are both infinite, `NaN` is returned.
- If this is finite (i.e., has no infinite or NaN parts) and `rhs` is infinite (one or both parts infinite), `ZERO` is returned.
- If this is infinite and `rhs` is finite, NaN values are returned in the parts of the result if the `Double` rules applied to the definitional formula force NaN results.

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:
  e`this`
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:
  `this``x`
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

- `|a| = `Math.abs(int)`(a)`
- `|a + bi| = `abs()`(a + bi)`
- `sign(b) = `MathUtils.indicator(byte)`(b)`

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 - `this`2 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 - `this`2
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<Complex> 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