OptaPlanner User Guide Version 6.0.0.CR3 by The OptaPlanner team [http://www.optaplanner.org/community/team.html] ........................................................................................................................................ ix 1. Planner introduction .................................................................................................... 1 1.1. What is OptaPlanner? ......................................................................................... 1 1.2. What is a planning problem? ............................................................................... 3 1.2.1. A planning problem is NP-complete .......................................................... 3 1.2.2. A planning problem has (hard and soft) constraints .................................... 3 1.2.3. A planning problem has a huge search space ............................................ 4 1.3. Download and run the examples ......................................................................... 4 1.3.1. Get the release zip and run the examples ................................................. 4 1.3.2. Run the examples in an IDE (IntelliJ, Eclipse, NetBeans) ............................ 6 1.3.3. Use OptaPlanner with Maven, Gradle, Ivy, Buildr or ANT ............................ 7 1.3.4. Build OptaPlanner from source ................................................................. 8 1.4. Status of OptaPlanner ......................................................................................... 8 1.5. Compatibility ....................................................................................................... 9 1.6. Questions, issues and blog ................................................................................. 9 2. Quick start ................................................................................................................. 11 2.1. Cloud balancing tutorial ..................................................................................... 11 2.1.1. Problem statement ................................................................................. 11 2.1.2. Problem size .......................................................................................... 12 2.1.3. Domain model diagram ........................................................................... 13 2.1.4. Main method .......................................................................................... 14 2.1.5. Solver configuration ................................................................................ 15 2.1.6. Domain model implementation ................................................................ 17 2.1.7. Score configuration ................................................................................ 20 2.1.8. Beyond this tutorial ................................................................................ 24 3. Use cases and examples ........................................................................................... 25 3.1. Examples overview ........................................................................................... 25 3.2. Basic examples ................................................................................................ 26 3.2.1. N queens ............................................................................................... 26 3.2.2. Cloud balancing ..................................................................................... 30 3.2.3. Traveling salesman (TSP - Traveling salesman problem) .......................... 30 3.2.4. Manners 2009 ........................................................................................ 31 3.3. Real examples .................................................................................................. 31 3.3.1. Course timetabling (ITC 2007 track 3 - Curriculum course scheduling) ...... 31 3.3.2. Machine reassignment (Google ROADEF 2012) ....................................... 33 3.3.3. Vehicle routing ....................................................................................... 35 3.3.4. Project job scheduling ............................................................................ 37 3.3.5. Hospital bed planning (PAS - Patient admission scheduling) ...................... 39 3.4. Difficult examples .............................................................................................. 41 3.4.1. Exam timetabling (ITC 2007 track 1 - Examination) .................................. 41 3.4.2. Employee rostering (INRC 2010 - Nurse rostering) ................................... 44 3.4.3. Sport scheduling (TTP - Traveling tournament problem) ............................ 49 4. Planner configuration ................................................................................................ 53 4.1. Overview .......................................................................................................... 53 iii OptaPlanner User Guide 4.2. Solver configuration .......................................................................................... 54 4.2.1. Solver configuration by XML file .............................................................. 54 4.2.2. Solver configuration by Java API ............................................................. 55 4.3. Model your planning problem ............................................................................. 56 4.3.1. Is this class a problem fact or planning entity? ......................................... 56 4.3.2. Problem fact .......................................................................................... 57 4.3.3. Planning entity ....................................................................................... 59 4.3.4. Planning variable .................................................................................... 61 4.3.5. Planning value and planning value ranges ............................................... 63 4.3.6. Planning problem and planning solution ................................................... 74 4.4. Use the Solver .................................................................................................. 82 4.4.1. The Solver interface ............................................................................... 82 4.4.2. Solving a problem .................................................................................. 83 4.4.3. Environment mode: Are there bugs in my code? ...................................... 84 4.4.4. Logging level: What is the Solver doing? ................................................. 86 5. Score calculation ....................................................................................................... 89 5.1. Score terminology ............................................................................................. 89 5.1.1. What is a score? .................................................................................... 89 5.1.2. Score constraint signum (positive or negative) .......................................... 89 5.1.3. Score constraint weight .......................................................................... 91 5.1.4. Score level ............................................................................................ 91 5.1.5. Pareto scoring (AKA multi-objective optimization scoring) .......................... 93 5.1.6. Combining score techniques ................................................................... 95 5.1.7. The Score interface ................................................................................ 95 5.2. Choose a Score definition ................................................................................. 97 5.2.1. SimpleScore .......................................................................................... 97 5.2.2. HardSoftScore (recommended) ............................................................... 98 5.2.3. HardMediumSoftScore ............................................................................ 98 5.2.4. BendableScore ....................................................................................... 98 5.2.5. Implementing a custom Score ................................................................. 99 5.3. Calculate the Score .......................................................................................... 99 5.3.1. Score calculation types ........................................................................... 99 5.3.2. Simple Java score calculation ............................................................... 100 5.3.3. Incremental Java score calculation ........................................................ 101 5.3.4. Drools score calculation ........................................................................ 104 5.3.5. Detecting invalid scores ........................................................................ 109 5.4. Score calculation performance tricks ................................................................ 109 5.4.1. Overview .............................................................................................. 109 5.4.2. Average calculation count per second .................................................... 109 5.4.3. Incremental score calculation (with delta's) ............................................. 110 5.4.4. Avoid calling remote services during score calculation ............................. 111 5.4.5. Unused constraint ................................................................................ 111 5.4.6. Build-in hard constraint ........................................................................