net.sf.cpsolver.exam.model
Class Exam

java.lang.Object
  extended by net.sf.cpsolver.ifs.model.Variable<Exam,ExamPlacement>
      extended by net.sf.cpsolver.exam.model.Exam
All Implemented Interfaces:
Comparable<Exam>

public class Exam
extends Variable<Exam,ExamPlacement>

Representation of an exam (problem variable). Each exam has defined a length (in minutes), type (whether it is a section or a course exam), seating type (whether it requires normal or alternate seating) and a maximal number of rooms. If the maximal number of rooms is zero, the exam will be timetabled only in time (it does not require a room).

An exam can be only assigned to a period ExamPeriod that is long enough (see ExamPeriod.getLength()) and that is available for the exam (see getPeriodPlacements()).

A set of rooms that are available in the given period (see ExamRoom.isAvailable(ExamPeriod), ExamRoomPlacement.isAvailable(ExamPeriod)), and which together cover the size of exam (number of students attending the exam) has to be assigned to an exam. Based on the type of seating (see hasAltSeating()), either room sizes (see ExamRoom.getSize()) or alternative seating sizes (see ExamRoom.getAltSize()) are used. An exam has a list of available rooms with their penalties assiciated with (see getRoomPlacements()).

Various penalties for an assignment of a period or a set of rooms may apply. See ExamPlacement for more details.

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
protected static DecimalFormat sDoubleFormat
           
 
Fields inherited from class net.sf.cpsolver.ifs.model.Variable
iId, iValue
 
Constructor Summary
Exam(long id, String name, int length, boolean altSeating, int maxRooms, int minSize, List<ExamPeriodPlacement> periodPlacements, List<ExamRoomPlacement> roomPlacements)
          Constructor
 
