Skip to content

Roster Staff Assignment Plan

ShiftSolver problem data

XML format for ShiftSolver problem instances

This document describes the data format used for ShiftSolver problem instances. As well as being read by the rostering engine, the format can also be read by RosterViewer. The data format is an XML based format and so can be created and edited using any text editor. An XML aware editor is recommended to allow the data to be validated against the format's schema as it is edited. Many XML editors also provide other useful features such as tag suggestion and auto-completion.

To help get started a ShiftSolver XML template file is also available.

Although instances can be created by hand using an editor, in practice the XML is normally generated dynamically by another application. This XML is then passed to the rostering engine which solves the problem and returns the solution. The solution is also encoded using an XML format.

Throughout this document, a number of terms such as 'shifts', 'tasks', 'scheduling period', 'index' are frequently used. The figure below shows an annotated example roster to help explain some commonly used terms. In this example there are three tasks labelled 't', 'u' and 'b' ('b' represents a break).

The data required to describe an employee scheduling problem instance can be split into five main sections:

  • The planning horizon. The planning horizon (sometimes called the scheduling period) is defined using the tags <StartDate> and <EndDate>. The time interval length that each day is split up into is specified using the tag <IntervalLength> (in the example shown above the time interval is 15 minutes).
  • Tasks. The tasks that can be assigned during each time interval in a schedule. These are specified within the tag <Tasks>.
  • Employees. The employees available for assigning the tasks to are specified within the tag <Employees>.
  • Schedule constraints. The schedules (sometimes called work patterns) that each employee can work are usually subject to a large number of constraints. For example constraints related to the min/max amount of work, shift start times and durations, breaks, night shifts etc.

    These constraints are entered within the tag <Contracts>. Each employee can have their own contract but it is common for employees to have the same constraints so contracts may also be shared by two or more employees.

    The schedule for each employee in the current planning period is clearly also affected by the employee's schedule in the previous planning period. To model this there are two options:

    1. Include the previous planning period (or as much of it as is relevant) in the current planning period (by making the start date earlier) and then fix all these assignments in place using <FixedAssignments> so they cannot be changed.
    2. The second option is to enter constraints (in the contracts) which are based on the assignments made in the previous schedules. For example, if a night shift can only followed by a night shift or a day off and the last day of the previous schedule has a night shift, then enter a constraint (e.g. using <Match>) in this scheduling horizon which ensures that only a night shift or day off is assigned on the first day.

    The second method is slightly more efficient for the solver but may be more effort to model. An effective compromise is to include some of the previous roster (fixed in place) and then add additional constraints for the ones which would require long sections of the previous schedule.
  • Cover constraints. Cover constraints describe the min and max numbers of employees that must be working each day. The cover is specified per task. The cover can be further split up by skill levels or requirements for specific groups of employees.

Examples of instances modelled using the format can be found in the example instances section. See also the FAQs for examples of how to model some of the more common constraints.

The root element of the document is <SchedulingHorizon>. This is the opening tag.

<SchedulingHorizon>

The root element of the document.

Attributes

NameRequiredTypeDescription
IDOptionalstringAn ID used to identify the instance.

Elements

SchedulingHorizon contains the following elements in any order:

NameRequiredTypeDescriptionVer.
<StartDate>RequireddateThe date of the first day in the scheduling horizon. Specified in the format : YYYY-MM-DD.1.0+
<EndDate>RequireddateThe date of the last day in the scheduling horizon. Specified in the format : YYYY-MM-DD.1.0+
<IntervalLength>RequiredNonNegativeIntegerThe length in minutes of the time intervals that the scheduling horizon is split into.1.0+
<DayRanges>OptionalDayRangesBy default each day runs from 00:00 (midnight) to 00:00 the next day. Using DayRanges the problem can be made smaller (and faster to solve) by defining a shorter time range for each day during which shifts can be assigned. For example, if it is known that shifts can only be assigned between 07:00 and 20:00 then each day can be compacted to a scheduling range of 07:00-20:00 each day using DayRanges.1.0+
<SkillGroups>OptionalSkillGroupsSkills can be grouped together and cover specified for different skill groups. The groups are defined here.1.0+
<Tasks>OptionalTasksThe tasks to assign during a shift.1.0+
<TaskGroups>OptionalTaskGroupsSome constraints require task types to be grouped together (for example for cover constraints). The task groups are defined here.1.0+
<ShiftTypes>OptionalShiftTypesFor some constraints it is necessary to categorise each shift as a certain type e.g. a 'Night Shift', 'Late Shift' or 'Early Shift' etc. The shifts can be categorised by their start times, end times and lengths. The shift types are defined here.1.0+
<ShiftGroups>OptionalShiftGroupsSome constraints require shift types to be grouped together (for example a group of night shifts). The groups are defined here.1.0+
<Contracts>OptionalContractsEach employee can have a different set of constraints for their work schedule. These are specified within contracts which are linked to each employee.1.0+
<Employees>OptionalEmployeesThe employees to assign the shifts to.1.0+
<CoverRequirements>OptionalCoverRequirementsThe minimum and maximum numbers of employees required (and/or preferred) to cover tasks at certain times in the scheduling horizon.1.0+
<DayOffRequests>OptionalDayOffRequestsDates on which employees request not to be working.1.2+
<DayOnRequests>OptionalDayOnRequestsDates on which employees want to be working.1.2+
<ShiftOffRequests>OptionalShiftOffRequestsDates on which employees do not want specific shifts.1.2+
<ShiftOnRequests>OptionalShiftOnRequestsDates on which employees want specific shifts.1.2+
<FixedAssignments>OptionalFixedAssignmentsTasks, time periods and days which must be assigned or not assigned (in other words they are fixed in place and cannot be changed).1.0+
<FixedShiftTasks>OptionalFixedShiftTasksTasks which must appear at defined points and durations within a shift if a shift is assigned on the defined day to the defined employee.1.29+
<Rules>OptionalRulesRules can be used to create new, custom constraints related to shift types that cannot otherwise be modelled using other options such as Patterns.1.47+

Example

