edu.neu.ccs
Class XComplex

java.lang.Object
  java.awt.geom.Point2D
      java.awt.geom.Point2D.Double
          edu.neu.ccs.XPoint2D
              edu.neu.ccs.XComplex

All Implemented Interfaces:

Cloneable, JPTConstants, Serializable, Stringable, SwingConstants

public class XComplex

extends XPoint2D

Class XComplex extends XPoint2D in order to implement the operations of complex numbers.

This class provides arithmetic operations both as member methods and static methods. The following policies prevail.

• Arguments to methods are never changed.
• Member methods that return information do not modify the object this.
• Member methods that return void do modify the object this and try to avoid creation of intermediate helper objects if at all possible.
• Static methods whose return type is XComplex always construct a new XComplexobject that is returned.
• An argument that is null is treated as if it were zero.
• An argument whether zero or null that would lead to division by zero will cause an ArithmeticException to be thrown.

The only exceptions to the above policies are with the static method calls that do copy operations or data conversions. These method calls return null for null arguments.

This class provides the arithmetic operations add, subtract, multiply, and divide in four forms. There are two member methods and two static methods. In each pair, one has its arguments as XComplex objects and the other as x,y coordinates. This maximizes convenience since it is not necessary to construct an object solely to pass its data to one of the arithmetic operations.

This class also provides operations that will efficiently add or subtract the product of two complex numbers directly. These methods are used by the class XPolynomialComplex.

Since:

2.4.0

Version:

2.4.0

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class java.awt.geom.Point2D

Point2D.Double, Point2D.Float

Field Summary

static String	complexMessage The standard error message for fromStringData for XComplex.
private static double	twopi Helper constant for certain methods.

Fields inherited from class edu.neu.ccs.XPoint2D

BLANK, changeAdapter, standardMessage, XY

Fields inherited from class java.awt.geom.Point2D.Double

x, y

Fields inherited from interface edu.neu.ccs.util.JPTConstants

ABOVE, ALIGNMENT, BELOW, BOTTOM_LEFT, BOTTOM_RIGHT, DEFAULT, FONT, INPUT_PROPERTIES, MANDATORY, OPTIONAL, ORIENTATION, TOP_LEFT, TOP_RIGHT, VALUE

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Constructor Summary

XComplex()
Constructs a default XComplex 0,0.

XComplex(double x)
Constructs an XComplex x,0 using the given double x.

XComplex(double[] data)
Constructs an XComplex using the pair of values in the given array of double which must be of size 2.

XComplex(double x, double y)
Constructs an XComplex using the given x,y double values.

XComplex(float[] data)
Constructs an XComplex using the pair of values in the given array of float which must be of size 2.

XComplex(Point2D p)
Constructs an XComplex using a copy of the data in the given Point2D.

XComplex(String data)
Constructs an XComplex object from a String representation of the data state.

Method Summary