Method Summary
 void addContstraint(Constraint<Exam,ExamPlacement> constraint)
          Adds a constraint.
 void allowAllStudentConflicts(ExamPeriod period)
          Allow all direct student conflict for the given period (see ExamStudent.canConflict(Exam, Exam)).
 void assign(long iteration, ExamPlacement placement)
          Assign value to this variable.
 boolean checkDistributionConstraints(ExamPeriodPlacement period)
          Check all distribution constraint that this exam is involved in
 boolean checkDistributionConstraints(ExamRoomPlacement room)
          Check all distribution constraint that this exam is involved in
 int compareTo(Exam o)
          An exam with more correlated exams is preferred ( nrStudentCorrelatedExams()).
 int countStudentConflicts(ExamPeriodPlacement period)
          Number of students of this exam (that does not have direct conflicts allowed, see ExamStudent.canConflict(Exam, Exam)) that attend some other exam in the given period.
 Set<ExamRoomPlacement> findBestAvailableRooms(ExamPeriodPlacement period)
          Find best available rooms for the exam in the given period.
 Set<ExamRoomPlacement> findRoomsRandom(ExamPeriodPlacement period)
          Randomly find a set of available rooms for the exam in the given period.
 Set<ExamRoomPlacement> findRoomsRandom(ExamPeriodPlacement period, boolean checkConflicts)
          Randomly find a set of available rooms for the exam in the given period.
 int getAveragePeriod()
          Average period.
 int getDistributionConstraintPenalty(ExamRoomPlacement room)
          Check all soft distribution constraint that this exam is involved in
 List<ExamDistributionConstraint> getDistributionConstraints()
          List of distribution constraints that this exam is involved in
 List<ExamInstructor> getInstructors()
          List of instructors that are assigned to this exam
 Map<Exam,List<ExamStudent>> getJointEnrollments()
          Joint enrollments
 int getLength()
          Length of the exam in minutes.
 int getMaxRooms()
          Maximal number of rooms that can be assigned to the exam
 int getMinSize()
          Minimal exam size, see getSize()
 String getName()
          Exam name
 List<ExamOwner> getOwners()
          Courses and/or sections that are having this exam
 Collection<ExamOwner> getOwners(ExamInstructor instructor)
          Courses/sections of this exam into which the given instructor is enrolled into
 Collection<ExamOwner> getOwners(ExamStudent student)
          Courses/sections of this exam into which the given student is enrolled into
 ExamPeriodPlacement getPeriodPlacement(ExamPeriod period)
          Returns appropriate ExamPeriodPlacement for the given period, if it is available for this exam, null otherwise.
 ExamPeriodPlacement getPeriodPlacement(Long periodId)
          Returns appropriate ExamPeriodPlacement for the given period, if it is available for this exam, null otherwise.
 List<ExamPeriodPlacement> getPeriodPlacements()
          Return list of possible period placements.
 Integer getPrintOffset()
          Print offset -- for reporting purposes
 ExamRoomPlacement getRoomPlacement(ExamRoom room)
          Returns appropriate ExamRoomPlacement for the given room, if it is available for this exam, null otherwise.
 ExamRoomPlacement getRoomPlacement(long roomId)
          Returns appropriate ExamRoomPlacement for the given room, if it is available for this exam, null otherwise.
 List<ExamRoomPlacement> getRoomPlacements()
          Return list of possible room placements.
 int getSize()
          Exam size, it is bigger from getMinSize() and the number of students enrolled into the exam getStudents().
 Integer getSizeOverride()
          Override exam size with given value (revert to default when null)
 HashSet<Exam> getStudentConflicts(ExamPeriod period)
          List of exams that are assigned to the given period and share one or more students with this exam (that does not have direct conflicts allowed, see ExamStudent.canConflict(Exam, Exam)).
 Set<Exam> getStudentCorrelatedExams()
          Exams that are correlated with this exam (there is at least one student attending both exams).
 List<ExamStudent> getStudents()
          List of students that are enrolled in the exam
 boolean hasAltSeating()
          True if alternative seating is required (ExamRoom.getAltSize() is to be used), false if normal seating is required ( ExamRoom.getSize() is to be used).
 boolean hasAveragePeriod()
          True if there is an average period assigned to the exam.
 boolean hasName()
          Exam name
 boolean hasStudentConflictWithPreAssigned(ExamPeriod period)
          True, if there is a student of this exam (that does not have direct conflicts allowed, see ExamStudent.canConflict(Exam, Exam)) that attends some other exam in the given period.
 boolean hasValues()
          Return true if there are some values in the domain of this variable
 boolean isAllowDirectConflicts()
          True if a direct student conflict is allowed, see ExamStudent.canConflict(Exam, Exam)
 int nrStudentCorrelatedExams()
          Number of exams that are correlated with this exam (there is at least one student attending both exams).
 void removeContstraint(Constraint<Exam,ExamPlacement> constraint)
          Removes a constraint.
 void setAllowDirectConflicts(boolean allowDirectConflicts)
          Set whether a direct student conflict is allowed, see ExamStudent.canConflict(Exam, Exam)
 void setAveragePeriod(int period)
          Set average period.
 void setMaxRooms(int maxRooms)
          Set maximal number of rooms that can be assigned to the exam
 void setMinSize(int minSize)
          Minimal exam size, see getSize()
 void setName(String name)
          Exam name
 void setPrintOffset(Integer printOffset)
          Print offset -- for reporting purposes
 void setSizeOverride(Integer size)
          Override exam size with given value (revert to default when null)
 String toString()
          String representation
 List<ExamPlacement> values()
          Values (assignment of a period and a set of rooms)
 
Methods inherited from class net.sf.cpsolver.ifs.model.Variable
addVariableListener, constraints, constraintVariables, countAssignments, equals, getAssignment, getBestAssignment, getBestAssignmentIteration, getDescription, getExtra, getId, getInitialAssignment, getModel, getVariableListeners, hardConstraints, hasAssignment, hashCode, hasInitialAssignment, lastAssignmentIteration, lastUnassignmentIteration, removeInitialValue, removeValue, removeVariableListener, setBestAssignment, setExtra, setInitialAssignment, setModel, setValues, softConstraints, unassign
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

sDoubleFormat

protected static DecimalFormat sDoubleFormat
Constructor Detail

Exam

