Complex (parent patrimoine de base SIRIUS 3.4 API)

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.math3.complex
Class Complex

java.lang.Object
  org.apache.commons.math3.complex.Complex

All Implemented Interfaces:: Serializable, FieldElement<Complex>

public class Complex
extends Object
implements FieldElement<Complex>, Serializable
extends Object
implements FieldElement<Complex>, 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 is in contradiction with 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 Precision conforms with IEEE-754 while this class conforms with the standard behavior for Java object types.
Implements Serializable since 2.0

Version:: $Id: Complex.java 7721 2013-02-14 14:07:13Z CardosoP $
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)` Create a complex number given only the real part.
`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 addend)` Returns a `Complex` whose value is `(this + addend)`.
`Complex`	`add(double addend)` Returns a `Complex` whose value is `(this + addend)`, with `addend` interpreted as a real 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 divisor)` Returns a `Complex` whose value is `(this / divisor)`.
`Complex`	`divide(double divisor)` Returns a `Complex` whose value is `(this / divisor)`, with `divisor` interpreted as a real 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()` Checks whether 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()` Checks whether either or both parts of this complex number is `NaN`.
`Complex`	`log()` Compute the natural logarithm of this complex number.
`Complex`	`multiply(Complex factor)` Returns a `Complex` whose value is `this * factor`.
`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`	`negate()` Returns a `Complex` whose value is `(-this)`.
`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`.
`Complex`	`pow(double 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`	`reciprocal()` Returns the multiplicative inverse of `this` element.
`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²` for this complex number.
`Complex`	`subtract(Complex subtrahend)` Returns a `Complex` whose value is `(this - subtrahend)`.
`Complex`	`subtract(double 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.
`String`	`toString()`
`static Complex`	`valueOf(double realPart)` Create a complex number given only the real part.
`static Complex`	`valueOf(double realPart, double imaginaryPart)` Create a complex number given the real and imaginary parts.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, 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)

Create a complex number given only the real part.

Parameters:: real - Real part.

Complex

public Complex(double real,
               double imaginary)

Create a complex number given the real and imaginary parts.

Parameters:: real - Real part.; imaginary - 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 is infinite.

Returns:: the absolute value.

add

public Complex add(Complex addend)
            throws NullArgumentException

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

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

If either this or addend has a NaN value in either part, NaN is returned; otherwise Infinite 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:: addend - Value to be added to this Complex.
Returns:: this + addend.
Throws:: NullArgumentException - if addend is null.

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()

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 divisor)
               throws NullArgumentException

Returns a Complex whose value is (this / divisor). Implements the definitional formula

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

but uses prescaling of operands to limit the effects of overflows and underflows in the computation.
Infinite and NaN values are handled according to the following rules, applied in the order presented:

If either this or divisor has a NaN value in either part, NaN is returned.
If divisor equals ZERO, NaN is returned.
If this and divisor are both infinite, NaN is returned.
If this is finite (i.e., has no Infinite or NaN parts) and divisor is infinite (one or both parts infinite), ZERO is returned.
If this is infinite and divisor 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:: divisor - Value by which this Complex is to be divided.
Returns:: this / divisor.
Throws:: NullArgumentException - if divisor is null.

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

Specified by:: reciprocal in interface FieldElement<Complex>

Returns:: the inverse of this.

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 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. Any Double.NaN value in real or imaginary part produces the same hash code 7.

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()

Checks whether either or both parts of this complex number is NaN.

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

isInfinite

public boolean isInfinite()

Checks whether 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 factor)
                 throws NullArgumentException

Returns a Complex whose value is this * factor. 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 factor has one or more NaN parts.
Returns INF if neither this nor factor has one or more NaN parts and if either this or factor 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:: factor - value to be multiplied by this Complex.
Returns:: this * factor.
Throws:: NullArgumentException - if factor is null.

multiply

public Complex multiply(int factor)

Returns a Complex whose value is this * factor, with factor interpreted as a integer number.

Specified by:: multiply in interface FieldElement<Complex>

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 NaN if either real or imaginary part of this Complex number equals Double.NaN.

Specified by:: negate in interface FieldElement<Complex>

Returns:: -this.

subtract

public Complex subtract(Complex subtrahend)
                 throws NullArgumentException

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

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

If either this or subtrahend has a NaN] value in either part, NaN is returned; otherwise infinite 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:: subtrahend - value to be subtracted from this Complex.
Returns:: this - subtrahend.
Throws:: NullArgumentException - if subtrahend is null.

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²))))

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 - z²) + 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), FastMath.cosh(double) and FastMath.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}

  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:: the value ln this, the natural logarithm of this.
Since:: 1.2

pow

public Complex pow(Complex x)
            throws NullArgumentException

Returns of value of this complex number raised to the power of x. Implements the formula:

  
   y^x = 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 - exponent to which this Complex is to be raised.
Returns:: this^x.
Throws:: NullArgumentException - if x is null.
Since:: 1.2

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:: this^x.
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

  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

  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.
Since:: 1.2

sqrt

public Complex sqrt()

Compute the square root of this complex number. Implements the following algorithm to compute sqrt(a + bi):

Let t = sqrt((|a| + |a + bi|) / 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 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.
Since:: 1.2

sqrt1z

public Complex sqrt1z()

Compute the square root of 1 - this² for this complex number. Computes the result directly as sqrt(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².
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 FastMath.sin(double), FastMath.cos(double), FastMath.cosh(double) and FastMath.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(a ± INFINITY i) = 0 ± i
   tan(±INFINITY + bi) = NaN + NaN i
   tan(±INFINITY ± INFINITY i) = NaN + NaN i
   tan(±π/2 + 0 i) = ±INFINITY + NaN i

Returns:: the tangent of this.
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 FastMath.sin(double), FastMath.cos(double), FastMath.cosh(double) and FastMath.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(a ± INFINITY i) = NaN + NaN i
   tanh(±INFINITY + bi) = ±1 + 0 i
   tanh(±INFINITY ± INFINITY i) = NaN + NaN i
   tanh(0 + (π/2)i) = NaN + INFINITY i

Returns:: the hyperbolic tangent of this.
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 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.

nthRoot

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

Computes the n-th roots of this complex number. The nth roots are defined by the formula:

  
   z_k = 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:: a List of all n-th roots of this.
Throws:: NotPositiveException - if n <= 0.
Since:: 2.0

createComplex

protected Complex createComplex(double realPart,
                                double imaginaryPart)

Create a complex number given the real and imaginary parts.

Parameters:: realPart - Real part.; imaginaryPart - Imaginary part.
Returns:: a new complex number instance.
Since:: 1.2
See Also:: valueOf(double, double)

valueOf

public static Complex valueOf(double realPart,
                              double imaginaryPart)

Create a complex number given the real and imaginary parts.

Parameters:: realPart - Real part.; imaginaryPart - Imaginary part.
Returns:: a Complex instance.

valueOf

public static Complex valueOf(double realPart)

Create a complex number given only the real part.

Parameters:: realPart - Real part.
Returns:: a Complex instance.

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

toString

public String toString()

Overrides:: toString in class Object

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.math3.complex Class Complex

I

NaN

INF

ONE

ZERO

Complex

Complex

abs

add

add

conjugate

divide

divide

reciprocal

equals

hashCode

getImaginary

getReal

isNaN

isInfinite

multiply

multiply

multiply

negate

subtract

subtract

acos

asin

atan

cos

cosh

exp

log

pow

pow

sin

sinh

sqrt

sqrt1z

tan

tanh

getArgument

nthRoot

createComplex

valueOf

valueOf

readResolve

getField

toString

org.apache.commons.math3.complex
Class Complex