AIMMS Function Reference - Time Functions

Transcription

1 AIMMS Function Reference - Time Functions This file contains only one chapter of the book. For a free download of the complete book in pdf format, please visit Aimms 3.13

2 Time Functions Aimms supports the following time-related functions: Aggregate ConvertReferenceDate CreateTimeTable CurrentToMoment CurrentToString CurrentToTimeSlot DaylightSavingEndDate DaylightSavingStartDate DisAggregate MomentToString MomentToTimeSlot PeriodToString StringToMoment StringToTimeSlot TestDate TimeSlotCharacteristic TimeSlotToMoment TimeSlotToString TimeZoneOffSet

3 Time Functions 86 Aggregate With the procedure Aggregate you can aggregate time-dependent data from a calendar time scale (time slots to a horizon time scale (periods. Aggregate( TimeslotData,! (input an indexed identifier over a calendar PeriodData,! (output an indexed identifier over a horizon TimeTable,! (input an AIMMS time table Type,! (input an element in the set AggregationTypes [Locus]! (optional a value between 0 and 1 TimeslotData An identifier (slice containing the data to be aggregated. The domain sets in the index domain of this identifier should at least contain a calendar set, and all other sets should coincide with the domain of PeriodData. PeriodData An identifier (slice that on return will contain the aggregated data. The domain sets in the index domain of this identifier should at least contain a horizon set, and all other sets should coincide with the domain of TimeslotData. TimeTable An indexed set in a calendar and defined over a horizon. This horizon and calendar should match with the index domains of TimeslotData and PeriodData. Type An element of the pre-defined set AggregationTypes (summation, average, maximum, minimum, or interpolation. Locus (only for interpolation type A number between 0 and 1, that indicates at which moment in a period the quantity is to be measured. The procedure DisAggregate. Time-dependent aggregation and disaggregation is discussed in full detail in Section 32.5 of the Language Reference.

4 Time Functions 87 ConvertReferenceDate The function ConvertReferenceDate converts a reference date from one timezone to the other. ConvertReferenceDate( ReferenceDate,! (input a string expression FromTimezone,! (input an element expression ToTimezone,! (input an element expression IgnoreDST! (optional a numerical expression (default 0 ReferenceDate A string that holds a reference date in FromTimezone. FromTimezone An element of AllTimeZones with respect to which ReferenceDate is expressed. ToTimezone An element of AllTimeZones with respect to which the resulting reference date must be expressed. IgnoreDST A numerical expression indicating whether daylight saving time must be ignored in the conversion. The result of ConvertReferenceDate is a reference date in ToTimezone corresponding to the reference date ReferenceDate in FromTimezone. Aimms support for time zones is discussed in full detail in Sections and of the Language Reference.

5 Time Functions 88 CreateTimeTable With the procedure CreateTimeTable you can create a timetable in Aimms. CreateTimeTable( Timetable, CurrentTimeslot, CurrentPeriod, PeriodLength, LengthDominates, InactiveTimeSlots, DelimiterSlots! (output an indexed set! (input an element in a calendar! (input an element in a horizon! (input one-dimensional integer parameter! (input one-dimensional binary parameter! (input a subset of a calendar! (input a subset of a calendar Timetable An indexed set in a calendar and defined over the horizon to be linked to the calendar. This argument implicitly sets the calendar and horizon used for the creation of the timetable. The other arguments of the procedure should match with this calendar and horizon. CurrentTimeslot An element of a calendar (a time slot that should be aligned with the CurrentPeriod in the horizon. CurrentPeriod An element of a horizon (a period that should be aligned with the timeslot in the calendar. PeriodLength A one-dimensional integer parameter, specifying the desired length of each period in the horizon in terms of the number of time slots to be contained in it. LengthDominates A one-dimensional binary parameter, indicating whether reaching the specified PeriodLength dominates over the presence of any delimiter slot for every period in the horizon. InactiveTimeSlots A subset of the calendar, indicating the time slots that must be excluded from the timetable. DelimiterSlots A subset of the calendar, indicating the time slots that will (usually result in starting a new period in the horizon. The procedures Aggregate, DisAggregate. For a more detailed description of the creation of timetables, see Section 32.4 of the Language Reference.

6 Time Functions 89 CurrentToMoment The function CurrentToMoment converts the current time to the elapsed time with respect to a specific reference date. CurrentToMoment( Unit, ReferenceDate! (input a time unit! (input a string expression Unit The time unit that is used to return the elapsed time. ReferenceDate A string that holds the begin date using the fixed format for date and time, see paragraph Reference date format on page 511 of the Language Reference. The result of CurrentToMoment is the elapsed time in Unit since Reference- Date. The function StringToMoment.

7 Time Functions 90 CurrentToString The function CurrentToString creates a string representation of the current time in the a specified format. CurrentToString( Format! (input a string expression Format A string that holds the date and time format used in the returned string. Valid format strings are described in Section The result of CurrentToString is a description of the current time according to Format. Remarks: There is an option Current Time in LocalDST that specifies whether this function takes into account the effects of daylight savings time. The functions MomentToString, CurrentToMoment.

8 Time Functions 91 CurrentToTimeSlot The function CurrentToTimeSlot determines the time slot in a calendar that corresponds with the current time. CurrentToTimeSlot( Calendar! (input a calendar Calendar An identifier of type calendar. The function CurrentToTimeSlot returns the time slot in the calendar that contains the current moment. Remarks: There is an option Current Time in LocalDST that specifies whether this function takes into account the effects of daylight savings time. The functions StringToTimeSlot, MomentToTimeSlot.

9 Time Functions 92 DaylightSavingEndDate The function DaylightSavingEndDate computes the end date of daylight saving time for a particular year in a particular time zone. DaylightSavingEndDate( Year, Timezone! (input an element expression! (input an element expression Year An element of a yearly calendar for the end date of daylight saving time must be computed. Timezone An element in the predefined set AllTimeZones. The result of DaylightSavingEndDate is the end date of daylight saving time, as a reference date, for the time zone Timezone in the year Year. Aimms support for time zones is discussed in full detail in Sections and of the Language Reference.

10 Time Functions 93 DaylightSavingStartDate The function DaylightSavingStartDate computes the start date of daylight saving time for a particular year in a particular time zone. DaylightSavingStartDate( Year, Timezone! (input an element expression! (input an element expression Year An element of a yearly calendar for the end date of daylight saving time must be computed. Timezone An element in the predefined set AllTimeZones. The result of DaylightSavingStartDate is the start date of daylight saving time, as a reference date, for the time zone Timezone in the year Year. Aimms support for time zones is discussed in full detail in Sections and of the Language Reference.

11 Time Functions 94 DisAggregate With the procedure DisAggregate you can disaggregate time-dependent data from a horizon time scale (periods to a calendar time scale (time slots. DisAggregate( PeriodData,! (input an indexed identifier over a horizon TimeslotData,! (output an indexed identifier over a calendar Timetable,! (input an AIMMS time table Type,! (input an element in the set AggregationTypes [Locus]! (optional a value between 0 and 1 PeriodData An identifier (slice containing the data to be disaggregated. The domain sets in the index domain of this identifier should at least contain a horizon set, and all other sets should coincide with the domain of TimeslotData. TimeslotData An identifier (slice that on returns will contain the disaggregated data. The domain sets in the index domain of this identifier should at least contain a calendar set, and all other sets should coincide with the domain of PeriodData. Timetable An indexed set in a calendar and defined over a horizon. This horizon and calendar should match with the index domains of TimeslotData and PeriodData. Type An element of the pre-defined set AggregationTypes (summation, average, maximum, minimum, or interpolation. Locus (only for interpolation type A number between 0 and 1, that indicates at which moment in a period the quantity is to be measured. The procedure Aggregate. Time-dependent aggregation and disaggregation is discussed in full detail in Section 32.5 of the Language Reference.

12 Time Functions 95 MomentToString The function MomentToString creates a string representation of a moment, that is calculated from a given amount of elapsed time since a specific reference date. MomentToString( Format, unit, ReferenceDate, Elapsed! (input a string expression! (input a time unit! (input a string expression! (input a numerical expression Format A string that holds the date and time format used in the returned string. Valid format strings are described in Section unit The time unit that is used in the argument Elapsed. ReferenceDate A string that holds the begin date using the fixed format for date and time, see paragraph Reference date format on page 511 of the Language Reference. Elapsed A numerical value of the time elapsed since ReferenceDate. The result of MomentToString is a string describing the corresponding moment according to Format. The function StringToMoment.

13 Time Functions 96 MomentToTimeSlot The function MomentToTimeSlot determines the time slot in a calendar that corresponds with the a moment that is specified as the elapsed time since a specific reference date. MomentToTimeSlot( Calendar, ReferenceDate, Elapsed! (input a calendar! (input an element (time-slot in the calendar! (input a numerical value Calendar An identifier of type calendar. ReferenceDate A specific time-slot in Calendar holding the reference time. Elapsed The elapsed time since ReferenceDate. This should be an integral multiple of the calendar s time unit in order to select the time slot that is the return value of this function. The function MomentToTimeSlot returns the time slot in the calendar that contains the given moment. When the time slot is outside the calendar the empty element is returned. The functions TimeSlotToMoment, CurrentToTimeSlot, StringToTimeSlot.

14 Time Functions 97 PeriodToString With the function PeriodToString you can obtain a description of a period in a timetable that consists of multiple calendar slots. PeriodToString( Format, Timetable, Period! (input a string expression! (input an AIMMS time table! (input an element in a horizon Format A string that holds the date and time format used in the returned string. This format string can contain period specific conversion specifiers to generate a description referring to both the beginning and end of the period, see Section 32.7 Timetable An indexed set in a calendar and defined over a horizon. Period An element in the horizon that is defined by Timetable. The result of PeriodToString is a string describing the corresponding moment according to Format. The procedure CreateTimeTable.

15 Time Functions 98 StringToMoment The function StringToMoment converts a given time string (in a free time format to the elapsed time with a respect to a specific reference date. StringToMoment( Format, Unit, ReferenceDate, Timeslot! (input a string expression! (input a time unit! (input a string expression! (input a string expression Format A string that holds the date and time format used in the fourth argument Timeslot. Valid format strings are described in Section Unit The time unit that is used to return the elapsed time. ReferenceDate A string that holds the begin date using the fixed format for date and time, see paragraph Reference date format on page 511 of the Language Reference. Timeslot A string representing a specific date and time moment using the format specified in the first argument Format. The result of StringToMoment is the elapsed time in unit between referencedate and date. The functions MomentToString, CurrentToMoment.

16 Time Functions 99 StringToTimeSlot The function StringToTimeSlot determines the time slot in a calendar that corresponds with the a moment that is specified using a free format string. StringToTimeSlot( Format, Calendar, MomentString! (input a string expression! (input a calendar! (input a string expression Format A string that holds the date and time format used in the third argument MomentString. Valid format strings are described in Section Calendar An identifier of type calendar. MomentString A string expression of the moment (using the format given in Format that should be matched with the time slots in the calendar. The function StringToTimeSlot returns the time slot in the calendar that contains the given moment. The functions CurrentToTimeSlot, MomentToTimeSlot.

17 Time Functions 100 TestDate The function TestDate tests whether or not a particular date is according to given format. TestDate( Format, Date! (input a string expression! (input a string expression Format A string that holds the date and time format used in the returned string. Valid format strings are described in Section Date It is tested whether or not this string is according to format Format. The result of TestDate is 1 if Date is according to format Format and 0 otherwise. If the result is 0, the pre-defined identifier CurrentErrorMessage will contain a proper error message. The function CurrentToString.

18 Time Functions 101 TimeSlotCharacteristic The function TimeSlotCharacteristic obtains a numeric value which characterizes the time slot, in terms of its day of the week, its day in the year, etc. TimeSlotCharacteristic( Timeslot,! (input an element (time-slot in a calendar Characteristic,! (input an element in TimeslotCharacteristics Timezone,! (optional an element in AllTimeZones, default Local. IgnoreDST! (optional 0-1 expression, default 0. Timeslot A element refering to a time-slot in a calendar. Characteristic An element in the predefined set TimeSlotCharacteristics, each element in this set refers to a specific value that can be retrieved for a time slot. Timezone A time zone from the predefined set AllTimeZones. IgnoreDST A 0-1 expression indicating whether or not to ignore daylight savings time. The function TimeSlotCharacteristic returns a numerical value for the requested time slot characteristic. The function TimeSlotCharacteristic is discussed in full detail in Section 32.4 of the Language Reference.

19 Time Functions 102 TimeSlotToMoment The function TimeSlotToMoment calculates the elapsed time since a specific reference date for a given time slot in a calendar. TimeSlotToMoment( Calendar,! (input a calendar ReferenceDate,! (input an element (time-slot in the calendar Timeslot! (input an element (time-slot in the calendar Calendar An identifier of type calendar. ReferenceDate A specific time-slot in Calendar holding the reference time. Timeslot A specific time slot in the calendar. The function TimeSlotToMoment returns the elapsed time since the reference date for the given time slot (measured in the calendar s unit. The functions MomentToTimeSlot, CurrentToTimeSlot, StringToTimeSlot.

20 Time Functions 103 TimeSlotToString The function TimeSlotToString creates a string representation of a specific time slot in a calendar. TimeSlotToString( Format, Calendar, Timeslot! (input a string expression! (input a calendar! (input an element (timeslot in the calendar Format A string that holds the date and time format used in the returned string. Valid format strings are described in Section Calendar An identifier of type calendar. Timeslot A specific time-slot in the calendar. The function TimeSlotToString returns a string representation of the time slot. The functions MomentToString, CurrentToTimeSlot, StringToTimeSlot.

21 Time Functions 104 TimeZoneOffSet The function TimeZoneOffSet computes, in minutes, the offset between two time zones. TimeZoneOffSet( FromTZ, ToTZ! (input an element expression! (input an element expression FromTZ An element from the set AllTimeZones. ToTZ An element from the set AllTimeZones. The result of TimeZoneOffSet is the offset, in minutes, between FromTZ and ToTZ. Remarks: The result of the function has an associated unit, namely minutes. If FromTZ is UTC, the offset of ToTZ is the usual offset with respect to UTC (or GMT. Aimms support for time zones is discussed in full detail in Sections and of the Language Reference.