<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Frepple / Calendar</title>
<link rel='stylesheet' href='../styles.css' type='text/css' />
<!--PageHeaderFmt-->
</head>
<body>
<div id="container">
<div id="menubar">
<div id="logo" align="center">
<br/><img src='../frepple.bmp' alt="frepple" /><br/>
<a href='http://www.frepple.com/'>
<strong>a Free<br/>Production Planning<br/>Library</strong>
</a></div>
<div id="menu">
<br/>
<h3><a href='../Main/HomePage.html'>Main</a></h3>
<h3><a href='../UI/Main.html'>User Manual</a></h3>
<h3><a href='../Tutorial/Main.html'>Tutorial</a></h3>
<h3><a href='Main.html'>Reference Manual</a></h3>
<h3><a href='../Main/FAQ.html'>FAQ</a></h3>
<h3><a href='../reference/index.html'>C++ API</a></h3>
<br/><div>
</div>
</div>
</div>
<div id="content">
<br/>
<!--PageText-->
<div id='wikitext'>
<p><a class='wikilink' href='../Main/HomePage.html'>Main</a> > <span class='wikitrail'><a class='wikilink' href='Main.html'>Reference Manual</a> > <a class='wikilink' href='Modeling.html'>Modeling</a> > <a class='selflink' href='ModelingCalendar.html'>Calendar</a></span>
</p>
<p class='vspace'>A calendar represents a value that is varying over time.<br />Calendars can be linked to multiple entities: a maximum capacity limit of a resource, a minimum capacity usage of a resource, a minimum or maximum inventory limit of a buffer, etc...
</p>
<p class='vspace'>Different types of calendar exist:
</p><ul><li>calendar_void:<br /> A calendar without any value in its buckets.
</li><li>calendar_double:<br /> A calendar storing double numbers.
</li><li>calendar_integer:<br /> A calendar storing integer numbers.
</li><li>calendar_boolean:<br /> A calendar storing boolean values.
</li><li>calendar_string:<br /> A calendar storing string values.
</li><li>calendar_operation:<br /> A calendar storing operation values.
</li></ul><p class='vspace'>A calendar has multiple buckets to define the values over time. To determine the calendar value at a certain date the calendar will evaluate each of the buckets and combine the results in the following way:
</p><ul><li>A bucket is only valid from its "start" date (inclusive) till its "end" date (exclusive).<br /> Outside of this date range a bucket is never selected.
</li><li>If multiple bucket are effective on a date, the one with the lowest "priority" value is taken.<br /> In case buckets have the same priority, the value of the bucket with the latest start date is selected.
</li><li>In case no bucket is effective on a certain date, the calendar will return the "default" value.
</li></ul><div class='vspace'></div><h2>Calendar Fields</h2>
<table border='1' width='100%' ><tr><td width='20%' valign='top'><strong>Field</strong>
</td><td width='20%' valign='top'><strong>Type</strong>
</td><td width='60%' valign='top'><strong>Description</strong>
</td></tr><tr><td valign='top'>name
</td><td valign='top'>non-empty string
</td><td valign='top'>
<p>Name of the calendar.<br />This is the key field and a required attribute.
</p></td></tr><tr><td valign='top'>default
</td><td valign='top'>Varies with the calendar type
</td><td valign='top'>
<p>The default value of the calendar when no bucket is effective.
</p></td></tr><tr><td valign='top'>action
</td><td valign='top'>
<p>A<br />C<br />AC (default)<br />R
</p></td><td valign='top'>
<p>Type of action to be executed:
</p><ul><li>A: Add an new entity, and report an error if the entity already exists.
</li><li>C: Change an existing entity, and report an error if the entity doesn't exist yet.
</li><li>AC: Change an entity or create a new one if it doesn't exist yet.
</li><li>R: Remove an entity, and report an error if the entity doesn't exist.
</li></ul></td></tr></table>
<div class='vspace'></div>
<table border='1' width='100%' ><tr><td width='30%' valign='top'><strong>Method</strong>
</td><td width='70%' valign='top'><strong>Description</strong>
</td></tr><tr><td valign='top'>setValue([start date],[end date],[value])
</td><td valign='top'>
<p>Creates or updates calendar buckets to reflect the specified value in the given date range.
</p></td></tr><tr><td valign='top'>buckets()
</td><td valign='top'>
<p>Returns an iterator over the calendar buckets.
</p></td></tr><tr><td valign='top'>events()
</td><td valign='top'>
<p>Returns an iterator over the calendar events. These are the dates at which the calendar value is changing.<br />Each event is a tuple with 2 fields:
</p><ul><li>date: date of the event.
</li><li>value: value that becomes effective at the time of the event.
</li></ul></td></tr></table>
<div class='vspace'></div><h2>Bucket Fields</h2>
<table border='1' width='100%' ><tr><td width='20%' valign='top'><strong>Field</strong>
</td><td width='20%' valign='top'><strong>Type</strong>
</td><td width='60%' valign='top'><strong>Description</strong>
</td></tr><tr><td valign='top'>start
</td><td valign='top'>dateTime
</td><td valign='top'>
<p>Start date of the validity of this bucket.<br />When left unspecified, the entry is effective from the infinite past.
</p></td></tr><tr><td valign='top'>end
</td><td valign='top'>dateTime
</td><td valign='top'>
<p>End date of the validity of this bucket.<br />When left unspecified, the entry is effective indefinitely in the future.
</p></td></tr><tr><td valign='top'>name
</td><td valign='top'>normalizedString
</td><td valign='top'>
<p>Optional name of the bucket.<br />When left unspecified the default name is the start date of the bucket.
</p></td></tr><tr><td valign='top'>priority
</td><td valign='top'>integer
</td><td valign='top'>
<p>Priority of this bucket when multiple buckets are effective for the same date.<br />Lower values indicate higher priority.
</p></td></tr><tr><td valign='top'>value
</td><td valign='top'>Varies with the calendar type
</td><td valign='top'>
<p>The actual time-varying value.
</p></td></tr><tr><td valign='top'>action
</td><td valign='top'>A<br />C<br />AC (default)<br />R
</td><td valign='top'>
<p>Type of action to be executed:
</p><ul><li>A: Add an new entity, and report an error if the entity already exists.
</li><li>C: Change an existing entity, and report an error if the entity doesn't exist yet.
</li><li>AC: Change an entity or create a new one if it doesn't exist yet.
</li><li>R: Remove an entity, and report an error if the entity doesn't exist.
</li></ul></td></tr></table>
<div class='vspace'></div><h2>Example XML structures</h2>
<ul><li>Adding or changing a calendar and its buckets
</li></ul><pre> <plan>
<calendars>
<calendar name="cal" xsi:type="calendar_double">
<default>5</default>
<buckets>
<bucket start="2007-01-01T00:00:00" value="10"
priority="1"/>
<!-- This entry overrides the first one during February. -->
<bucket start="2007-02-01T00:00:00" end="2007-03-01T00:00:00
value="20" priority="0"/>
</buckets>
</calendar >
</calendars>
</plan>
</pre><div class='vspace'></div><ul><li>Removing a calendar
</li></ul><pre> <plan>
<calendars>
<calendar name="cal" action="R"/>
</calendars>
</plan>
</pre><div class='vspace'></div><h2>Example Python code</h2>
<ul><li>Adding or changing a calendar and its buckets
</li></ul><pre> cal = frepple.calendar_double(name="cal", default=5)
</pre><div class='vspace'></div><ul><li>Removing a calendar
</li></ul><pre> frepple.calendar(name="cal", action="R")
</pre><div class='vspace'></div><ul><li>Iterating over all buckets of a calendar
</li></ul><pre> for b in frepple.calendar(name="cal").buckets():
print b.name, b.value
</pre><div class='vspace'></div><ul><li>Iterating over all events of a calendar, going forward in time from a certain date
</li></ul><pre> start = datetime.datetime(2009,1,1)
for date, value in frepple.calendar(name="cal").events(start, True):
print date, value
</pre>
</div>
<!--PageFooterFmt-->
<!--HTMLFooter-->
</div></div>
</body>
</html>
