ca.uwaterloo.alumni.dwharder.Numbers
Class Complex

java.lang.Object
  ca.uwaterloo.alumni.dwharder.Numbers.Complex

All Implemented Interfaces:

java.io.Serializable

public final class Complex
extends java.lang.Object
implements java.io.Serializable

A class implementing complex numbers using pairs of doubles.

This package allows the user to construct, manipulate, and model with complex numbers. A complex number is of the form a + ib where a, b are real numbers. The symbol i commutes with real numbers and obeys the multiplication rule i² = -1.

In the description of each non-static method, this complex number is represented by z = a + ib. The coefficients a and ib are the real and imaginary parts of z, respectively. The parts a and ib will also be referred to as the 0th and 1st terms of the complex number z, respectively.

Any other complex number is represented by w = c + id. The variables x and n are used to represent real numbers and integers, respectively.

Instances of this class are immutable.

This class returns correct answers on branch cuts. Additionally, this class tries to give reasonable treatment to ∞ and NaN. For example, ONE.multiply(Double.POSITIVE_INFINITY) returns ∞ + i0. Most implementations would return ∞ + iNaN because they would simply multiply both the real part and the imaginary part by the multiplier. This result is probably not the desired result.

This class is based on the methods found in the Java classes Double, Math, and java.math.BigDecimal.

There is very little interaction between the classes in this package. If there is a significant request for such behaviour, it will be added (seemlessly) in the future.

Since:

JDK 5.0

Version:

1.0beta 22-Mar-2005

Author:

Douglas Wilhelm Harder, Department of Electrical and Computer Engineering, University of Waterloo, My email can be derived from the package name.

See Also:

Double, Math, Serialized Form

Field Summary

static Complex	I The constant i.
static Complex	NaN The constant NaN + iNaN.
static Complex	ONE The constant 1.
static Complex	ZERO The constant 0.

Constructor Summary

Complex(double b)
Generates the imaginary complex number 0 + ib.

Complex(double[] v)
Generates a complex number based on the entries of the array v.

Complex(double a, double b)
Generates the complex number a + ib.

Method Summary

