ptolemy.data

Class SmoothToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.ScalarToken

ptolemy.data.DoubleToken

ptolemy.data.SmoothToken

All Implemented Interfaces:

BitwiseOperationToken, PartiallyOrderedToken

public class SmoothToken
extends DoubleToken

A double-valued token that contains zero or more derivatives, representing the value of a function of time at a particular time. In mathematical analysis, smoothness has to do with how many derivatives a function possesses. A smooth function is one that has derivatives of all orders everywhere in its domain. An instance of this class represents a sample of a function at a point in time together with some finite number of derivatives of the function at that same point.

This token will be treated exactly like a DoubleToken by any actor or operation that does not specifically support it, and it will be represented in the type systems as a "double." But it can (potentially) carry additional information giving one or more derivatives of the function from which it is a sample and giving the time at which it represents a sample of the signal. This token, therefore, gives a way for actors that either generate or use this derivative information to make that information available to other actors that can use it. Such actors should declare their input ports to be of type double, but when they receive an input token, they should check (using instanceof) whether the token is a SmoothToken, and if so, access these derivatives using the derivativeValues() method, or extrapolate the value to a specified time using the extrapolate(Time) method.

Note that if two SmoothTokens are added or subtracted, then the derivatives also add or subtract. If the times of the two tokens that are added or subtracted are not the same, then the one with the lesser time is extrapolated to the larger time, and the result will be the sum at the later time. If a SmoothToken is added to a DoubleToken, the derivatives of the DoubleToken are assumed to be zero, and similarly for subtraction.

If a SmoothToken is multiplied by a SmoothToken, then the product rule of calculus is used to determine the derivatives of the product. The product rule stipulates that

      (xy)' = x'y + xy'
   

Again, if the times of the two tokens are not equal, then the one with the lesser time will be extrapolated to the larger time before being multiplied, and the time of the result will be the larger time. If a SmoothToken is multiplied by a DoubleToken, then the derivatives of the DoubleToken are assumed to be zero.

Division works similarly:

      (x/y)' = x'/y + x(1/y)' = x'/y - xy'/y^2
   

where the last equality follows from the reciprocal rule of calculus. The second derivative of a multiplication or division is obtained by applying the above rules to x' and y' rather than to x and y. Higher-order derivatives are similarly obtained.

You can construct an instance of this token in the Ptolemy expression language using the smoothToken(double, double, {double}) function. The first argument specifies the value, and the second argument specifies the time, and the third specifies the derivatives. Also provided in the expression language are one and two argument versions of this function that assume the time is zero. These should be used only during initialization, and only if the start time of the model is actually zero.

By default, instances of SmoothToken have no more than three derivatives. This can be changed using the setOrderLimit(int) method.

FIXME: Division is not implemented yet.

Since:

Ptolemy II 11.0

Version:

$Id$

Author:

Thierry S. Nouidui, Michael Wetter, Edward A. Lee

Pt.AcceptedRating:

Red (mw)

Pt.ProposedRating:

Red (mw)

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static int	_maxOrder
static SmoothToken	NIL A token that represents a missing value.

Fields inherited from class ptolemy.data.DoubleToken

_value, ONE, ZERO

Fields inherited from class ptolemy.data.ScalarToken

_unitCategoryExponents

Constructor Summary

Constructors

Constructor and Description
SmoothToken() Construct a SmoothToken with value 0.0 at time zero and no derivatives.
SmoothToken(double value) Construct a SmoothToken with the specified value at time zero and no derivatives.
SmoothToken(double[] x, Time time) Construct a SmoothToken with the specified value and derivatives, given as a single array, at the specified time.
SmoothToken(double value, double[] derivatives) Construct a SmoothToken with the specified value at time zero and the specified derivatives.
SmoothToken(double value, Time time, double[] derivatives) Construct a SmoothToken with the specified value at the specified time, and with the specified derivatives.
SmoothToken(java.lang.String init) Construct a SmoothToken from the specified string, which specifies only a value.