<?xml version="1.0" encoding="UTF-8"?><SchedulingHorizonID="DemoProblem1"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:noNamespaceSchemaLocation="SchedulingHorizon-1.0.xsd"><StartDate>2011-11-13</StartDate><EndDate>2011-11-19</EndDate><IntervalLength>15</IntervalLength><Tasks><TaskID="w"><Name>Work</Name><Label>w</Label></Task></Tasks><Contracts><ContractID="Contract1"><ShiftLengths><Min><Length>480</Length><Label>Shift must not be less than 8h</Label><Weightfunction="quadratic">100</Weight></Min><Max><Length>540</Length><Label>Shifts must be more than 9h</Label><Weightfunction="quadratic">100</Weight></Max></ShiftLengths><Workload><TimeUnits><Max><Count>2400</Count><Label>Max 40 hours</Label><Weightfunction="quadratic">1</Weight></Max><Min><Count>2160</Count><Label>Min 36 hours</Label><Weight>1</Weight></Min></TimeUnits></Workload></Contract></Contracts><Employees><EmployeeID="E1"><ContractID>Contract1</ContractID><Name>E1</Name></Employee><EmployeeID="E2"><ContractID>Contract1</ContractID><Name>E2</Name></Employee></Employees><CoverRequirements><CoverRequirement><Start>2011-11-13T10:00</Start><End>2011-11-13T10:15</End><Cover><Task>w</Task><Minweight="1000">2</Min><Maxfunction="quadratic"weight="1">2</Max></Cover></CoverRequirement><CoverRequirement><Start>2011-11-13T10:15</Start><End>2011-11-13T10:30</End><Cover><Task>w</Task><Minweight="1000">2</Min><Maxfunction="quadratic"weight="1">2</Max></Cover></CoverRequirement></CoverRequirements></SchedulingHorizon>

<DayRanges>

By default each day runs from 00:00 (midnight) to 00:00 the next day. Using DayRanges the problem can be made smaller (and faster to solve) by defining a shorter time range for each day during which shifts can be assigned. For example, if it is known that shifts can only be assigned between 07:00 and 20:00 then each day can be shortened to a scheduling range of 07:00-20:00 each day using DayRanges.

Note that the <StartTime> in a DayRange also affects the shift start times on that day. For example if the <StartTime> is 09:00 and the <IntervalLength> for the instance is 15 minutes then the shifts can start at 09:00, 09:15, 09:30, 09:45 etc. If however the start time was set as 09:01 then the shifts will start at 09:01, 09:16, 09:31, 09:46 etc.

Parents : SchedulingHorizon

Attributes

None

Elements

0 or more DayRange elements.

NameRequiredTypeDescription
<DayRange>OptionalDayRangeA start and end time for a day. Assignments can only be made within this time range.

Example

<DayRanges><DayRange><Date>2011-11-13</Date><StartTime>07:00</StartTime><EndTime>17:30</EndTime></DayRange><DayRange><Date>2011-11-14</Date><StartTime>07:00</StartTime><EndTime>20:30</EndTime></DayRange><DayRange><Date>2011-11-15</Date><StartTime>07:00</StartTime><EndTime>20:30</EndTime></DayRange></DayRanges>

<DayRange>

A start and end time for a day. Assignments can only be made within this time range.

Parents : DayRanges

Attributes

None

Elements

DayRange contains a <Date> or <Day> element, a <StartTime> and an <EndTime> element (all optional).

If neither the <Date> or <Day> elements are used then the <StartTime> and/or <EndTime> are considered the default for all days for which there is not a DayRange specified. In other words if neither the <Date> or <Day> elements are used then it is considered a default DayRange.

NameRequiredTypeDescription
<Date>OptionaldateThe date in the scheduling horizon this range applies to. Specified in the format : YYYY-MM-DD.
<Day>OptionalNonNegativeIntegerThe day in the scheduling horizon this range applies to. The scheduling horizon starts on day zero.
<StartTime>OptionalTimeOfDayThe range start time. Default value is 00:00:00.
<EndTime>OptionalTimeSpanThe range end time. Default value is 1.00:00:00

Example

<DayRange><Date>2011-11-13</Date><StartTime>07:00</StartTime><EndTime>17:30</EndTime></DayRange>

<SkillGroups>

Skills can be placed in groups for use in cover constraints. They skill groups are defined here.

Parents : SchedulingHorizon

Attributes

None

Elements

SkillGroups contains zero or more <SkillGroup> elements.

NameRequiredTypeDescription
<SkillGroup>OptionalSkillGroupA group of skills.

Example

<SkillGroups><SkillGroupID="AorB"><Skill>A</Skill><Skill>B</Skill></SkillGroup></SkillGroups>

<SkillGroup>

A group of skills.

Parents : SkillGroups

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this group.

Elements

SkillGroup contains one or more <Skill> elements.

NameRequiredTypeDescription
<Skill>RequiredstringA skill ID.

Example

<SkillGroupID="123"><Skill>1</Skill><Skill>2</Skill><Skill>3</Skill></SkillGroup>

<Tasks>

The tasks to be assigned during shifts.

Parents : SchedulingHorizon

Attributes

None

Elements

0 or more Task elements.

NameRequiredTypeDescription
<Task>OptionalTaskA task definition.

Example

<Tasks><TaskID="T1"><Label>1</Label></Task><TaskID="T2"><Label>2</Label></Task><TaskID="T3"><Label>3</Label></Task></Tasks>

<Task>

A task definition.

Parents : Tasks

Attributes

NameRequiredTypeDescriptionVer.
IDRequiredIDA unique ID for this task.1.0+

Elements

Task contains the following elements in any order:

NameRequiredTypeDescriptionVer.
<Name>OptionalstringA name for this task.1.0+
<Label>OptionalstringA label for the task when displaying schedules. The ID is used if this element is omitted.1.0+
<Color>OptionalstringA colour for the task when displaying schedules. Any valid HTML colour may be used.1.0+
<AutoAllocate>OptionalBooleanIf false then this task will not be assigned by the solver unless it is pre-assigned in the FixedAssignments. If this tag is omitted the default value is true.1.0+
<Break>OptionalBooleanSet this as true to indicate that this task is to be used as the break task. If this tag is omitted the default value is false. If a break task is not defined then a default break task is created with the ID '$b'. Only one break task can be defined. 1.23+