double	abs() Returns the absolute value of the complex number this; this value is the same as the value returned by the inherited method radius(), that is, sqrt(x*x+y*y).
static double	abs(XComplex z) Returns the absolute value of the complex number z.
void	add(double x, double y) Sets this to (this + w) where w is the complex with coordinates x,y.
static XComplex	add(double x1, double y1, double x2, double y2) Returns a new XComplex whose value is z + w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.
void	add(XComplex w) Sets this to (this + w).
static XComplex	add(XComplex z, XComplex w) Returns a new XComplex whose value is z + w.
void	addProduct(double x1, double y1, double x2, double y2) Sets this to (this + z * w) where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.
void	addProduct(XComplex z, XComplex w) Sets this to (this + z * w).
void	conjugate() Sets this to its complex conjugate: in coordinates [x;y] is replaced by [x;-y].
static XComplex	conjugate(XComplex z) Returns a new XComplex whose value is the complex conjugate of the given z: in coordinates, if z is [x;y], then the new value returned is [x;-y].
static XComplex	copy(XComplex z) If z is null returns null otherwise returns a new copy of z via the constructor call new XComplex(z).
static XComplex[]	copy(XComplex[] array) If array is null returns null otherwise returns a new XComplex[] that uses the method copy(XComplex) to copy the array items.
static XComplex	copyData(double[] data) If data is null returns null otherwise returns a new XComplex via the constructor call new XComplex(data).
static XComplex[]	copyData(double[][] array) If array is null returns null otherwise returns a new XComplex[] that uses the method copyData(double[]) to copy the array items.
static XComplex	copyData(float[] data) If data is null returns null otherwise returns a new XComplex via the constructor call new XComplex(data).
static XComplex[]	copyData(float[][] array) If array is null returns null otherwise returns a new XComplex[] that uses the method copyData(float[]) to copy the array items.
void	divide(double x, double y) Sets this to (this / w) where w is the complex with coordinates x,y.
static XComplex	divide(double x1, double y1, double x2, double y2) Returns a new XComplex whose value is z / w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.
void	divide(XComplex w) Sets this to (this / w).
static XComplex	divide(XComplex z, XComplex w) Returns a new XComplex whose value is z / w.
static XComplex	exp(XComplex z) Returns the complex exponential of the given z.
void	fromStringData(String data) Defines the data state for this XComplex object from a String representation of the data state.
static XComplex	generalPower(XComplex z, double d) Returns the d-th power of z, zd, using the given double exponent d.
static XComplex	generalPower(XComplex z, XComplex w) Returns the w-th power of z, zw, using the given complex exponent w.
double	Im() Returns the imaginary part of this using notation familiar to mathematicians; this is the same value as returned by the inherited method getY().
static double	Im(XComplex z) Returns the imaginary part of the complex number z using notation familiar to mathematicians.
void	invert() Sets this to its multiplicative inverse which is equal to its conjugate divided by the value of its radius squared: in coordinates [x;y] is replaced by [x/rr;-y/rr] where rr=x*x+y*y.
static XComplex	invert(XComplex z) Returns a new XComplex whose value is the the multiplicative inverse of the given z.
boolean	isAlmostEqualTo(XComplex w, double epsilon) Returns true if the given complex number w is null and this is almost zero relative to epsilon or if the given complex number w is non-null and the maximum of the absolute value of the differences in the x,y coordinates of w and this is less than or equal to epsilon.
static boolean	isAlmostEqualTo(XComplex z, XComplex w, double epsilon) Returns true if both arguments are null, or if one argument is null and the other is almost zero, or if the two arguments have almost equal x,y coordinates.
boolean	isAlmostZero(double epsilon) Returns true if this is almost zero in the sense that its maxabs is less than or equal to epsilon.
static boolean	isAlmostZero(XComplex z, double epsilon) Returns true if the given complex number z is null or is almost zero relative to epsilon.
boolean	isEqualTo(XComplex w) Returns true if the given complex number w is null and this is zero or if the given complex number w is non-null and this and w have equal x,y coordinates.
static boolean	isEqualTo(XComplex z, XComplex w) Returns true if both arguments are null, or if one argument is null and the other is zero, or if the two arguments have equal x,y coordinates.
boolean	isZero() Returns true if this is zero.
static boolean	isZero(XComplex z) Returns true if the given complex number z is null or zero.
static XComplex	log(XComplex z) Returns the branch of the logarithm of z that is determined by the constraint that the imaginary part is between 0 and 2*pi, that is, 0<=Im(log(z))<2*pi.
static XComplex	makeUsingRadiusAndDegrees(double radius, double degrees) Returns the complex number whose coordinates are x=radius*MathUtilities.cosdeg(degrees) and y=radius*MathUtilities.sindeg(degrees).
static XComplex	makeUsingRadiusAndRadians(double radius, double radians) Returns the complex number whose coordinates are x=radius*Math.cos(radians) and y=radius*Math.sin(radians).
double	maxabs() Returns the maximum of the absolute value of the x,y coordinates of the complex number this, that is, max(abs(x),abs(y)).
static double	maxabs(XComplex z) Returns the maximum of the absolute value of the x,y coordinates of the complex number z.
void	multiply(double x, double y) Sets this to (this * w) where w is the complex with coordinates x,y.
static XComplex	multiply(double x1, double y1, double x2, double y2) Returns a new XComplex whose value is z * w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.
void	multiply(XComplex w) Sets this to (this * w).
static XComplex	multiply(XComplex z, XComplex w) Returns a new XComplex whose value is z * w.
void	negate() Sets this to (-this): in coordinates [x;y] is replaced by [-x;-y].
static XComplex	negate(XComplex z) Returns a new XComplex whose value is the negation of the given z.
static XComplex	power(XComplex z, int n) Returns the n-th power of z, zn, using the given integer exponent n.
double	Re() Returns the real part of this using notation familiar to mathematicians; this is the same value as returned by the inherited method getX().
static double	Re(XComplex z) Returns the real part of the complex number z using notation familiar to mathematicians.
static XComplex	rootOfUnity(int n, int k) Returns the k-th root among the n-th roots of unity for 0<=k<n.
static XComplex[]	rootsOfUnity(int n) Returns an array of size n with the n-th roots of unity.
void	scale(double s) Sets this to (s * this): in coordinates [x;y] is replaced by [s*x;s*y].
static XComplex	scale(double s, XComplex z) Returns a new XComplex whose value is s * z.
void	setValue(double x) Sets this complex number to x,0 using the given double x.
static XComplex	sqrt(XComplex z) Returns one of the two complex square roots of z, specifically, the one whose angle in radians is between 0 and pi.
void	subtract(double x, double y) Sets this to (this - w) where w is the complex with coordinates x,y.
static XComplex	subtract(double x1, double y1, double x2, double y2) Returns a new XComplex whose value is z - w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.
void	subtract(XComplex w) Sets this to (this - w).
static XComplex	subtract(XComplex z, XComplex w) Returns a new XComplex whose value is z - w.
void	subtractProduct(double x1, double y1, double x2, double y2) Sets this to (this - z * w) where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.
void	subtractProduct(XComplex z, XComplex w) Sets this to (this - z * w).
static double[]	toData(XComplex z) If z is null returns null otherwise returns a new double[] whose elements are x and y components of z.
static double[][]	toData(XComplex[] array) If array is null returns null otherwise returns a new double[][] whose elements are obtained by using toData(XComplex) on the array items.
String	toString() Returns a human readable String representing the data state of this XComplex as an annotated string.
static String	toString(XComplex z) Returns a human readable String representing the data state of the complex number z as an annotated string.
static String	toStringData(XComplex z) Returns a human readable String representing the data state of the complex number z as a simple string.

