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

java.lang.Object
- net.sf.cpsolver.ifs.criteria.AbstractCriterion<Exam,ExamPlacement>
- - net.sf.cpsolver.exam.criteria.ExamCriterion
  - - net.sf.cpsolver.exam.split.ExamSplitter

All Implemented Interfaces:

Criterion<Exam,ExamPlacement>, InfoProvider<Exam>, ModelListener<Exam,ExamPlacement>
```
public class ExamSplitter
extends ExamCriterion
```
Experimental criterion that allows an exam to be split into two if it decreases the number of student conflicts.

An examination split is improving (and is considered) if the weighted number of student conflicts that will be removed by the split is bigger than the weight of the splitter criterion AbstractCriterion.getWeight().

To enable examination splitting, following parameters needs to be set:
- HillClimber.AdditionalNeighbours=net.sf.cpsolver.exam.split.ExamSplitMoves
- GreatDeluge.AdditionalNeighbours=net.sf.cpsolver.exam.split.ExamSplitMoves
- Exams.AdditionalCriteria=net.sf.cpsolver.exam.split.ExamSplitter
- Exams.ExamSplitWeight=500
The Exams.ExamSplitWeight represents the weight of a split. For instance, to allow only splits that decrease the number of student direct conflicts, half of the weight of a direct student conflict is a good value for this weight.
Version:

ExamTT 1.2 (Examination Timetabling)
Copyright (C) 2008 - 2013 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/.

Nested Class Summary
- Nested classes/interfaces inherited from class net.sf.cpsolver.ifs.criteria.AbstractCriterion
  AbstractCriterion.ValueUpdateType

Field Summary
- Fields inherited from class net.sf.cpsolver.ifs.criteria.AbstractCriterion
  iBest, iDebug, iValue, iValueUpdateType, iWeight, sDoubleFormat, sPercentFormat

Constructor Summary

Constructors
Constructor and Description

ExamSplitter()
Examination splitter criterion.

Constructors
Constructor and Description
`ExamSplitter()` Examination splitter criterion.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`bestRestored()` Best solution was restored, change the splits back to what it was in the best solution
`void`	`bestSaved()` Best solution was saved, remember the current splits
`boolean`	`canMerge(Exam exam)` True, if the given exam can be merged (it has been split)
`boolean`	`canSplit(Exam exam)` True, if an exam can be split
`List<Exam>`	`children(Exam parent)` Children exams of an exam that has been split.
`double`	`delta(ExamStudent student, ExamPlacement oldPlacement, ExamPlacement newPlacement)` Difference in the total weighted student conflicts (including `StudentDirectConflicts`, `StudentMoreThan2ADayConflicts`, and `StudentBackToBackConflicts`) if a student is moved from an exam with one placement into an exam with another placement.
`double[]`	`getBounds(Collection<Exam> exams)` Not used
`void`	`getInfo(Map<String,String> info)` Lists the split
`double`	`getValue(ExamPlacement value, Set<ExamPlacement> conflicts)` Not used
`double`	`getWeightDefault(DataProperties config)` Returns half of a student direct conflict weight
`String`	`getWeightName()` Returns Exams.ExamSplitWeight
`String`	`getXmlWeightName()` Returns examSplitWeight
`boolean`	`init(Solver<Exam,ExamPlacement> solver)` Initialization
`Exam`	`merge(Exam child, long iteration)` Merge an exam
`Exam`	`parent(Exam exam)` Parent of an exam that has been split.
`void`	`shuffle(Exam exam, long iteration)` Shuffle students between the given exam and all the other exams in the split (if there are any).
`Exam`	`split(Exam parent, long iteration, ExamPlacement placement)` Split an exam
`String`	`toString()`

Methods inherited from class net.sf.cpsolver.exam.criteria.ExamCriterion
getPeriodValue, getRoomValue, getXmlParameters, isPeriodCriterion, isRoomCriterion, setWeight, setXmlParameters

Methods inherited from class net.sf.cpsolver.ifs.criteria.AbstractCriterion
afterAssigned, afterUnassigned, beforeAssigned, beforeUnassigned, clearCache, computeBounds, constraintAdded, constraintRemoved, getBest, getBounds, getInfo, getModel, getName, getPerc, getPercRev, getValue, getValue, getWeight, getWeightedBest, getWeightedValue, getWeightedValue, getWeightedValue, inc, variableAdded, variableRemoved

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

- Constructor Detail
  - ExamSplitter
```
public ExamSplitter()
```
    Examination splitter criterion.
- Method Detail
  - init
```
public boolean init(Solver<Exam,ExamPlacement> solver)
```
    Initialization
    
    Specified by:
    
    init in interface ModelListener<Exam,ExamPlacement>
    
    Overrides:
    
    init in class AbstractCriterion<Exam,ExamPlacement>
    
    Parameters:
    
    solver - IFS solver
  - getWeightName