double	abs() Returns the absolute value of this complex number z.
double	abs2() Returns the square of the absolute value of this complex number z.
Complex	acos() Returns the principal inverse cosine of this complex number z.
Complex	acosh() Returns the principal inverse hyperbolic cosine of this complex number z.
Complex	acot() Returns the principal inverse cotangent of this complex number z.
Complex	acoth() Returns the principal inverse hyperbolic cotangent of this complex number z.
Complex	acsc() Returns the principal inverse cosecant of this complex number z.
Complex	acsch() Returns the principal inverse hyperbolic cosecant of this complex number z.
Complex	add(Complex w) Returns the sum of this complex number z and the complex number w = c + id.
Complex	add(double x) Returns the sum of this complex number z and the real number x.
Complex	add(int n, double x) Returns this complex number z with x added onto its nth term.
Complex	addI(double x) Returns the sum of this complex number z and the imaginary number ix.
double	argument() Returns the argument of this complex number z.
Complex	asec() Returns the principal inverse secant of this complex number z.
Complex	asech() Returns the principal inverse hyperbolic secant of this complex number z.
Complex	asin() Returns the principal inverse sine of this complex number z.
Complex	asinh() Returns the principal inverse hyperbolic sine of this complex number z.
Complex	atan() Returns the principal inverse tangent of this complex number z.
Complex	atanh() Returns the principal inverse hyperbolic tangent of this complex number z.
Complex	ceil() Returns the ceiling of each of the parts of this complex number z.
double	coefficient(int n) Returns the coefficient of the nth term of this complex number z.
Complex	conjugate() Returns the complex conjugate of this complex number z.
Complex	cos() Returns the cosine of this complex number z.
Complex	cosh() Returns the hyperbolic cosine of this complex number z.
Complex	cot() Returns the cotangent of this complex number z.
Complex	coth() Returns the hyperbolic cotangent of this complex number z.
Complex	csc() Returns the cosecant of this complex number z.
Complex	csch() Returns the hyperbolic cosecant of this complex number z.
double	csgn() Returns the sign of the real part of this complex number z when |z| != 0, and 0.0 otherwise.
Complex	divide(Complex w) Returns the quotient of this complex number z over the complex number w = c + id.
boolean	equals(java.lang.Object w) This complex number z equals the complex number w = c + id if a == c and b == d.
boolean	equals(java.lang.Object z, double eps) Returns true if this complex number z equals the complex number w = c + id.
Complex	exp() Returns Euler's number (e) raised to the power of this complex number z.
Complex	floor() Returns the floor of each of the parts of this complex number z.
int	hashCode() Returns a hash code for the this complex number z based on the real and imaginary parts.
Complex	horner(Complex[] v) Evaluate the polynomial with complex coefficients, given by the array of complex numbers v, at this complex number z.
Complex	horner(double[] v) Evaluate the polynomial with real coefficients, given by the array of doubles v, at this complex number z.
Complex	imag() Returns the imaginary part of this complex number z.
double	imagI() Returns the coefficient of i of this complex number z.
static java.lang.String	imaginaryUnit(java.lang.String s) Set the character to be used for the imaginary unit.
boolean	isImaginary() Returns true if the real part of this complex number z is zero, otherwise false.
boolean	isInfinite() Returns true if either part of this complex number z is infinite, otherwise false.
boolean	isNaN() Returns true if either coefficient of this complex number z is not-a-number (NaN), otherwise false.
boolean	isReal() Returns true if the coefficient of the imaginary part of this complex number z is zero, otherwise false.
boolean	isZero() Returns true if both coefficients of this complex number z are zero, otherwise false.
Complex	log() Returns the natural logarithm of this complex number z.
Complex	log10() Returns the logarithm base 10 of this complex number z.
Complex	multiply(Complex w) Returns the product of this complex number z and the complex number w = c + id.
Complex	multiply(double x) Returns the product of this complex number z and the real number x.
Complex	multiplyI(double x) Returns the product of this complex number z and the imaginary number ix.
Complex	negate() Returns the negative of this complex number z.
Complex	pow(Complex w) Returns this complex number z raised to the complex number w = c + id.
Complex	pow(double x) Returns this complex number z raised to the real number x.
Complex	pow(int n) Returns this complex number z raised to the integer n.
Complex	project(boolean[] v) Project this complex number z onto the subspace defined by the boolean vector v.
Complex	project(int n) Project this complex number z onto the nth term.
static Complex	random() A factory method for constructing a complex number with a random real and imaginary parts.
Complex	random(boolean[] v) A factory method to create a random complex number defined by the boolean vector v.
static Complex	random(int n) A factory method for constructing a complex number with a random nth coefficient.
static Complex	randomImaginary() A factory method for constructing a complex number with a random imaginary part.
static Complex	randomReal() A factory method for constructing a complex number with a random real part.
double	real() Returns the real part of this complex number z.
Complex	rint() Returns each part of the complex number z rounded to the nearest double equal to an integer.
Complex	sec() Returns the secant of this complex number z.
Complex	sech() Returns the hyperbolic secant of this complex number z.
Complex	signum() Returns a normalized form of this complex number z when it is non-zero and z otherwise.
Complex	sin() Returns the sine of this complex number z.
Complex	sinh() Returns the hyperbolic sine of this complex number z.
Complex	sqr() Returns the square of this complex number z.
Complex	sqrt() Returns the square root of this complex number z.
Complex	subtract(Complex w) Returns the difference between this complex number z and the complex number w = c + id.
Complex	tan() Returns the tangent of this complex number z.
Complex	tanh() Returns the hyperbolic tangent of this complex number z.
double[]	toArray() Convert this complex number z to an array of doubles.
double[]	toArray(byte[] v) Convert this complex number z to an array of doubles.
java.lang.String	toMathMLContent() Returns this complex number z as a string using content MathML.
java.lang.String	toMathMLPresentation() Returns this complex number z as a string using presentation MathML.
java.lang.String	toString() Returns a string representing this complex number z.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final Complex ZERO