Example

<TaskID="T1"><Name>Task1</Name><Label>t</Label><Color>LightBlue</Color></Task>

<TaskGroups>

Task types can be placed in groups which are then used in some constraints.

Parents : SchedulingHorizon

Attributes

None

Elements

TaskGroups contains zero or more <TaskGroup> elements.

NameRequiredTypeDescription
<TaskGroup>OptionalTaskGroupA group of task types.

Example

<TaskGroups><TaskGroupID="Grp1"><Task>t1</Task><Task>t2</Task></TaskGroup><TaskGroupID="Grp2"><Task>t3</Task><Task>t4</Task></TaskGroup></TaskGroups>

<TaskGroup>

A group of task types.

Parents : TaskGroups

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this group.

Elements

TaskGroup contains one or more <Task> elements.

NameRequiredTypeDescription
<Task>RequiredstringThe ID of a task type. Specified in Task attribute 'ID'.

Example

<TaskGroupID="Grp1"><Task>t1</Task><Task>t2</Task><Task>t3</Task></TaskGroup>

<ShiftTypes>

For some constraints it is necessary to categorise each shift as a certain type e.g. a 'Night Shift', 'Late Shift' or 'Early Shift' etc. The shifts can be categorised by their start times, end times and lengths. The shift types are defined here.

When categorising a shift the engine looks through the shift types defined here in the order they are defined here and uses the first shift type definition it finds with a matching set of start time, end time and length definitions. If no matching shift type is found then the last shift type in the list is used by default. The start, end and length definitions are all optional.

Parents : SchedulingHorizon

Attributes

None

Elements

0 or more Shift elements.

NameRequiredTypeDescription
<Shift>OptionalShiftA shift type definition.

Example

<ShiftTypes><ShiftID="N"><Name>Night Shift</Name><Label>N</Label><MinEnd>23:00</MinEnd><MaxEnd>1.08:00</MaxEnd></Shift><ShiftID="L"><Name>Late Shift</Name><Label>L</Label><MinEnd>18:00</MinEnd><MaxEnd>23:00</MaxEnd></Shift><ShiftID="E"><Name>Early Shift</Name><Label>E</Label><MaxStart>06:00</MaxStart></Shift><ShiftID="D"><Name>Day Shift</Name><Label>D</Label></Shift></ShiftTypes>

<Shift>

A shift type definition.

Parents : ShiftTypes

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this shift type.

Elements

Shift contains the following elements in any order:

NameRequiredTypeDescriptionVer.
<Name>OptionalstringA name for this shift.1.0+
<Label>OptionalstringA label for the shift when displaying schedules. The ID is used if this element is omitted.1.0+
<Color>OptionalstringA colour for the shift when displaying schedules. Any valid HTML colour may be used.1.0+
<MinStart>OptionalTimeOfDayA shift must start at or after this time to be categorised as this shift type.1.33+
<MaxStart>OptionalTimeOfDayA shift must start before or at this time to be categorised as this shift type.1.33+
<MinEnd>OptionalTimeSpanA shift must end at or after this time to be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00. 1.33+
<MaxEnd>OptionalTimeSpanA shift must end before or at this time to be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00. 1.33+
<MinLength>OptionalNonNegativeDoubleIn minutes. A shift must be at least this length to be categorised as this shift type.1.33+
<MaxLength>OptionalNonNegativeDoubleIn minutes. A shift must be at most this length to be categorised as this shift type. 1.33+
<EndsAfter>OptionalTimeSpan This element is obsolete. It is recommended to use <MinStart>, <MaxStart>, <MinEnd> and <MaxEnd> instead for more control.
If a shift starts before or at this time and ends after this time it will be categorised as this shift type. For shift types which end on the next day use the TimeSpan day prefix e.g. for midnight use 1.00:00, for 02:00AM the next day use 1.02:00.
1.0+
<Resources>OptionalResourcesThis can be used to define 'resources' (keys and numerical values) which are associated with the shift type. The resources defined here can then be referenced in the Rule constraint.1.47+

Example

<ShiftID="N"><Name>Night Shift</Name><Label>N</Label><Color>SkyBlue</Color><MinStart>00:00</MinStart><MaxStart>23:59</MaxStart><MinEnd>23:00</MinEnd><MaxEnd>1.08:00</MaxEnd><MinLength>15</MinLength><MaxLength>1440</MaxLength></Shift>

<Resources>

Resources contains resource ID's and numerical values. Resource values may also be specified to be used only on certain days in the planning period.

Parents : Shift

Attributes

None

Elements

Resources contains zero or more <Resource> elements.

NameRequiredTypeDescriptionVer.
<Resource>OptionalResourceA resource ID and quantity.1.47+.

Example

<ShiftID="D1"><Resources><ResourceID="ShiftUnits">2</Resource><ResourceID="TimeUnits">10</Resource></Resources></Shift>

<Resource>

Resource contains an ID attribute and a NonNegativeDouble value. A resource value may also be specified to be used only on certain days in the planning period using the attributes below. If none of these attributes are used then the resource value applies to all days in the planning period.

Parents : Resources

Attributes

NameRequiredTypeDescriptionVer.
IDRequiredstringThe ID for the resource.1.47+
DayOptionalNonNegativeIntegerIf this attribute is used then the value specified for this resource only applies on this day in the planning period (the first day is day zero).1.47+
DateOptionalDateIf this attribute is used then the value specified for this resource only applies on this date in the planning period. Specified in the format : YYYY-MM-DD.1.47+
DayOfWeekOptionalstringIf this attribute is used then the value specified for this resource only applies on these days of the week, in the planning period. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.1.47+

Element

Each <Resource> element is a NonNegativeDouble defining the quantity/value for this resource.

NameRequiredTypeDescriptionVer.
<Resource>OptionalNonNegativeDoubleA quantity/value for the specified resource ID.1.47+

Example

<ShiftID="D1"><Resources><ResourceID="TimeUnits">8</Resource><ResourceID="TimeUnits"DayOfWeek="Monday">12</Resource><ResourceID="R1"Date="2010-09-14">100</Resource><ResourceID="R1"Date="2010-09-15">100</Resource><ResourceID="R1"Date="2010-09-16">100</Resource></Resources></Shift>