Methods inherited from class edu.neu.ccs.XPoint2D

addPropertyChangeListener, addPropertyChangeListener, angleInDegrees, angleInDegrees, angleInDegrees, angleInRadians, angleInRadians, angleInRadians, isFinite, isFinite, move, move, radius, radiusSq, removePropertyChangeListener, removePropertyChangeListener, setLocation, setLocation, setLocation, setLocation, setValue, setValue, setValue, setValue, toDoubleArray, toFloatArray, toStringData

Methods inherited from class java.awt.geom.Point2D.Double

getX, getY

Methods inherited from class java.awt.geom.Point2D

clone, distance, distance, distance, distanceSq, distanceSq, distanceSq, equals, hashCode

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

complexMessage

public static final String complexMessage

The standard error message for fromStringData for XComplex.

Replaces the error message used in the base class XPoint2D.

See Also:

Constant Field Values

twopi

private static final double twopi

Helper constant for certain methods.

See Also:

Constant Field Values

Constructor Detail

XComplex

public XComplex()

Constructs a default XComplex 0,0.

XComplex

public XComplex(double x)

Constructs an XComplex x,0 using the given double x.

Parameters:

x - the x-coordinate of the complex number

XComplex

public XComplex(double x,
                double y)

Constructs an XComplex using the given x,y double values.

Parameters:

x - the x-coordinate of the complex number

