jas.engine
Class SimTime

java.lang.Object
  jas.engine.SimTime

public class SimTime
extends java.lang.Object

A time unit converter. The simulation time is put in a long variable.
Agent based model do not consider time as a real time, but as a sequential loop of events. For these kind of models the time is expressed as a number of ticks of the internal clock.
Discrete event simulations often represent real systems and use a real time representation. These model could use a clock iternal representation expressed using a time unit. To be extermely precise you can use the Milliseconds time unit, but when simulating mountains erosion Months time unit can be a good choice. Also in this last case you can express the time in milliseconds and when an event using some months must be scheduled you can simply use the months() method to convert automatically the time.

Example: the time unit is TIME_MILLIS. I want to schedule an event by 2 months and 3 hours.
The code is scheduleEvent(months(2) + hours(3), ...); The SimTime will convert these times into an absolute long time.

Title: JAS

Description: Java Agent-based Simulation library

Copyright (C) 2002 Michele Sonnessa

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

Author:

Michele Sonnessa

Field Summary

static int	TIME_DAYS Represent Days time unit.
static int	TIME_HOURS Represent Hours time unit.
static int	TIME_MILLIS Represent Milliseconds time unit.
static int	TIME_MINUTES Represent Minmutes time unit.
static int	TIME_MONTHS Represent Months time unit.
static int	TIME_SECONDS Represent Seconds time unit.
static int	TIME_TICKS Represent untimed time unit.
static int	TIME_YEARS Represent Years time unit.

Constructor Summary

SimTime(int time_unit)
Initialize SimTime to a time unit.

Method Summary

int	days() Return current days.
long	days(int value) Convert days in absolute time.
long	elapsedTimeFrom(long fromTime) Return the absolute elapsed time from the given time.
long	getAbsoluteTime() Return absolute current time.
int	getTimeUnit() Return the current time unit.
java.lang.String	getTimeUnitDescriptor() Return the string representing current time unit.
java.lang.String	getTimeUnitDescriptor(int i) Return the string representing the given time unit.
java.lang.String[]	getTimeUnits() Return an array of String representing the time unit.
java.lang.String	getTimeUnitShortDescriptor(int i) Return the simbol representing the given time unit.
int	getUnitLength(int time_unit) Return how many units of the given time unit compose the greater time unit.
int	hours() Return current hours.
long	hours(int value) Convert hours in absolute time.
void	increaseTime(long elapsedTime) Increase current time by a period of time.
int	millis() Return current milliseconds.
long	millis(int value) Convert millis in absolute time.
int	mins() Return current minutes.
long	mins(int value) Convert minutes in absolute time.
int	months() Return current months.
long	months(int value) Convert months in absolute time.
static long	realTime(int year, int month, int date, int hour, int minute) Compute the absolute time of a given date and time.
static long	realTime(int year, int month, int date, int hour, int minute, int second) Compute the absolute time of a given date and time.
int	secs() Return current seconds
long	secs(int value) Convert seconds in absolute time.
void	setTimeUnit(int time_unit) Set the current time unit.
void	setUnitLength(int time_unit, int newLength) This method lets to change the default time unit lenght.
java.lang.String	toShortString() Return a short time-formatted string representing the current time.
java.lang.String	toString() Return a time-formatted string representing the current time.
java.lang.String	toString(long absoluteTime) Return a time formatted string representing the given time.
void	update(long newTime) Update the current time.
long	years() Return current years.
long	years(int value) Convert years in absolute time.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TIME_DAYS

public static final int TIME_DAYS

Represent Days time unit.

See Also:

Constant Field Values

TIME_HOURS

public static final int TIME_HOURS

Represent Hours time unit.

See Also:

Constant Field Values

TIME_MILLIS

public static final int TIME_MILLIS

Represent Milliseconds time unit.

See Also:

Constant Field Values

TIME_MINUTES

public static final int TIME_MINUTES

Represent Minmutes time unit.

See Also:

Constant Field Values

TIME_MONTHS

public static final int TIME_MONTHS

Represent Months time unit.

See Also:

Constant Field Values

TIME_SECONDS

public static final int TIME_SECONDS

Represent Seconds time unit.

See Also:

Constant Field Values

TIME_TICKS

public static final int TIME_TICKS

Represent untimed time unit. The time is expressed in clock ticks.

See Also:

Constant Field Values

TIME_YEARS

public static final int TIME_YEARS

Represent Years time unit.

See Also:

Constant Field Values

Constructor Detail

SimTime

public SimTime(int time_unit)

Initialize SimTime to a time unit.

Parameters:

time_unit - One of the constants representing time units.

Method Detail

days

public int days()

Return current days.

Returns:

Current days.

days

public long days(int value)

Convert days in absolute time. If time unit is greater it returns 0.

Parameters:

value - A number of days.

Returns:

The corresponding the time unit.