<ShiftGroups>

Shift types can be placed in groups which are used in some constraints.

Parents : SchedulingHorizon

Attributes

None

Elements

ShiftGroups contains zero or more <ShiftGroup> elements.

NameRequiredTypeDescription
<ShiftGroup>OptionalShiftGroupA group of shift types.

Example

<ShiftGroups><ShiftGroupID="N"><Shift>N1</Shift><Shift>N2</Shift></ShiftGroup><ShiftGroupID="L"><Shift>L1</Shift><Shift>L2</Shift><Shift>L3</Shift></ShiftGroup><ShiftGroupID="E"><Shift>E1</Shift><Shift>E2</Shift><Shift>E3</Shift></ShiftGroup></ShiftGroups>

<ShiftGroup>

A group of shift types.

Parents : ShiftGroups

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this group.

Elements

ShiftGroup contains one or more <Shift> elements.

NameRequiredTypeDescription
<Shift>RequiredstringThe ID of a shift type. Specified in Shift attribute 'ID'.

Example

<ShiftGroupID="EN"><Shift>E</Shift><Shift>N</Shift></ShiftGroup>

<Contracts>

Contracts contain the constraints on the employees' work schedules.

Parents : SchedulingHorizon

Attributes

None

Elements

Contracts contains zero or more <Contract> elements.

NameRequiredTypeDescription
<Contract>OptionalContractContains the working preferences and requirements (constraints) for each employee with this contract.

Example

<Contracts><ContractID="C1"><ShiftLengths><Min><Length>300</Length><Label>Shift must not be less than 5h</Label><Weightfunction="quadratic">100</Weight></Min><Max><Length>480</Length><Label>Shifts must be more than 8h</Label><Weightfunction="quadratic">100</Weight></Max></ShiftLengths></Contract><ContractID="C2"><ShiftLengths><Min><Length>480</Length><Label>Shift must not be less than 8h</Label><Weightfunction="quadratic">100</Weight></Min><Max><Length>540</Length><Label>Shifts must be more than 9h</Label><Weightfunction="quadratic">100</Weight></Max></ShiftLengths></Contract></Contracts>

<Contract>

The working preferences and requirements (constraints) for each employee assigned this contract. Since version 1.36 an employee can be assigned more than one contract. If more than one contract is assigned to an employee then all the constraints in each contract apply to the employee.

Parents : Contracts

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this contract.

Elements

Contract contains zero or more of the following elements in any order.

NameRequiredTypeDescriptionVer.
<Label>OptionalstringA label for this contract which is used when displaying solutions.1.0+
<ShiftStartTimes>OptionalShiftStartTimesEarliest and latest shift start times (optionally for each day).1.0+
<ShiftEndTimes>OptionalShiftEndTimesEarliest and latest shift finish times (optionally for each day).1.0+
<ShiftStartEndTimes>OptionalShiftStartEndTimesValid combined start and finish times for shifts (optionally for each day).1.52+
<ShiftLengths>OptionalShiftLengthsMinimum and maximum shift lengths (optionally for each day).1.0+
<TaskLengths>OptionalTaskLengthsMinimum and maximum amount of time the employee can work consecutively on a single task.1.0+
<BreakDefinitions>OptionalBreakDefinitionsThe number of, length of and position of breaks. How many, how long and where the breaks should be positioned can be specified according to the shift length, shift start time and shift end time. 1.0+
<Workload>OptionalWorkloadMinimum and maximum total working time between any two dates in the planning period.1.0+
<Patterns>OptionalPatternsA flexible constraint which can model a wide variety of requirements on the employee's work schedule.1.0+
<AllowTaskTransfers>OptionalBooleanIf false then the employee will only be assigned one task type during a shift (apart from breaks), that is, they will not transfer between tasks during a shift. If this tag is omitted the default value is true, that is, by default tasks transfers are allowed during a shift.1.9+
<SplitShifts>OptionalSplitShiftsIf this is used then split-shifts can be assigned to the employee. Split-shifts are shifts which have durations where the employee is not at work. For example an employee may work from 09:00-12:00 then go home for five hours and then return to complete the shift from 17:00-22:00.1.16+
<UseIfNeeded>OptionalUseIfNeededIf this is used then employees with this contract will only be assigned shifts if they are needed. The constraint is given a weight and the employee will only be scheduled if doing so enables other constraints with higher weights to be satisfied. The constraint can be used to leave certain employees unscheduled if possible (for example, 'temporary' or 'dummy employees').1.36+
<MinRestTime>OptionalNonNegativeDoubleThe minimum amount of rest time (non-work time) required between shifts. The time is in minutes. This is a hard constraint.1.37+
<MinRestInPeriod>OptionalMinRestInPeriodA minimum amount of consecutive rest required within a defined period.1.59+
<MaxTot>OptionalMaxTotUsed for modelling constraints such as a maximum number of days on or off or a maximum number of shifts of a particular type (optionally between two dates in the planning period).1.37+
<MinTot>OptionalMinTotUsed for modelling constraints such as a minimum number of days on or off or a minimum number of shifts of a particular type (optionally between two dates in the planning period).1.37+
<MaxSeq>OptionalMaxSeqUsed for modelling constraints such as a maximum number of consecutive days on or off or a maximum number of consecutive shifts of a particular type.1.37+
<MinSeq>OptionalMinSeqUsed for modelling constraints such as a minimum number of consecutive days on or off or a minimum number of consecutive shifts of a particular type.1.37+

Example

<ContractID="C1"><MinRestTime>840</MinRestTime><ShiftStartTimes><Min><Time>07:00</Time><Label>Shifts must start after 7am</Label><Weight>10</Weight></Min><Max><Time>12:00</Time

AutoRoster problem data

XML format for AutoRoster problem instances

This document describes the data format used for AutoRoster problem instances. As well as being read by the rostering engine, the data format can also be read by RosterViewer. The data format is an XML based format and so can be created and edited using any text editor. An XML aware editor is recommended to allow the data to be validated against the format's schema as it is edited. Many XML editors also provide other useful features such as tag suggestion and auto-completion.

