ExamModel (Constraint Solver API Documentation -- CPSolver v1.2 build 156)

java.lang.Object
- net.sf.cpsolver.ifs.model.Model<Exam,ExamPlacement>
- - net.sf.cpsolver.exam.model.ExamModel

```
public class ExamModel
extends Model<Exam,ExamPlacement>
```
Examination timetabling model. Exams Exam are modeled as variables, rooms ExamRoom and students ExamStudent as constraints. Assignment of an exam to time (modeled as non-overlapping periods ExamPeriod) and space (set of rooms) is modeled using values ExamPlacement. In order to be able to model individual period and room preferences, period and room assignments are wrapped with ExamPeriodPlacement and ExamRoomPlacement classes respectively. Moreover, additional distribution constraint ExamDistributionConstraint can be defined in the model.

The objective function consists of the following criteria:
- Direct student conflicts (a student is enrolled in two exams that are scheduled at the same period, weighted by Exams.DirectConflictWeight)
- Back-to-Back student conflicts (a student is enrolled in two exams that are scheduled in consecutive periods, weighted by Exams.BackToBackConflictWeight). If Exams.IsDayBreakBackToBack is false, there is no conflict between the last period and the first period of consecutive days.
- Distance Back-to-Back student conflicts (same as Back-to-Back student conflict, but the maximum distance between rooms in which both exam take place is greater than Exams.BackToBackDistance, weighted by Exams.DistanceBackToBackConflictWeight).
- More than two exams a day (a student is enrolled in three exams that are scheduled at the same day, weighted by Exams.MoreThanTwoADayWeight).
- Period penalty (total of period penalties PeriodPenalty of all assigned exams, weighted by Exams.PeriodWeight).
- Room size penalty (total of room size penalties RoomSizePenalty of all assigned exams, weighted by Exams.RoomSizeWeight).
- Room split penalty (total of room split penalties RoomSplitPenalty of all assigned exams, weighted by Exams.RoomSplitWeight).
- Room penalty (total of room penalties RoomPenalty of all assigned exams, weighted by Exams.RoomWeight).
- Distribution penalty (total of distribution constraint weights ExamDistributionConstraint.getWeight() of all soft distribution constraints that are not satisfied, i.e., ExamDistributionConstraint.isSatisfied() = false; weighted by Exams.DistributionWeight).
- Direct instructor conflicts (an instructor is enrolled in two exams that are scheduled at the same period, weighted by Exams.InstructorDirectConflictWeight)
- Back-to-Back instructor conflicts (an instructor is enrolled in two exams that are scheduled in consecutive periods, weighted by Exams.InstructorBackToBackConflictWeight). If Exams.IsDayBreakBackToBack is false, there is no conflict between the last period and the first period of consecutive days.
- Distance Back-to-Back instructor conflicts (same as Back-to-Back instructor conflict, but the maximum distance between rooms in which both exam take place is greater than Exams.BackToBackDistance, weighted by Exams.InstructorDistanceBackToBackConflictWeight).
- Room split distance penalty (if an examination is assigned between two or three rooms, distance between these rooms can be minimized using this criterion)
- Front load penalty (large exams can be penalized if assigned on or after a certain period)
Version:

ExamTT 1.2 (Examination Timetabling)
Copyright (C) 2008 - 2010 Tomáš Müller
muller@unitime.org
http://muller.unitime.org

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not see http://www.gnu.org/licenses/.

Field Summary
- Fields inherited from class net.sf.cpsolver.ifs.model.Model
  iAssignedVariables, iPerturbVariables, iUnassignedVariables, sDoubleFormat, sPercentageFormat, sTimeFormat

Constructor Summary

Constructors
Constructor and Description

ExamModel(DataProperties properties)
Constructor