Method Summary

Modifier and Type	Method and Description
protected ScalarToken	_add(ScalarToken rightArgument) Return a new token whose value is the value of the argument Token added to the value of this Token.
protected ScalarToken	_divide(ScalarToken divisor) Return a new token whose value is the value of this token divided by the value of the argument token.
protected boolean	_isClose(double arg1, double arg2, double epsilon) Return true if the two arguments are within epsilon of one another.
protected BooleanToken	_isCloseTo(ScalarToken rightArgument, double epsilon) Test that the value of this token is close to the first argument, where "close" means that the distance between their values is less than or equal to the second argument.
protected BooleanToken	_isLessThan(ScalarToken rightArgument) Test for ordering of the values of this Token and the argument Token.
protected ScalarToken	_multiply(ScalarToken rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument token.
protected static double[]	_multiplyPolynomials(double[] p1, double[] p2) Multiply two polynomials.
protected ScalarToken	_subtract(ScalarToken rightArgument) Return a new token whose value is the value of the argument token subtracted from the value of this token.
(package private) SmoothToken[]	align(SmoothToken arg1, SmoothToken arg2) Given two SmoothTokens, align them by finding the maximum time of the tokens, extrapolating the other token to that time, and returning an array of tokens with the extrapolated values and derivatives.
static Token[]	align(Token[] args) Given an array of Tokens, align them by finding the maximum time of all the tokens, extrapolating all tokens that are instances of SmoothToken to that time, and returning an array of tokens with the extrapolated values and derivatives.
static Token[]	align(Token[] args, Time time) Given an array of Tokens and a time, align them by extrapolating all tokens that are instances of SmoothToken to that time, and returning an array of tokens with the extrapolated values and derivatives.
static double	derivativeValue(DoubleToken token, int n) Return the n-th derivative of the specified token.
double[]	derivativeValues() Return the derivatives of the token as a double[], or null if there are no derivatives.
boolean	equals(java.lang.Object object) Return true if the argument's class is SmoothToken and it has the same value and derivatives as this token.
SmoothToken	extrapolate(Time time) Return a SmoothToken at the specified time whose value and derivatives are the result of extrapolating this token to the specified time.
static int	getOrderLimit() Get the maximum order of any token (the number of derivatives).
Time	getTime() Return the time for which the values of this smooth token are valid.
int	hashCode() Return the hash code for the SmoothToken object.
boolean	isNil() Return true if the token is nil, (aka null or missing).
static int	maxOrder(DoubleToken arg1, DoubleToken arg2) Return the maximum number of specified derivatives for the two tokens.
SmoothToken	negate() Return a new token that is the negative of this one.
static int	order(DoubleToken token) Return the number of specified derivatives for the token.
static void	setOrderLimit(int maxOrder) Set the maximum order of any token (the number of derivatives).
static SmoothToken	smoothToken(double value) Return a SmoothToken with the specified value at time zero and no derivatives.
static SmoothToken	smoothToken(double value, double[] derivatives) Return a SmoothToken with the specified value at time zero and derivatives.
java.lang.String	toString() Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value and derivatives.

Methods inherited from class ptolemy.data.DoubleToken

_absolute, _bitwiseAnd, _bitwiseNot, _bitwiseOr, _bitwiseXor, _modulo, complexValue, convert, doubleValue, getType, one, zero

Methods inherited from class ptolemy.data.ScalarToken

_addCategoryExponents, _areUnitsEqual, _copyOfCategoryExponents, _isEqualTo, _isUnitless, _subtractCategoryExponents, absolute, add, addReverse, bitwiseAnd, bitwiseNot, bitwiseOr, bitwiseXor, byteValue, divide, divideReverse, fixValue, floatValue, intValue, inUnitsOf, isCloseTo, isEqualTo, isGreaterThan, isLessThan, isLessThan, leftShift, logicalRightShift, longValue, modulo, moduloReverse, multiply, multiplyReverse, rightShift, setUnitCategory, shortValue, subtract, subtractReverse, unitsString

Methods inherited from class ptolemy.data.Token

isCloseTo, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, pow, zeroReturnType

Methods inherited from class java.lang.Object

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

Field Detail

NIL

public static final SmoothToken NIL

A token that represents a missing value. Null or missing tokens are common in analytical systems like R and SAS where they are used to handle sparsely populated data sources. In database parlance, missing tokens are sometimes called null tokens. Since null is a Java keyword, we use the term "nil". The toString() method on a nil token returns the string "nil".

_maxOrder

static int _maxOrder

Constructor Detail

SmoothToken

public SmoothToken()

Construct a SmoothToken with value 0.0 at time zero and no derivatives.

SmoothToken

public SmoothToken(double value)

Construct a SmoothToken with the specified value at time zero and no derivatives.

Parameters:

value - The specified value.

SmoothToken

public SmoothToken(double value,
                   double[] derivatives)

Construct a SmoothToken with the specified value at time zero and the specified derivatives. This constructor does not copy the derivatives argument, so it is up to the caller to ensure that the array passed in does not later get modified (tokens are required to be immutable).

Parameters:

value - The specified value.

derivatives - The specified derivatives.

SmoothToken

public SmoothToken(double value,
                   Time time,
                   double[] derivatives)

Construct a SmoothToken with the specified value at the specified time, and with the specified derivatives. This constructor copies the derivatives argument, so the caller is free to modify it (tokens are required to be immutable).

Parameters:

value - The specified value.

time - The specified time.

derivatives - The specified derivatives.

SmoothToken

public SmoothToken(double[] x,
                   Time time)

Construct a SmoothToken with the specified value and derivatives, given as a single array, at the specified time. This constructor copies the data from argument, so the caller is free to modify the array after this method returns.

Parameters:

x - An array where the first element is the value, and optionally any other elements can be present to specify the first, second, etc. derivatives.

time - The time at which this token is a sample.

SmoothToken

public SmoothToken(java.lang.String init)
            throws IllegalActionException

Construct a SmoothToken from the specified string, which specifies only a value. The resulting token will have no derivatives and will represent a sample at time zero.

Parameters:

init - The initialization string, which is in a format suitable for java.lang.Double.parseDouble(String).

Throws:

IllegalActionException - If the Token could not be created with the given String.

Method Detail

align

public static Token[] align(Token[] args,
                            Time time)

Given an array of Tokens and a time, align them by extrapolating all tokens that are instances of SmoothToken to that time, and returning an array of tokens with the extrapolated values and derivatives. If any of the tokens is not a SmoothToken, it is returned unmodified in the result. The returned array will have the same size as the argument array, and all the tokens will have the same maximum time.

Parameters:

args - The tokens to be aligned.

time - The Time to which the tokens will be aligned.

Returns:

An array of aligned tokens.

align

public static Token[] align(Token[] args)

Given an array of Tokens, align them by finding the maximum time of all the tokens, extrapolating all tokens that are instances of SmoothToken to that time, and returning an array of tokens with the extrapolated values and derivatives. If any of the tokens is not a SmoothToken, it is returned unmodified in the result. The returned array will have the same size as the argument array, and all the tokens will have the same maximum time.

Parameters:

args - The tokens to be aligned.

Returns:

An array of aligned tokens.

align

SmoothToken[] align(SmoothToken arg1,
                    SmoothToken arg2)

Given two SmoothTokens, align them by finding the maximum time of the tokens, extrapolating the other token to that time, and returning an array of tokens with the extrapolated values and derivatives. The returned array will have size 2, and all the tokens will have the same maximum time.

Parameters:

arg1 - The first SmoothToken to be aligned.

arg2 - The second SmoothToken to be aligned.

Returns:

An array of tokens with the extrapolated values and derivatives.

derivativeValue

public static final double derivativeValue(DoubleToken token,
                                           int n)

Return the n-th derivative of the specified token. If no n-th derivative has been specified, return 0.0. If n is 0 or negative, just return the value.

Parameters:

token - The token.

n - The order of the desired derivative.

Returns:

The value of n-th derivatives of this token.

derivativeValues

public double[] derivativeValues()

Return the derivatives of the token as a double[], or null if there are no derivatives. Since tokens are immutable, the caller of this method must copy the returned array if it intends to modify the array.

Returns:

The value of the derivatives contained in this token.

equals

public boolean equals(java.lang.Object object)

Return true if the argument's class is SmoothToken and it has the same value and derivatives as this token. Note that this ignores the time of the tokens. This is needed to be able to use this in tests.

Overrides:

equals in class DoubleToken

Parameters:

object - An object to compare for equality.

Returns:

True if the argument is a SmoothToken with the same value and derivatives. If either this object or the argument is a nil Token, return false.

extrapolate

public SmoothToken extrapolate(Time time)

Return a SmoothToken at the specified time whose value and derivatives are the result of extrapolating this token to the specified time.

Parameters:

time - The time to which to extrapolate this token.

Returns:

A SmoothToken at the specified time.

getOrderLimit

public static int getOrderLimit()

Get the maximum order of any token (the number of derivatives). E.g., if maxOrder = 2, the token will have one value, the first and the 2nd derivative. By default, tokens will have maxOrder = 3.

Returns:

the maximum order.

See Also:

setOrderLimit(int)

getTime

public Time getTime()

Return the time for which the values of this smooth token are valid.

Returns:

The time of this token.

hashCode

public int hashCode()

Return the hash code for the SmoothToken object. If two SmoothToken objects have the same double value and their derivatives have the same hashCode, then the two SmoothTokens will have the same hashcode.

Overrides:

hashCode in class DoubleToken

Returns:

The hash code for this SmoothToken object.

isNil

public boolean isNil()

Return true if the token is nil, (aka null or missing). Nil or missing tokens occur when a data source is sparsely populated.

Overrides:

isNil in class DoubleToken

Returns:

True if the token is the NIL token.

maxOrder

public static final int maxOrder(DoubleToken arg1,
                                 DoubleToken arg2)

Return the maximum number of specified derivatives for the two tokens.

Parameters:

arg1 - The first token.

arg2 - The second token.

Returns:

The maximum of the number of derivatives specified.

negate

public SmoothToken negate()

Return a new token that is the negative of this one.

Returns:

The negative, where all the derivatives are also negated.

order

public static final int order(DoubleToken token)

Return the number of specified derivatives for the token.

Parameters:

token - The token.

Returns:

The number of derivatives specified.

setOrderLimit

public static void setOrderLimit(int maxOrder)

Set the maximum order of any token (the number of derivatives). This is static, so calling it will affect all instances of SmoothToken in the same JVM. Its effect is not even limited to a single Ptolemy model. E.g., if maxOrder = 2, the token will have one value, the first and the 2nd derivative. By default, tokens will have maxOrder = 3. The maxOrder must be non-negative.

Parameters:

maxOrder - The maximum order of the token.

See Also:

getOrderLimit()

smoothToken

public static SmoothToken smoothToken(double value)

Return a SmoothToken with the specified value at time zero and no derivatives. This function gets registered by PtParser, after which it becomes available in the expression language. Note that there is no way in the expression language to construct a SmoothToken with a time other than zero. This makes sense because usually expressions are evaluated only once when a model is opened.

Parameters:

value - The value.

Returns:

The SmoothToken with the specified value at time zero and no derivatives.

smoothToken

public static SmoothToken smoothToken(double value,
                                      double[] derivatives)

Return a SmoothToken with the specified value at time zero and derivatives. This function gets registered by PtParser, after which it becomes available in the expression language. Note that there is no way in the expression language to construct a SmoothToken with a time other than zero. This makes sense because usually expressions are evaluated only once when a model is opened.

Parameters:

value - The value.

derivatives - An array containing the first derivative, the second derivative, etc.

Returns:

The SmoothToken with the specified value at time zero and derivatives.

toString

public java.lang.String toString()

Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value and derivatives. However, the parsed token will not have the same time. It will have time zero. If there are no derivatives, then this just returns what the superclass returns to represent a double. Otherwise, the returned string has the form "smoothToken(value, derivatives)", where the value is the value returned by DoubleToken.doubleValue(), and derivatives is an array of doubles.

Overrides:

toString in class DoubleToken

Returns:

A String representing the double value and the units (if any) of this token.

See Also:

ScalarToken.unitsString()

_add

protected ScalarToken _add(ScalarToken rightArgument)

Return a new token whose value is the value of the argument Token added to the value of this Token. The argument is guaranteed to be either a DoubleToken or a SmoothToken by the caller. If the argument is a DoubleToken, then its value is simply added to the value of this token, and a new SmoothToken is returned with the sum value, time, and the derivatives of this token. If the argument is a SmoothToken, then this token and the argument are first aligned using align(SmoothToken, SmoothToken), and then added. The returned SmoothToken will have the maximum of the number of derivatives of this token and the derivatives of the argument, and for derivatives given by both tokens, the derivative will be the sum of the two derivatives. The time of the returned token will be the maximum of the time of this token and the argument.

Overrides:

_add in class DoubleToken

Parameters:

rightArgument - The token to add to this token.

Returns:

A new SmoothToken containing the result.

_divide

protected ScalarToken _divide(ScalarToken divisor)

Return a new token whose value is the value of this token divided by the value of the argument token. It is assumed that the type of the argument is a SmoothToken

Overrides:

_divide in class DoubleToken

Parameters:

divisor - The token to divide this token by.

Returns:

A new SmoothToken containing the result.

_isClose

protected final boolean _isClose(double arg1,
                                 double arg2,
                                 double epsilon)

Return true if the two arguments are within epsilon of one another.

Parameters:

arg1 - First argument.

arg2 - Second argument.

epsilon - The maximum difference.

Returns:

true if the two arguments are within epsilon of one another.

_isCloseTo

protected BooleanToken _isCloseTo(ScalarToken rightArgument,
                                  double epsilon)

Test that the value of this token is close to the first argument, where "close" means that the distance between their values is less than or equal to the second argument. It is assumed that the type of the first argument is DoubleToken. Here, "close" also means that the derivatives have to be close.

Overrides:

_isCloseTo in class DoubleToken

Parameters:

rightArgument - The token to compare to this token.

epsilon - The distance.

Returns:

A token containing tue if the value of this token is close to that of the argument.

_isLessThan

protected BooleanToken _isLessThan(ScalarToken rightArgument)
                            throws IllegalActionException

Test for ordering of the values of this Token and the argument Token. It is assumed that the type of the argument is SmoothToken.

Overrides:

_isLessThan in class DoubleToken

Parameters:

rightArgument - The token to compare to this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_multiply

protected ScalarToken _multiply(ScalarToken rightArgument)

Return a new token whose value is the value of this token multiplied by the value of the argument token. The derivatives of the result are calculated using the product rule. The argument is assumed to be a DoubleToken. It may also be a SmoothToken.

Overrides:

_multiply in class DoubleToken

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new SmoothToken containing the result.

_multiplyPolynomials

protected static double[] _multiplyPolynomials(double[] p1,
                                               double[] p2)

Multiply two polynomials.

Parameters:

p1 - First polynomial.

p2 - Second polynomial

Returns:

The product of the polynomials

_subtract

protected ScalarToken _subtract(ScalarToken rightArgument)

Return a new token whose value is the value of the argument token subtracted from the value of this token. It is assumed that the type of the argument is a DoubleToken.

Overrides:

_subtract in class DoubleToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new SmoothToken containing the result.