The constant 0.

ONE

public static final Complex ONE

The constant 1.

I

public static final Complex I

The constant i.

NaN

public static final Complex NaN

The constant NaN + iNaN.

Constructor Detail

Complex

public Complex(double a,
               double b)

Generates the complex number a + ib.

Parameters:

a - the real part

b - the coefficient of i

Complex

public Complex(double b)

Generates the imaginary complex number 0 + ib.

Parameters:

b - the coefficient of i

Complex

public Complex(double[] v)

Generates a complex number based on the entries of the array v.

An array v of length 2 defines the complex number v₀ + iv₁, and

an array v of length 1 defines the complex number 0 + iv₁.

Parameters:

v - array of length 1 or 2

Method Detail

random

public static final Complex random()

A factory method for constructing a complex number with a random real and imaginary parts.

Returns:

r₁ + ir₂, where each r_n is a random double.

See Also:

Math.random()

random

public static final Complex random(int n)

A factory method for constructing a complex number with a random nth coefficient.

Returns:

r + i0 or 0 + ir where r is a random double.

See Also:

Math.random()

random

public final Complex random(boolean[] v)

A factory method to create a random complex number defined by the boolean vector v.

In the result, the coefficient of the nth term is a random double if v_n == true.

Parameters:

v - an array indicating a subspace

Returns:

a random complex number s

See Also:

Math.random()

randomReal

public static final Complex randomReal()

A factory method for constructing a complex number with a random real part.

Returns:

r where r is a random double

See Also:

Math.random()

randomImaginary

public static final Complex randomImaginary()

A factory method for constructing a complex number with a random imaginary part.

Returns:

0 + ir, where r is a random double.

See Also:

Math.random()

equals

public final boolean equals(java.lang.Object w)

This complex number z equals the complex number w = c + id if a == c and b == d.

Note: NaN == NaN returns false but 0.0 == -0.0 returns true.

Overrides:

equals in class java.lang.Object

Returns:

true if the complex numbers are equal.

equals

public final boolean equals(java.lang.Object z,
                            double eps)

Returns true if this complex number z equals the complex number w = c + id.

Two nonzero complex numbers o and p are equal up to ε if |z - w|/min( |z|, |w| ) < ε.

If z = 0 or w = 0 then we check that |z| < ε or |w| < ε, respectively.

Parameters:

eps - the allowable relative difference: greater than or equal to 0

Returns:

true if the complex numbers are approximation equal

hashCode

public final int hashCode()

Returns a hash code for the this complex number z based on the real and imaginary parts.

Overrides:

hashCode in class java.lang.Object

toString

public final java.lang.String toString()

Returns a string representing this complex number z.

If N₁ = abs(a) and N₂ = abs(b), then the return value is "[-]N₁ (+|-) iN₂".

The user can force the use of 'j' instead of 'i' as the imaginary unit by Complex.imaginaryUnit('j').

Overrides:

toString in class java.lang.Object

Returns:

a string of the form "a + ib"

See Also:

imaginaryUnit(char)

imaginaryUnit

public static final java.lang.String imaginaryUnit(java.lang.String s)

Set the character to be used for the imaginary unit.

For example, "j".

Returns:

the previous used string for the imaginary unit

toMathMLContent

public final java.lang.String toMathMLContent()

Returns this complex number z as a string using content MathML.

Returns:

a string of content MathML

See Also:

MathML 2.0 Chapter 4 Content Markup

toMathMLPresentation

public final java.lang.String toMathMLPresentation()

Returns this complex number z as a string using presentation MathML.

Returns:

a string of presentation MathML

See Also:

MathML 2.0 Chapter 3 Presentation Markup

toArray

public final double[] toArray()

Convert this complex number z to an array of doubles.

Returns:

new double[] {a, b}