To help get started an AutoRoster XML template file is also available.

Although instances can be created by hand using an editor, in practice the XML is normally generated dynamically by another application. This XML is then passed to the rostering engine which solves the problem and returns the solution. The solution is also encoded using an XML format.

Throughout this document, a number of terms such as 'shift types', 'cells', 'scheduling period' are frequently used. The figure below shows an annotated example roster to help explain some commonly used terms.

The data required to describe an employee scheduling problem instance can be split into five main sections:

  • The planning horizon. The planning period (sometimes called the scheduling horizon) is simply specified using the tags <StartDate> and <EndDate>.
  • Shift types. The shift types that can be assigned in the roster. This information is specified within the tag <ShiftTypes>.
  • Employees. The employees available for assigning the shifts to are specified within the tag <Employees>.
  • Schedule constraints. The schedules (sometimes called work patterns) that each employee can work are usually subject to a large number of constraints. For example, constraints related to the min/max amount of work, weekends, night shifts etc.

    To model these requirements, three general constraints are provided (<Workload>, <Patterns> and <Conditionals>). The vast majority of scheduling requirements can be modelled using these constraints.

    These constraints are entered within the tag <Contracts>. Each employee can have their own contract but it is common for employees to have the same constraints so contracts may also be shared by two or more employees.

    The schedule for each employee in the current planning period is clearly also affected by the employee's schedule in the previous planning period. To model this there are two options:

    1. Include the previous planning period (or as much of it as is relevant) in the current planning period (by making the start date earlier) and then fix all these assignments in place using <FixedAssignments> so they cannot be changed. (See the example instance Ikegami-3Shift-DATA1 for an example of this method).

    2. The second option is to enter constraints (in the contracts) which are based on the assignments made in the previous schedules. For example if a night shift can only followed by a night shift or a day off and the last day of the previous schedule has a night shift, then enter a constraint (e.g. using <Patterns>) in this scheduling period which ensures that only a night shift or day off is assigned on the first day.

    The second method is usually more efficient for the solver but may be more effort to model. An effective compromise is to include some of the previous roster (fixed in place) and then add additional constraints for the ones which would require long sections of the previous schedule.
  • Cover constraints. Cover constraints describe the min and max numbers of employees that must be working each day. The cover can be specified per shift and/or for a specific time period in the day. The cover can be further split up by skill levels or requirements for specific groups of employees.

Examples of instances modelled using the format can be found in the example instances section. See also the FAQs for examples of how to model some of the more common constraints.

The root element of the document is <SchedulingPeriod>. This is the opening tag.

<SchedulingPeriod>

The root element of the document.

Attributes

NameRequiredTypeDescription
IDOptionalstringAn ID used to identify the instance.

Elements

SchedulingPeriod contains the following elements in any order:

NameRequiredTypeDescriptionVer.
<StartDate>RequiredDateThe date of the first day in the scheduling period. Specified in the format : YYYY-MM-DD.3.0+
<EndDate>RequiredDateThe date of the last day in the scheduling period. Specified in the format : YYYY-MM-DD.3.0+
<ShiftTypes>OptionalShiftTypesThe shifts to be assigned e.g. early shifts, night shifts, 12 hour shifts etc.3.0+
<ShiftGroups>OptionalShiftGroupsSome constraints require shift types to be grouped together (for example a group of night shifts). The groups are defined here.3.0+
<Contracts>OptionalContractsEach employee can have a different set of constraints for their work schedule. These are specified within contracts which are linked to each employee.3.0+
<Employees>OptionalEmployeesThe employees to be scheduled.3.0+
<Rules>OptionalRulesRules is an alternative way of expressing and modelling the constraints that are modelled using <Contracts>, <EmployeePairings> and <CoverRequirements>. Due to its flexibility it can also be used to create new, custom constraints.3.0+
<EmployeePairings>OptionalEmployeePairingsThis is used to model constraints such as two or more employees must work certain shifts at the same time. Or oppositely, two or more employees must not work certain shifts at the same time.3.0+
<SkillGroups>OptionalSkillGroupsSkills can be grouped together and cover specified for different skill groups. The groups are defined here.3.0+
<ShiftBlocks>OptionalShiftBlocksCover requirements can be specified for a sequence of consecutive shifts. These 'blocks' can be defined here.3.32+
<CoverRequirements>OptionalCoverRequirementsThe minimum and maximum numbers of employees working at certain times/shifts during the scheduling period.3.0+
<DayOffRequests>OptionalDayOffRequestsDates on which employees request not to be working.3.0+
<DayOnRequests>OptionalDayOnRequestsDates on which employees want to be working.3.0+
<ShiftOffRequests>OptionalShiftOffRequestsDates on which employees do not want specific shifts.3.0+
<ShiftOnRequests>OptionalShiftOnRequestsDates on which employees want specific shifts.3.0+
<FixedAssignments>OptionalFixedAssignmentsShift assignments and day off assignments which must be in the solution.3.0+

Example

<?xml version="1.0" encoding="UTF-8"?><SchedulingPeriodxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:noNamespaceSchemaLocation="SchedulingPeriod-3.0.xsd"><StartDate>2009-04-05</StartDate><EndDate>2009-04-30</EndDate><ShiftTypes><ShiftID="E"><Color>#66FF00</Color><StartTime>07:00:00</StartTime><EndTime>14:45:00</EndTime></Shift></ShiftTypes><Contracts><ContractID="A"><MaxTotlabel="Max 10 E shifts"value="10"shift="E"weight="1000"/></Contract></Contracts><Employees><EmployeeID="A"><ContractID>A</ContractID></Employee></Employees><CoverRequirements><DayOfWeekCover><Day>Saturday</Day><Cover><Shift>E</Shift><Minweight="1000">1</Min></Cover></DayOfWeekCover></CoverRequirements></SchedulingPeriod>

<SkillGroups>

Skills can be placed in groups for use in cover constraints.

Parents : SchedulingPeriod

Attributes

None

Elements

SkillGroups contains zero or more <SkillGroup> elements.

NameRequiredTypeDescription
<SkillGroup>OptionalSkillGroupA group of skills.

Example

<SkillGroups><SkillGroupID="AorB"><Skill>A</Skill><Skill>B</Skill></SkillGroup></SkillGroups>

