Schedule API

You can work with a schedule programmatically using the corresponding API of the Schedule class.

Demo model: Schedule Created Programmatically

Obtaining schedule values

Getting the value - getValue()

<ValueType> getValue() - Returns the value corresponding to the current model date.

<ValueType> getValue(double time) - Returns the value corresponding to the given model time (time).

<ValueType> getValue(double time, TimeUnits units) - Returns the schedule value corresponding to the given model time. You define the time moment as the number of specified time units (minutes, hours, etc.). For example, getValue(9, TIME_UNIT_HOUR) returns the schedule value for model time: 9 hours.
Parameters:
time - the number of time units
units - time unit constant (TIME_UNIT_MINUTE, TIME_UNIT_HOUR, etc.)

<ValueType> getValue(Date date) - Returns the value corresponding to the given model date.

Getting a timeout to the next change moment - getTimeoutToNextValue()

double getTimeoutToNextValue() - Returns timeout to the next change moment in the schedule, measured in the model time units from the current model time.

double getTimeoutToNextValue(double time) - Returns timeout to the schedule change moment next to the given time, measured in the model time units from that time.

double getTimeoutToNextValue(Date date) - Returns timeout to the schedule change moment next to the given date, measured in the model time units from that date.

Getting a time of the next change moment - getTimeOfNextValue()

double getTimeOfNextValue() - Returns time of the schedule change moment next to the current model time.

double getTimeOfNextValue(double time) - Returns time of the schedule change moment next to the given time.

double getTimeOfNextValue(Date date) - Returns time of the schedule change moment next to the given date.

Getting a date of the next change moment - getDateOfNextValue()

Date getDateOfNextValue() - Returns date of the schedule change moment next to the current model time.

Date getDateOfNextValue(double time) - Returns date of the schedule change moment next to the given time.

Date getDateOfNextValue(Date date) - Returns date of the schedule change moment next to the given date.

Getting next value - getNextValue()

<ValueType> getNextValue() - Returns value corresponding to the schedule change moment next to the current model time.

<ValueType> getNextValue(double time) - Returns value corresponding to the schedule change moment next to the given time.

<ValueType> getNextValue(double time, TimeUnits units) - Returns value corresponding to the schedule change moment next to the given model time (defined as the number of specified time units). For example, getValue(9, TIME_UNIT_HOUR) returns the schedule value for the next schedule change moment after 9 hours.
Parameters:
time - the number of time units
units - time unit constant (TIME_UNIT_MINUTE, TIME_UNIT_HOUR, etc.)

<valuetype> getNextValue(Date date) - Returns value corresponding to the schedule change moment next to the given date.

Getting a date of value - getDateOfValue()

Date getDateOfValue() - Returns the model date the current value of the schedule has been held since.

Date getDateOfValue(Date date) - Returns the model date of the schedule change moment of the value corresponding to the given model date.

Date getDateOfValue(double time) - Returns the model date of the schedule change moment of the value corresponding to the given model time.

Getting a time of value - getTimeOfValue()

double getTimeOfValue() - Returns the model time the current value of the schedule has been held since.

double getTimeOfValue(Date date) - Returns the model time of the schedule change moment of the value corresponding to the given model date.

double getTimeOfValue(double time) - Returns the model time of the schedule change moment of the value corresponding to the given model time.

Getting time units of the schedule - getTimeUnits()

long getTimeUnits() - Returns time units of the schedule, one of the time unit constants (TIME_UNIT_MINUTE, TIME_UNIT_HOUR, etc.)

Creating and initializing schedule programmatically on model startup

Creating empty schedule with no data using the simple constructor

new Schedule() - creates a new schedule with no data. You can specify the type of data this schedule will use like this:
new Schedule<Boolean>() - "on/off"
new Schedule<Integer>() - integer
new Schedule<Double>() - real

new ScheduleWithUnits(U units) - creates a new rate schedule with the specified rate measure units.

Parameters:
units - rate measure unit

Adding intervals - addInterval()

Note: Depending on the type of schedule you are creating, in the following functions use the value argument to pass the value of the corresponding type. For example, for an "on/off" schedule pass the value of boolean type to specify the interval you are adding to the schedule. If the period you are adding is "on", pass true. If the period you are adding is "off", pass false.

void addInterval(int startWeek, int startDayOfWeek, int startHour, int startMinute, int startSecond, int endWeek, int endDayOfWeek, int endHour, int endMinute, int endSecond, V value) - Adds new particular time interval to this schedule.

Parameters:
startWeek - start week of the interval
startDayOfWeek - start day of week of the interval
startHour - start hour of the interval
startMinute - start minute of the interval
startSecond - start second of the interval
endWeek - end week of the interval
endDayOfWeek - end day of week of the interval
endHour - end hour of the interval
endMinute - end minute of the interval
endSecond - end second of the interval
value - value of the interval

