edu.neu.ccs
Class XPolynomialComplex

java.lang.Object
  edu.neu.ccs.XPolynomialComplex

All Implemented Interfaces:

FunctionComplex.OneArg, JPTConstants, ParameterComplex.ArrayParam, Serializable, Stringable, SwingConstants

public class XPolynomialComplex

extends Object

implements FunctionComplex.OneArg, ParameterComplex.ArrayParam, Stringable, JPTConstants, Serializable

Class XPolynomialComplex provides an implementation of a polynomial in one complex variable with complex coefficients.

XPolynomialComplex fits into the family of functions that implement FunctionComplex.OneArg.

For convenience of data entry, XPolynomialComplex also implements Stringable.

Since:

2.4.0

Version:

2.4.0

See Also:

Serialized Form

Field Summary

protected SwingPropertyChangeSupport	changeAdapter Helper object for property change API.
protected XComplex[]	coefficients The polynomial coefficients or null if no storage has been allocated.
private static String	divisionMessage Division by zero error message.
static String	standardMessage The standard error message for fromStringData.

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

XPolynomialComplex()
The constructor that sets the polynomial to the zero polynomial but allocates no storage for future coefficients.

XPolynomialComplex(double[][] params)
The constructor that sets the polynomial coefficients to a copy of the given params array.

XPolynomialComplex(float[][] params)
The constructor that sets the polynomial coefficients to a copy of the given params array.

XPolynomialComplex(int capacity)
The constructor that sets the polynomial to the zero polynomial and allocates storage with the given capacity.

XPolynomialComplex(String data)
The constructor that uses fromStringData to set the polynomial coefficients.

XPolynomialComplex(String[] strings)
The constructor that uses fromStringArrayData to set the polynomial coefficients.

XPolynomialComplex(XComplex[] params)
The constructor that sets the polynomial coefficients to a copy of the given params array.

XPolynomialComplex(XPolynomialComplex polynomial)
Constructs and initializes an XPolynomialComplex from the specified XPolynomialComplex object.

Method Summary

