edu.neu.ccs
Class XPolynomial

java.lang.Object
  edu.neu.ccs.XPolynomial

All Implemented Interfaces:

Function.OneArg, JPTConstants, Parameter.ArrayParam, Serializable, Stringable, SwingConstants

public class XPolynomial

extends Object

implements Function.OneArg, Parameter.ArrayParam, Stringable, JPTConstants, Serializable

Class XPolynomial provides an implementation of a polynomial in one real variable with real coefficients.

XPolynomial fits into the family of functions that implement Function.OneArg.

For convenience of data entry, XPolynomial 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 double[]	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

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

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

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

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

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

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

Method Summary

static XPolynomial	add(XPolynomial p, XPolynomial 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 XPolynomial[]	divide(XPolynomial p, XPolynomial q) Returns a polynomial array consisting of 2 items: the quotient of p divided by q and the remainder of p divided by q.
double	evaluate(double x) Returns the value of the polynomial at the given x.
void	fromStringArrayData(String[] strings) Defines the data state for this XPolynomial object from a String array representation of the data state.
void	fromStringData(String data) Defines the data state for this XPolynomial 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.
double	getCoefficient(int index) Returns the coefficient at the given index.
double[]	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(XPolynomial 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 absolute value less than or equal epsilon.
boolean	isEqualTo(XPolynomial p) Returns true if the given polynomial is equal to this in the sense that the degrees are the same and all coefficients agree.
boolean	isZero() Returns true if the polynomial is the zero polynomial.
double	maxCoefficient() Returns the maximum of the absolute value of the coefficients in this polynomial.
static XPolynomial	multiply(XPolynomial p, XPolynomial 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 XPolynomial	scale(double f, XPolynomial p) Returns a new polynomial equivalent mathematically to (f * p), that is, the polynomial obtained by multipying each coefficient of p by the 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, double value) Sets the coefficient at the given index to 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(XPolynomial polynomial) Sets the coefficients of this polynomial to a copy of the data in the given XPolynomial.
void	setParam(double[] 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 XPolynomial	subtract(XPolynomial p, XPolynomial q) Returns a new polynomial equivalent mathematically to (p - q).
String	toString() Returns a human readable String representing the data state of this XPolynomial as an annotated string.
String[]	toStringArrayData() Returns the data state of this XPolynomial as an array of strings.
String	toStringData() Returns a human readable String representing the data state of this XPolynomial 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 double[] coefficients

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

changeAdapter

protected SwingPropertyChangeSupport changeAdapter

Helper object for property change API.

Constructor Detail

XPolynomial

public XPolynomial()

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

XPolynomial

public XPolynomial(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

XPolynomial

public XPolynomial(double[] params)

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

Parameters:

params - the array of polynomial coefficients to copy

XPolynomial

public XPolynomial(XPolynomial polynomial)

Constructs and initializes an XPolynomial from the specified XPolynomial object.

Parameters:

polynomial - the XPolynomial object to copy

XPolynomial

public XPolynomial(String data)
            throws ParseException

The constructor that uses fromStringData to set the polynomial coefficients.

XPolynomial

public XPolynomial(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.

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 double[] 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.

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, sets this polynomial to the zero polynomial.

Fires property change VALUE.

Parameters:

params - the array of polynomial coefficients to copy

setCoefficients

public void setCoefficients(XPolynomial polynomial)

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

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

Fires property change VALUE.

Parameters:

polynomial - the XPolynomial object to copy

getCoefficient

public double getCoefficient(int index)

Returns the coefficient at the given index.

Returns zero if the index is invalid.

Parameters:

index - the index of the coefficient

setCoefficient

public void setCoefficient(int index,
                           double value)

Sets the coefficient at the given index to 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.

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 absolute value of the coefficients in this polynomial.

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 absolute value less than or equal 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) * epsilon

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

Parameters:

epsilon - the measure of closeness to zero

isEqualTo

public boolean isEqualTo(XPolynomial p)

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

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

Parameters:

p - a polynomial

isAlmostEqualTo

public boolean isAlmostEqualTo(XPolynomial 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 double evaluate(double x)

Returns the value of the polynomial at the given x.

Implements Function.OneArg.

Specified by:

evaluate in interface Function.OneArg

Parameters:

x - the position at which to evaluate the polynomial

setParam

public void setParam(double[] params)

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

Implements Parameter.ArrayParam.

Equivalent to setCoefficients.

Fires property change VALUE.

Specified by:

setParam in interface Parameter.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 XPolynomial as an annotated string.

XPolynomial[c0=...;c1=...;c2=...;etc]

where ... stands for the polynomial coefficients in increasing order from left to right.

The zero polynomial is represented as:

XPolynomial[]

toStringData

public String toStringData()

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

[...;...;...;etc]

where ... stands for 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 XPolynomial 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 XPolynomial 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 XPolynomial 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 XPolynomial scale(double f,
                                XPolynomial p)

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

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

Parameters:

f - a scale factor

p - a polynomial

add

public static XPolynomial add(XPolynomial p,
                              XPolynomial 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 XPolynomial subtract(XPolynomial p,
                                   XPolynomial 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 XPolynomial multiply(XPolynomial p,
                                   XPolynomial 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 XPolynomial[] divide(XPolynomial p,
                                   XPolynomial 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 XPolynomial.

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