Model time and date
1. Model calendar
A concept of time in simulation is represented by a double
number.
It is 0
on simulation start and grows continuously during the simulation progress.
However most simulation use cases also need a concept of model calendar to relate the behavior of a system to a real-world time. In Amalgama Platform it is called "model date" (to distinguish it from model time) and is represented by Java’s LocalDateTime class. To define the model calendar (model date), it is sufficient to specify the calendar date (and time) of zero simulation instant and the time unit.
Thus, model date and model time are related by the following formula:
(model date) = (begin date) + (time unit) * (model time)
Below is the example of model time and date axis for the the zero simulation time date of Jan 1, 2022 and days as simulation time units:
On the figure above, the instant of Jan 1, 2022 0:00 corresponds to simulation time 0, the instant of the next day’s beginning Jan 2, 2022 0:00 corresponds to model time 1, and so on.
Note that non-integer and negative model time values can also be matched with some calendar dates.
Model date (which is LocalDateTime) does not include a time-zone information. Because it is a description of the date, as used for birthdays, combined with the local time as seen on a wall clock. Thus, it is very convenient for simulation models, where time zones are rarely needed and add unnecessary complexity.
There is a rich Java Date and Time API that allows programmers to conveniently do date and time related calculations, such as:
-
get the date of the next Monday,
-
get the instant of current day’s beginning,
-
add exactly one week to some specified date-time, etc.
2. Classes to deal with
Model time and corresponding model date are managed by the simulation engine.
To specify the correct mapping between these two quantities, you should call the Engine::setTemporal method.
For models that are not related to real-world calendar time, this step can be omitted.
In such cases, some default beginDate
and timeUnit
will be set.
However, all model date-related methods can be ignored in the application, and only model time-related methods are used.
You can get the current values with time() and date() methods respectively. For convenience Model and StateMachine classes provide the same methods, though under the hood obtaining time information from the engine.
Also, these 3 classes implement Timeable interface (see below) that provides a lot of facilities for converting between model time and model date.
Thus, implementing your simulation model as a descendant from Amalgama Platform’s abstract Model class, you can use mentioned methods to easily deal with model time and model date: E.g.:
// a moment in a simulation future after 1 day and 7.5 hours after a current model time
double someMoment = time() + 1 * day() + 7 * hour() + 30 * minute();
// a second moment 2 days and 4 hours later in a real-world calendar form
LocalDateTime anotherTime = timeToDate(someMoment).plusDays(2).plusHours(4);
3. Timeable interface
Timeable interface contains convenience methods for recalculations between model time and model calendar dates. It contains the two methods that must be overridden in its implementors: beginDate and timeUnit. These methods specify the date of zero simulation time and the time unit. This interface also has a static method of that allows programmers to conveniently create instances of the interface.
The main methods of the Timeable
interface are:
-
double dateToTime(LocalDateTime date)
that converts the calendar date to the simulation model time, and -
LocalDateTime timeToDate(double time)
that converts the simulation model time to calendar date.
Below is the basic example of usage of Timeable interface:
LocalDateTime beginDate = LocalDateTime.of(2022, 1, 1, 0, 0);
// We create a Timeable instance with begin date-time of Jan 1, 2022 0:00 and days as model time units
Timeable timeable = Timeable.of(beginDate, ChronoUnit.DAYS);
// This will print "2022-01-02T00:00", as model time 1 corresponds to date-time of Jan 2, 2022 0:00
System.out.println(timeable.timeToDate(1));
// This will print "2.0", as date-time of Jan 3, 2022 0:00 corresponds to model time 2
System.out.println(timeable.dateToTime(LocalDateTime.of(2022, 1, 3, 0, 0)));
Timeable` interface contains method that return the duration of some real-world calendar periods in simulation time units:
4. Implementors of Timeable interface
The following classes of Amalgama Platform implement Timeable
interface:
-
Engine - the class for the simulation engine,
-
Model - the base class of simulation models,
-
StateMachine - the class for state machines.