static XPolynomialComplex	add(XPolynomialComplex p, XPolynomialComplex q) Returns a new polynomial equivalent mathematically to (p + q).
void	addPropertyChangeListener(PropertyChangeListener listener) Registers the given object to listen for property change events generated by this object.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener) Registers the given object to listen for property change events generated by this object with the given property name.
static XPolynomialComplex[]	divide(XPolynomialComplex p, XPolynomialComplex q) Returns a polynomial array consisting of 2 items: the quotient of p divided by q and the remainder of p divided by q.
XComplex	evaluate(XComplex x) Returns the value of the polynomial at the given x.
void	fromStringArrayData(String[] strings) Defines the data state for this XPolynomialComplex object from a String array representation of the data state.
void	fromStringData(String data) Defines the data state for this XPolynomialComplex object from a String representation of the data state.
int	getCapacity() Returns the capacity of the current internal storage, that is, the largest index into which data may be stored without reallocation of the coefficients array.
XComplex	getCoefficient(int index) Returns a copy of the coefficient at the given index.
XComplex[]	getCoefficients() Returns a copy of the polynomial coefficients.
int	getDegree() Returns the degree of the polynomial which is defined to be the highest index whose coefficient is non-zero; by convention, the zero polynomial has degree -1.
boolean	isAlmostEqualTo(XPolynomialComplex p, double epsilon) Returns true if the given polynomial is almost equal to this polynomial in the sense that all coefficients agree to within the measure epsilon.
boolean	isAlmostZero(double epsilon) Returns true if the polynomial is almost the zero polynomial relative to the measure epsilon, that is, if all of its coefficients have a maxabs value that is less than or equal to epsilon.
boolean	isEqualTo(XPolynomialComplex p) Returns true if the given polynomial is equal to this in the sense that the degrees are the same and all coefficients agree using XComplex.isEqualTo to test equality.
boolean	isZero() Returns true if the polynomial is the zero polynomial.
double	maxCoefficient() Returns the maximum of the method maxabs applied to the coefficients in this polynomial.
static XPolynomialComplex	multiply(XPolynomialComplex p, XPolynomialComplex q) Returns a new polynomial equivalent mathematically to (p * q).
void	removePropertyChangeListener(PropertyChangeListener listener) Deregisters the given object from listening for property change events generated by this object.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener) Deregisters the given object from listening for property change events generated by this object with the given property name.
static XPolynomialComplex	scale(XComplex f, XPolynomialComplex p) Returns a new polynomial equivalent mathematically to (f * p), that is, the polynomial obtained by multipying each coefficient of p by the complex scale factor f.
void	setCapacity(int capacity) Sets the capacity of this polynomial to the given value except that any negative value will cause the polynomial storage to be deallocated and the capacity will be -1.
void	setCoefficient(int index, XComplex value) Sets the coefficient at the given index to a copy of the given value.
void	setCoefficients(double[][] params) Sets the coefficients of the polynomial to a copy of the data in the given params array.
void	setCoefficients(float[][] params) Sets the coefficients of the polynomial to a copy of the data in the given params array.
void	setCoefficients(XComplex[] params) Sets the coefficients of the polynomial to a copy of the data in the given params array.
void	setCoefficients(XPolynomialComplex polynomial) Sets the coefficients of this polynomial to a copy of the data in the given XPolynomialComplex.
void	setParam(XComplex[] params) Sets the coefficients of the polynomial to a copy of the data in the given params array.
void	setPolynomialToZero() Sets the polynomial to the zero polynomial, that is, the polynomial that evaluates to zero everywhere.
void	shrinkCapacity() Sets the capacity to the degree.
static XPolynomialComplex	subtract(XPolynomialComplex p, XPolynomialComplex q) Returns a new polynomial equivalent mathematically to (p - q).
double[][]	toData() Returns a copy of the polynomial coefficient data as an array of type double[][].
String	toString() Returns a human readable String representing the data state of this XPolynomialComplex as an annotated string.
String[]	toStringArrayData() Returns the data state of this XPolynomialComplex as an array of strings.
String	toStringData() Returns a human readable String representing the data state of this XPolynomialComplex as a simple string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

standardMessage

public static final String standardMessage

The standard error message for fromStringData.

See Also:

Constant Field Values

divisionMessage

private static String divisionMessage

Division by zero error message.

coefficients

protected XComplex[] coefficients

The polynomial coefficients or null if no storage has been allocated.

If the coefficients array is non-null, it may nevertheless have null entries which are treated as equal to zero. This avoid excess allocation of complex number storage that may not be used.

changeAdapter

protected SwingPropertyChangeSupport changeAdapter

Helper object for property change API.

Constructor Detail

XPolynomialComplex

public XPolynomialComplex()

The constructor that sets the polynomial to the zero polynomial but allocates no storage for future coefficients.

XPolynomialComplex

public XPolynomialComplex(int capacity)

The constructor that sets the polynomial to the zero polynomial and allocates storage with the given capacity.

Parameters:

capacity - the desired storage capacity

XPolynomialComplex

public XPolynomialComplex(XComplex[] params)

The constructor that sets the polynomial coefficients to a copy of the given params array.

If params is null or of length 0, sets the polynomial to the zero polynomial but allocates no storage for future coefficients.

Parameters:

params - the array of polynomial coefficients to copy

XPolynomialComplex

public XPolynomialComplex(double[][] params)

The constructor that sets the polynomial coefficients to a copy of the given params array.

If params is null or of length 0, sets the polynomial to the zero polynomial but allocates no storage for future coefficients.

Parameters:

params - the double[][] array of data to copy

XPolynomialComplex

public XPolynomialComplex(float[][] params)

The constructor that sets the polynomial coefficients to a copy of the given params array.