elapsedTimeFrom

public long elapsedTimeFrom(long fromTime)

Return the absolute elapsed time from the given time.

Parameters:

fromTime - The absolute beginning time of the interval.

Returns:

The difference between fromTime and current time.

getAbsoluteTime

public long getAbsoluteTime()

Return absolute current time.

Returns:

The long value representing the number of elpased time units

getTimeUnit

public int getTimeUnit()

Return the current time unit.

Returns:

Current time unit.

getTimeUnitDescriptor

public java.lang.String getTimeUnitDescriptor()

Return the string representing current time unit.

Returns:

The string describing the current time unit.

getTimeUnitDescriptor

public java.lang.String getTimeUnitDescriptor(int i)

Return the string representing the given time unit.

Parameters:

i - A time unit.

Returns:

The string describing the asked time unit.

getTimeUnits

public java.lang.String[] getTimeUnits()

Return an array of String representing the time unit.

Returns:

A list of strings describing supported time units.

getTimeUnitShortDescriptor

public java.lang.String getTimeUnitShortDescriptor(int i)

Return the simbol representing the given time unit.

Parameters:

i - A time unit.

Returns:

The short string describing the asked time unit.

getUnitLength

public int getUnitLength(int time_unit)

Return how many units of the given time unit compose the greater time unit. For instance: getUnitLength(TIME_HOURS) returns 24, because 24 hours corresponds to 1 dat.

Parameters:

time_unit - A time unit.

Returns:

The length of the given time unit.

hours

public int hours()

Return current hours.

Returns:

Current hours.

hours

public long hours(int value)

Convert hours in absolute time. If time unit is greater it returns 0.

Parameters:

value - A number of hours.

Returns:

The corresponding the time unit.

increaseTime

public void increaseTime(long elapsedTime)

Increase current time by a period of time.

Parameters:

elapsedTime - The absolute time interval to add to the current time.

millis

public int millis()

Return current milliseconds.

Returns:

Current millis.

millis

public long millis(int value)

Convert millis in absolute time. If time unit is greater it returns 0.

Parameters:

value - A number of milliseconds.

Returns:

The corresponding the time unit.

mins

public int mins()

Return current minutes.

Returns:

Current mins.

mins

public long mins(int value)

Convert minutes in absolute time. If time unit is greater it returns 0.

Parameters:

value - A number of minutes.

Returns:

The corresponding the time unit.

months

public int months()

Return current months.

Returns:

Current months.

months

public long months(int value)

Convert months in absolute time. If time unit is greater it returns 0.

Parameters:

value - A number of months.

Returns:

The corresponding the time unit.

realTime

public static long realTime(int year,
                            int month,
                            int date,
                            int hour,
                            int minute)

Compute the absolute time of a given date and time.

Parameters:

year - An year nuber.

month - A month number from 1 to 12.

date - A day number.

hour - An hour (0-23).

minute - A minute (0-59).

Returns:

The corresponding absolute time.

realTime

public static long realTime(int year,
                            int month,
                            int date,
                            int hour,
                            int minute,
                            int second)

Compute the absolute time of a given date and time.

Parameters:

year - An year nuber.

month - A month number from 1 to 12.

date - A day number.

hour - An hour (0-23).

minute - A minute (0-59).

second - A second (0-59).

Returns:

The corresponding absolute time.

secs

public int secs()

Return current seconds. *

Returns:

Current secs.

secs

public long secs(int value)

Convert seconds in absolute time. If time unit is greater it returns 0.

Parameters:

value - A number of seconds.

Returns:

The corresponding the time unit.

setTimeUnit

public void setTimeUnit(int time_unit)

Set the current time unit.

Parameters:

time_unit - The new time unit.

setUnitLength

public void setUnitLength(int time_unit,
                          int newLength)

This method lets to change the default time unit lenght. If you want to consider only the days and skip the nights in your simulation, you have to write setUnitLength(TIME_HOURS, 12).

Parameters:

time_unit - The time unit to update.

newLength - New time unit length.

toShortString

public java.lang.String toShortString()

Return a short time-formatted string representing the current time.

Returns:

The short string describing the current time.

toString

public java.lang.String toString()

Return a time-formatted string representing the current time.

Overrides:

toString in class java.lang.Object

Returns:

The string describing the current time.

toString

public java.lang.String toString(long absoluteTime)

Return a time formatted string representing the given time.
WARNING: This method is much slower than toString().

Parameters:

absoluteTime - An absolute time.

Returns:

The string describing the asked time.

update

public void update(long newTime)

Update the current time. The simulation engine updates the current time value at each simulation step.

Parameters:

newTime - The new absolute time.

years

public long years()

Return current years.

Returns:

Current years.

years

public long years(int value)

Convert years in absolute time.

Parameters:

value - A number of years.

Returns:

The corresponding the time unit.