void addInterval(int startDay, int startHour, int startMinute, int startSecond, int endDay, int endHour, int endMinute, int endSecond, V value) - Adds new particular time interval to this schedule.

Parameters:
startDay - start day of the interval
startHour - start hour of the interval
startMinute - start minute of the interval
startSecond - start second of the interval
endDay - end day of the interval
endHour - end hour of the interval
endMinute - end minute of the interval
endSecond - end second of the interval
value - value of the interval

void addInterval(int startHour, int startMinute, int startSecond, int endHour, int endMinute, int endSecond, V value) - Adds new particular time interval to this schedule.

Parameters:
startHour - start hour of the interval
startMinute - start minute of the interval
startSecond - start second of the interval
endHour - end hour of the interval
endMinute - end minute of the interval
endSecond - end second of the interval
value - value of the interval

void addInterval(int startHour, int startMinute, int startSecond, int endHour, int endMinute, int endSecond, V value, int[] weekDays) - Adds new particular time intervals to this schedule.

void addInterval(long start, long end, V value) - Adds new particular time interval to this schedule.

Parameters:
start - start time of the interval, measured in milliseconds
end - end time of the interval, measured in milliseconds
value - value of the interval

Adding exact time moments - addMoment()

Note: Depending on the type of schedule you are creating, in the following functions use the value argument to pass the value of the corresponding type.

void addMoment(int week, int dayOfWeek, int hour, int minute, int second, V value) - Adds new particular time moment to this schedule.

Parameters:
week - week of the moment
dayOfWeek - day of the week of the moment
hour - hour of the moment
minute - minute of the moment
second - second of the moment
value - value of the moment

void addMoment(int day, int hour, int minute, int second, V value) - Adds new particular time moment to this schedule.

Parameters:
day - day of the moment
hour - hour of the moment
minute - minute of the moment
second - second of the moment
value - value of the moment

void addMoment(int hour, int minute, int second, V value) - Adds new particular time moment to this schedule.

Parameters:
hour - hour of the moment
minute - minute of the moment
second - second of the moment
value - value of the moment

void addMoment(int hour, int minute, int second, V value, int[] weekDays) - Adds new particular time moment to this schedule.

Parameters:
hour - hour of the moment
minute - minute of the moment
second - second of the moment
value - value of the moment
weekDays - an array of week days to create moments

void addMoment(long time, V value) - Adds new particular time moment to this schedule.

Parameters:
time - time of the moment, measured in milliseconds
value - value of the moment

Adding exceptions - addException()

Note: Depending on the type of schedule you are creating, in the following function use the value argument to pass the value of the corresponding type.

void addException(int startYear, int startMonth, int startDay, int startHour, int startMinute, int startSecond, int endYear, int endMonth, int endDay, int endHour, int endMinute, int endSecond, V value, boolean annually) - Adds new particular time intervals when the value defined by this schedule should have other values. Parameters:
startYear - start year of the interval
startMonth - start month of the interval
startDay - start day of the interval
startHour - start hour of the interval
startMinute - start minute of the interval
startSecond - start second of the interval
endYear - end year of the interval
endMonth - end month of the interval
endDay - end day of the interval
endHour - end hour of the interval
endMinute - end minute of the interval
endSecond - end second of the interval
value - value of the interval
annually - if you want the defined exception to occur annually in the specified day, sets true. Otherwise, if you want it to occur only in the specified year, sets false

Setting the start time of the schedule - setSnapTo()

void setSnapTo(int year, int month, int day, int hour, int minute, int second) - Sets start time of the schedule.

Parameters:
year - start year of the interval
month - start month of the interval
day - start day of the interval
hour - start hour of the interval
minute - start minute of the interval
second - start second of the interval

void setSnapTo(long snapTo) - Sets start time of the schedule.

Parameters:
snapTo - the absolute date (if calendarType == true) or the number of milliseconds from the zero model time

Setting a calendar type - setCalendarType()

void setCalendarType(boolean calendarType) - Sets the calendar type.

Parameters:
calendarType - if true then schedule works with calendar dates. For example, if you create a schedule for 8:00-17:00 each day - these times will be preserved even during the days of Daylight Saving Time switching.
If this parameter is false, "1 day" will be treated as 24*60*60 seconds - this is good for modeling the behavior of some automatic machines which don't watch at the wall-clock during e.g. self-maintenance procedures.

Setting the default value - setDefaultValue()

void setDefaultValue(V defaultValue) - Sets the default value used when there is no interval defined in the schedule.

Parameters:
defaultValue - the value used when there is no interval defined in the schedule

Setting the first day of week - setFirstDayOfWeek()

void setFirstDayOfWeek(int firstDayOfWeek) - Sets the first day of the week.

Parameters:
firstDayOfWeek - the first day of the week, this parameter is actually used when calendarType is true and timeUnit is week