<SkillGroup>

A group of skills.

Parents : SkillGroups

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this group.

Elements

SkillGroup contains one or more <Skill> elements.

NameRequiredTypeDescription
<Skill>RequiredstringA skill ID.

Example

<SkillGroupID="123"><Skill>1</Skill><Skill>2</Skill><Skill>3</Skill></SkillGroup>

<ShiftTypes>

ShiftTypes contains the definitions of the different shifts to be assigned in the scheduling period.

Parents : SchedulingPeriod

Attributes

None

Elements

Contains zero or more <Shift> elements.

NameRequiredTypeDescription
<Shift>OptionalShiftA specific shift type. For example a night shift.

Example

<ShiftTypes><ShiftID="N"><Label>N</Label><Color>LightBlue</Color><Name>Night</Name><StartTime>18:00:00</StartTime><EndTime>06:00:00</EndTime></Shift><ShiftID="E"><Label>E</Label><Color>LightGreen</Color><Name>Evening</Name><StartTime>12:00:00</StartTime><EndTime>20:00:00</EndTime></Shift><ShiftID="D"><Label>D</Label><Color>Yellow</Color><Name>Day</Name><StartTime>06:00:00</StartTime><EndTime>16:00:00</EndTime></Shift><ShiftID="O"><Label>O</Label><Color>Red</Color><Name>Other work</Name><StartTime>06:00:00</StartTime><EndTime>18:00:00</EndTime><AutoAllocate>false</AutoAllocate></Shift></ShiftTypes>

<Shift>

A specific shift type. For example a night shift.

Parents : ShiftTypes

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this shift type.

Elements

Shift contains the following elements in any order:

NameRequiredTypeDescription
<StartTime>OptionalTimeOfDayThe shift's start time. Specified in the format : hh:mm:ss or hh:mm. Default value is 00:00:00.
<EndTime>OptionalTimeOfDayThe shift's end time. Specified in the format : hh:mm:ss or hh:mm. Default value is 00:00:00. If the end time is earlier than the start time then it is assumed the shift finishes on the next day.
<Duration>OptionalNonNegativeIntegerThe shift's length in minutes. This can be used instead of EndTime. The maximum shift length is 48 hours minus the start time. That is, the shift can finish on the next day but not on the day after the next day (it can only span one midnight).
<Name>OptionalstringA name for this shift.
<Label>OptionalstringA label for the shift when displaying schedules. The ID is used if this element is omitted.
<Color>OptionalstringA colour for the shift when displaying schedules. Any valid HTML colour may be used.
<TimeUnits>OptionalNonNegativeDoubleThe amount of working time this shift counts as. This is used by the Workload constraint.
In version 3.23+ if this tag is not included then a value in minutes is automatically calculated.
<AutoAllocate>OptionalBooleanIf false then this shift will not be assigned by the solver (except where it is pre-assigned in FixedAssignments). If this tag is omitted the default value is true.
<TimePeriods>OptionalTimePeriodsIf the shift covers more than one time period in the day then the start and end times of the periods are specified here. This may be used to model shifts which actually represent a combination of two or more shifts.
<Resources>OptionalResourcesThis can be used to define 'resources' other than TimeUnits. The resources defined here are used in the Workload constraint to impose minimum and/or maximum limits on the amount of a resource that can be assigned to an employee.

Example

<ShiftID="E"><Label>E</Label><Color>#66FF00</Color><Name>Early</Name><StartTime>07:00:00</StartTime><EndTime>14:45:00</EndTime><TimeUnits>75</TimeUnits></Shift>

<Resources>

Resources contains resource ID's and numerical values. Resource values may also be specified to be used only on certain days in the planning period.

Parents : Shift

Attributes

None

Elements

Resources contains zero or more <Resource> elements.

NameRequiredTypeDescription
<Resource>OptionalResourceA resource ID and quantity.

Example

<ShiftID="D1"><TimePeriods><TimePeriod><Start>08:30:00</Start><End>15:30:00</End></TimePeriod><TimePeriod><Start>17:30:00</Start><End>22:30:00</End></TimePeriod></TimePeriods><Resources><ResourceID="ShiftUnits">2</Resource><ResourceID="TimeUnits">10</Resource></Resources></Shift>

<Resource>

Resource contains an ID attribute and a NonNegativeDouble value. A resource value may also be specified to be used only on certain days in the planning period using the attributes below. If none of these attributes are used then the resource value applies to all days in the planning period.

Parents : Resources

Attributes

NameRequiredTypeDescription
IDRequiredstringThe ID for the resource.
DayOptionalNonNegativeIntegerIf this attribute is used then the value specified for this resource only applies on this day in the planning period (the first day is day zero).
DateOptionalDateIf this attribute is used then the value specified for this resource only applies on this date in the planning period. Specified in the format : YYYY-MM-DD.
DayOfWeekOptionalstringIf this attribute is used then the value specified for this resource only applies on these days of the week, in the planning period. Valid values are 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.

Element

Each <Resource> element is a NonNegativeDouble defining the quantity/value for this resource.

NameRequiredTypeDescription
<Resource>OptionalNonNegativeDoubleA quantity/value for the specified resource ID.

Example

<ShiftID="D1"><Resources><ResourceID="TimeUnits">8</Resource><ResourceID="TimeUnits"DayOfWeek="Monday">12</Resource><ResourceID="R1"Date="2010-09-14">100</Resource><ResourceID="R1"Date="2010-09-15">100</Resource><ResourceID="R1"Date="2010-09-16">100</Resource></Resources></Shift>

<ShiftGroups>

Shift types can be placed in groups which are used in some constraints.

Parents : SchedulingPeriod

Attributes

None

Elements

ShiftGroups contains zero or more <ShiftGroup> elements.

NameRequiredTypeDescription
<ShiftGroup>OptionalShiftGroupA group of shift types.

Example

<ShiftGroups><ShiftGroupID="N"><Shift>N1</Shift><Shift>N2</Shift></ShiftGroup><ShiftGroupID="L"><Shift>L1</Shift><Shift>L2</Shift><Shift>L3</Shift></ShiftGroup><ShiftGroupID="E"><Shift>E1</Shift><Shift>E2</Shift><Shift>E3</Shift></ShiftGroup></ShiftGroups>