toArray

public final double[] toArray(byte[] v)

Convert this complex number z to an array of doubles.

The coefficient placed into the nth entry of the array is determined by v_n.

Parameters:

v - an array of 0 or 1 indicating which coefficient is to be placed into the nth entry of the array

Returns:

an array of doubles of coefficients as specified by v

isZero

public final boolean isZero()

Returns true if both coefficients of this complex number z are zero, otherwise false.

Returns:

true if z is zero

isReal

public final boolean isReal()

Returns true if the coefficient of the imaginary part of this complex number z is zero, otherwise false.

Returns:

true if z is real

isImaginary

public final boolean isImaginary()

Returns true if the real part of this complex number z is zero, otherwise false.

Returns:

true if z is imaginary

isNaN

public final boolean isNaN()

Returns true if either coefficient of this complex number z is not-a-number (NaN), otherwise false.

Returns:

true if either coefficient is NaN

See Also:

Double.isNaN(double)

isInfinite

public final boolean isInfinite()

Returns true if either part of this complex number z is infinite, otherwise false.

Returns:

true if either part is infinite

See Also:

Double.isInfinite(double)

abs

public final double abs()

Returns the absolute value of this complex number z.

abs(z) = |z| = sqrt(a² + b²)

Special cases:

• If |a| = ∞ or |b| = ∞ then |z| = ∞.

Returns:

|z|

abs2

public final double abs2()

Returns the square of the absolute value of this complex number z.

abs2(z) = |z|² = a² + b²

Special cases:

• If |a| = ∞ or |b| = ∞ then |z|² = ∞.

Returns:

|z|²

real

public final double real()

Returns the real part of this complex number z.

real(z) = a.

Returns:

a

See Also:

project(int)

imag

public final Complex imag()

Returns the imaginary part of this complex number z.

imag(z) = 0 + ib.

To be consistent with all other classes in this package, this routine returns a complex number. To get the double value, use imagI

Returns:

0 + ib

See Also:

imagI(), project(int)

imagI

public final double imagI()

Returns the coefficient of i of this complex number z.

imagI(z) = b

Returns:

b

See Also:

coefficient(int)

coefficient

public final double coefficient(int n)

Returns the coefficient of the nth term of this complex number z.

Parameters:

n - the number (0 or 1) of the coefficient to return

Returns:

the nth coefficient

project

public final Complex project(int n)

Project this complex number z onto the nth term.

Parameters:

n - the number of term (0 or 1) to be projected onto

Returns:

a + i0 or 0 + ib

project

public final Complex project(boolean[] v)

Project this complex number z onto the subspace defined by the boolean vector v.

In the result, the coefficient of the nth term is set to 0.0 if v_n == false.

Parameters:

v - an array indicating the terms to project onto

Returns:

a perpendicular projection of z

conjugate

public final Complex conjugate()

Returns the complex conjugate of this complex number z.

conjugate(z) = a - ib

Returns:

a - ib

argument

public final double argument()

Returns the argument of this complex number z.

This is a value on the interval (π, &pi] and z = |z|e^iargument(z).

argument(z) = atan2( b, a )

Returns:

atan2( b, a )

signum

public final Complex signum()

Returns a normalized form of this complex number z when it is non-zero and z otherwise.

Returns:

z/|z| for nonzero z

csgn

public final double csgn()

Returns the sign of the real part of this complex number z when |z| != 0, and 0.0 otherwise.

Special cases:

• csgn( NaN + ib ) = 1

Returns:

the sign of the real part of the complex number

add

public final Complex add(Complex w)

Returns the sum of this complex number z and the complex number w = c + id.

z + w = (a + c) + i(b + d)

Returns:

z + w

add

public final Complex add(int n,
                         double x)

Returns this complex number z with x added onto its nth term.

Parameters:

n - the number (0, 1, 2, ..., 15) of the onto which to add x

Returns:

z with x added onto the coefficient of the nth term

add

public final Complex add(double x)