Setting intervals merging - setGlueIntervals()

void setGlueIntervals(boolean glueIntervals) - Sets the intervals with the same value to merge.

Parameters:
glueIntervals - if true then intersecting intervals with the same 'value' will be merged, e.g. two intervals "Day1 18:00-24:00 value=5" and "Day2 00:00-02:00 value=5" will be treated as one interval "Day1 18:00 - Day2 02:00 value=5"

Setting a calendar period - setPeriod()

void setPeriod(int period) - Sets the recurrence period of the schedule.

Parameters:
period - recurrence period of the schedule, measured in the time units specified in setTimeUnit() function. Time units may be actual - if calendarType is false, and hypothetical - if true.

Setting the thread mode - setThreadMode()

void setSingleThreadMode(boolean singleThreadMode) - Sets the thread mode.

Parameters:
singleThreadMode - this parameter indicates whether schedule will work in single thread environment or will be used by multiple concurrent threads. This parameter is usually set to true for schedules inside agents and experiment which don't allow parallel execution (e.g. simulation experiment). But for schedules, located in optimization and parameter variation experiment which allow parallel execution this parameter should be set to false.

Setting time units of the schedule - setTimeUnits()

void setTimeUnits(long timeUnits) - Sets the time units of the schedule.

Parameters:
timeUnits - time units of the schedule, one of the time unit constants (TIME_UNIT_MINUTE, TIME_UNIT_HOUR, etc.). In the calendar-mode the only supported time units are day and week

Creating and initializing schedules using one complex constructor - not recommended

new Schedule<ValueType>(Utilities owner, boolean calendarType, int firstDayOfWeek, long period, long timeUnits, Long snapTo, <valuetype> defaultValue, long[] starts, long[] ends, Object[] values, boolean glueIntervals, boolean[] exceptionsAnnually, boolean singleThreadMode)

Example:

Schedule<Integer> NursePlan = new Schedule<Integer>(this, true, MONDAY, 1L * TIME_UNIT_DAY, TIME_UNIT_DAY, null, 0, varNursePlanTime, null, varNursePlanNumber, false, null, true );

Parameters:

owner - owner agent or experiment owning the schedule.

calendarType - if true then schedule works with calendar dates. For example, if you create a schedule for 8:00-17:00 each day - these times will be preserved even during the days of Daylight Saving Time switching.

If this parameter is false, "1 day" will be treated as 24*60*60 seconds - this is good for modeling the behavior of some automatic machines which don't watch at the wall-clock during e.g. self-maintenance procedures.

firstDayOfWeek - the first day of the week, this parameter is actually used when calendarType is true and timeUnit is TIME_UNIT_WEEK

period - recurrence period of the schedule, measured in milliseconds. Milliseconds may be actual - if calendarType is false, and hypothetical - if true, which means that 1000*60*60*24 milliseconds denotes one day independently on Daylight Saving Time switching.

timeUnits - time units of the schedule, one of the time unit constants (TIME_UNIT_MINUTE, TIME_UNIT_HOUR, etc.)

snapTo - the absolute date (if calendarType == true) or the number of milliseconds from the zero model time (if calendarType == false) which points to the time moment to which the schedule should be snapped (usually it is defined in the Snap to property of the schedule). Moments are cloned started from the given time moment in both directions of the time-axis, with the schedule's recurrence period.

May be null - in this case schedule will be snapped to the date corresponding to the zero model time.
defaultValue - the value used when there is no interval defined in the schedule
starts - start times of intervals, measured in milliseconds from the beginning of the period (milliseconds may be actual - if calendarType is false, and hypothetical - if true, which means that 1000*60*60*24 milliseconds denotes one day independently on Daylight Saving Time switching). This array may also contain starts exceptions (see exceptionsAnnually parameter).
ends - end times of intervals, the same description as for starts.
values - values for intervals.
glueIntervals - if true then intersecting intervals with the same 'value' will be merged, e.g. two intervals "Day1 18:00-24:00 value=5" and "Day2 00:00-02:00 value=5" will be treated as one interval "Day1 18:00 - Day2 02:00 value=5".

exceptionsAnnually - the array of exception flags (true means annual exception, false - single occurrence), may be empty. The number of exceptions equals the length of exceptionsAnnually array. The exceptions are read from starts, ends, values arrays. Exceptions data is located in the tails of these arrays. Note that for exceptions, starts and ends arrays contain absolute dates encoded as long numbers (see Date.getTime()).

singleThreadMode - this parameter indicates whether schedule will work in single thread environment or will be used by multiple concurrent threads. This parameter is usually set to true for schedules inside agents and experiment which don't allow parallel execution (e.g. simulation experiment). But for schedules, located in optimization and parameter variation experiment which allow parallel execution this parameter should be set to false.

Schedule API

Obtaining schedule values

Creating and initializing schedule programmatically on model startup

See also