public Exam(long id,
            String name,
            int length,
            boolean altSeating,
            int maxRooms,
            int minSize,
            List<ExamPeriodPlacement> periodPlacements,
            List<ExamRoomPlacement> roomPlacements)
Constructor

Parameters:
id - exam unique id
length - exam length in minutes
altSeating - true if alternative seating is requested
maxRooms - maximum number of rooms to be used
minSize - minimal size of rooms into which an exam can be assigned (see getSize())
periodPlacements - list of periods and their penalties ExamPeriodPlacement into which an exam can be assigned
roomPlacements - list of rooms and their penalties ExamRoomPlacement into which an exam can be assigned
Method Detail

getSize

public int getSize()
Exam size, it is bigger from getMinSize() and the number of students enrolled into the exam getStudents(). If getMaxRooms() is greater than zero, an exam must be assigned into rooms which overall size (or alternative seating size if hasAltSeating()) must be equal or greater than this size.


setSizeOverride

public void setSizeOverride(Integer size)
Override exam size with given value (revert to default when null)


getSizeOverride

public Integer getSizeOverride()
Override exam size with given value (revert to default when null)


getPrintOffset

public Integer getPrintOffset()
Print offset -- for reporting purposes


setPrintOffset

public void setPrintOffset(Integer printOffset)
Print offset -- for reporting purposes


getMinSize

public int getMinSize()
Minimal exam size, see getSize()


setMinSize

public void setMinSize(int minSize)
Minimal exam size, see getSize()


values

public List<ExamPlacement> values()
Values (assignment of a period and a set of rooms)

Overrides:
values in class Variable<Exam,ExamPlacement>
Returns:
list of ExamPlacement

getRoomPlacements

public List<ExamRoomPlacement> getRoomPlacements()
Return list of possible room placements.

Returns:
list of ExamRoomPlacement

getPeriodPlacements

public List<ExamPeriodPlacement> getPeriodPlacements()
Return list of possible period placements.

Returns:
list of ExamPeriodPlacement

hasAltSeating

public boolean hasAltSeating()
True if alternative seating is required (ExamRoom.getAltSize() is to be used), false if normal seating is required ( ExamRoom.getSize() is to be used).

Returns:
true if alternative seating is required, false otherwise

getLength

public int getLength()
Length of the exam in minutes. The assigned period has to be of the same or greater length.

Returns:
length of the exam in minutes

setAveragePeriod

public void setAveragePeriod(int period)
Set average period. This represents an average period that the exam was assigned to in the past. If set, it is used in exam rotation penalty ExamRotationPenalty in order to put more weight on exams that were badly assigned last time(s) and ensuring some form of fairness.

Parameters:
period - average period

getAveragePeriod

public int getAveragePeriod()
Average period. This represents an average period that the exam was assigned to in the past. If set, it is used in exam rotation penalty ExamRotationPenalty in order to put more weight on exams that were badly assigned last time(s) and ensuring some form of fairness.

Returns:
average period

hasAveragePeriod

public boolean hasAveragePeriod()
True if there is an average period assigned to the exam. This represents an average period that the exam was assigned to in the past. If set, it is used in exam rotation penalty ExamRotationPenalty in order to put more weight on exams that were badly assigned last time(s) and ensuring some form of fairness.


isAllowDirectConflicts

public boolean isAllowDirectConflicts()
True if a direct student conflict is allowed, see ExamStudent.canConflict(Exam, Exam)

Returns:
true if a direct student conflict is allowed

setAllowDirectConflicts

public void setAllowDirectConflicts(boolean allowDirectConflicts)
Set whether a direct student conflict is allowed, see ExamStudent.canConflict(Exam, Exam)

Parameters:
allowDirectConflicts - true if a direct student conflict is allowed

addContstraint

public void addContstraint(Constraint<Exam,ExamPlacement> constraint)
Adds a constraint. Called automatically when the constraint is added to the model, i.e., Model.addConstraint(Constraint) is called.

Overrides:
addContstraint in class Variable<Exam,ExamPlacement>
Parameters:
constraint - added constraint