Returns the sum of this complex number z and the real number x.

z + x = (a + x) + ib

Returns:

z + x

addI

public final Complex addI(double x)

Returns the sum of this complex number z and the imaginary number ix.

z + ix = a + i(b + x)

Returns:

z + ix

subtract

public final Complex subtract(Complex w)

Returns the difference between this complex number z and the complex number w = c + id.

z - w = (a - c) + i(b - d)

Returns:

z - w

negate

public final Complex negate()

Returns the negative of this complex number z.

-z = -a - ib

Returns:

-z

multiply

public final Complex multiply(Complex w)

Returns the product of this complex number z and the complex number w = c + id.

z w = (ac - bd) + i(ad + bc)

Multiplication is distributive with the following multiplication matrix for 1 and the imaginary unit:

×	1	i
1	1	i
i	i	-1

There are numerous special cases when any component is NaN or infinite.

Returns:

zw

multiply

public final Complex multiply(double x)

Returns the product of this complex number z and the real number x.

z x = ax + ibx

Special cases:

• (a + i0) ∞ = ∞ + i0
• (0 + ib) ∞ = 0 + i(∞ b)
• (a + i0) NaN = NaN + i0
• (0 + ib) NaN = 0 + iNaN

Returns:

zx

multiplyI

public final Complex multiplyI(double x)

Returns the product of this complex number z and the imaginary number ix.

z ix = -bx + iax

Special cases:

• (a + i0) i∞ = 0 + ia∞
• (0 + ib) i∞ = -b∞ + i0
• (a + i0) iNaN = 0 + iNaN
• (0 + ib) iNaN = NaN + i0

Returns:

zix

divide

public final Complex divide(Complex w)

Returns the quotient of this complex number z over the complex number w = c + id.

z/w = (ac + bd)/|w|² + i(-ad + bc)|w|².

There are numerous special cases when any component is NaN or infinite.

Returns:

z/w

pow

public final Complex pow(Complex w)

Returns this complex number z raised to the complex number w = c + id.

Returns:

z^w

pow

public final Complex pow(double x)

Returns this complex number z raised to the real number x.

Returns:

z^x

pow

public final Complex pow(int n)

Returns this complex number z raised to the integer n.

Returns:

zⁿ

sqr

public final Complex sqr()

Returns the square of this complex number z.

Returns:

z²

horner

public final Complex horner(double[] v)

Evaluate the polynomial with real coefficients, given by the array of doubles v, at this complex number z.

If n = v.length - 1 then this method evaluates v₀ + v₁z + ... + v_nzⁿ using Horner's rule.

Returns:

v₀ + v₁z + ... + v_nzⁿ.

horner

public final Complex horner(Complex[] v)

Evaluate the polynomial with complex coefficients, given by the array of complex numbers v, at this complex number z.

If n = v.length - 1 then this method evaluates v₀ + v₁z + ... + v_nzⁿ using Horner's rule.

This method is not defined for other classes due to non-commutativity.

Returns:

v₀ + v₁z + ... + v_nzⁿ.

sqrt

public final Complex sqrt()

Returns the square root of this complex number z.

The branch cut is on (-∞, 0).

Returns:

sqrt(z)

exp

public final Complex exp()

Returns Euler's number (e) raised to the power of this complex number z.

e^z = e^a(cos(b) + isin(b))

Returns:

e^z

See Also:

log()

log

public final Complex log()

Returns the natural logarithm of this complex number z.

Returns:

log(z)

See Also:

exp()

log10

public final Complex log10()

Returns the logarithm base 10 of this complex number z.

Returns:

log₁₀(z)

sin

public final Complex sin()

Returns the sine of this complex number z.

Returns:

sin(z)

See Also:

asin()

cos

public final Complex cos()

Returns the cosine of this complex number z.

Returns:

cos(z)

See Also:

acos()

tan

public final Complex tan()

Returns the tangent of this complex number z.

Returns:

tan(z)

See Also:

atan()

sec

public final Complex sec()

