OptaPlanner User Guide Version 6.0.0.Beta1 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 ............................ 6 1.3.4. Build OptaPlanner from source ................................................................. 7 1.4. Status of OptaPlanner ......................................................................................... 7 1.5. Compatibility ....................................................................................................... 7 1.6. Questions, issues and blog ................................................................................. 8 2. Quick start ................................................................................................................... 9 2.1. Cloud balancing tutorial ....................................................................................... 9 2.1.1. Problem statement ................................................................................... 9 2.1.2. Problem size .......................................................................................... 10 2.1.3. Domain model diagram ........................................................................... 11 2.1.4. Main method .......................................................................................... 12 2.1.5. Solver configuration ................................................................................ 13 2.1.6. Domain model implementation ................................................................ 15 2.1.7. Score configuration ................................................................................ 18 2.1.8. Beyond this tutorial ................................................................................ 22 3. Use cases and examples ........................................................................................... 23 3.1. Examples overview ........................................................................................... 23 3.2. Basic examples ................................................................................................ 24 3.2.1. N queens ............................................................................................... 24 3.2.2. Cloud balancing ..................................................................................... 28 3.2.3. Traveling salesman (TSP - Traveling salesman problem) .......................... 28 3.2.4. Manners 2009 ........................................................................................ 29 3.3. Real examples .................................................................................................. 29 3.3.1. Course timetabling (ITC 2007 track 3 - Curriculum course scheduling) ...... 29 3.3.2. Machine reassignment (Google ROADEF 2012) ....................................... 31 3.3.3. Vehicle routing ....................................................................................... 33 3.3.4. Hospital bed planning (PAS - Patient admission scheduling) ...................... 35 3.4. Difficult examples .............................................................................................. 37 3.4.1. Exam timetabling (ITC 2007 track 1 - Examination) .................................. 37 3.4.2. Employee rostering (INRC 2010 - Nurse rostering) ................................... 41 3.4.3. Sport scheduling (TTP - Traveling tournament problem) ............................ 46 4. Planner configuration ................................................................................................ 49 4.1. Overview .......................................................................................................... 49 4.2. Solver configuration .......................................................................................... 50 iii OptaPlanner User Guide 4.2.1. Solver configuration by XML file .............................................................. 50 4.2.2. Solver configuration by Java API ............................................................. 51 4.3. Model your planning problem ............................................................................. 52 4.3.1. Is this class a problem fact or planning entity? ......................................... 52 4.3.2. Problem fact .......................................................................................... 53 4.3.3. Planning entity and planning variables ..................................................... 55 4.3.4. Planning value and planning value ranges ............................................... 59 4.3.5. Planning problem and planning solution ................................................... 67 4.4. Use the Solver .................................................................................................. 74 4.4.1. The Solver interface ............................................................................... 74 4.4.2. Solving a problem .................................................................................. 75 4.4.3. Environment mode: Are there bugs in my code? ...................................... 76 4.4.4. Logging level: What is the Solver doing? ................................................. 78 5. Score calculation ....................................................................................................... 81 5.1. Score terminology ............................................................................................. 81 5.1.1. What is a score? .................................................................................... 81 5.1.2. Score constraint signum (positive or negative) .......................................... 81 5.1.3. Score constraint weight .......................................................................... 83 5.1.4. Score level ............................................................................................ 83 5.1.5. Pareto scoring (AKA multi-objective optimization scoring) .......................... 85 5.1.6. Combining score techniques ................................................................... 87 5.1.7. The Score interface ................................................................................ 87 5.2. Choose a Score definition ................................................................................. 89 5.2.1. SimpleScore .......................................................................................... 89 5.2.2. HardSoftScore (recommended) ............................................................... 90 5.2.3. HardMediumSoftScore ............................................................................ 90 5.2.4. BendableScore ....................................................................................... 90 5.2.5. Implementing a custom Score ................................................................. 91 5.3. Calculate the Score .......................................................................................... 91 5.3.1. Score calculation types ........................................................................... 91 5.3.2. Simple Java score calculation ................................................................. 91 5.3.3. Incremental Java score calculation .......................................................... 93 5.3.4. Drools score calculation .......................................................................... 96 5.3.5. Detecting invalid scores ........................................................................ 100 5.4. Score calculation performance tricks ................................................................ 101 5.4.1. Overview .............................................................................................. 101 5.4.2. Average calculation count per second .................................................... 101 5.4.3. Incremental score calculation (with delta's) ............................................. 102 5.4.4. Avoid calling remote services during score calculation ............................. 102 5.4.5. Unused constraint ................................................................................ 103 5.4.6. Build-in hard constraint ......................................................................... 103 5.4.7. Other performance tricks ....................................................................... 103 5.4.8. Score trap ...........................................................................................