removeContstraint

public void removeContstraint(Constraint<Exam,ExamPlacement> constraint)
Removes a constraint. Called automatically when the constraint is removed from the model, i.e., Model.removeConstraint(Constraint) is called.

Overrides:
removeContstraint in class Variable<Exam,ExamPlacement>
Parameters:
constraint - added constraint

getStudents

public List<ExamStudent> getStudents()
List of students that are enrolled in the exam

Returns:
list of ExamStudent

getDistributionConstraints

public List<ExamDistributionConstraint> getDistributionConstraints()
List of distribution constraints that this exam is involved in

Returns:
list of ExamDistributionConstraint

getInstructors

public List<ExamInstructor> getInstructors()
List of instructors that are assigned to this exam

Returns:
list of ExamInstructor

checkDistributionConstraints

public boolean checkDistributionConstraints(ExamPeriodPlacement period)
Check all distribution constraint that this exam is involved in

Parameters:
period - a period to be assigned to this exam
Returns:
true, if there is no assignment of some other exam in conflict with the given period

checkDistributionConstraints

public boolean checkDistributionConstraints(ExamRoomPlacement room)
Check all distribution constraint that this exam is involved in

Parameters:
room - a room to be assigned to this exam
Returns:
true, if there is no assignment of some other exam in conflict with the given room

getDistributionConstraintPenalty

public int getDistributionConstraintPenalty(ExamRoomPlacement room)
Check all soft distribution constraint that this exam is involved in

Parameters:
room - a room to be assigned to this exam
Returns:
sum of penalties of violated distribution constraints

getMaxRooms

public int getMaxRooms()
Maximal number of rooms that can be assigned to the exam

Returns:
maximal number of rooms that can be assigned to the exam

setMaxRooms

public void setMaxRooms(int maxRooms)
Set maximal number of rooms that can be assigned to the exam

Parameters:
maxRooms - maximal number of rooms that can be assigned to the exam

findBestAvailableRooms

public Set<ExamRoomPlacement> findBestAvailableRooms(ExamPeriodPlacement period)
Find best available rooms for the exam in the given period. First of all, it tries to find the minimal number of rooms that cover the size of the exam. Among these, a set of rooms of total smallest size is preferred. If the original room is available and of enough size, it is returned. All necessary checks are made (availability of rooms, room penalties, room sizes etc.).

Parameters:
period - given period.
Returns:
best available rooms for the exam in the given period, null if there is no valid assignment

findRoomsRandom

public Set<ExamRoomPlacement> findRoomsRandom(ExamPeriodPlacement period)
Randomly find a set of available rooms for the exam in the given period. First of all, it tries to find the minimal number of rooms that cover the size of the exam. Among these, a set of rooms of total smallest size is preferred. All necessary checks are made (availability of rooms, room penalties, room sizes etc.).

Parameters:
period - given period.
Returns:
randomly computed set of available rooms for the exam in the given period, null if there is no valid assignment

findRoomsRandom

public Set<ExamRoomPlacement> findRoomsRandom(ExamPeriodPlacement period,
                                              boolean checkConflicts)
Randomly find a set of available rooms for the exam in the given period. First of all, it tries to find the minimal number of rooms that cover the size of the exam. Among these, a set of rooms of total smallest size is preferred. All necessary checks are made (availability of rooms, room penalties, room sizes etc.).

Parameters:
period - given period.
checkConflicts - if false, room and distribution conflicts are not checked
Returns:
randomly computed set of available rooms for the exam in the given period, null if there is no valid assignment

nrStudentCorrelatedExams

public int nrStudentCorrelatedExams()
Number of exams that are correlated with this exam (there is at least one student attending both exams).

Returns:
number of correlated exams

getStudentCorrelatedExams

public Set<Exam> getStudentCorrelatedExams()
Exams that are correlated with this exam (there is at least one student attending both exams).

Returns:
number of correlated exams

compareTo

public int compareTo(Exam o)
An exam with more correlated exams is preferred ( nrStudentCorrelatedExams()). If it is the same, ratio number of students / number of available periods is used. If the same, exam ids are used.

