# Overview: Calendars in AIMMS

The word “programming” in Mathematical Programming is about creating a plan, typically a plan to be executed over some period in real-time. This makes reference to real-time an essential ingredient for most decision support applications. Calendars are used in AIMMS to reference to real-time. In this how-to article we will discuss:

1. How calendars are constructed flexibly

2. How calendars relate to the date/time fields in database tables

3. How current time is mapped to elements in a calendar

4. How information about calendars can be used to construct meaningful subsets such as the Sundays.

## Construction of calendars

A calendar is an AIMMS set, a finite collection of elements. The calendar elements, called timeslots, are descriptions of periods of equal length. To describe such a calendar, the length of each timeslot, the begin, and end of the calendar need to be known. The length is based on the unit of measurement available in the quantity `SI_Time_Duration`. Finally, the presentation of timeslots to users should follow the conventions of those users. As a running example, let’s use:

``` 1DeclarationSection Calendar_Declaration {
2    Quantity SI_Time_Duration {
3        BaseUnit: s;
4        Conversions: {
5            century->s : #-># * 3153600000,
6            day    ->s : #-># * 86400,
7            hour   ->s : #-># * 3600,
8            minute ->s : #-># * 60,
9            month  ->s : #-># * 2628000,
10            year   ->s : #-># * 31536000
11        }
12        Comment: "Expresses the value for the duration of periods.""    }
13    Parameter p_YearNumber {
14        InitialData: 2016;
15    }
16    StringParameter sp_CalBeg {
17        Definition: FormatString("%i-01-01", p_YearNumber);
18    }
19    StringParameter sp_CalEnd {
20        Definition: FormatString("%i-12-31", p_YearNumber);
21    }
22    StringParameter sp_TimeslotFormat {
23        InitialData: "%Am|AllAbbrMonths| %d, %c%y";
24    }
25    Calendar cal_daysInYear {
26        Index: i_day;
27        Parameter: ep_day;
28        Unit: day;
29        BeginDate: sp_CalBeg;
30        EndDate: sp_CalEnd;
31        TimeslotFormat: sp_TimeslotFormat;
32    }
33}
```

Some remarks on the above:

1. Lines 2-13. To define the length of a timeslot, we need to use the quantity `SI_Time_Duration`. In our example, we only use the conversion for `day`.

2. Lines 14-16. This example shows all days in a particular year, so the year number is the actual input.

3. Lines 17-19. The calendar begin date is captured by the string parameter `sp_CalBeg`. It captures the first day of the year specified by the year number `p_YearNumber`, so it is easily defined using `FormatString`.

4. Lines 20-22. The calendar end date is defined similarly via the string parameter `sp_CalEnd`.

5. Lines 23-25. The timeslot format specifies how timeslots are formatted. A possible value for this format we use the standard AIMMS format for days; so a timeslot is formatted as `2019-01-01`. Clearly, this may not be the presentation of timeslots your users may be used to. Here we use “%Am|AllAbbrMonths| %d, %c%y”, the format custom to people in the USA. You can choose the format freely, as long as all timeslots are unique.

6. Lines 26-33 The calendar itself. Almost fully parametrized, using the definitions explained above, but still a daily calendar. The only part not parametrized is that it is by day, and not by some number of days, or by some unit of measurement. However, to change the granularity of a decision support application, changing it from day to month, or to hours, is quite rare.

Calendars page provides further details on declaring Calendars.

## Relating calendars in AIMMS to date/time columns in databases

A key feature of Calendars in AIMMS is the natural mapping to date/time columns in a database. Consider the following simple database table:

with design view:

Using the AIMMS mapping wizard, we can map the columns in the database table to the identifiers in AIMMS:

Reading the data and then displaying it in the WebUI results in:

As you can see, without any programming on dates, the format of the dates in the WebUI presentation changed. This is achieved because the calendar timeslots are mapped onto date/time fields in the database.

## Using current time

AIMMS provides two functions to obtain the current time: `CurrentToString` and `CurrentToTimeSlot`. The difference is that the one is resulting in a string, the other a timeslot. Both are useful for our running example.

### Initializing the current year

The function `CurrentToString` returns the current date/time formatted according its argument. So the current year can be initialized by the following statement:

```p_YearNumber := val( CurrentToString("%c%y") );
```

in the procedure `MainInitialization`.

Further information about the function `CurrentToString` can be found in AIMMS The Function Reference.

### Obtaining the current day as element in Calendar

The function `CurrentToTimeSlot` returns the timeslot in which we are “now” as illustrated in the next statement:

```ep_day := CurrentToTimeSlot(Calendar : cal_daysInYear );
```

Further information about the function `CurrentToTimeSlot` can be found in AIMMS The Function Reference.

## Creating subsets of a calendar based on characteristics of the timeslot

To continue our running example, we want to construct a subset of all weekend days, say `s_WeekendDays`, of calendar `cal_daysInYear`. AIMMS views Saturday as day number 6 and Sunday as day number 7 in a week. Thus we can construct the set `s_WeekendDays` as follows:

```Set s_WeekendDays {
SubsetOf: cal_daysInYear;
Definition: {
{ i_day |
TimeslotCharacteristic( i_day, 'weekday' ) = 6 or
TimeslotCharacteristic( i_day, 'weekday' ) = 7 }
}
}
```

Further information about the function `TimeSlotCharacteristic` can be found in AIMMS The Function Reference.

The running example is contained in: `AIMMS project download`