Constructors
Constructor and Description
`ExamModel(DataProperties properties)` Constructor

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ExamPeriod`	`addPeriod(Long id, String day, String time, int length, int penalty)` Add a period
`void`	`afterAssigned(long iteration, ExamPlacement placement)` Called after a value is assigned to its variable, optimization criteria are updated
`void`	`beforeUnassigned(long iteration, ExamPlacement placement)` Called before a value is unassigned from its variable, optimization criteria are updated
`double`	`getBackToBackDistance()` Back-to-back distance, can be set by problem property Exams.BackToBackDistance, or in the input xml file, property backToBackDistance)
`DistanceMetric`	`getDistanceMetric()`
`List<ExamDistributionConstraint>`	`getDistributionConstraints()` Distribution constraints
`Map<String,String>`	`getExtendedInfo()` Extended info table
`List<ExamInstructor>`	`getInstructors()` Problem instructors
`int`	`getMaxRooms()` Default maximum number of rooms (can be set by problem property Exams.MaxRooms, or in the input xml file, property maxRooms)
`int`	`getNrDays()` Number of days
`int`	`getNrPeriods()` Number of periods
`ExamPeriod`	`getPeriod(Long id)` Period of given unique id
`List<ExamPeriod>`	`getPeriods()` List of periods, use `addPeriod(Long, String, String, int, int)` to add a period
`DataProperties`	`getProperties()` Problem properties
`List<ExamRoom>`	`getRooms()` Problem rooms
`ExamRoomSharing`	`getRoomSharing()` Return examination room sharing model
`List<ExamStudent>`	`getStudents()` Problem students
`double[]`	`getTotalMultiValue()` Return weighted individual objective criteria.
`double`	`getTotalValue()` Objective function.
`boolean`	`hasRoomSharing()` True if there is an examination sharing model
`void`	`init()` Initialization of the model
`boolean`	`isDayBreakBackToBack()` True when back-to-back student conflict is to be encountered when a student is enrolled into an exam that is on the last period of one day and another exam that is on the first period of the consecutive day.
`boolean`	`load(Document document)` Load model (including its solution) from XML.
`boolean`	`load(Document document, Callback saveBest)` Load model (including its solution) from XML.
`Document`	`save()` Save model (including its solution) into XML.
`void`	`setMaxRooms(int maxRooms)` Default maximum number of rooms (can be set by problem property Exams.MaxRooms, or in the input xml file, property maxRooms)
`void`	`setRoomSharing(ExamRoomSharing sharing)` Set examination sharing model
`String`	`toString()` String representation -- returns a list of values of objective criteria

Methods inherited from class net.sf.cpsolver.ifs.model.Model
addConstraint, addCriterion, addGlobalConstraint, addModelListener, addVariable, afterUnassigned, assignedVariables, beforeAssigned, bestUnassignedVariables, clearBest, conflictConstraints, conflictValues, constraints, countConstraints, countGlobalConstraints, countVariables, getBestPerturbations, getBestUnassignedVariables, getCriteria, getCriterion, getInfo, getInfo, getInfoProviders, getModelListeners, getPerc, getPercRev, getTotalValue, globalConstraints, inConflict, init, invalidateVariablesWithInitialValueCache, modelListenerOfType, nrAssignedVariables, nrUnassignedVariables, perturbVariables, perturbVariables, removeConstraint, removeCriterion, removeCriterion, removeGlobalConstraint, removeModelListener, removeVariable, restoreBest, restoreBest, saveBest, unassignedHardConstraints, unassignedVariables, variables, variablesWithInitialValue, weaken

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - ExamModel
```
public ExamModel(DataProperties properties)
```
    Constructor
    
    Parameters:
    
    properties - problem properties
- Method Detail
  - getDistanceMetric
```
public DistanceMetric getDistanceMetric()
```
  - hasRoomSharing
```
public boolean hasRoomSharing()
```
    True if there is an examination sharing model
  - getRoomSharing
```
public ExamRoomSharing getRoomSharing()
```
    Return examination room sharing model
  - setRoomSharing
```
public void setRoomSharing(ExamRoomSharing sharing)
```
    Set examination sharing model
  - init
```
public void init()
```
    Initialization of the model
  - getMaxRooms
```
public int getMaxRooms()
```
    Default maximum number of rooms (can be set by problem property Exams.MaxRooms, or in the input xml file, property maxRooms)
  - setMaxRooms
```
public void setMaxRooms(int maxRooms)
```
    Default maximum number of rooms (can be set by problem property Exams.MaxRooms, or in the input xml file, property maxRooms)
  - addPeriod
```
public ExamPeriod addPeriod(Long id,
                            String day,
                            String time,
                            int length,
                            int penalty)