y - the y-coordinate of the complex number

XComplex

public XComplex(Point2D p)

Constructs an XComplex using a copy of the data in the given Point2D.

If the given point is null, then initializes this complex number to 0,0.

Parameters:

p - an existing point whose data will be copied

XComplex

public XComplex(double[] data)

Constructs an XComplex using the pair of values in the given array of double which must be of size 2.

If the given array is null or not of size 2, then initializes this complex number to 0,0.

Parameters:

data - the array of size 2 with the x,y data

XComplex

public XComplex(float[] data)

Constructs an XComplex using the pair of values in the given array of float which must be of size 2.

If the given array is null or not of size 2, then initializes this complex number to 0,0.

Parameters:

data - the array of size 2 with the x,y data

XComplex

public XComplex(String data)
         throws ParseException

Constructs an XComplex object from a String representation of the data state.

Parameters:

data - String representation of the data state

Throws:

ParseException - if the data is malformed

Method Detail

toString

public String toString()

Returns a human readable String representing the data state of this XComplex as an annotated string.

XComplex[x=...;y=...]

where the dots stand for the x,y coordinate data.

Remark: The related method toStringData() is inherited as is from class XPoint2D.

Overrides:

toString in class XPoint2D

toString

public static String toString(XComplex z)

Returns a human readable String representing the data state of the complex number z as an annotated string.

XComplex[x=...;y=...]

where the dots stand for the x,y coordinate data of z.

Returns

XComplex[x=0;y=0]

if z is null.

Parameters:

z - the explicit argument

toStringData

public static String toStringData(XComplex z)

Returns a human readable String representing the data state of the complex number z as a simple string.

[...;...]

where the dots stand for the x,y coordinate data of z.

Returns

[0;0]

if z is null.

Parameters:

z - the explicit argument

fromStringData

public void fromStringData(String data)
                    throws ParseException

Defines the data state for this XComplex object from a String representation of the data state.

Uses the same algorithm as the corresponding method in the base class XPoint2D but uses an error message that is specific to this class. Therefore, expects data as an x,y pair in the form [x;y]. Does not attempt to parse expressions involving complex numbers and does not use the mathematician's symbol i for sqrt(-1).

Fires property change VALUE.

Specified by:

fromStringData in interface Stringable

Overrides:

fromStringData in class XPoint2D

Parameters:

data - String representation of the data state

Throws:

ParseException - if the data is malformed

setValue

public final void setValue(double x)

Sets this complex number to x,0 using the given double x.

Parameters:

x - the x-coordinate of the complex number

copy

public static XComplex copy(XComplex z)

If z is null returns null otherwise returns a new copy of z via the constructor call new XComplex(z).

This method avoids making a new object when none is necessary.

Parameters:

z - the explicit argument

copyData

public static XComplex copyData(double[] data)

If data is null returns null otherwise returns a new XComplex via the constructor call new XComplex(data).

This method avoids making a new object when none is necessary.

Parameters:

data - the array of size 2 with the x,y data

copyData

public static XComplex copyData(float[] data)

If data is null returns null otherwise returns a new XComplex via the constructor call new XComplex(data).

This method avoids making a new object when none is necessary.

Parameters:

data - the array of size 2 with the x,y data

toData

public static double[] toData(XComplex z)

If z is null returns null otherwise returns a new double[] whose elements are x and y components of z.

This method avoids making a new object when none is necessary.

Parameters:

z - the XComplex argument to copy

copy

public static XComplex[] copy(XComplex[] array)

If array is null returns null otherwise returns a new XComplex[] that uses the method copy(XComplex) to copy the array items.

This method avoids making a new objects when none are necessary.

Parameters:

array - the XComplex array to copy

copyData

public static XComplex[] copyData(double[][] array)

If array is null returns null otherwise returns a new XComplex[] that uses the method copyData(double[]) to copy the array items.

This method avoids making new objects when none are necessary.

Parameters:

array - the double[][] array to copy

copyData

public static XComplex[] copyData(float[][] array)