<ShiftGroup>

A group of shift types.

Parents : ShiftGroups

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this group.

Elements

ShiftGroup contains one or more <Shift> elements.

NameRequiredTypeDescription
<Shift>RequiredstringThe ID of a shift type. Specified in Shift attribute 'ID'.

Example

<ShiftGroupID="EN"><Shift>E</Shift><Shift>N</Shift></ShiftGroup>

<Contracts>

Contracts contain the constraints on the employees' work schedules.

Parents : SchedulingPeriod

Attributes

None

Elements

Contracts contains zero or more <Contract> elements.

NameRequiredTypeDescription
<Contract>OptionalContractContains the working preferences and requirements (constraints) for each employee with this contract.

Example

<Contracts><ContractID="FullTime"><Workload><TimeUnits><Max><Count>168</Count><Weightfunction="quadratic">100</Weight><Label>Max 168 hours</Label></Max><Min><Count>160</Count><Weightfunction="quadratic">100</Weight><Label>Min 160 hours</Label></Min><RegionStartDate>2014-09-01</RegionStartDate></TimeUnits></Workload><!-- Prevents the sequence off-on-off. --><MinSeqlabel="Min two consecutive working days"value="2"shift="E,D,L"weight="1000"/><!-- Prevents the sequence on-off-on. --><MinSeqlabel="Min two consecutive days off"value="2"shift="-"weight="1000"/><!-- Limit the employee to five consecutive working days. --><MaxSeqlabel="Max five consecutive working days"value="5"shift="E,D,L"weight="1000"/><!-- MinRestTime constraint. --><MinRestTimelabel="At least 14 hours rest after a shift"weight="10000">840</MinRestTime></Contract></Contracts>

<Contract>

The working preferences and requirements (constraints) for each employee assigned this contract. Note that since version 3.26 an employee can be assigned more than one contract. If more than one contract is assigned to an employee then all the constraints in each contract apply to the employee.

Parents : Contracts

Attributes

NameRequiredTypeDescription
IDRequiredIDA unique ID for this contract.

Elements

Contract may contain zero or more of the following elements in any order.

NameRequiredTypeDescriptionVer.
<Conditionals>OptionalConditionalsConditional constraints take the form of IF ... THEN ... statements. The IF and THEN expressions contain boolean variables and the operators 'AND' and 'OR'. The variables are defined in the Patterns and Workload constraints and will have the values true or false depending on whether the underlying pattern or workload constraint is satisfied. If the IF expression evaluates to true then the THEN expression must also evaluate to true otherwise the constraint is violated. 3.0+
<DailyRest>OptionalDailyRestA minimum amount of continuous rest (non-work) time required during 24 hours.3.31+
<Label>OptionalstringA label for this contract (used when displaying solutions).3.0+
<MaxSeq>OptionalMaxSeqUsed for modelling constraints such as a maximum number of consecutive days on or off or a maximum number of consecutive shifts of a particular type.3.26+
<MaxTot>OptionalMaxTotUsed for modelling constraints such as a maximum number of days on or off or a maximum number of shifts of a particular type (optionally between two dates in the planning period).3.26+
<MaxWeekends>OptionalMaxWeekendsUsed for modelling constraints such as a maximum number of weekends or weekend shifts.3.34+
<MinRestTime>OptionalMinRestTimeA minimum amount of rest (non-work) time in minutes required after shifts (or specific shifts).3.24+
<MinSeq>OptionalMinSeqUsed for modelling constraints such as a minimum number of consecutive days on or off or a minimum number of consecutive shifts of a particular type.3.26+
<MinTot>OptionalMinTotUsed for modelling constraints such as a minimum number of days on or off or a minimum number of shifts of a particular type (optionally between two dates in the planning period).3.26+
<MinWeekends>OptionalMinWeekendsUsed for modelling constraints such as a minimum number of weekends or weekend shifts.3.34+
<MultipleShiftsPerDay>OptionalMultipleShiftsPerDayBy default employees cannot be assigned more than one shift per day. This is used to allow more than one shift to assigned on a day. 3.19+
<Patterns>OptionalPatternsThis is a very general and flexible constraint which can model a wide variety of requirements on the employee's schedule.3.0+
<RestBetweenDates>OptionalRestBetweenDatesA minimum amount of continuous rest (non-work) time required between two dates.3.31+
<ValidShifts>OptionalValidShiftsUsed to restrict which shift types can be assigned to employees with this contract. This is a hard constraint, meaning only the shifts defined here can be assigned. If this tag is not used then all shift types can be assigned. 3.28+
<Workload>OptionalWorkloadThis constraint is used to model the requirements of min/max total time units (or any other resource) between any two dates in the planning period. Each shift has an associated number of time units (and other resources) (see ShiftTypes).3.0+

Example

<ContractID="StandardConstraints"><!-- Limit the employee to five consecutive working days. --><MaxSeqlabel="Max five consecutive working days"value="5"shift="$"weight="1000"/><!-- MinRestTime constraint. --><MinRestTimelabel="At least 14 hours rest after a shift"weight="10000">840</MinRestTime><!-- Prevent the sequence on-off-on. --><MinSeqlabel="Min two consecutive days off"value="2"shift="-"weight="1000"/><!-- Let all staff be assigned these shifts: --><ValidShiftsshift="EA,DA,LA"/><Workload><TimeUnits><Max><Count>168</Count><Weightfunction="quadratic">100</Weight><Label>Max 168 hours</Label></Max><RegionStartDate>2014-09-01</RegionStartDate></TimeUnits></Workload></Contract>

<Workload>

This constraint is used to model the requirements of min/max total time units (or any other resource) between any two dates in the planning period. Each shift has an associated number of time units (and other resources) (see ShiftTypes).

Parents : Contract

Attributes

None

Elements

Workload contains one or more <TimeUnits> elements.

NameRequiredTypeDescription
<TimeUnits>RequiredTimeUnitsTimeUnits specifies a minimum and/or maximum total number of time units (or other resource) that can be assigned to the employee between any two dates in the planning period.

Example