Specified by:
compareTo in interface Comparable<Exam>
Overrides:
compareTo in class Variable<Exam,ExamPlacement>

hasStudentConflictWithPreAssigned

public boolean hasStudentConflictWithPreAssigned(ExamPeriod period)
True, if there is a student of this exam (that does not have direct conflicts allowed, see ExamStudent.canConflict(Exam, Exam)) that attends some other exam in the given period.

Parameters:
period - a period
Returns:
true if there is a student conflict

countStudentConflicts

public int countStudentConflicts(ExamPeriodPlacement period)
Number of students of this exam (that does not have direct conflicts allowed, see ExamStudent.canConflict(Exam, Exam)) that attend some other exam in the given period.

Parameters:
period - a period
Returns:
number of direct student conflicts that are prohibited

getStudentConflicts

public HashSet<Exam> getStudentConflicts(ExamPeriod period)
List of exams that are assigned to the given period and share one or more students with this exam (that does not have direct conflicts allowed, see ExamStudent.canConflict(Exam, Exam)).

Parameters:
period - a period
Returns:
list of Exam (other than this exam, that are placed in the given period and create prohibited direct conflicts)

allowAllStudentConflicts

public void allowAllStudentConflicts(ExamPeriod period)
Allow all direct student conflict for the given period (see ExamStudent.canConflict(Exam, Exam)).

Parameters:
period - a period

toString

public String toString()
String representation

Overrides:
toString in class Variable<Exam,ExamPlacement>
Returns:
exam id (periods: number of periods, rooms: number of rooms, student: number of students, maxRooms: max rooms[, alt if alternate seating is required])

getName

public String getName()
Exam name

Overrides:
getName in class Variable<Exam,ExamPlacement>

setName

public void setName(String name)
Exam name


hasName

public boolean hasName()
Exam name


getJointEnrollments

public Map<Exam,List<ExamStudent>> getJointEnrollments()
Joint enrollments

Returns:
table Exam (an exam that has at least one student in common with this exam) -> List (list of students in common)

getOwners

public List<ExamOwner> getOwners()
Courses and/or sections that are having this exam

Returns:
list of ExamOwner

getOwners

public Collection<ExamOwner> getOwners(ExamStudent student)
Courses/sections of this exam into which the given student is enrolled into

Parameters:
student - a student that is enrolled into this exam
Returns:
list of courses/sections ExamOwner which are having this exam with the given student enrolled in

getOwners

public Collection<ExamOwner> getOwners(ExamInstructor instructor)
Courses/sections of this exam into which the given instructor is enrolled into

Parameters:
instructor - an instructor that is enrolled into this exam
Returns:
list of courses/sections ExamOwner which are having this exam with the given instructor enrolled in

getPeriodPlacement

public ExamPeriodPlacement getPeriodPlacement(Long periodId)
Returns appropriate ExamPeriodPlacement for the given period, if it is available for this exam, null otherwise.


getRoomPlacement

public ExamRoomPlacement getRoomPlacement(long roomId)
Returns appropriate ExamRoomPlacement for the given room, if it is available for this exam, null otherwise.


getPeriodPlacement

public ExamPeriodPlacement getPeriodPlacement(ExamPeriod period)
Returns appropriate ExamPeriodPlacement for the given period, if it is available for this exam, null otherwise.


getRoomPlacement

public ExamRoomPlacement getRoomPlacement(ExamRoom room)
Returns appropriate ExamRoomPlacement for the given room, if it is available for this exam, null otherwise.


hasValues

public boolean hasValues()
Return true if there are some values in the domain of this variable

Overrides:
hasValues in class Variable<Exam,ExamPlacement>

assign

public void assign(long iteration,
                   ExamPlacement placement)
Description copied from class: Variable
Assign value to this variable. If the variable has already assigned another value, it is unassigned first. Also, all conflicting values are unassigned before the given value is assigned to this variable.

Overrides:
assign in class Variable<Exam,ExamPlacement>
Parameters:
iteration - current iteration
placement - the value to be assigned