If array is null returns null otherwise returns a new XComplex[] that uses the method copyData(float[]) to copy the array items.

This method avoids making new objects when none are necessary.

Parameters:

array - the float[][] array to copy

toData

public static double[][] toData(XComplex[] array)

If array is null returns null otherwise returns a new double[][] whose elements are obtained by using toData(XComplex) on the array items.

This method avoids making new objects when none are necessary.

Parameters:

array - the XComplex array argument to copy

negate

public final void negate()

Sets this to (-this): in coordinates [x;y] is replaced by [-x;-y].

Fires property change: VALUE.

negate

public static XComplex negate(XComplex z)

Returns a new XComplex whose value is the negation of the given z.

Returns zero if z is null.

Parameters:

z - the explicit argument

scale

public final void scale(double s)

Sets this to (s * this): in coordinates [x;y] is replaced by [s*x;s*y].

Fires property change: VALUE.

Parameters:

s - the scale argument

scale

public static XComplex scale(double s,
                             XComplex z)

Returns a new XComplex whose value is s * z.

Returns zero if z is null.

Parameters:

s - the scale argument

z - the complex argument

conjugate

public final void conjugate()

Sets this to its complex conjugate: in coordinates [x;y] is replaced by [x;-y].

Fires property change: VALUE.

conjugate

public static XComplex conjugate(XComplex z)

Returns a new XComplex whose value is the complex conjugate of the given z: in coordinates, if z is [x;y], then the new value returned is [x;-y].

Returns zero if z is null.

Parameters:

z - the explicit argument

invert

public final void invert()

Sets this to its multiplicative inverse which is equal to its conjugate divided by the value of its radius squared: in coordinates [x;y] is replaced by [x/rr;-y/rr] where rr=x*x+y*y.

Throws ArithmeticException if this is zero.

Fires property change: VALUE.

Throws:

ArithmeticException - if this is zero

invert

public static XComplex invert(XComplex z)

Returns a new XComplex whose value is the the multiplicative inverse of the given z.

The multiplicative inverse is the conjugate divided by the radius squared.

Throws ArithmeticException if z is null or zero.

Parameters:

z - the explicit argument

Throws:

ArithmeticException - if z is null or zero

add

public final void add(XComplex w)

Sets this to (this + w).

Does nothing if w is null or zero.

Fires property change: VALUE.

Parameters:

w - the explicit argument

add

public final void add(double x,
                      double y)

Sets this to (this + w) where w is the complex with coordinates x,y.

Fires property change: VALUE.

Parameters:

x - the x-coordinate of the complex number w

y - the y-coordinate of the complex number w

add

public static XComplex add(XComplex z,
                           XComplex w)

Returns a new XComplex whose value is z + w.

Parameters:

z - the LHS argument

w - the RHS argument

add

public static XComplex add(double x1,
                           double y1,
                           double x2,
                           double y2)

Returns a new XComplex whose value is z + w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.

Parameters:

x1 - the x-coordinate of the complex number z

y1 - the y-coordinate of the complex number z

x2 - the x-coordinate of the complex number w

y2 - the y-coordinate of the complex number w

subtract

public final void subtract(XComplex w)

Sets this to (this - w).

Does nothing if w is null or zero.

Fires property change: VALUE.

Parameters:

w - the explicit argument

subtract

public final void subtract(double x,
                           double y)

Sets this to (this - w) where w is the complex with coordinates x,y.

Fires property change: VALUE.

Parameters:

x - the x-coordinate of the complex number w

y - the y-coordinate of the complex number w

subtract

public static XComplex subtract(XComplex z,
                                XComplex w)

Returns a new XComplex whose value is z - w.

Parameters:

z - the LHS argument

w - the RHS argument

subtract

public static XComplex subtract(double x1,
                                double y1,
                                double x2,
                                double y2)

Returns a new XComplex whose value is z - w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.

Parameters:

x1 - the x-coordinate of the complex number z

y1 - the y-coordinate of the complex number z

x2 - the x-coordinate of the complex number w

