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 Description

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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	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.
`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".
- 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.
  - 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.

Class SmoothToken

Field Summary

Fields inherited from class ptolemy.data.DoubleToken

Fields inherited from class ptolemy.data.ScalarToken

Constructor Summary

Method Summary

Methods inherited from class ptolemy.data.DoubleToken

Methods inherited from class ptolemy.data.ScalarToken

Methods inherited from class ptolemy.data.Token

Methods inherited from class java.lang.Object

Field Detail

NIL

Constructor Detail

SmoothToken

SmoothToken

SmoothToken

SmoothToken

SmoothToken

SmoothToken

Method Detail

align

align

derivativeValue

derivativeValues

equals

extrapolate

getOrderLimit

getTime

hashCode

isNil

maxOrder

negate

order

setOrderLimit

smoothToken

smoothToken

toString

_add

_divide

_isClose

_isCloseTo

_isLessThan

_multiply

_multiplyPolynomials

_subtract