If params is null or of length 0, sets the polynomial to the zero polynomial but allocates no storage for future coefficients.

Parameters:

params - the float[][] array of data to copy

XPolynomialComplex

public XPolynomialComplex(XPolynomialComplex polynomial)

Constructs and initializes an XPolynomialComplex from the specified XPolynomialComplex object.

If polynomial is null, sets the polynomial to the zero polynomial but allocates no storage for future coefficients.

Parameters:

polynomial - the XPolynomialComplex object to copy

XPolynomialComplex

public XPolynomialComplex(String data)
                   throws ParseException

The constructor that uses fromStringData to set the polynomial coefficients.

XPolynomialComplex

public XPolynomialComplex(String[] strings)
                   throws ParseException

The constructor that uses fromStringArrayData to set the polynomial coefficients.

Method Detail

setPolynomialToZero

public void setPolynomialToZero()

Sets the polynomial to the zero polynomial, that is, the polynomial that evaluates to zero everywhere.

Fires property change VALUE.

getDegree

public int getDegree()

Returns the degree of the polynomial which is defined to be the highest index whose coefficient is non-zero; by convention, the zero polynomial has degree -1.

getCapacity

public int getCapacity()

Returns the capacity of the current internal storage, that is, the largest index into which data may be stored without reallocation of the coefficients array.

Returns -1 if no storage is currently allocated.

setCapacity

public void setCapacity(int capacity)

Sets the capacity of this polynomial to the given value except that any negative value will cause the polynomial storage to be deallocated and the capacity will be -1.

This method does not allocate new storage for individual complex coefficients since by convention this class treats a null coefficient as equal to zero.

If the capacity is set to a value less than the degree, then information will be lost.

Fires property change VALUE if information is lost due to a call of this method.

Parameters:

capacity - the desired storage capacity

shrinkCapacity

public void shrinkCapacity()

Sets the capacity to the degree.

Equivalent to setCapacity(getDegree()).

getCoefficients

public XComplex[] getCoefficients()

Returns a copy of the polynomial coefficients.

Returns an array of size (d+1) where d is the degree. If the degree is -1, this array is empty but is not null.

Uses XComplex.copy so it is possible that some items in the array returned are null.

Note that the internal coefficient capacity is ignored by this method.

toData

public double[][] toData()

Returns a copy of the polynomial coefficient data as an array of type double[][].

Returns an array of size (d+1) where d is the degree. If the degree is -1, this array is empty but is not null.

Uses XComplex.toData so it is possible that some items in the array returned are null.

Note that the internal coefficient capacity is ignored by this method.

setCoefficients

public void setCoefficients(XComplex[] params)

Sets the coefficients of the polynomial to a copy of the data in the given params array.

If the given params is null or of length 0, sets this polynomial to the zero polynomial.

Uses XComplex.copy to copy the data from the given params array.

Fires property change VALUE.

Parameters:

params - the array of polynomial coefficients to copy

setCoefficients

public void setCoefficients(double[][] params)

Sets the coefficients of the polynomial to a copy of the data in the given params array.

If the given params is null or of length 0, sets this polynomial to the zero polynomial.

Uses XComplex.copyData to copy the data from the given params array.

Fires property change VALUE.

Parameters:

params - the double[][] array of data to copy

setCoefficients

public void setCoefficients(float[][] params)

Sets the coefficients of the polynomial to a copy of the data in the given params array.

If the given params is null or of length 0, sets this polynomial to the zero polynomial.

Uses XComplex.copyData to copy the data from the given params array.

Fires property change VALUE.

Parameters:

params - the float[][] array of data to copy

setCoefficients

public void setCoefficients(XPolynomialComplex polynomial)

Sets the coefficients of this polynomial to a copy of the data in the given XPolynomialComplex.

If the given polynomial is null, sets this polynomial to the zero polynomial.

Uses XComplex.copy to copy the data from the given polynomial.

Fires property change VALUE.

Parameters:

