edu.neu.ccs
Class XFourier

java.lang.Object
  edu.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:

• a constant term
• a series of sin terms
• a series of cos terms

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:

• type is the letter r or d for radians or degrees
• constant is the fourier constant term
• the next terms are the sin coefficients starting at index 1
• the next terms are the cos coefficients starting at index 1

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:

• type is the letter r or d for radians or degrees
• constant is the fourier constant term
• the next terms are the sin coefficients starting at index 1
• the next terms are the cos coefficients starting at index 1

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