y2 - the y-coordinate of the complex number w

multiply

public final void multiply(XComplex w)

Sets this to (this * w).

If w is null or zero, sets this to zero.

Fires property change: VALUE.

Parameters:

w - the explicit argument

multiply

public final void multiply(double x,
                           double y)

Sets this to (this * w) where w is the complex with coordinates x,y.

Fires property change: VALUE.

Parameters:

x - the x-coordinate of the complex number w

y - the y-coordinate of the complex number w

multiply

public static XComplex multiply(XComplex z,
                                XComplex w)

Returns a new XComplex whose value is z * w.

Parameters:

z - the LHS argument

w - the RHS argument

multiply

public static XComplex multiply(double x1,
                                double y1,
                                double x2,
                                double y2)

Returns a new XComplex whose value is z * w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.

Parameters:

x1 - the x-coordinate of the complex number z

y1 - the y-coordinate of the complex number z

x2 - the x-coordinate of the complex number w

y2 - the y-coordinate of the complex number w

divide

public final void divide(XComplex w)

Sets this to (this / w).

Throws ArithmeticException on division by zero.

Fires property change: VALUE.

Parameters:

w - the explicit argument

Throws:

ArithmeticException - on division by zero

divide

public final void divide(double x,
                         double y)

Sets this to (this / w) where w is the complex with coordinates x,y.

Throws ArithmeticException on division by zero.

Fires property change: VALUE.

Parameters:

x - the x-coordinate of the complex number w

y - the y-coordinate of the complex number w

Throws:

ArithmeticException - on division by zero

divide

public static XComplex divide(XComplex z,
                              XComplex w)

Returns a new XComplex whose value is z / w.

Throws ArithmeticException on division by zero.

Parameters:

z - the LHS argument

w - the RHS argument

Throws:

ArithmeticException - on division by zero

divide

public static XComplex divide(double x1,
                              double y1,
                              double x2,
                              double y2)

Returns a new XComplex whose value is z / w where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.

Throws ArithmeticException on division by zero.

Parameters:

x1 - the x-coordinate of the complex number z

y1 - the y-coordinate of the complex number z

x2 - the x-coordinate of the complex number w

y2 - the y-coordinate of the complex number w

Throws:

ArithmeticException - on division by zero

addProduct

public final void addProduct(XComplex z,
                             XComplex w)

Sets this to (this + z * w).

Does nothing if z or w is null or zero.

Fires property change: VALUE.

Parameters:

z - the LHS argument

w - the RHS argument

addProduct

public final void addProduct(double x1,
                             double y1,
                             double x2,
                             double y2)

Sets this to (this + z * w) where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.

Fires property change: VALUE.

Parameters:

x1 - the x-coordinate of the complex number z

y1 - the y-coordinate of the complex number z

x2 - the x-coordinate of the complex number w

y2 - the y-coordinate of the complex number w

subtractProduct

public final void subtractProduct(XComplex z,
                                  XComplex w)

Sets this to (this - z * w).

Does nothing if z or w is null or zero.

Fires property change: VALUE.

Parameters:

z - the LHS argument

w - the RHS argument

subtractProduct

public final void subtractProduct(double x1,
                                  double y1,
                                  double x2,
                                  double y2)

Sets this to (this - z * w) where z is the complex with coordinates x1,y1 and w is the complex with coordinates x2,y2.

Fires property change: VALUE.

Parameters:

x1 - the x-coordinate of the complex number z

y1 - the y-coordinate of the complex number z

x2 - the x-coordinate of the complex number w

y2 - the y-coordinate of the complex number w

makeUsingRadiusAndRadians

public static XComplex makeUsingRadiusAndRadians(double radius,
                                                 double radians)

Returns the complex number whose coordinates are x=radius*Math.cos(radians) and y=radius*Math.sin(radians).

Parameters:

radius - the distance of the complex from the origin

radians - the angle in radians of the complex from the x-axis

makeUsingRadiusAndDegrees

