edu.neu.ccs
Class XFourier

java.lang.Object
  extended byedu.neu.ccs.XFourier
All Implemented Interfaces:
Function.OneArg, JPTConstants, Serializable, Stringable, SwingConstants

public class XFourier
extends Object
implements Function.OneArg, Stringable, JPTConstants, Serializable

Class XFourier provides an implementation of a fourier series in one real variable with real coefficients.

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

For convenience of data entry, XFourier also implements Stringable.

Conceptually, a fourier series is a sum of three kinds of entities:

The sin series is a sum of products where each product has the form:

s[i] * sin(i * x)

where s[i] is the i-th fourier sin coefficient and i >= 1.

The cos series is structured in a similar way.

This class makes provisions for the input x to be either in RADIANS or DEGREES.

When the sin or cos series are given internally using arrays of double, the 0-th entry in the array is ignored in order to keep the array index and the term index in the trigonometric series synchronized.

On the other hand, when data input is given via the Stringable interface, the user does NOT supply the useless 0-th degree entry in the sin and cos series. The parser makes the transition from the external string format to the internal array conventions.

Since:
2.4.0
Version:
2.4.0
See Also:
Serialized Form

Nested Class Summary
static class XFourier.Type
          The abstract class to define the sin and cos functions for the given input type.
 
Field Summary
protected  SwingPropertyChangeSupport changeAdapter
          Helper object for property change API.
protected  double constant
          The fourier constant term.
protected  double[] cosCoefficients
          The fourier cos coefficients or null if no storage has been allocated.
static XFourier.Type DEGREES
          The type for degrees input.
static XFourier.Type RADIANS
          The type for radians input.
protected  double[] sinCoefficients
          The fourier sin coefficients or null if no storage has been allocated.
static String standardMessage
          The standard error message for fromStringData.
protected  XFourier.Type type
          The fourier type.
 
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
XFourier()
          The constructor that sets the fourier to the zero with type radians.
XFourier(String data)
          The constructor that uses fromStringData to set the fourier coefficients.
XFourier(XFourier.Type type, double constant, double[] sinArray, double[] cosArray)
          The constructor that supplies the type, constant, and array data for the sin and cos coefficients.
XFourier(XFourier fourier)
          Constructs and initializes an XFourier from the specified XFourier object.
 
Method Summary
static XFourier add(XFourier p, XFourier q)
          Returns a new fourier 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.
 void copyFourier(XFourier fourier)
          Sets the data of this fourier to a copy of the data in the given XFourier.
 double evaluate(double x)
          Returns the value of the fourier at the given x.
 void fromStringData(String data)
          Defines the data state for this XFourier object from a String representation of the data state.
 double getConstant()
          Returns the fourier constant.
 int getCosCapacity()
          Returns the capacity of the current internal storage for the cos terms in the fourier series, that is, the largest index into which data may be stored without reallocation.
 double getCosCoefficient(int index)
          Returns the cos coefficient at the given index.
 double[] getCosCoefficients()
          Returns a copy of the fourier cos coefficients.
 int getCosDegree()
          Returns the cos degree of the fourier which is defined to be the highest index whose cos coefficient is non-zero; by convention, the zero fourier has cos degree -1.
 int getSinCapacity()
          Returns the capacity of the current internal storage for the sin terms in the fourier series, that is, the largest index into which data may be stored without reallocation.
 double getSinCoefficient(int index)
          Returns the sin coefficient at the given index.
 double[] getSinCoefficients()
          Returns a copy of the fourier sin coefficients.
 int getSinDegree()
          Returns the sin degree of the fourier which is defined to be the highest index whose sin coefficient is non-zero; by convention, the zero fourier has sin degree -1.
 XFourier.Type getType()
          Returns the XFourier.Type parameter.
private  XFourier.Type getTypeViaString(String string)
          Helper method for getting type from String.
 boolean isAlmostEqualTo(XFourier fourier, double epsilon)
          Returns true if the given fourier is almost equal to this fourier in the sense that all coefficients agree to within the measure epsilon.
 boolean isAlmostZero(double epsilon)
          Returns true if the fourier is almost the zero fourier relative to the measure epsilon, that is, if all of its coefficients have absolute value less than or equal epsilon.
 boolean isEqualTo(XFourier fourier)
          Returns true if the given fourier is equal to this fourier in the sense that all coefficients exactly agree.
 boolean isZero()
          Returns true if the fourier is the zero fourier.
 double maxCoefficient()
          Returns the maximum of the absolute value of the various coefficients in this fourier.
private  void parse4(String[] items)
          Helper method for parsing non-zero fourier.
private  double[] parseFourierCoefficients(String terms, String name)
           
