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 time in a model. An instance of Time has a value that is immutable. It has no limit on the magnitude, and it does not lose resolution as the magnitude increases. 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. There are three exceptions that do not really need a notion of time resolution, ZERO, POSITIVE_INFINITY, and NEGATIVE_INFINITY. These are provided as static fields, and normally these should be the only instances of Time constructed without a director.

This implementation of Time does not lose resolution as the magnitude of the time increases (unlike floating point numbers). This is because Time is represented internally as a multiple of the resolution, and the multiple is not constrained to any limited magnitude.

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 cannot 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 or negative infinities yield a positive or negative infinity; adding a positive infinity to a negative infinity, however, triggers an ArithmeticException; the negation of a positive or negative infinity is a negative or positive infinity, respectively.

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 cannot be changed when a model is running (attempting to do so will trigger an exception).

Since:

Ptolemy II 4.1

Version:

$Id$

Author:

Haiyang Zheng, Edward A. Lee, Elaine Cheong

Pt.AcceptedRating:

Red (hyzheng)

Pt.ProposedRating:

Yellow (hyzheng)

Field Summary

Fields

Modifier and Type	Field and Description
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.
static Time	ZERO A static and final time constant holding a zero.

Constructor Summary

Constructors

Constructor and Description
Time(Director director) Construct a Time object with zero as the time value.
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.

Method Summary

Modifier and Type	Method and Description
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.
Time	addUnchecked(double timeValue) Add the specified double to this time without checking whether the specified double is too large to ensure the time resolution of the director.
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	isNegative() Return true if the current time value is a negative value (including negative infinity).
boolean	isNegativeInfinite() Return true if the current time value is a negative infinity.
boolean	isPositive() Return true if the current time value is a positive value (including positive infinity).
boolean	isPositiveInfinite() Return true if the current time value is a positive infinity.
boolean	isZero() Return true if the current time value is zero.
double	maximumAccurateValueAsDouble() Return the maximum value of time whose representation as a double is always accurate to the specified time resolution.
static Time	milliseconds(Director director, long milliseconds) Return a new Time object whose value equals the argument, which is interpreted in milliseconds.
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.
double	subtractToDouble(Time time) Subtract the specified time from this time and return the result as a double.
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

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.

ZERO

public static final Time ZERO

A static and final time constant holding a zero.

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.

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

addUnchecked

public Time addUnchecked(double timeValue)

Add the specified double to this time without checking whether the specified double is too large to ensure the time resolution of the director.

That is, two calls to this method could yield the same result even if the two arguments differ by more than the time resolution. The add(double) method, in contrast, will throw an exception if two such calls could yield the same result.

This method should only be used if the time resolution is not really needed for this addition. For example, when finding the stop time of long simulation, where `timeValue` is a large number, it would be reasonable to use this method if the stop time does not need to be so precise.

Parameters:

timeValue - The value to add.

Returns:

The sum of this Time object and the value to add.

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

isNegative

public final boolean isNegative()

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

Returns:

true if the current time value is a negative value (including negative infinity).

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.

isPositive

public final boolean isPositive()

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

Returns:

true if the current time value is a positive value (including positive 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.

isZero

public final boolean isZero()

Return true if the current time value is zero.

Returns:

true if the current time value is a zero.

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.

milliseconds

public static Time milliseconds(Director director,
                                long milliseconds)

Return a new Time object whose value equals the argument, which is interpreted in milliseconds.

Parameters:

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

milliseconds - The time in ms.

Returns:

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.

subtractToDouble

public double subtractToDouble(Time time)

Subtract the specified time from this time and return the result as a double.

This is equivalent to calling subtract(Time) and then invoking getDoubleValue(), but it is more efficient, in that it avoids unnecessary construction of Time objects.

Parameters:

time - The time to subtract.

Returns:

This Time minus the specified time, as a double.

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. If no director was given, then return a default time resolution of 10E-10. This is a protected method to allow subclasses to use their own time resolution.

Returns:

The time resolution of the director.