Returns the secant of this complex number z.

Returns:

sec(z)

See Also:

asec()

csc

public final Complex csc()

Returns the cosecant of this complex number z.

Returns:

csc(z)

See Also:

acsc()

cot

public final Complex cot()

Returns the cotangent of this complex number z.

Returns:

cot(z)

See Also:

acot()

sinh

public final Complex sinh()

Returns the hyperbolic sine of this complex number z.

Returns:

sinh(z)

See Also:

asinh()

cosh

public final Complex cosh()

Returns the hyperbolic cosine of this complex number z.

Returns:

cosh(z)

See Also:

acosh()

tanh

public final Complex tanh()

Returns the hyperbolic tangent of this complex number z.

Returns:

tanh(z)

See Also:

atanh()

sech

public final Complex sech()

Returns the hyperbolic secant of this complex number z.

Returns:

sech(z)

See Also:

asech()

csch

public final Complex csch()

Returns the hyperbolic cosecant of this complex number z.

Returns:

csch(z)

See Also:

acsch()

coth

public final Complex coth()

Returns the hyperbolic cotangent of this complex number z.

Returns:

coth(z)

See Also:

acoth()

asin

public final Complex asin()

Returns the principal inverse sine of this complex number z.

The branch cuts are (-∞, -1) and (1, ∞).

Returns:

asin(z)

See Also:

sin()

acos

public final Complex acos()

Returns the principal inverse cosine of this complex number z.

The branch cuts are (-∞, -1) and (1, ∞).

Returns:

acos(z)

See Also:

cos()

atan

public final Complex atan()

Returns the principal inverse tangent of this complex number z.

The branch cuts are (-i∞, -i] and [i, i∞).

Returns:

atan(z)

See Also:

tan()

asec

public final Complex asec()

Returns the principal inverse secant of this complex number z.

The branch cut is (-1, 1).

Returns:

asec(z)

See Also:

sec()

acsc

public final Complex acsc()

Returns the principal inverse cosecant of this complex number z.

The branch cut is (-1, 1).

Returns:

acsc(z)

See Also:

csc()

acot

public final Complex acot()

Returns the principal inverse cotangent of this complex number z.

The branch cut is (-i, i).

Returns:

acot(z)

See Also:

cot()

asinh

public final Complex asinh()

Returns the principal inverse hyperbolic sine of this complex number z.

The branch cuts are (-i∞, -i) and (i, i∞).

Returns:

asinh(z)

See Also:

sinh()

acosh

public final Complex acosh()

Returns the principal inverse hyperbolic cosine of this complex number z.

The branch cut is (-∞, 1).

Returns:

acosh(z)

See Also:

cosh()

atanh

public final Complex atanh()

Returns the principal inverse hyperbolic tangent of this complex number z.

The branch cuts are (-∞, -1] and [1, ∞).

Returns:

atanh(z)

See Also:

tanh()

asech

public final Complex asech()

Returns the principal inverse hyperbolic secant of this complex number z.

The branch cuts are (-∞, 0] and (1, ∞).

Returns:

asech(z)

See Also:

sech()

acsch

public final Complex acsch()

Returns the principal inverse hyperbolic cosecant of this complex number z.

The branch cut is (-i, i).

Returns:

acsch(z)

See Also:

csch()

acoth

public final Complex acoth()

Returns the principal inverse hyperbolic cotangent of this complex number z.

The branch cut is [-1, 1].

Returns:

acoth(z)

See Also:

coth()

ceil

public final Complex ceil()

Returns the ceiling of each of the parts of this complex number z.

Returns:

ceil(a) + iceil(b)

See Also:

Math.ceil(double)

floor

public final Complex floor()

Returns the floor of each of the parts of this complex number z.

Returns:

floor(a) + ifloor(b)

See Also:

Math.floor(double)

rint

public final Complex rint()

Returns each part of the complex number z rounded to the nearest double equal to an integer.

Returns:

rint(a) + irint(b)

See Also:

Math.rint(double)