private  double parseFourierConstant(String term)
           
 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 XFourier scale(double f, XFourier fourier)
          Returns a new fourier equivalent mathematically to (f * p), that is, the fourier obtained by multipying each coefficient of p by the scale factor f.
 void setConstant(double constant)
          Sets the fourier constant to the given constant.
 void setCosCapacity(int capacity)
          Sets the capacity for the cos terms of this fourier to the given value except that any negative value will cause the storage to be deallocated and the capacity will be -1.
 void setCosCoefficient(int index, double value)
          Sets the cos coefficient at the given index to the given value.
 void setCosCoefficients(double[] cosArray)
          Sets the cos coefficients of the fourier to a copy of the data in the given array.
 void setFourier(XFourier.Type type, double constant, double[] sinArray, double[] cosArray)
          Sets the fourier to the given parameters.
 void setFourierToZero()
          Sets the fourier to the zero fourier, that is, the fourier that evaluates to zero everywhere.
 void setSinCapacity(int capacity)
          Sets the capacity for the sin terms of this fourier to the given value except that any negative value will cause the storage to be deallocated and the capacity will be -1.
 void setSinCoefficient(int index, double value)
          Sets the sin coefficient at the given index to the given value.
 void setSinCoefficients(double[] sinArray)
          Sets the sin coefficients of the fourier to a copy of the data in the given array.
 void setType(XFourier.Type type)
          Sets the XFourier.Type parameter to determine the RADIANS or DEGREES setting.
 void setTypeViaString(String type)
          Sets the XFourier.Type parameter to determine the RADIANS or DEGREES setting using the given string to signal the type.
 void shrinkCapacity()
          Sets the sin and cos capacity to the minimal possible without loss of information.
static XFourier subtract(XFourier p, XFourier q)
          Returns a new fourier equivalent mathematically to (p - q).
 String toString()
          Returns a human readable String representing the data state of this XFourier as an annotated string.
 String toStringData()
          Returns a human readable String representing the data state of this XFourier 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

RADIANS

public static final XFourier.Type RADIANS

The type for radians input.

The toString method returns "r".


DEGREES

public static final XFourier.Type DEGREES

The type for degrees input.

The toString method returns "d".


type

protected XFourier.Type type
The fourier type.


constant

protected double constant
The fourier constant term.


sinCoefficients

protected double[] sinCoefficients
The fourier sin coefficients or null if no storage has been allocated.


cosCoefficients

protected double[] cosCoefficients
The fourier cos coefficients or null if no storage has been allocated.


changeAdapter

protected SwingPropertyChangeSupport changeAdapter
Helper object for property change API.

Constructor Detail

XFourier

public XFourier()

The constructor that sets the fourier to the zero with type radians.


XFourier

public XFourier(XFourier.Type type,
                double constant,
                double[] sinArray,
                double[] cosArray)

The constructor that supplies the type, constant, and array data for the sin and cos coefficients.

The 0-th index entries in sinArray and cosArray are ignored since no corresponding fourier terms are defined.

Parameters:
type - the type: RADIANS or DEGREES
constant - the fourier constant
sinArray - the array of sin coefficients
cosArray - the array of cos coefficients

XFourier

public XFourier(XFourier fourier)

Constructs and initializes an XFourier from the specified XFourier object.

Parameters:
fourier - the XFourier object to copy

XFourier

public XFourier(String data)
         throws ParseException
The constructor that uses fromStringData to set the fourier coefficients.

Method Detail

setFourierToZero

public void setFourierToZero()

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

Fires property change VALUE.


getType

public XFourier.Type getType()

Returns the XFourier.Type parameter.


setType

public void setType(XFourier.Type type)

Sets the XFourier.Type parameter to determine the RADIANS or DEGREES setting.

If the given type is null, it is set to RADIANS.

Fires property change VALUE.

Parameters:
type - the XFourier.Type parameter

setTypeViaString

public void setTypeViaString(String type)

Sets the XFourier.Type parameter to determine the RADIANS or DEGREES setting using the given string to signal the type.

If the given string is null or has length 0, the type is set to RADIANS.

If the first letter of the given string is 'D' or 'd', the type is set to DEGREES otherwise it is set to RADIANS.

Fires property change VALUE.

Parameters:
type - the XFourier.Type parameter represented as the first character of a string

getTypeViaString

private XFourier.Type getTypeViaString(String string)
Helper method for getting type from String.


getConstant

public double getConstant()

Returns the fourier constant.


setConstant

public void setConstant(double constant)

Sets the fourier constant to the given constant.

Fires property change VALUE.

Parameters:
constant - the fourier constant

getSinDegree

public int getSinDegree()

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


getCosDegree

public int getCosDegree()

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


getSinCapacity

public int getSinCapacity()

Returns the capacity of the current internal storage for the sin terms in the fourier series, that is, the largest index into which data may be stored without reallocation.

Returns -1 if no storage is currently allocated.


getCosCapacity

public int getCosCapacity()

Returns the capacity of the current internal storage for the cos terms in the fourier series, that is, the largest index into which data may be stored without reallocation.

Returns -1 if no storage is currently allocated.


setSinCapacity

public void setSinCapacity(int capacity)

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

If the given capacity is 0, it will also be set to -1 since a fourier series has no degree 0 terms.

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 for sin terms

setCosCapacity

public void setCosCapacity(int capacity)

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

If the given capacity is 0, it will also be set to -1 since a fourier series has no degree 0 terms.

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 for cos terms

shrinkCapacity

public void shrinkCapacity()

Sets the sin and cos capacity to the minimal possible without loss of information.


