Class ORG.netlib.math.complex.Complex

java.lang.Object
   |
   +----ORG.netlib.math.complex.Complex

public class Complex
extends Object
implements Cloneable, Serializable

Version:

1.0 FINAL
ALM Fri 29-Aug-97

A Java class for performing complex number arithmetic to double precision.

Make yours a Java enabled browser and OS!

This applet has been adapted
from a Vector Visualization applet by Vladimir Sorokin.

Author:

Sandy Anderson, Priyantha Jayanetti

 Copyright (c) 1997,  ALMA Services.  All Rights Reserved.
 

     Permission to  use, copy,  modify, and distribute  this software  and its
 documentation is  hereby granted provided that  this copyright notice appears
 in all copies and that all modifications are clearly marked.
 

     THE AUTHORS MAKE NO  REPRESENTATIONS OR WARRANTIES  ABOUT THE SUITABILITY
 OF THE SOFTWARE,  EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 IMPLIED WARRANTIES OF MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE,  OR
 NON-INFRINGEMENT.   THE AUTHORS SHALL NOT BE LIABLE FOR  ANY DAMAGES SUFFERED
 BY LICENSEE AS A RESULT OF USING,  MODIFYING OR DISTRIBUTING THIS SOFTWARE OR
 ITS DERIVATIVES.
 

 Last change:  ALM  29 Aug 97    2:13 am

The latest version of this Complex class is available from the Netlib Repository.

Here's an example of the style the class permits:

         import  ORG.netlib.math.complex.Complex;

         public class Test {

             public boolean isInMandelbrot (Complex c, int maxIter) {
                 Complex z= new Complex(0, 0);

                 for (int i= 0; i < maxIter; i++) {
                     z= z.mul(z).add(c);
                     if (z.abs() > 2) return false;
                 }

                 return true;
             }

         }

This class was developed by Sandy Anderson at the School of Electronic Engineering, Middlesex University, UK, and Priyantha Jayanetti at The Power Systems Program, the University of Maine, USA.

And many, many thanks to Mr. Daniel Hirsch, for his constant advice on the mathematics, his exasperating ability to uncover bugs blindfold, and for his persistent badgering over the exact wording of this documentation.

For instance, he starts to growl like a badger if you say "infinite set".

"Grrr...What's that mean? Countably infinite?"

You think for a while.

"Grrr..."

"Yes."

"Ah! Then you mean infinitely many."

AUTHOR
DATE
i: A constant representing i, the famous square root of -1.
REMARK
TWO_PI: Twice PI radians is the same thing as 360 degrees.
VERSION

Complex(): Constructs a Complex representing the number zero.
Complex(Complex): Constructs a separate new Complex from an existing Complex.
Complex(double): Constructs a Complex representing a real number.
Complex(double, double): Constructs a Complex from real and imaginary parts.

abs(): Returns the magnitude of a Complex number.
acos(): Returns the principal arc cosine of a Complex number.
acosh(): Returns the principal inverse hyperbolic cosine of a Complex number.
add(Complex): To perform z1 + z2, you write z1.add(z2) .
arg(): Returns the principal angle of a Complex number, in radians, measured counter-clockwise from the real axis.
asin(): Returns the principal arc sine of a Complex number.
asinh(): Returns the principal inverse hyperbolic sine of a Complex number.
atan(): Returns the principal arc tangent of a Complex number.
atanh(): Returns the principal inverse hyperbolic tangent of a Complex number.
cart(double, double): Returns a Complex from real and imaginary parts.
conj(): Returns the Complex "conjugate".
cos(): Returns the cosine of a Complex number.
cosec(): Returns the cosecant of a Complex number.
cosh(): Returns the hyperbolic cosine of a Complex number.
cot(): Returns the cotangent of a Complex number.
div(Complex): To perform z1 / z2, you write z1.div(z2) .
equals(Complex, double): Decides if two Complex numbers are "sufficiently" alike to be considered equal.
exp(): Returns the number e "raised to" a Complex power.
im(): Extracts the imaginary part of a Complex as a double.
isInfinite(): Returns true if either the real or imaginary component of this Complex is an infinite value.
isNaN(): Returns true if either the real or imaginary component of this Complex is a Not-a-Number (NaN) value.
log(): Returns the principal natural logarithm of a Complex number.
main(String[]): Useful for checking up on the exact version.
mul(Complex): To perform z1 * z2, you write z1.mul(z2) .
neg(): Returns the "negative" of a Complex number.
norm(): Returns the square of the "length" of a Complex number.
polar(double, double): Returns a Complex from a size and direction.
pow(Complex): Returns this Complex raised to the power of a Complex exponent.
pow(Complex, Complex): Returns the Complex base raised to the power of the Complex exponent.
pow(Complex, double): Returns the Complex base raised to the power of the exponent.
pow(double, Complex): Returns the base raised to the power of the Complex exponent.
re(): Extracts the real part of a Complex as a double.
real(double): Returns a Complex representing a real number.
scale(double): Returns the Complex scaled by a real number.
sec(): Returns the secant of a Complex number.
sin(): Returns the sine of a Complex number.
sinh(): Returns the hyperbolic sine of a Complex number.
sqrt(): Returns a Complex representing one of the two square roots.
sub(Complex): To perform z1 - z2, you write z1.sub(z2) .
tan(): Returns the tangent of a Complex number.
tanh(): Returns the hyperbolic tangent of a Complex number.
toString(): Converts a Complex into a String of the form (a + bi).