```
public String getWeightName()
```
    Returns Exams.ExamSplitWeight
    
    Overrides:
    
    getWeightName in class ExamCriterion
  - getXmlWeightName
```
public String getXmlWeightName()
```
    Returns examSplitWeight
    
    Overrides:
    
    getXmlWeightName in class ExamCriterion
  - getWeightDefault
```
public double getWeightDefault(DataProperties config)
```
    Returns half of a student direct conflict weight
    
    Overrides:
    
    getWeightDefault in class AbstractCriterion<Exam,ExamPlacement>
  - canSplit
```
public boolean canSplit(Exam exam)
```
    True, if an exam can be split
  - parent
```
public Exam parent(Exam exam)
```
    Parent of an exam that has been split.
    
    Parameters:
    
    exam - an exam in question
    
    Returns:
    
    parent exam if the exam has been split, or the exam itself otherwise (each non-split exam is its own parent)
  - children
```
public List<Exam> children(Exam parent)
```
    Children exams of an exam that has been split. These are all the exams that the parent exam has been split into.
    
    Parameters:
    
    parent - an exam in question
    
    Returns:
    
    all children exams, or null of the exam has not been split yet
  - split
```
public Exam split(Exam parent,
                  long iteration,
                  ExamPlacement placement)
```
    Split an exam
    
    Parameters:
    
    parent - an exam to be split
    
    iteration - solver iteration
    
    placement - placement of the new exam
    
    Returns:
    
    new exam assigned to the given placement with students moved into it; null if the given exam cannot be split
  - canMerge
```
public boolean canMerge(Exam exam)
```
    True, if the given exam can be merged (it has been split)
  - merge
```
public Exam merge(Exam child,
                  long iteration)
```
    Merge an exam
    
    Parameters:
    
    child - an exam to be merged
    
    iteration - solver iteration
    
    Returns:
    
    parent exam of the exam that has been deleted; null if the given exam cannot be merged
  - delta
```
public double delta(ExamStudent student,
                    ExamPlacement oldPlacement,
                    ExamPlacement newPlacement)
```
    Difference in the total weighted student conflicts (including StudentDirectConflicts, StudentMoreThan2ADayConflicts, and StudentBackToBackConflicts) if a student is moved from an exam with one placement into an exam with another placement.
    
    Parameters:
    
    student - a student in question
    
    oldPlacement - placement of the exam in which the student is now
    
    newPlacement - placement of the exam into which the student would be moved
    
    Returns:
    
    difference in the student conflict weight
  - shuffle
```
public void shuffle(Exam exam,
                    long iteration)
```
    Shuffle students between the given exam and all the other exams in the split (if there are any). Only moves between exams that improve delta(ExamStudent, ExamPlacement, ExamPlacement) are considered.
    
    Parameters:
    
    exam - an exam in question
    
    iteration - solver iteration
  - getValue
```
public double getValue(ExamPlacement value,
                       Set<ExamPlacement> conflicts)
```
    Not used
  - getBounds
```
public double[] getBounds(Collection<Exam> exams)
```
    Not used
    
    Specified by:
    
    getBounds in interface Criterion<Exam,ExamPlacement>
    
    Overrides:
    
    getBounds in class ExamCriterion
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getInfo
```
public void getInfo(Map<String,String> info)
```
    Lists the split
    
    Specified by:
    
    getInfo in interface InfoProvider<Exam>
    
    Overrides:
    
    getInfo in class ExamCriterion
  - bestSaved
```
public void bestSaved()
```
    Best solution was saved, remember the current splits
    
    Specified by:
    
    bestSaved in interface Criterion<Exam,ExamPlacement>
    
    Overrides:
    
    bestSaved in class AbstractCriterion<Exam,ExamPlacement>
  - bestRestored
```
public void bestRestored()
```
    Best solution was restored, change the splits back to what it was in the best solution
    
    Specified by:
    
    bestRestored in interface Criterion<Exam,ExamPlacement>
    
    Overrides:
    
    bestRestored in class AbstractCriterion<Exam,ExamPlacement>

Class ExamSplitter

Nested Class Summary

Nested classes/interfaces inherited from class net.sf.cpsolver.ifs.criteria.AbstractCriterion

Field Summary

Fields inherited from class net.sf.cpsolver.ifs.criteria.AbstractCriterion

Constructor Summary

Method Summary

Methods inherited from class net.sf.cpsolver.exam.criteria.ExamCriterion

Methods inherited from class net.sf.cpsolver.ifs.criteria.AbstractCriterion

Methods inherited from class java.lang.Object

Constructor Detail

ExamSplitter

Method Detail

init

getWeightName

getXmlWeightName

getWeightDefault

canSplit

parent

children

split

canMerge

merge

delta

shuffle

getValue

getBounds

toString

getInfo

bestSaved

bestRestored