getSinCoefficients

public double[] getSinCoefficients()

Returns a copy of the fourier sin coefficients.

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

The 0-th index value will be 0 since it is ignored.


getCosCoefficients

public double[] getCosCoefficients()

Returns a copy of the fourier cos coefficients.

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

The 0-th index value will be 0 since it is ignored.


setSinCoefficients

public void setSinCoefficients(double[] sinArray)

Sets the sin coefficients of the fourier to a copy of the data in the given array.

The 0-th index array value will be ignored.

Fires property change VALUE.

Parameters:
sinArray - the array of fourier sin coefficients to copy

setCosCoefficients

public void setCosCoefficients(double[] cosArray)

Sets the cos coefficients of the fourier to a copy of the data in the given array.

The 0-th index array value will be ignored.

Fires property change VALUE.

Parameters:
cosArray - the array of fourier cos coefficients to copy

getSinCoefficient

public double getSinCoefficient(int index)

Returns the sin coefficient at the given index.

Returns zero if the index is invalid.


getCosCoefficient

public double getCosCoefficient(int index)

Returns the cos coefficient at the given index.

Returns zero if the index is invalid.


setSinCoefficient

public void setSinCoefficient(int index,
                              double value)

Sets the sin coefficient at the given index to the given value.

Does nothing if the index is less than one.

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

setCosCoefficient

public void setCosCoefficient(int index,
                              double value)

Sets the cos coefficient at the given index to the given value.

Does nothing if the index is less than one.

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 various coefficients in this fourier.


setFourier

public void setFourier(XFourier.Type type,
                       double constant,
                       double[] sinArray,
                       double[] cosArray)

Sets the fourier to the given parameters.

Fires property change VALUE.

Parameters:
type - the type: RADIANS or DEGREES
constant - the fourier constant
sinArray - the array of sin coefficients
cosArray - the array of cos coefficients

copyFourier

public void copyFourier(XFourier fourier)

Sets the data of this fourier to a copy of the data in the given XFourier.

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

Fires property change VALUE.

Parameters:
fourier - the XFourier object to copy

isZero

public boolean isZero()
Returns true if the fourier is the zero fourier.


isAlmostZero

public boolean isAlmostZero(double epsilon)

Returns true if the fourier is almost the zero fourier 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 fourier has sin degree d and cos degree e and is almost zero to within epsilon, then for all values of x:

evaluate(x) <= (d + e + 1) * epsilon

In other words, a fourier that is almost zero to within epsilon has quite small values for all x.

Parameters:
epsilon - the measure of closeness to zero

isEqualTo

public boolean isEqualTo(XFourier fourier)

Returns true if the given fourier is equal to this fourier in the sense that all coefficients exactly agree.

If the given fourier is null then returns false.

If the type of the given fourier is not equal to the type of this fourier then returns false.

This method is not called equals in order to avoid redefinition of the default hashCode method.

Parameters:
fourier - a fourier

isAlmostEqualTo

public boolean isAlmostEqualTo(XFourier fourier,
                               double epsilon)

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

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

If the given fourier is null then returns false.

If the type of the given fourier is not equal to the type of this fourier then returns false.

Parameters:
fourier - a fourier
epsilon - the measure of closeness

evaluate

public double evaluate(double x)

Returns the value of the fourier at the given x.

Implements Function.OneArg.

If the current type is RADIANS, use x in radians.

If the current type is DEGREES, use x in degrees.

Specified by:
evaluate in interface Function.OneArg
Parameters:
x - the position at which to evaluate the fourier

toString

public String toString()

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

XFourier{type|constant|[s1=...;s2=...;etc]|[c1=...;c2=...;etc]}

where:

The zero fourier is represented as:

XFourier{type}

since the type must be designated regardless.


toStringData

public String toStringData()

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

{type|constant|[...;...]|[...;...]}

where:

The zero fourier is represented as:

{type}

since the type must be designated regardless.

Specified by:
toStringData in interface Stringable
See Also:
Stringable.fromStringData(String)

fromStringData

public void fromStringData(String data)
                    throws ParseException

Defines the data state for this XFourier 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 si= or ci= and reads only the fourier coefficient data from index 1 on up in each case.

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

parse4

private void parse4(String[] items)
             throws ParseException

Helper method for parsing non-zero fourier.

Parameters:
items - the array of the 4 main fourier terms
Throws:
ParseException

parseFourierConstant

private double parseFourierConstant(String term)
                             throws ParseException
Throws:
ParseException

parseFourierCoefficients

private double[] parseFourierCoefficients(String terms,
                                          String name)
                                   throws ParseException
Throws:
ParseException

scale

public static XFourier scale(double f,
                             XFourier fourier)

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

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

Parameters:
f - a scale factor
fourier - a fourier

add

public static XFourier add(XFourier p,
                           XFourier q)

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

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

If p and q do not have the same type, an exception is thrown.

Parameters:
p - a fourier
q - a fourier

subtract

public static XFourier subtract(XFourier p,
                                XFourier q)

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

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

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

If p and q do not have the same type, an exception is thrown.

Parameters:
p - a fourier
q - a fourier

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