ptolemy.actor.util
Class Time

java.lang.Object
  ptolemy.actor.util.Time

All Implemented Interfaces:

java.lang.Comparable

public class Time
extends java.lang.Object
implements java.lang.Comparable

An object of the Time class represents model time, as distinct from "wall-clock time," which is time in the physical world. An instance of Time has a value that is immutable. It has no limit on the magnitude. There are two time constants: NEGATIVE_INFINITY and POSITIVE_INFINITY.

The time value is quantized to the time resolution specified by the timeResolution parameter of the associated director. The reason for this is that without quantization, it is extremely difficult to compare two time values with digit-to-digit accuracy because of the unpredictable numerical errors introduced during computation. In practice, two time values can only be distinguished if their difference can be detected by some measuring instrument, which always has a smallest unit for measurement. This smallest unit measurement gives the physical meaning of the time resolution used for quantization.

The time value can be retrieved in three ways, the toString()method and the getDoubleValue()method and the getLongValue() method. The first method returns a string representation while the second method returns a double value. There are some limitations on both methods. For the toString() method, we can not directly do numerical operations on strings. For the getDoubleValue() method, we can not guarantee that the returned double value preserves the time resolution because of the limited digits for double representation. We recommend to operate on time objects directly instead of the time values of time objects. getLongValue() returns an integer multiple of the director resolution.

Two operations, add and subtract, can be performed on a time object, where the argument can be a double or a time object. If the argument is not a time object, the argument is quantized before the operations are performed. These operations return a new time object with a quantized result.

The time value of a time object can be infinite. The add and subtract operations on infinite time values follow rules similar to the IEEE Standard 754 for Floating Point Numbers. In particular, adding two positive/negative infinities yield a positive/negative infinity; adding a positive infinity and a negative infinity, however, triggers an ArithmeticException; the negation of a positive/negative infinity is a negative/positive infinity. The following link gives a list of operations, http://en.wikipedia.org/wiki/Infinity.

This class implements the Comparable interface, where two time objects can be compared in the following way. If any of the two time objects contains an infinite time value, the rules are: a negative infinity is equal to a negative infinity and less than anything else; a positive infinity is equal to a positive infinity and bigger than anything else. If none of the time objects has an infinite time value, the time values of two time objects are compared. If the time values are the same, the two time objects are treated equal, or they represent the same model time. Otherwise, the time object containing a bigger time value is regarded to happen after the time object with a smaller time value.

All time objects share the same time resolution, which is provided by the top-level director. In some domains, such as CT and DE, users can change the time resolution by configuring the timeResolution parameter. The default value for this parameter "1E-10", which has value 10 ^-10 . To preserve the consistency of time values, timeResolution can not be changed when a model is running (attempting to do so will trigger an exception).

Since:

Ptolemy II 4.1

Version:

$Id: Time.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Haiyang Zheng, Edward A. Lee, Elaine Cheong

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Yellow (hyzheng)

Field Summary

private Director	_director The director that this time object is associated with.
private boolean	_isNegativeInfinite A boolean variable is true if the time value is a negative infinity.
private boolean	_isPositiveInfinite A boolean variable is true if the time value is a positive infinity.
private static int	_NEGATIVE_INFINITY
private static int	_POSITIVE_INFINITY
private java.math.BigInteger	_timeValue The time value, as a multiple of the resolution.
static Time	NEGATIVE_INFINITY A static and final time constant holding a negative infinity.
static Time	POSITIVE_INFINITY A static and final time constant holding a positive infinity.

Constructor Summary

	Time(Director director) Construct a Time object with zero as the time value.
private	Time(Director director, java.math.BigInteger timeValue) Construct a Time object with the specified BigInteger value as its time value (as a multiple of the precision).
	Time(Director director, double timeValue) Construct a Time object with the specified double value as its time value.
	Time(Director director, long timeValue) Construct a Time object with the specified long value as its time value.
private	Time(int value) Construct a Time object with value that is one of _POSITIVE_INFINITY or _NEGATIVE_INFINITY.

Method Summary