public static XComplex makeUsingRadiusAndDegrees(double radius,
                                                 double degrees)

Returns the complex number whose coordinates are x=radius*MathUtilities.cosdeg(degrees) and y=radius*MathUtilities.sindeg(degrees).

Parameters:

radius - the distance of the complex from the origin

degrees - the angle in degrees of the complex from the x-axis

Re

public final double Re()

Returns the real part of this using notation familiar to mathematicians; this is the same value as returned by the inherited method getX().

Re

public static double Re(XComplex z)

Returns the real part of the complex number z using notation familiar to mathematicians.

Returns zero if z is null; otherwise, returns z.getX().

Parameters:

z - the explicit argument

Im

public final double Im()

Returns the imaginary part of this using notation familiar to mathematicians; this is the same value as returned by the inherited method getY().

Im

public static double Im(XComplex z)

Returns the imaginary part of the complex number z using notation familiar to mathematicians.

Returns zero if z is null; otherwise, returns z.getY().

Parameters:

z - the explicit argument

abs

public final double abs()

Returns the absolute value of the complex number this; this value is the same as the value returned by the inherited method radius(), that is, sqrt(x*x+y*y).

From the mathematician's point of view, abs satisfies the important identity:

abs(z * w) = abs(z) * abs(w)

However, because of the square root, abs is expensive to compute. If you wish to simply obtain a rough estimate of the size of a complex number, we suggest the alternate method maxabs.

abs

public static double abs(XComplex z)

Returns the absolute value of the complex number z.

Returns 0 if z is null; otherwise, returns z.abs().

From the mathematician's point of view, abs satisfies the important identity:

abs(z * w) = abs(z) * abs(w)

However, because of the square root, abs is expensive to compute. If you wish to simply obtain a rough estimate of the size of a complex number, we suggest the alternate method maxabs.

Parameters:

z - the explicit argument

maxabs

public final double maxabs()

Returns the maximum of the absolute value of the x,y coordinates of the complex number this, that is, max(abs(x),abs(y)).

The relationship between the value of abs and the value of maxabs is:

  maxabs <= abs <= sqrt(2) * maxabs

Therefore, maxabs provides a reasonably tight estimate for abs without the cost of computing a square root.

maxabs

public static double maxabs(XComplex z)

Returns the maximum of the absolute value of the x,y coordinates of the complex number z.

Returns 0 if z is null; otherwise, returns z.maxabs().

Parameters:

z - the explicit argument

isZero

public final boolean isZero()

Returns true if this is zero.

isZero

public static boolean isZero(XComplex z)

Returns true if the given complex number z is null or zero.

Parameters:

z - the explicit argument

isAlmostZero

public final boolean isAlmostZero(double epsilon)

Returns true if this is almost zero in the sense that its maxabs is less than or equal to epsilon.

Replaces epsilon with its absolute value before testing.

Parameters:

epsilon - the measure of closeness to zero

isAlmostZero

public static boolean isAlmostZero(XComplex z,
                                   double epsilon)

Returns true if the given complex number z is null or is almost zero relative to epsilon.

Parameters:

z - the explicit argument

isEqualTo

public final boolean isEqualTo(XComplex w)

Returns true if the given complex number w is null and this is zero or if the given complex number w is non-null and this and w have equal x,y coordinates.

Parameters:

w - the explicit argument

isEqualTo

public static boolean isEqualTo(XComplex z,
                                XComplex w)

Returns true if both arguments are null, or if one argument is null and the other is zero, or if the two arguments have equal x,y coordinates.

Parameters:

z - the LHS argument

w - the RHS argument

isAlmostEqualTo

public final boolean isAlmostEqualTo(XComplex w,
                                     double epsilon)

Returns true if the given complex number w is null and this is almost zero relative to epsilon or if the given complex number w is non-null and the maximum of the absolute value of the differences in the x,y coordinates of w and this is less than or equal to epsilon.

Replaces epsilon with its absolute value before testing.

Parameters:

w - the explicit argument

epsilon - the measure of closeness to zero

isAlmostEqualTo