VERSION

  public final static String VERSION

DATE

  public final static String DATE

AUTHOR

  public final static String AUTHOR

REMARK

  public final static String REMARK

TWO_PI

  protected final static double TWO_PI

Twice PI radians is the same thing as 360 degrees.

  public final static Complex i

A constant representing i, the famous square root of -1.

The other square root of -1 is - i.

Complex

  public Complex()

Constructs a Complex representing the number zero.

Complex

  public Complex(double re)

Constructs a Complex representing a real number.

Parameters:: re - The real number
See Also:: real

Complex

  public Complex(Complex z)

Constructs a separate new Complex from an existing Complex.

Parameters:: z - A Complex number

Complex

  public Complex(double re,
                 double im)

Constructs a Complex from real and imaginary parts.

Note:

All methods in class Complex which deliver a Complex are written such that no intermediate Complex objects get generated. This means that you can easily anticipate the likely effects on garbage collection caused by your own coding.

Parameters:: re - Real part; im - Imaginary part
See Also:: cart, polar

main

  public static void main(String args[])

Useful for checking up on the exact version.

real

  public static Complex real(double real)

Returns a Complex representing a real number.

Parameters:: real - The real number
Returns:: Complex representation of the real
See Also:: re, cart

cart

  public static Complex cart(double re,
                             double im)

Returns a Complex from real and imaginary parts.

Parameters:: re - Real part; im - Imaginary part
Returns:: Complex from Cartesian coordinates
See Also:: re, im, polar, toString

polar

  public static Complex polar(double r,
                              double theta)

Returns a Complex from a size and direction.

Parameters:: r - Size; theta - Direction (in radians)
Returns:: Complex from Polar coordinates
See Also:: abs, arg, cart

pow

  public static Complex pow(Complex base,
                            double exponent)

Returns the Complex base raised to the power of the exponent.

Parameters:: base - The base "to raise"; exponent - The exponent "by which to raise"
Returns:: base "raised to the power of" exponent
See Also:: pow

pow

  public static Complex pow(double base,
                            Complex exponent)

Returns the base raised to the power of the Complex exponent.

Parameters:: base - The base "to raise"; exponent - The exponent "by which to raise"
Returns:: base "raised to the power of" exponent
See Also:: pow, exp

pow

  public static Complex pow(Complex base,
                            Complex exponent)

Returns the Complex base raised to the power of the Complex exponent.

Parameters:: base - The base "to raise"; exponent - The exponent "by which to raise"
Returns:: base "raised to the power of" exponent
See Also:: pow, pow

isInfinite

  public boolean isInfinite()

Returns true if either the real or imaginary component of this Complex is an infinite value.

Returns:: true if either component of the Complex object is infinite; false, otherwise.

isNaN

  public boolean isNaN()

Returns true if either the real or imaginary component of this Complex is a Not-a-Number (NaN) value.

Returns:: true if either component of the Complex object is NaN; false, otherwise.

equals

  public boolean equals(Complex z,
                        double tolerance)

Decides if two Complex numbers are "sufficiently" alike to be considered equal.

tolerance is the maximum magnitude of the difference between them before they are considered not equal.

Checking for equality between two real numbers on computer hardware is a tricky business. Try

    System.out.println((1.0/3.0 * 3.0));

and you'll see the nature of the problem! It's just as tricky with Complex numbers.

Realize that because of these complications, it's possible to find that the magnitude of one Complex number a is less than another, b, and yet a.equals(b, myTolerance) returns true. Be aware!

Parameters:: z - The Complex to compare with; tolerance - The tolerance for equality
Returns:: true, or false

  public double re()

Extracts the real part of a Complex as a double.

     re(x + i*y)  =  x

Returns:: The real part
See Also:: im, cart, real

  public double im()

Extracts the imaginary part of a Complex as a double.

     im(x + i*y)  =  y

Returns:: The imaginary part
See Also:: re, cart

norm

  public double norm()

Returns the square of the "length" of a Complex number.

     norm(x + i*y)  =  x*x + y*y

Always non-negative.

Returns:: The norm
See Also:: abs