private java.math.BigInteger	_doubleToMultiple(double value) Given a double, return the BigInteger that represents its quantized value.
protected double	_timeResolution() Return the time resolution for this Time object, which in this class is the time resolution of the director given in the constructor.
Time	add(double timeValue) Return a new time object whose time value is increased by the given double value.
Time	add(Time time) Return a new time object whose time value is the sum of that of this time object and of the specified time object.
int	compareTo(java.lang.Object time) Return -1, 0, or 1 if this time object is less than, equal to, or greater than the given argument.
boolean	equals(java.lang.Object time) Return true if this time object has the same time value as that of the given time object.
double	getDoubleValue() Return the double representation of the time value of this time object.
long	getLongValue() Return the long representation of the time value of this time object.
int	hashCode() Return the hash code for the time object.
boolean	isInfinite() Return true if the current time value is infinite.
boolean	isNegativeInfinite() Return true if the current time value is a negative infinity.
boolean	isPositiveInfinite() Return true if the current time value is a positive infinity.
double	maximumAccurateValueAsDouble() Return the maximum value of time whose representation as a double is always accurate to the specified time resolution.
Time	subtract(double timeValue) Return a new time object whose time value is decreased by the given double value.
Time	subtract(Time time) Return a new time object whose time value is decreased by the time value of the specified time object.
java.lang.String	toString() Return the string representation of this time object.

Methods inherited from class java.lang.Object

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

Field Detail

_NEGATIVE_INFINITY

private static int _NEGATIVE_INFINITY

_POSITIVE_INFINITY

private static int _POSITIVE_INFINITY

NEGATIVE_INFINITY

public static final Time NEGATIVE_INFINITY

A static and final time constant holding a negative infinity.

POSITIVE_INFINITY

public static final Time POSITIVE_INFINITY

A static and final time constant holding a positive infinity.

_director

private Director _director

The director that this time object is associated with.

_isPositiveInfinite

private boolean _isPositiveInfinite

A boolean variable is true if the time value is a positive infinity. By default, it is false.

_isNegativeInfinite

private boolean _isNegativeInfinite

A boolean variable is true if the time value is a negative infinity. By default, it is false.

_timeValue

private java.math.BigInteger _timeValue

The time value, as a multiple of the resolution.

Constructor Detail

Time

public Time(Director director)

Construct a Time object with zero as the time value. This object is associated with the given director, which provides the necessary information for quantization.

Parameters:

director - The director with which this time object is associated. This must not be null, or subsequent uses of the class will fail.

Time

public Time(Director director,
            double timeValue)
     throws IllegalActionException

Construct a Time object with the specified double value as its time value. The specified director provides the resolution that is used to quantize the double value so that the value of the resulting Time object is a multiple of the precision.

Parameters:

director - The director with which this time object is associated.

timeValue - A double value as the specified time value.

Throws:

java.lang.ArithmeticException - If the argument is NaN.

IllegalActionException - If the given double time value does not match the time resolution.

Time

public Time(Director director,
            long timeValue)

Construct a Time object with the specified long value as its time value.

Parameters:

director - The director with which this time object is associated.

timeValue - A long value as the specified time value, as a multiple of the resolution.

Time

private Time(Director director,
             java.math.BigInteger timeValue)

Construct a Time object with the specified BigInteger value as its time value (as a multiple of the precision). The time object is associated with the given director, which provides the necessary information for quantization. This constructor is private and can only be accessed by the methods defined inside this class.

Parameters:

director - The director with which this time object is associated.

timeValue - The multiple of the precsision that is the time value.

Time

private Time(int value)

Construct a Time object with value that is one of _POSITIVE_INFINITY or _NEGATIVE_INFINITY.

Parameters:

value - One of _POSITIVE_INFINITY or _NEGATIVE_INFINITY.

Method Detail

add

public Time add(double timeValue)

Return a new time object whose time value is increased by the given double value. The specified double value is quantized to a multiple of the precision before it is added.

Parameters:

timeValue - The amount of the time increment.

Returns:

A new time object with the incremented time value.

Throws:

java.lang.ArithmeticException - If the result is not a valid number (the argument is NaN or the sum would be), or the given time value does not match the time resolution.

add

public Time add(Time time)

Return a new time object whose time value is the sum of that of this time object and of the specified time object. The two time objects are expected to have directors with the same time resolution. If they do not, then the returned result is a new Time object representing the sum of the double values of the two Time objects. This would not be as accurate.