polynomial - the XPolynomialComplex object to copy

getCoefficient

public XComplex getCoefficient(int index)

Returns a copy of the coefficient at the given index.

Uses XComplex.copy.

Returns null if the index is invalid or the internal coefficient at the index is null.

Parameters:

index - the index of the coefficient

setCoefficient

public void setCoefficient(int index,
                           XComplex value)

Sets the coefficient at the given index to a copy of the given value.

Does nothing if the index is less than zero.

If the index is greater than the capacity, then the capacity is increased to accomodate the index.

Technical note: If several coefficients are to be set via this method, it is most efficient to set the highest index first since that will guarantee enough capacity for all other assignments.

Uses XComplex.copy.

Fires property change VALUE.

Parameters:

index - the index of the coefficient

value - the value of the coefficient

maxCoefficient

public double maxCoefficient()

Returns the maximum of the method maxabs applied to the coefficients in this polynomial.

We use maxabs rather than abs to avoid the computation of numerous square roots.

Returns 0 if the polynomial has no non-trivial coefficients.

isZero

public boolean isZero()

Returns true if the polynomial is the zero polynomial.

isAlmostZero

public boolean isAlmostZero(double epsilon)

Returns true if the polynomial is almost the zero polynomial relative to the measure epsilon, that is, if all of its coefficients have a maxabs value that is less than or equal to epsilon.

Replaces epsilon with its absolute value before testing.

Remark: If the polynomial has degree d and is almost zero to within epsilon, then for x with absolute value at most one:

  abs(evaluate(x)) <= (d + 1) * sqrt(2) * epsilon

In other words, a polynomial that is almost zero to within epsilon has quite small values for arguments x at most one.

The reason for sqrt(2) in the above estimate is that we use maxabs to bound the size of the coefficients rather than the more expensive abs; we also use the relation: abs<=sqrt(2)*maxabs.

Parameters:

epsilon - the measure of closeness to zero

isEqualTo

public boolean isEqualTo(XPolynomialComplex p)

Returns true if the given polynomial is equal to this in the sense that the degrees are the same and all coefficients agree using XComplex.isEqualTo to test equality.

If the given polynomial is null then returns true if and only if this equals the zero polynomial.

Ignores polynomial capacity since this is irrelevant as far as testing equality.

Parameters:

p - a polynomial

isAlmostEqualTo

public boolean isAlmostEqualTo(XPolynomialComplex p,
                               double epsilon)

Returns true if the given polynomial is almost equal to this polynomial in the sense that all coefficients agree to within the measure epsilon.

Equivalently, returns true if the difference between this and the given polynomial is almost zero to within the measure epsilon.

If the given polynomial is null then returns true if and only if this is almost zero to within epsilon.

Parameters:

p - a polynomial

epsilon - the measure of closeness

evaluate

public XComplex evaluate(XComplex x)

Returns the value of the polynomial at the given x.

Implements FunctionComplex.OneArg.

Specified by:

evaluate in interface FunctionComplex.OneArg

Parameters:

x - the position at which to evaluate the polynomial

setParam

public void setParam(XComplex[] params)

Sets the coefficients of the polynomial to a copy of the data in the given params array.

Implements ParameterComplex.ArrayParam.

Equivalent to setCoefficients.

Fires property change VALUE.

Specified by:

setParam in interface ParameterComplex.ArrayParam

Parameters:

params - the array of polynomial coefficients to copy

toString

public String toString()

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

XPolynomialComplex{c0=[...;...]|c1=[...;...]|c2=[...;...]|etc}

where [...;...] stands for the complex numbers that form the polynomial coefficients in increasing order from left to right.

The zero polynomial is represented as:

XPolynomialComplex{}

toStringData

public String toStringData()

Returns a human readable String representing the data state of this XPolynomialComplex as a simple string.

{[...;...]|[...;...]|[...;...]|etc}

where [...;...] stands for the complex numbers that form the polynomial coefficients in increasing order from left to right.