abs

  public double abs()

Returns the magnitude of a Complex number.

     abs(z)  =  sqrt(norm(z))

In other words, it's Pythagorean distance from the origin (0 + 0i, or zero).

The magnitude is also referred to as the "modulus" or "length".

Always non-negative.

Returns:: The magnitude (or "length")
See Also:: arg, polar, norm

arg

  public double arg()

Returns the principal angle of a Complex number, in radians, measured counter-clockwise from the real axis. (Think of the reals as the x-axis, and the imaginaries as the y-axis.)

There are infinitely many solutions, besides the principal solution. If A is the principal solution of arg(z), the others are of the form:

     A + 2*k*PI

where k is any integer.

arg() always returns a double between -PI and +PI.

Note:

2*PI radians is the same as 360 degrees.

Domain Restrictions:

There are no restrictions: the class defines arg(0) to be 0

Returns:: Principal angle (in radians)
See Also:: abs, polar

neg

  public Complex neg()

Returns the "negative" of a Complex number.

     neg(a + i*b)  =  -a - i*b

The magnitude of the negative is the same, but the angle is flipped through PI (or 180 degrees).

Returns:: Negative of the Complex
See Also:: scale

conj

  public Complex conj()

Returns the Complex "conjugate".

     conj(x + i*y)  =  x - i*y

The conjugate appears "flipped" across the real axis.

Returns:: The Complex conjugate

scale

  public Complex scale(double scalar)

Returns the Complex scaled by a real number.

     scale((x + i*y), s)  =  (x*s + i*y*s)

Scaling by the real number 2.0, doubles the magnitude, but leaves the arg() unchanged. Scaling by -1.0 keeps the magnitude the same, but flips the arg() by PI (180 degrees).

Parameters:: scalar - A real number scale factor
Returns:: Complex scaled by a real number
See Also:: mul, div, neg

add

  public Complex add(Complex z)

To perform z1 + z2, you write z1.add(z2) .

     (a + i*b) + (c + i*d)  =  ((a+c) + i*(b+d))

sub

  public Complex sub(Complex z)

To perform z1 - z2, you write z1.sub(z2) .

     (a + i*b) - (c + i*d)  =  ((a-c) + i*(b-d))

mul

  public Complex mul(Complex z)

To perform z1 * z2, you write z1.mul(z2) .

     (a + i*b) * (c + i*d)  =  ( (a*c) - (b*d) + i*((a*d) + (b*c)) )

See Also:: scale

div

  public Complex div(Complex z)

To perform z1 / z2, you write z1.div(z2) .

     (a + i*b) / (c + i*d)  =  ( (a*c) + (b*d) + i*((b*c) - (a*d)) ) / norm(c + i*d)

Take care not to divide by zero!

Note:

Complex arithmetic in Java never causes exceptions. You have to deliberately check for overflow, division by zero, and so on, for yourself.

Domain Restrictions:

z1/z2 is undefined if z2 = 0

See Also:: scale

sqrt

  public Complex sqrt()

Returns a Complex representing one of the two square roots.

     sqrt(z)  =  sqrt(abs(z)) * ( cos(arg(z)/2) + i * sin(arg(z)/2) )

For any complex number z, sqrt(z) will return the complex root whose arg is arg(z)/2.

Note:

There are always two square roots for each Complex number, except for 0 + 0i, or zero. The other root is the neg() of the first one. Just as the two roots of 4 are 2 and -2, the two roots of -1 are i and - i.

Returns:: The square root whose arg is arg(z)/2.
See Also:: pow

pow

  public Complex pow(Complex exponent)

Returns this Complex raised to the power of a Complex exponent.

Parameters:: exponent - The exponent "by which to raise"
Returns:: this Complex "raised to the power of" the exponent
See Also:: pow

exp

  public Complex exp()

Returns the number e "raised to" a Complex power.

     exp(x + i*y)  =  exp(x) * ( cos(y) + i * sin(y) )

Note:

The value of e, a transcendental number, is roughly 2.71828182846...
Also, the following is quietly amazing:
e^PI*i = - 1

Returns:: e "raised to the power of" this Complex
See Also:: log, pow

log

  public Complex log()

Returns the principal natural logarithm of a Complex number.

     log(z)  =  log(abs(z)) + i * arg(z)

There are infinitely many solutions, besides the principal solution. If L is the principal solution of log(z), the others are of the form:

     L + (2*k*PI)*i

where k is any integer.

Returns:: Principal Complex natural logarithm
See Also:: exp

sin

  public Complex sin()

Returns the sine of a Complex number.

     sin(z)  =  ( exp(i*z) - exp(-i*z) ) / (2*i)

Returns:: The Complex sine
See Also:: asin, sinh, cosec, cos, tan

cos

  public Complex cos()