public static boolean isAlmostEqualTo(XComplex z,
                                      XComplex w,
                                      double epsilon)

Returns true if both arguments are null, or if one argument is null and the other is almost zero, or if the two arguments have almost equal x,y coordinates.

Replaces epsilon with its absolute value before testing.

Parameters:

z - the LHS argument

w - the RHS argument

epsilon - the measure of closeness to zero

exp

public static XComplex exp(XComplex z)

Returns the complex exponential of the given z.

If z has coordinates [x;y], then returns the complex with coordinates [exp(x)*cos(y);exp(x)*sin(y)]

This is a formula proved in the theory of complex functions.

Returns the complex number 1 if z is null.

Parameters:

z - the explicit argument

log

public static XComplex log(XComplex z)

Returns the branch of the logarithm of z that is determined by the constraint that the imaginary part is between 0 and 2*pi, that is, 0<=Im(log(z))<2*pi.

If z has coordinates [x;y], then returns the complex with coordinates [Math.log(radius);radians] where radius=z.radius() and radians=z.angleInRadians().

Throws ArithmeticException if z is null or zero.

This is a formula proved in the theory of complex functions.

Parameters:

z - the explicit argument

Throws:

ArithmeticException - if z is null or zero

sqrt

public static XComplex sqrt(XComplex z)

Returns one of the two complex square roots of z, specifically, the one whose angle in radians is between 0 and pi.

Returns zero if z is null or zero.

Parameters:

z - the explicit argument

power

public static XComplex power(XComplex z,
                             int n)

Returns the n-th power of z, zn, using the given integer exponent n.

Computes using ordinary complex arithmetic.

Throws ArithmeticException if z is null or if n is negative and z is zero.

Note: Departs from the convention of the Java Math class by calling the method power rather than simply pow.

Parameters:

z - the explicit argument

n - the exponent

Throws:

ArithmeticException - as explained above

generalPower

public static XComplex generalPower(XComplex z,
                                    double d)

Returns the d-th power of z, zd, using the given double exponent d.

Computes zd via the formula exp(d*log(z)). Note that, since log is a complex function with multiple branches and our rule for log arbitrarily selects one such branch, the value of zd computed in this fashion is also to some degree arbitrary.

This method may be used to compute an n-th root. If n is a positive integer then generalPower(z,1.0/n) computes one of the n-th roots of z. One can obtain the other n-th roots of z by multiplying this root by any one of the corresponding "n-th roots of unity" that may be computed by using the method rootsOfUnity.

Throws ArithmeticException if z is null or zero.

Parameters:

z - the explicit argument

d - the exponent

Throws:

ArithmeticException - if z is null or zero

generalPower

public static XComplex generalPower(XComplex z,
                                    XComplex w)

Returns the w-th power of z, zw, using the given complex exponent w.

Computes zw via the formula exp(w*log(z)). Note that, since log is a complex function with multiple branches and our rule for log arbitrarily selects one such branch, the value of zw computed in this fashion is also to some degree arbitrary.

Throws ArithmeticException if z is null or zero.

Parameters:

z - the explicit argument

w - the exponent

Throws:

ArithmeticException - if z is null or zero

rootOfUnity

public static XComplex rootOfUnity(int n,
                                   int k)

Returns the k-th root among the n-th roots of unity for 0<=k<n.

For convenience, the condition on k, 0<=k<n, is not checked but the roots returned will be repeated for values of k that fall outside this range (up to roundoff error).

Computes the complex number of radius 1 and angle in radians of (2*pi*k)/n.

Throws ArithmeticException if n<=0.

Parameters:

n - the positive root specifier n that determines the n-th root

k - a root selector with 0<=k<n

Throws:

ArithmeticException - if n<=0

rootsOfUnity

public static XComplex[] rootsOfUnity(int n)

Returns an array of size n with the n-th roots of unity.

Throws ArithmeticException if n<=0.

Parameters:

n - the positive root specifier n that determines the n-th root

Throws:

ArithmeticException - if n<=0