The zero polynomial is represented as:

{}

Specified by:

toStringData in interface Stringable

See Also:

Stringable.fromStringData(String)

toStringArrayData

public String[] toStringArrayData()

Returns the data state of this XPolynomialComplex as an array of strings.

This is a convenience method that allows to caller to use the string representations of the individual coefficients in any way desired.

Returns an array of size (d+1) where d is the degree. If the degree is -1, this array is empty but is not null.

fromStringData

public void fromStringData(String data)
                    throws ParseException

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

Accepts string data in the format output by toString or by toStringData.

Technical note: The parser ignores any labels of the form ci= and reads only the coefficient data from index 0 on up.

The labels if present simply help the user track the index of each coefficient as data is entered. In particular, it is not valid to omit coefficients and depend on the labels to make this clear.

Fires property change VALUE.

Specified by:

fromStringData in interface Stringable

Parameters:

data - String representation of the data state

Throws:

ParseException - if the data is malformed

See Also:

Stringable.toStringData()

fromStringArrayData

public void fromStringArrayData(String[] strings)
                         throws ParseException

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

Each string in the array is used to defining the correspoding coefficient in the polynomial.

Technical note: The parser ignores any labels of the form ci= and reads only the coefficient data from index 0 on up.

Fires property change VALUE.

Parameters:

strings - String array representation of the data state

Throws:

ParseException - if the data is malformed

scale

public static XPolynomialComplex scale(XComplex f,
                                       XPolynomialComplex p)

Returns a new polynomial equivalent mathematically to (f * p), that is, the polynomial obtained by multipying each coefficient of p by the complex scale factor f.

If the polynomial p is null or the zero polynomial or if f is null returns a zero polynomial.

Parameters:

f - a scale factor

p - a polynomial

add

public static XPolynomialComplex add(XPolynomialComplex p,
                                     XPolynomialComplex q)

Returns a new polynomial equivalent mathematically to (p + q).

If either polynomial is null or the zero polynomial returns a copy of the other polynomial.

Parameters:

p - a polynomial

q - a polynomial

subtract

public static XPolynomialComplex subtract(XPolynomialComplex p,
                                          XPolynomialComplex q)

Returns a new polynomial equivalent mathematically to (p - q).

If polynomial q is null or the zero polynomial returns a copy of polynomial p.

If polynomial p is null or the zero polynomial returns a copy of the negative of polynomial q.

Parameters:

p - a polynomial

q - a polynomial

multiply

public static XPolynomialComplex multiply(XPolynomialComplex p,
                                          XPolynomialComplex q)

Returns a new polynomial equivalent mathematically to (p * q).

If either polynomial is null or the zero polynomial returns a zero polynomial.

Parameters:

p - a polynomial

q - a polynomial

divide

public static XPolynomialComplex[] divide(XPolynomialComplex p,
                                          XPolynomialComplex q)

Returns a polynomial array consisting of 2 items: the quotient of p divided by q and the remainder of p divided by q.

More precisely, if we let s,t denote the two components of the returned array, then p = s * q + t and degree(t) < degree(q). The equality is correct to within roundoff error.

If the polynomial q is null or the zero polynomial, then throws an ArithmeticException with the message:

Division by zero in class XPolynomialComplex.

Otherwise, if the polynomial p is null or the zero polynomial, returns a pair of zero polynomials.

Parameters:

p - a polynomial

q - a polynomial

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Registers the given object to listen for property change events generated by this object.

Parameters:

listener - the listener to be registered

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)

Registers the given object to listen for property change events generated by this object with the given property name.

Parameters:

propertyName - the name of the desired property

listener - the listener to be registered

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Deregisters the given object from listening for property change events generated by this object.

Parameters:

listener - the listener to be deregistered

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)

Deregisters the given object from listening for property change events generated by this object with the given property name.

Parameters:

propertyName - the name of the desired property

listener - the listener to be deregistered