Returns the cosine of a Complex number.

     cos(z)  =  ( exp(i*z) + exp(-i*z) ) / 2

Returns:: The Complex cosine
See Also:: acos, cosh, sec, sin, tan

tan

  public Complex tan()

Returns the tangent of a Complex number.

     tan(z)  =  sin(z) / cos(z)

Domain Restrictions:

tan(z) is undefined whenever z = (k + 1/2) * PI
where k is any integer

Returns:: The Complex tangent
See Also:: atan, tanh, cot, sin, cos

cosec

  public Complex cosec()

Returns the cosecant of a Complex number.

     cosec(z)  =  1 / sin(z)

Domain Restrictions:

cosec(z) is undefined whenever z = k * PI
where k is any integer

Returns:: The Complex cosecant
See Also:: sin, sec, cot

sec

  public Complex sec()

Returns the secant of a Complex number.

     sec(z)  =  1 / cos(z)

Domain Restrictions:

sec(z) is undefined whenever z = (k + 1/2) * PI
where k is any integer

Returns:: The Complex secant
See Also:: cos, cosec, cot

cot

  public Complex cot()

Returns the cotangent of a Complex number.

     cot(z)  =  1 / tan(z)

Domain Restrictions:

cot(z) is undefined whenever z = k * PI
where k is any integer

Returns:: The Complex cotangent
See Also:: tan, cosec, sec

sinh

  public Complex sinh()

Returns the hyperbolic sine of a Complex number.

     sinh(z)  =  ( exp(z) - exp(-z) ) / 2

Returns:: The Complex hyperbolic sine
See Also:: sin, asinh

cosh

  public Complex cosh()

Returns the hyperbolic cosine of a Complex number.

     cosh(z)  =  ( exp(z) + exp(-z) ) / 2

Returns:: The Complex hyperbolic cosine
See Also:: cos, acosh

tanh

  public Complex tanh()

Returns the hyperbolic tangent of a Complex number.

     tanh(z)  =  sinh(z) / cosh(z)

Returns:: The Complex hyperbolic tangent
See Also:: tan, atanh

asin

  public Complex asin()

Returns the principal arc sine of a Complex number.

     asin(z)  =  -i * log(i*z + sqrt(1 - z*z))

There are infinitely many solutions, besides the principal solution. If A is the principal solution of asin(z), the others are of the form:

     k*PI + (-1)^k  * A

where k is any integer.

Returns:: Principal Complex arc sine
See Also:: sin, sinh

acos

  public Complex acos()

Returns the principal arc cosine of a Complex number.

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

There are infinitely many solutions, besides the principal solution. If A is the principal solution of acos(z), the others are of the form:

     2*k*PI +/- A

where k is any integer.

Returns:: Principal Complex arc cosine
See Also:: cos, cosh

atan

  public Complex atan()

Returns the principal arc tangent of a Complex number.

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

There are infinitely many solutions, besides the principal solution. If A is the principal solution of atan(z), the others are of the form:

     A + k*PI

where k is any integer.

Domain Restrictions:

atan(z) is undefined for z = + i or z = - i

Returns:: Principal Complex arc tangent
See Also:: tan, tanh

asinh

  public Complex asinh()

Returns the principal inverse hyperbolic sine of a Complex number.

     asinh(z)  =  log(z + sqrt(z*z + 1))

There are infinitely many solutions, besides the principal solution. If A is the principal solution of asinh(z), the others are of the form:

     k*PI*i + (-1)^k  * A

where k is any integer.

Returns:: Principal Complex inverse hyperbolic sine
See Also:: sinh

acosh

  public Complex acosh()

Returns the principal inverse hyperbolic cosine of a Complex number.

     acosh(z)  =  log(z + sqrt(z*z - 1))

There are infinitely many solutions, besides the principal solution. If A is the principal solution of acosh(z), the others are of the form:

     2*k*PI*i +/- A

where k is any integer.

Returns:: Principal Complex inverse hyperbolic cosine
See Also:: cosh

atanh

  public Complex atanh()

Returns the principal inverse hyperbolic tangent of a Complex number.

     atanh(z)  =  1/2 * log( (1+z)/(1-z) )

There are infinitely many solutions, besides the principal solution. If A is the principal solution of atanh(z), the others are of the form:

     A + k*PI*i

where k is any integer.

Domain Restrictions:

atanh(z) is undefined for z = + 1 or z = - 1

Returns:: Principal Complex inverse hyperbolic tangent
See Also:: tanh

toString

  public String toString()

Converts a Complex into a String of the form (a + bi).

This enables the Complex to be easily printed. For example, if z was 2 - 5i, then

     System.out.println("z = " + z);

would print

     z = (2 - 5i)

Returns:: String containing the cartesian coordinate representation
Overrides:: toString in class Object
See Also:: cart