001 package net.sf.cpsolver.exam.heuristics;
002
003 import java.util.ArrayList;
004 import java.util.Collection;
005 import java.util.HashSet;
006 import java.util.HashMap;
007 import java.util.List;
008 import java.util.Set;
009 import java.util.TreeSet;
010
011 import net.sf.cpsolver.exam.model.Exam;
012 import net.sf.cpsolver.exam.model.ExamInstructor;
013 import net.sf.cpsolver.exam.model.ExamModel;
014 import net.sf.cpsolver.exam.model.ExamPeriodPlacement;
015 import net.sf.cpsolver.exam.model.ExamPlacement;
016 import net.sf.cpsolver.exam.model.ExamRoomPlacement;
017 import net.sf.cpsolver.exam.model.ExamStudent;
018 import net.sf.cpsolver.ifs.heuristics.NeighbourSelection;
019 import net.sf.cpsolver.ifs.model.Neighbour;
020 import net.sf.cpsolver.ifs.solution.Solution;
021 import net.sf.cpsolver.ifs.solver.Solver;
022 import net.sf.cpsolver.ifs.util.DataProperties;
023 import net.sf.cpsolver.ifs.util.JProf;
024 import net.sf.cpsolver.ifs.util.Progress;
025
026 /**
027 * Examination timetabling construction heuristics based on graph vertex coloring.
028 * This approach is trying to find a (direct) conflict-free examination schedule using
029 * a depth-first search, assigning periods to exams in a way that there is not student or
030 * instructor direct conflict.
031 * <br>
032 * <br>
033 * This heuristics works in following modes (defined by Exam.ColoringConstructionMode).
034 * <ul>
035 * <li>Greedy .. all exams are greedily assigned with periods (and best available rooms);
036 * Exams with smallest number of available periods (or highest number of connected exams
037 * if multiple) are assigned first.
038 * <li>ColorOnly .. all exams are assigned with periods using a depth-first search (ignoring
039 * all other constraints), this coloring is then extended to exam placements as much as possible
040 * <li>Irredundant .. other constraints (distributions, rooms) are considered, however, to
041 * speedup the search redundant colorings are avoided -- this may not find a complete solution,
042 * especially when some periods are not swap-able
043 * <li>Full .. all constraints are considered, a complete solution is guaranteed to be found, if
044 * it exists (and enough time is given)
045 * </ul>
046 * <br>
047 * Time to run can be limited using Exam.ColoringConstructionTimeLimit parameter (double precision,
048 * limit is in seconds, defaults to 5 minutes)
049 * <br>
050 * <br>
051 *
052 * @version ExamTT 1.2 (Examination Timetabling)<br>
053 * Copyright (C) 2008 - 2010 Tomas Muller<br>
054 * <a href="mailto:muller@unitime.org">muller@unitime.org</a><br>
055 * <a href="http://muller.unitime.org">http://muller.unitime.org</a><br>
056 * <br>
057 * This library is free software; you can redistribute it and/or modify
058 * it under the terms of the GNU Lesser General Public License as
059 * published by the Free Software Foundation; either version 3 of the
060 * License, or (at your option) any later version. <br>
061 * <br>
062 * This library is distributed in the hope that it will be useful, but
063 * WITHOUT ANY WARRANTY; without even the implied warranty of
064 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
065 * Lesser General Public License for more details. <br>
066 * <br>
067 * You should have received a copy of the GNU Lesser General Public
068 * License along with this library; if not see
069 * <a href='http://www.gnu.org/licenses/'>http://www.gnu.org/licenses/</a>.
070 */
071 public class ExamColoringConstruction implements NeighbourSelection<Exam, ExamPlacement> {
072 private Progress iProgress;
073 private double iT0;
074 private double iTimeLimit = 300.0;
075 private boolean iTimeLimitReached = false;
076 private Solution<Exam, ExamPlacement> iSolution = null;
077 private Mode iMode = Mode.Full;
078 private Solver<Exam, ExamPlacement> iSolver;
079
080 private static enum Mode {
081 Greedy(true, false, true),
082 ColorOnly(false, false, false),
083 Irredundant(false, false, false),
084 Full(false, true, true);
085 boolean iGreedy, iRedundant, iConstraintCheck;
086 private Mode(boolean gr, boolean r, boolean ch) { iGreedy = gr; iRedundant = r; iConstraintCheck = ch; }
087 public boolean isGreedy() { return iGreedy; }
088 public boolean isRedundant() { return iRedundant; }
089 public boolean isConstraintCheck() { return iConstraintCheck; }
090 }
091
092 public ExamColoringConstruction(DataProperties config) {
093 iTimeLimit = config.getPropertyDouble("Exam.ColoringConstructionTimeLimit", iTimeLimit);
094 iMode = Mode.valueOf(config.getProperty("Exam.ColoringConstructionMode", iMode.name()));
095 }
096
097 private boolean backTrack(int index, HashSet<Integer> colorsUsedSoFar, Collection<Vertex> vertices) {
098 if (iTimeLimitReached || iSolver.isStop()) return false;
099 if (JProf.currentTimeSec() - iT0 > iTimeLimit) {
100 iTimeLimitReached = true;
101 return false;
102 }
103 if (index == vertices.size()) return true;
104 if (iProgress.getProgress() < index) {
105 iProgress.setProgress(index);
106 if (iMode.isConstraintCheck())
107 iSolution.saveBest();
108 }
109 Vertex vertex = null;
110 for (Vertex v: vertices) {
111 if (v.color() >= 0) continue;
112 if (vertex == null || v.compareTo(vertex) < 0) {
113 vertex = v;
114 }
115 }
116 if (colorsUsedSoFar != null) {
117 for (int color: new TreeSet<Integer>(colorsUsedSoFar))
118 if (vertex.colorize(color) && backTrack(1 + index, colorsUsedSoFar, vertices)) return true;
119 for (int color: vertex.domain()) {
120 if (colorsUsedSoFar.contains(color)) continue;
121 if (vertex.colorize(color)) {
122 colorsUsedSoFar.add(color);
123 if (backTrack(1 + index, colorsUsedSoFar, vertices)) return true;
124 colorsUsedSoFar.remove(color);
125 }
126 break;
127 }
128 } else {
129 for (int color: vertex.domain())
130 if (vertex.colorize(color) && backTrack(1 + index, colorsUsedSoFar, vertices)) return true;
131 }
132 vertex.colorize(-1);
133 return false;
134 }
135
136 @Override
137 public void init(Solver<Exam, ExamPlacement> solver) {
138 iProgress = Progress.getInstance(solver.currentSolution().getModel());
139 iSolver = solver;
140 }
141
142 public Set<ExamRoomPlacement> findRooms(Exam exam, ExamPeriodPlacement period) {
143 Set<ExamRoomPlacement> rooms = exam.findBestAvailableRooms(period);
144 if (rooms != null) return rooms;
145
146 rooms = new HashSet<ExamRoomPlacement>();
147 int size = 0;
148 while (size < exam.getSize()) {
149 ExamRoomPlacement bestRoom = null; int bestSize = 0;
150 for (ExamRoomPlacement r: exam.getRoomPlacements()) {
151 if (!r.isAvailable(period.getPeriod())) continue;
152 if (rooms.contains(r)) continue;
153 if (!r.getRoom().getPlacements(period.getPeriod()).isEmpty()) continue;
154 int s = r.getSize(exam.hasAltSeating());
155 if (bestRoom == null || s > bestSize) {
156 bestRoom = r;
157 bestSize = s;
158 }
159 }
160 if (bestRoom == null) return rooms;
161 rooms.add(bestRoom); size += bestSize;
162 }
163
164 return rooms;
165 }
166
167 @Override
168 public Neighbour<Exam, ExamPlacement> selectNeighbour(Solution<Exam, ExamPlacement> solution) {
169 iSolution = solution;
170 ExamModel model = (ExamModel)solution.getModel();
171 // if (!model.assignedVariables().isEmpty()) return null;
172 final HashMap<Exam, Vertex> vertices = new HashMap<Exam, Vertex>();
173 for (Exam x: model.variables()) {
174 vertices.put(x, new Vertex(x));
175 }
176 for (ExamStudent s: model.getStudents()) {
177 for (Exam x: s.variables()) {
178 for (Exam y: s.variables()) {
179 if (!x.equals(y)) {
180 vertices.get(x).neighbors().add(vertices.get(y));
181 vertices.get(y).neighbors().add(vertices.get(x));
182 }
183 }
184 }
185 }
186 for (ExamInstructor i: model.getInstructors()) {
187 for (Exam x: i.variables()) {
188 for (Exam y: i.variables()) {
189 if (!x.equals(y)) {
190 vertices.get(x).neighbors().add(vertices.get(y));
191 vertices.get(y).neighbors().add(vertices.get(x));
192 }
193 }
194 }
195 }
196 iProgress.setPhase("Graph coloring-based construction", vertices.size());
197 iProgress.info("Looking for a conflict-free assignment using " + model.getPeriods().size() + " periods.");
198 iT0 = JProf.currentTimeSec(); iTimeLimitReached = false;
199 if (iMode.isGreedy()) {
200 iProgress.info("Using greedy heuristics only (no backtracking)...");
201 } else if (backTrack(0, (iMode.isRedundant() ? null : new HashSet<Integer>()), vertices.values())) {
202 iProgress.info("Success!");
203 } else if (iTimeLimitReached) {
204 iProgress.info("There was no conflict-free schedule found during the given time.");
205 } else if (iSolver.isStop()) {
206 iProgress.info("Solver was stopped.");
207 } else {
208 if (iMode.isRedundant())
209 iProgress.info("There is no conflict-free schedule!");
210 else
211 iProgress.info("Conflict-free schedule not found.");
212 }
213 if (iMode.isConstraintCheck())
214 iSolution.restoreBest();
215 HashSet<Vertex> remaning = new HashSet<Vertex>();
216 for (Vertex v: vertices.values())
217 if (v.color() < 0) remaning.add(v);
218 remaining: while (!remaning.isEmpty()) {
219 Vertex vertex = null;
220 for (Vertex v: remaning)
221 if (vertex == null || v.compareTo(vertex) < 0)
222 vertex = v;
223 remaning.remove(vertex);
224 for (int color: vertex.domain())
225 if (vertex.colorize(color)) continue remaining;
226 }
227 if (!iMode.isConstraintCheck()) {
228 return new Neighbour<Exam, ExamPlacement>() {
229 @Override
230 public void assign(long iteration) {
231 iProgress.info("Using graph coloring solution ...");
232 for (Vertex vertex: new TreeSet<Vertex>(vertices.values())) {
233 ExamPeriodPlacement period = vertex.period();
234 if (period == null || !vertex.exam().checkDistributionConstraints(period)) continue;
235 Set<ExamRoomPlacement> rooms = findRooms(vertex.exam(), period);
236 if (rooms == null) continue;
237 vertex.exam().assign(iteration, new ExamPlacement(vertex.exam(), period, rooms));
238 }
239 HashSet<Vertex> unassigned = new HashSet<Vertex>();
240 for (Vertex vertex: vertices.values()) {
241 if (vertex.exam().getAssignment() == null) {
242 unassigned.add(vertex);
243 vertex.colorize(-1);
244 }
245 }
246 iSolution.saveBest();
247 iProgress.info("Extending ...");
248 unassigned: while (!unassigned.isEmpty()) {
249 Vertex vertex = null;
250 for (Vertex v: unassigned)
251 if (vertex == null || v.compareTo(vertex) < 0)
252 vertex = v;
253 unassigned.remove(vertex);
254 for (int color: vertex.domain()) {
255 if (!vertex.colorize(color)) continue;
256 ExamPeriodPlacement period = vertex.period(color);
257 if (period == null || !vertex.exam().checkDistributionConstraints(period)) continue;
258 Set<ExamRoomPlacement> rooms = findRooms(vertex.exam(), period);
259 if (rooms == null) continue;
260 vertex.exam().assign(iteration, new ExamPlacement(vertex.exam(), period, rooms));
261 continue unassigned;
262 }
263 vertex.colorize(-1);
264 }
265 iSolution.saveBest();
266 iProgress.info("Construction done.");
267 }
268 @Override
269 public double value() {
270 return 0;
271 }
272 };
273 }
274 return null;
275 }
276
277 /** Internal graph representation -- needed for domain caching */
278 private class Vertex implements Comparable<Vertex> {
279 private Exam iExam;
280 private List<Vertex> iNeighbors = new ArrayList<Vertex>();
281 private int iColor = -1;
282 private HashMap<Integer, ExamPeriodPlacement> iDomain = new HashMap<Integer, ExamPeriodPlacement>();
283 private HashMap<Integer, Vertex> iTaken = new HashMap<Integer, Vertex>();
284
285 public Vertex(Exam exam) {
286 iExam = exam;
287 for (ExamPeriodPlacement period: exam.getPeriodPlacements())
288 iDomain.put(period.getIndex(), period);
289 }
290
291 public List<Vertex> neighbors() { return iNeighbors; }
292
293 public Set<Integer> domain() { return iDomain.keySet(); }
294
295 public ExamPeriodPlacement period() { return (iColor < 0 ? null : iDomain.get(iColor)); }
296
297 public ExamPeriodPlacement period(int color) { return (color < 0 ? null : iDomain.get(color)); }
298
299 private boolean neighborColored(Vertex v, int color) {
300 if (!iDomain.containsKey(color)) return true;
301 if (iTaken.get(color) == null)
302 iTaken.put(color, v);
303 return iTaken.size() < iDomain.size();
304 }
305
306 private void neighborUncolored(Vertex v, int color) {
307 if (!iDomain.containsKey(color)) return;
308 if (v.equals(iTaken.get(color))) {
309 for (Vertex w: neighbors()) {
310 if (w.equals(v)) continue;
311 if (w.color() == color) {
312 iTaken.put(color, w);
313 return;
314 }
315 }
316 iTaken.remove(color);
317 }
318 }
319
320 public int color() { return iColor; }
321
322 public boolean colorize(int color) {
323 if (iColor == color) return true;
324 ExamPlacement placement = null;
325 if (color >= 0) {
326 if (iTaken.get(color) != null || !iDomain.containsKey(color))
327 return false;
328 if (iMode.isConstraintCheck()) {
329 ExamPeriodPlacement period = iDomain.get(color);
330 if (!iExam.checkDistributionConstraints(period)) return false;
331 Set<ExamRoomPlacement> rooms = findRooms(iExam, period);
332 if (rooms == null) return false;
333 placement = new ExamPlacement(iExam, period, rooms);
334 }
335 }
336 if (iColor >= 0) {
337 for (Vertex v: neighbors())
338 v.neighborUncolored(this, iColor);
339 }
340 boolean success = true;
341 if (color >= 0) {
342 for (Vertex v: neighbors()) {
343 if (!v.neighborColored(this, color)) {
344 success = false; break;
345 }
346 }
347 }
348 if (success) {
349 iColor = color;
350 if (iMode.isConstraintCheck()) {
351 if (placement != null)
352 iExam.assign(0l, placement);
353 else
354 iExam.unassign(0l);
355 }
356 } else { // undo
357 for (Vertex v: neighbors()) {
358 v.neighborUncolored(this, color);
359 if (iColor >= 0)
360 v.neighborColored(this, iColor);
361 }
362 }
363 return success;
364 }
365
366 public int degree() {
367 return iNeighbors.size();
368 }
369
370 public int available() {
371 return iDomain.size() - iTaken.size();
372 }
373
374 public int degreeNotColored() {
375 int ret = 0;
376 for (Vertex v: neighbors())
377 if (v.color() < 0) ret ++;
378 return ret;
379 }
380
381 public Exam exam() { return iExam; }
382
383 @Override
384 public int compareTo(Vertex v) {
385 if (available() < v.available()) return -1;
386 if (v.available() < available()) return 1;
387 if (degree() > v.degree()) return -1;
388 if (v.degree() > degree()) return 1;
389 if (degreeNotColored() > v.degreeNotColored()) return -1;
390 if (v.degreeNotColored() > degreeNotColored()) return 1;
391 return Double.compare(exam().getId(), v.exam().getId());
392 }
393 }
394 }