jmathlib.toolbox.jmathlib.matrix._private.Jampack
Class Z

java.lang.Object
  extended by jmathlib.toolbox.jmathlib.matrix._private.Jampack.Z
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class Z
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Version:
1.0.1
Last change: ALM 23 Mar 2001 8:56 pm

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 - 2001, Alexander Anderson.

  This  program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published  by
  the Free Software Foundation; either version 2 of the License, or (at
  your option) any later version.

  This program is distributed in the hope that it will be  useful,  but
  WITHOUT   ANY   WARRANTY;   without  even  the  implied  warranty  of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR  PURPOSE.   See  the  GNU
  General Public License for more details.

  You  should  have  received  a copy of the GNU General Public License
  along  with  this  program;  if  not,  write  to  the  Free  Software
  Foundation,  Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
  USA.
 

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 (Z c, int maxIter) { Z z= new Z(0, 0);
for (int i= 0; i < maxIter; i++) { z= z.Times(z).Plus(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."

See Also:
Serialized Form

Field Summary
static java.lang.String AUTHOR
           
static java.lang.String DATE
           
static Z i
          A constant representing i, the famous square root of -1.
static Z I
          Imaginary unit.
 double im
           
static Z One
          The number 1 stored as a complex number
static Z ONE
          Z 1.
 double re
           
static java.lang.String REMARK
           
protected static double TWO_PI
          Twice PI radians is the same thing as 360 degrees.
static java.lang.String VERSION
           
static Z Zero
          The number 0 stored as a complex number
static Z ZERO
          Z 0.
 
Constructor Summary
Z()
          Constructs a Complex representing the number zero.
Z(double re)
          Constructs a Complex representing a real number.
Z(double re, double im)
          Constructs a Complex from real and imaginary parts.
Z(Z z)
          Constructs a separate new Complex from an existing Complex.
 
Method Summary
 double abs()
          Returns the magnitude of a Complex number.
static double abs(Z z)
           
 Z acos()
          Returns the principal arc cosine of a Complex number.
 Z acosh()
          Returns the principal inverse hyperbolic cosine of a Complex number.
 double arg()
          Returns the principal angle of a Complex number, in radians, measured counter-clockwise from the real axis.
 Z asin()
          Returns the principal arc sine of a Complex number.
 Z asinh()
          Returns the principal inverse hyperbolic sine of a Complex number.
 Z atan()
          Returns the principal arc tangent of a Complex number.
 Z atanh()
          Returns the principal inverse hyperbolic tangent of a Complex number.
static Z cart(double re, double im)
          Returns a Complex from real and imaginary parts.
 java.lang.Object clone()
          Overrides the Cloneable interface.
 Z conj()
          Returns the Complex "conjugate".
 Z Conj(Z a)
           
 Z cos()
          Returns the cosine of a Complex number.
 Z cosec()
          Returns the cosecant of a Complex number.
 Z cosh()
          Returns the hyperbolic cosine of a Complex number.
 Z cot()
          Returns the cotangent of a Complex number.
 Z Div(Z z)
          To perform z1 / z2, you write z1.Div(z2) .
static Z Div(Z z, double x)
           
static Z Div(Z z, double x, double y)
           
 Z Div(Z a, Z b)
           
 Z Eq(Z a)
           
 boolean equals(java.lang.Object arg)
          test if the object is equal to this one within a tolerance of 1E-10
 boolean equals(Z z, double tolerance)
          Decides if two Complex numbers are "sufficiently" alike to be considered equal.
 Z Exch(Z a)
          Interchanges the real and imaginary parts of two Z's.
 Z exp()
          Returns the number e "raised to" a Complex power.
 double im()
          Extracts the imaginary part of a Complex as a double.
 boolean isInfinite()
          Returns true if either the real or imaginary component of this Complex is an infinite value.
 boolean isNaN()
          Returns true if either the real or imaginary component of this Complex is a Not-a-Number (NaN) value.
 Z log()
          Returns the principal natural logarithm of a Complex number.
 Z Minus(Z z)
          To perform z1 - z2, you write z1.Minus(z2) .
 Z Minus(Z z1, Z z2)
           
 Z neg()
          Returns the "negative" of a Complex number.
 double norm()
          Returns the square of the "length" of a Complex number.
 Z Plus(Z z)
          To perform z1 + z2, you write z1.Plus(z2) .
 Z Plus(Z z1, Z z2)
           
static Z polar(double r, double theta)
          Returns a Complex from a size and direction.
static Z pow(double base, Z exponent)
          Returns the base raised to the power of the Complex exponent.
 Z pow(Z exponent)
          Returns this Complex raised to the power of a Complex exponent.
static Z pow(Z base, double exponent)
          Returns the Complex base raised to the power of the exponent.
static Z pow(Z base, Z exponent)
          Returns the Complex base raised to the power of the Complex exponent.
 double re()
          Extracts the real part of a Complex as a double.
static Z real(double real)
          Returns a Complex representing a real number.
 Z scale(double scalar)
          Returns the Complex scaled by a real number.
 Z sec()
          Returns the secant of a Complex number.
 Z sin()
          Returns the sine of a Complex number.
 Z sinh()
          Returns the hyperbolic sine of a Complex number.
 Z Sqrt()
          Returns a Complex representing one of the two square roots.
static void Sqrt(Z z)
           
 Z tan()
          Returns the tangent of a Complex number.
 Z tanh()
          Returns the hyperbolic tangent of a Complex number.
 Z Times(Z z)
          To perform z1 * z2, you write z1.Times(z2) .
 Z Times(Z a, Z b)
           
 java.lang.String toString()
          Converts a Complex into a String of the form (a + bi).
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

VERSION

public static final java.lang.String VERSION
See Also:
Constant Field Values

DATE

public static final java.lang.String DATE
See Also:
Constant Field Values

AUTHOR

public static final java.lang.String AUTHOR
See Also:
Constant Field Values

REMARK

public static final java.lang.String REMARK
See Also:
Constant Field Values

ONE

public static final Z ONE
Z 1.


ZERO

public static final Z ZERO
Z 0.


I

public static final Z I
Imaginary unit.


TWO_PI

protected static final double TWO_PI
Twice PI radians is the same thing as 360 degrees.

See Also:
Constant Field Values

i

public static final Z i
A constant representing i, the famous square root of -1.

The other square root of -1 is - i.


One

public static final Z One
The number 1 stored as a complex number


Zero

public static final Z Zero
The number 0 stored as a complex number


re

public double re

im

public double im
Constructor Detail

Z

public Z()
Constructs a Complex representing the number zero.


Z

public Z(double re)
Constructs a Complex representing a real number.

Parameters:
re - The real number

See Also:
Complex#real(double)

Z

public Z(Z z)
Constructs a separate new Complex from an existing Complex.

Parameters:
z - A Complex number


Z

public Z(double re,
         double im)
Constructs a Complex from real and imaginary parts.

Note:

Parameters:
re - Real part
im - Imaginary part

See Also:
Complex#cart(double, double), Complex#polar(double, double)
Method Detail

real

public static Z real(double real)
Returns a Complex representing a real number.

Parameters:
real - The real number

Returns:
Complex representation of the real

See Also:
Complex#re(), Complex#cart(double, double)

cart

public static Z 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:
Complex#re(), Complex#im(), Complex#polar(double, double), Complex#toString()

polar

public static Z 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:
Complex#abs(), Complex#arg(), Complex#cart(double, double)

pow

public static Z pow(Z 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:
Complex#pow(double, Complex)

pow

public static Z pow(double base,
                    Z 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:
Complex#pow(Complex, Complex), Complex#exp()

pow

public static Z pow(Z base,
                    Z 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:
Complex#pow(Complex, double), Complex#pow(Complex)

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


equals

public boolean equals(java.lang.Object arg)
test if the object is equal to this one within a tolerance of 1E-10

Overrides:
equals in class java.lang.Object
Parameters:
arg - = the object to test against

clone

public java.lang.Object clone()
Overrides the Cloneable interface.

Standard override; no change in semantics.

The following Java code example illustrates how to clone, or copy, a Complex number:

     Z z1 =  new Z(0, 1);
     Z z2 =  (Complex) z1.clone();
 

Overrides:
clone in class java.lang.Object
Returns:
An Object that is a copy of this Complex object.

See Also:
Cloneable, Object.clone()

re

public double re()
Extracts the real part of a Complex as a double.

     re(x + i*y)  =  x
 

Returns:
The real part

See Also:
Complex#im(), Complex#cart(double, double), Complex#real(double)

im

public double im()
Extracts the imaginary part of a Complex as a double.

     im(x + i*y)  =  y
 

Returns:
The imaginary part

See Also:
Complex#re(), Complex#cart(double, double)

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:
Complex#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:
Complex#arg(), Complex#polar(double, double), Complex#norm()

abs

public static double abs(Z z)

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:

Domain Restrictions:

Returns:
Principal angle (in radians)

See Also:
Complex#abs(), Complex#polar(double, double)

neg

public Z 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:
Complex#scale(double)

conj

public Z conj()
Returns the Complex "conjugate".

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

The conjugate appears "flipped" across the real axis.

Returns:
The Complex conjugate


Conj

public Z Conj(Z a)

scale

public Z 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:
Complex#Times(Complex), Complex#Div(Complex), Complex#neg()

Plus

public Z Plus(Z z)
To perform z1 + z2, you write z1.Plus(z2) .

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


Plus

public Z Plus(Z z1,
              Z z2)

Minus

public Z Minus(Z z)
To perform z1 - z2, you write z1.Minus(z2) .

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


Minus

public Z Minus(Z z1,
               Z z2)

Times

public Z Times(Z z)
To perform z1 * z2, you write z1.Times(z2) .

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

See Also:
Complex#scale(double)

Times

public Z Times(Z a,
               Z b)

Div

public Z Div(Z 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:

Domain Restrictions:

See Also:
Complex#scale(double)

Div

public Z Div(Z a,
             Z b)

Div

public static Z Div(Z z,
                    double x)

Div

public static Z Div(Z z,
                    double x,
                    double y)

Sqrt

public Z 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:

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

See Also:
Complex#pow(Complex, double)

Sqrt

public static void Sqrt(Z z)

pow

public Z pow(Z 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:
Complex#pow(Complex, Complex)

exp

public Z exp()
Returns the number e "raised to" a Complex power.

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

Note:

Returns:
e "raised to the power of" this Complex

See Also:
Complex#log(), Complex#pow(double, Complex)

log

public Z 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:
Complex#exp()

sin

public Z sin()
Returns the sine of a Complex number.

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

Returns:
The Complex sine

See Also:
Complex#asin(), Complex#sinh(), Complex#cosec(), Complex#cos(), Complex#tan()

cos

public Z cos()
Returns the cosine of a Complex number.

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

Returns:
The Complex cosine

See Also:
Complex#acos(), Complex#cosh(), Complex#sec(), Complex#sin(), Complex#tan()

tan

public Z tan()
Returns the tangent of a Complex number.

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

Domain Restrictions:

Returns:
The Complex tangent

See Also:
Complex#atan(), Complex#tanh(), Complex#cot(), Complex#sin(), Complex#cos()

cosec

public Z cosec()
Returns the cosecant of a Complex number.

     cosec(z)  =  1 / sin(z)
 

Domain Restrictions:

Returns:
The Complex cosecant

See Also:
Complex#sin(), Complex#sec(), Complex#cot()

sec

public Z sec()
Returns the secant of a Complex number.

     sec(z)  =  1 / cos(z)
 

Domain Restrictions:

Returns:
The Complex secant

See Also:
Complex#cos(), Complex#cosec(), Complex#cot()

cot

public Z cot()
Returns the cotangent of a Complex number.

     cot(z)  =  1 / tan(z)
 

Domain Restrictions:

Returns:
The Complex cotangent

See Also:
Complex#tan(), Complex#cosec(), Complex#sec()

sinh

public Z sinh()
Returns the hyperbolic sine of a Complex number.

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

Returns:
The Complex hyperbolic sine

See Also:
Complex#sin(), Complex#asinh()

cosh

public Z cosh()
Returns the hyperbolic cosine of a Complex number.

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

Returns:
The Complex hyperbolic cosine

See Also:
Complex#cos(), Complex#acosh()

tanh

public Z tanh()
Returns the hyperbolic tangent of a Complex number.

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

Returns:
The Complex hyperbolic tangent

See Also:
Complex#tan(), Complex#atanh()

asin

public Z 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:
Complex#sin(), Complex#sinh()

acos

public Z 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:
Complex#cos(), Complex#cosh()

atan

public Z 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:

Returns:
Principal Complex arc tangent

See Also:
Complex#tan(), Complex#tanh()

asinh

public Z 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:
Complex#sinh()

acosh

public Z 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:
Complex#cosh()

atanh

public Z 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:

Returns:
Principal Complex inverse hyperbolic tangent

See Also:
Complex#tanh()

toString

public java.lang.String toString()
Converts a Complex into a String of the form (a + bi).

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

     System.out.println("z = " + z);
 
would print something like
     z = (2.0 - 5.0i)
 

Overrides:
toString in class java.lang.Object
Returns:
String containing the cartesian coordinate representation

See Also:
Complex#cart(double, double)

Exch

public Z Exch(Z a)
Interchanges the real and imaginary parts of two Z's.

Parameters:
a - a Z
Returns:
this = a, with a set to the original value of this.

Eq

public Z Eq(Z a)