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    }