Parameters:

time - The time object contains the amount of time increment.

Returns:

A new time object with the quantized and incremented time value.

Throws:

java.lang.ArithmeticException - If the result is not a valid number (it is the sum of positive and negative infinity).

compareTo

public int compareTo(java.lang.Object time)

Return -1, 0, or 1 if this time object is less than, equal to, or greater than the given argument. Note that a ClassCastException will be thrown if the argument is not an instance of Time. This object expects the directors associated with this and the specified Time objects to have the same time resolution. If this is not the case, then it compares the double representations of those time values, which is not as accurate.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

time - A time object to compare to.

Returns:

The integer -1, 0, or 1 if this is less than, equal to, or greater than the argument.

equals

public boolean equals(java.lang.Object time)

Return true if this time object has the same time value as that of the given time object.

Overrides:

equals in class java.lang.Object

Parameters:

time - The time object that this time object is compared to.

Returns:

True if the two time objects have the same time value.

getDoubleValue

public double getDoubleValue()

Return the double representation of the time value of this time object. Note that the returned result is not necessarily as accurate as the internal representation. In particular, if the internal representation is too large, then then the returned result may be infinite. In addition, if the magnitude of the retuned number is large relative to the time resolution of the associated director, then the result may be inaccurate by more than the time resolution.

Returns:

The double representation of the time value.

getLongValue

public long getLongValue()

Return the long representation of the time value of this time object. The long representation is a multiple of the resolution of the associated director. Note that a Time value of positive infinity will return Long.MAX_VALUE and a Time value of negative infinity will return Long.MIN_VALUE.

Returns:

The long representation of the time value.

hashCode

public int hashCode()

Return the hash code for the time object. If two time objects contains the same quantized time value, they have the same hash code. Note that the quantization is performed on the time value before calculating the hash code.

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code for the time object.

isInfinite

public final boolean isInfinite()

Return true if the current time value is infinite.

Returns:

true if the current time value is infinite.

isNegativeInfinite

public final boolean isNegativeInfinite()

Return true if the current time value is a negative infinity.

Returns:

true if the current time value is a negative infinity.

isPositiveInfinite

public final boolean isPositiveInfinite()

Return true if the current time value is a positive infinity.

Returns:

true if the current time value is a positive infinity.

maximumAccurateValueAsDouble

public double maximumAccurateValueAsDouble()

Return the maximum value of time whose representation as a double is always accurate to the specified time resolution. In other words, if you ask this instance of Time for its value as a double, if the returned double is larger than the number returned by this method, then the double representation is not necessarily accurate to the specified resolution.

Returns:

The maximum value of time above which the double representation may not be accurate to the specified resolution.

subtract

public Time subtract(double timeValue)

Return a new time object whose time value is decreased by the given double value. Quantization is performed on both the timeValue argument and the result.

Parameters:

timeValue - The amount of time decrement.

Returns:

A new time object with time value decremented.

subtract

public Time subtract(Time time)

Return a new time object whose time value is decreased by the time value of the specified time object. This method assumes that the two time values have directors with the same time resolution. If this is not the case, then the result is a new Time object whose value is constructed from the difference between the double values for this and the specified Time objects, using the time resolution of the director of this one.

Parameters:

time - The time object contains the amount of time decrement.

Returns:

A new time object with time value decremented.

toString

public java.lang.String toString()

Return the string representation of this time object. This is actually an approximation generated by first converting to a double. Note that the string representation of infinities can not be used to construct the time objects containing infinite time values.

Overrides:

toString in class java.lang.Object

Returns:

A String representation of this time object.

_timeResolution

protected double _timeResolution()

Return the time resolution for this Time object, which in this class is the time resolution of the director given in the constructor. This is a protected method to allow subclasses to use their own time resolution.

Returns:

The time resolution of the director.

_doubleToMultiple

private java.math.BigInteger _doubleToMultiple(double value)
                                        throws IllegalActionException

Given a double, return the BigInteger that represents its quantized value. The BigInteger is the rounded result of dividing the double by the time resolution.

Parameters:

value - The value as a double.

Returns:

A BigInteger that specifies this double value as a multiple of the resolution given by the associated director.

Throws:

IllegalActionException - If the given double time value does not match the time resolution.