```
    Add a period
    
    Parameters:
    
    id - period unique identifier
    
    day - day (e.g., 07/12/10)
    
    time - (e.g., 8:00am-10:00am)
    
    length - length of period in minutes
    
    penalty - period penalty
  - getNrDays
```
public int getNrDays()
```
    Number of days
  - getNrPeriods
```
public int getNrPeriods()
```
    Number of periods
  - getPeriods
```
public List<ExamPeriod> getPeriods()
```
    List of periods, use addPeriod(Long, String, String, int, int) to add a period
    
    Returns:
    
    list of ExamPeriod
  - getPeriod
```
public ExamPeriod getPeriod(Long id)
```
    Period of given unique id
  - isDayBreakBackToBack
```
public boolean isDayBreakBackToBack()
```
    True when back-to-back student conflict is to be encountered when a student is enrolled into an exam that is on the last period of one day and another exam that is on the first period of the consecutive day. It can be set by problem property Exams.IsDayBreakBackToBack, or in the input xml file, property isDayBreakBackToBack)
  - getBackToBackDistance
```
public double getBackToBackDistance()
```
    Back-to-back distance, can be set by problem property Exams.BackToBackDistance, or in the input xml file, property backToBackDistance)
  - beforeUnassigned
```
public void beforeUnassigned(long iteration,
                             ExamPlacement placement)
```
    Called before a value is unassigned from its variable, optimization criteria are updated
    
    Overrides:
    
    beforeUnassigned in class Model<Exam,ExamPlacement>
  - afterAssigned
```
public void afterAssigned(long iteration,
                          ExamPlacement placement)
```
    Called after a value is assigned to its variable, optimization criteria are updated
    
    Overrides:
    
    afterAssigned in class Model<Exam,ExamPlacement>
  - getTotalValue
```
public double getTotalValue()
```
    Objective function.
    
    Overrides:
    
    getTotalValue in class Model<Exam,ExamPlacement>
    
    Returns:
    
    weighted sum of objective criteria
  - getTotalMultiValue
```
public double[] getTotalMultiValue()
```
    Return weighted individual objective criteria.
    
    Returns:
    
    an array of weighted objective criteria
  - toString
```
public String toString()
```
    String representation -- returns a list of values of objective criteria
    
    Overrides:
    
    toString in class Model<Exam,ExamPlacement>
  - getExtendedInfo
```
public Map<String,String> getExtendedInfo()
```
    Extended info table
    
    Overrides:
    
    getExtendedInfo in class Model<Exam,ExamPlacement>
  - getProperties
```
public DataProperties getProperties()
```
    Problem properties
  - getRooms
```
public List<ExamRoom> getRooms()
```
    Problem rooms
    
    Returns:
    
    list of ExamRoom
  - getStudents
```
public List<ExamStudent> getStudents()
```
    Problem students
    
    Returns:
    
    list of ExamStudent
  - getInstructors
```
public List<ExamInstructor> getInstructors()
```
    Problem instructors
    
    Returns:
    
    list of ExamInstructor
  - getDistributionConstraints
```
public List<ExamDistributionConstraint> getDistributionConstraints()
```
    Distribution constraints
    
    Returns:
    
    list of ExamDistributionConstraint
  - save
```
public Document save()
```
    Save model (including its solution) into XML.
  - load
```
public boolean load(Document document)
```
    Load model (including its solution) from XML.
  - load
```
public boolean load(Document document,
                    Callback saveBest)
```
    Load model (including its solution) from XML.

Class ExamModel

Field Summary

Fields inherited from class net.sf.cpsolver.ifs.model.Model

Constructor Summary

Method Summary

Methods inherited from class net.sf.cpsolver.ifs.model.Model

Methods inherited from class java.lang.Object

Constructor Detail

ExamModel

Method Detail

getDistanceMetric

hasRoomSharing

getRoomSharing

setRoomSharing

init

getMaxRooms

setMaxRooms

addPeriod

getNrDays

getNrPeriods

getPeriods

getPeriod

isDayBreakBackToBack

getBackToBackDistance

beforeUnassigned

afterAssigned

getTotalValue

getTotalMultiValue

toString

getExtendedInfo

getProperties

getRooms

getStudents

getInstructors

getDistributionConstraints

save

load

load