<Workload><TimeUnits><Max><Count>1500</Count><Weight>100</Weight><Label>Max 150 hours for the total planning period</Label></Max></TimeUnits></Workload>

<TimeUnits>

TimeUnits specifies a minimum and/or maximum total number of time units (or other resource) that can be assigned to the employee between any two dates in the planning period. The dates can be specified using the day number in the planning horizon or actual dates. The first day in the planning period is day zero.

Parents : Workload

Attributes

None

Elements

Workload contains a <Min> and/or a <Max> element (in either order) a <RegionStart> or <RegionStartDate> (both are optional) a <RegionEnd> or <RegionEndDate> (both are optional) a <ShiftGroup> (optional) and a <Resource> (optional).

The default start day is day zero if <RegionStart> and <RegionStartDate> are omitted. The default end day is the last day in the planning horizon if <RegionEnd> and <RegionEndDate> are omitted.

NameRequiredTypeDescription
<Min>OptionalMinThe minimum number of time units.
<Max>OptionalMaxThe maximum number of time units.
<RegionStart>OptionalNonNegativeIntegerThe first day of the region in the planning period that this constraint applies to (the day is inclusive). The planning period starts on day zero.
<RegionStartDate>OptionalDateThe first day of the region in the planning period that this constraint applies to (the day is inclusive). Specified in the format : YYYY-MM-DD.
<RegionEnd>OptionalNonNegativeIntegerThe last day of the region in the planning period that this constraint applies to (the day is inclusive). The planning period starts on day zero.
<RegionEndDate>OptionalDateThe last day of the region in the planning period that this constraint applies to (the day is inclusive). Specified in the format : YYYY-MM-DD.
<ShiftGroup>OptionalstringIf a ShiftGroup is specified then only work done during the shift types in this group will be counted. The group is specified using an ID defined in ShiftGroups. Since version 3.29 it is also possible to specify a shift group as a comma separated list of ShiftType ID's (e.g. "E,D,L,N").
<Resource>OptionalstringIf a Resource is specified then units of that Resource are counted by the constraint instead of TimeUnits (the default resource). The Resource ID's and units of resource for each ShiftType are defined in ShiftTypes.

Example

<TimeUnits><Max><Count>750</Count><Weight>100</Weight><Label>Max 75 hours in two weeks</Label></Max><RegionStart>0</RegionStart><RegionEnd>13</RegionEnd></TimeUnits>

<Min>

Specifies a minimum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty function. It can then also have a function type to calculate the penalty function value. For example if a minimum is not satisfied and the function type specified is linear then the penalty function value will be the minimum value minus the value provided in the solution then multiplied by the weight. If the function is quadratic it will be minimum value minus the value provided in the solution then squared and then multiplied by the weight.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : TimeUnits

Attributes

None

Elements

Min contains the following elements in any order.

NameRequiredTypeDescription
<Count>RequiredNonNegativeDoubleThe minimum value.
<Weight>OptionalNonNegativeDoubleA value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic" , "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var>OptionalIDIf this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label>OptionalstringA label for this constraint for when displaying a solution.

Example

<Min><Count>1</Count><Weightfunction="Quadratic">1000</Weight></Min>

<Max>

Specifies a maximum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty function. It can then also have a function type to calculate the penalty function value. For example if a maximum is exceeded and the function type specified is linear then the penalty function value will be the value provided in the solution minus the maximum value then multiplied by the weight. If the function is quadratic it will be the value provided in the solution minus the maximum value then squared and then multiplied by the weight.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : TimeUnits

Attributes

None

Elements

Max contains the following elements in any order.

NameRequiredTypeDescription
<Count>RequiredNonNegativeDoubleThe maximum value.
<Weight>OptionalNonNegativeDoubleA value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var>OptionalIDIf this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label>OptionalstringA label for this constraint for when displaying a solution.

Example

<Max><Count>1</Count><Weightfunction="Quadratic">1000</Weight></Max>

<Min>

Specifies a minimum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty function. It can then also have a function type to calculate the penalty function value. For example if a minimum is not satisfied and the function type specified is linear then the penalty function value will be the minimum value minus the value provided in the solution then multiplied by the weight. If the function is quadratic it will be minimum value minus the value provided in the solution then squared and then multiplied by the weight.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : Match

Attributes

None

Elements

Min contains the following elements in any order.

NameRequiredTypeDescription
<Count>RequiredNonNegativeIntegerThe minimum value.
<Weight>OptionalNonNegativeDoubleA value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic" , "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var>OptionalIDIf this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label>OptionalstringA label for this constraint for when displaying a solution.

Example

<Min><Count>1</Count><Weightfunction="Quadratic">1000</Weight></Min>

<Max>

Specifies a maximum value for a constraint.

If the constraint has a weight it is a soft constraint and is part of the penalty function. It can then also have a function type to calculate the penalty function value. For example if a maximum is exceeded and the function type specified is linear then the penalty function value will be the value provided in the solution minus the maximum value then multiplied by the weight. If the function is quadratic it will be the value provided in the solution minus the maximum value then squared and then multiplied by the weight.

If the Var tag is used then the constraint becomes a boolean variable which can be referenced in the Conditional constraints. As a variable it is not considered in solution feasibility or the penalty function. It can only effect feasibility and the penalty function value through the Conditional constraints.

If neither the Var nor Weight tag is used then the constraint is a hard constraint by default.

Parents : Match

Attributes

None

Elements

Max contains the following elements in any order.

NameRequiredTypeDescription
<Count>RequiredNonNegativeIntegerThe maximum value.
<Weight>OptionalNonNegativeDoubleA value to represent this constraint's priority. Weight can optionally also have an attribute : function which can have the value "Linear", "Quadratic", "Constant" or "Constraint" (case-insensitive). The default value is "Linear". If "Constraint" is used then the weight value is ignored. If this element is omitted then the constraint is considered to be a hard constraint.
<Var>OptionalIDIf this element is used then the constraint becomes a boolean variable with the specified ID. Its value will be true if this constraint is satisfied and false if it is not satisfied. The variable can then be used in the Conditional constraints.
<Label>OptionalstringA label for this constraint for when displaying a solution.

Example

<Max><