OptaPlanner User Guide The OptaPlanner team [http://www.optaplanner.org/community/team.html] OptaPlanner User Guide by Version 6.3.0.Beta2 1. OptaPlanner Introduction ............................................................................................ 1 1.1. What is OptaPlanner? ......................................................................................... 1 1.2. Requirements ..................................................................................................... 3 1.3. What is a Planning Problem? .............................................................................. 4 1.3.1. A Planning Problem is NP-complete or NP-hard ......................................... 4 1.3.2. A Planning Problem Has (Hard and Soft) Constraints ................................. 5 1.3.3. A Planning Problem Has a Huge Search Space ......................................... 5 1.4. Download and Run the Examples ........................................................................ 6 1.4.1. Get the Release .zip and Run the Examples .............................................. 6 1.4.2. Run the Examples in an IDE (IntelliJ, Eclipse, NetBeans) ............................ 9 1.4.3. Use OptaPlanner with Maven, Gradle, Ivy, Buildr or ANT .......................... 10 1.4.4. Build OptaPlanner from Source ............................................................... 11 1.5. Governance ...................................................................................................... 12 1.5.1. Status of OptaPlanner ............................................................................ 12 1.5.2. Backwards Compatibility ......................................................................... 12 1.5.3. Community and Support ......................................................................... 13 1.5.4. Relationship with Drools and jBPM .......................................................... 13 2. Quick Start ................................................................................................................. 15 2.1. Cloud Balancing Tutorial ................................................................................... 15 2.1.1. Problem Description ............................................................................... 15 2.1.2. Problem Size ......................................................................................... 16 2.1.3. Domain Model Design ............................................................................ 17 2.1.4. Main Method .......................................................................................... 18 2.1.5. Solver Configuration ............................................................................... 19 2.1.6. Domain Model Implementation ................................................................ 20 2.1.7. Score Configuration ................................................................................ 23 2.1.8. Beyond this Tutorial ............................................................................... 26 3. Use Cases and Examples .......................................................................................... 27 3.1. Examples Overview .......................................................................................... 27 3.2. Basic Examples ................................................................................................ 31 3.2.1. N Queens .............................................................................................. 31 3.2.2. Cloud Balancing ..................................................................................... 34 3.2.3. Traveling Salesman (TSP - Traveling Salesman Problem) ......................... 34 3.2.4. Dinner Party .......................................................................................... 35 3.2.5. Tennis Club Scheduling .......................................................................... 36 3.3. Real Examples ................................................................................................. 37 3.3.1. Course Timetabling (ITC 2007 Track 3 - Curriculum Course Scheduling) .... 37 3.3.2. Machine Reassignment (Google ROADEF 2012) ...................................... 39 3.3.3. Vehicle Routing ...................................................................................... 42 3.3.4. Project Job Scheduling ........................................................................... 52 3.3.5. Hospital Bed Planning (PAS - Patient Admission Scheduling) .................... 55 3.4. Difficult Examples ............................................................................................. 58 3.4.1. Exam Timetabling (ITC 2007 track 1 - Examination) ................................. 58 3.4.2. Employee Rostering (INRC 2010 - Nurse Rostering) ................................. 62 iii OptaPlanner User Guide 3.4.3. Traveling Tournament Problem (TTP) ...................................................... 69 3.4.4. Cheap Time Scheduling ......................................................................... 72 4. Planner Configuration ................................................................................................ 77 4.1. Overview .......................................................................................................... 77 4.2. Solver Configuration .......................................................................................... 78 4.2.1. Solver Configuration by XML .................................................................. 78 4.2.2. Solver Configuration by Java API ............................................................ 79 4.3. Model a Planning Problem ................................................................................ 79 4.3.1. Is This Class a Problem Fact or Planning Entity? ..................................... 79 4.3.2. Annotation alternatives ........................................................................... 81 4.3.3. Problem Fact ......................................................................................... 82 4.3.4. Planning Entity ....................................................................................... 83 4.3.5. Planning Variable ................................................................................... 86 4.3.6. Planning Value and Planning Value Range .............................................. 88 4.3.7. Shadow Variable .................................................................................... 96 4.3.8. Planning Problem and Planning Solution ................................................ 102 4.4. Use the Solver .............................................................................................. 109 4.4.1. The Solver Interface ............................................................................ 109 4.4.2. Solving a Problem ................................................................................ 110 4.4.3. Environment Mode: Are There Bugs in my Code? .................................. 111 4.4.4. Logging Level: What is the Solver Doing? ............................................. 113 4.4.5. Random Number Generator .................................................................. 116 5. Score Calculation ..................................................................................................... 117 5.1. Score Terminology .......................................................................................... 117 5.1.1. What is a Score? ................................................................................. 117 5.1.2. Score Constraint Signum (Positive or Negative) ...................................... 118 5.1.3. Score Constraint Weight ....................................................................... 119 5.1.4. Score Level .......................................................................................... 120 5.1.5. Pareto Scoring (AKA Multi-objective Optimization Scoring) ...................... 123 5.1.6. Combining Score Techniques ................................................................ 125 5.1.7. Score interface ..................................................................................... 125 5.1.8. Avoid Floating Point Numbers in Score Calculation ................................. 126 5.2. Choose a Score Definition ............................................................................... 128 5.2.1. SimpleScore ......................................................................................... 128 5.2.2. HardSoftScore (Recommended) ............................................................ 128 5.2.3. HardMediumSoftScore .......................................................................... 129 5.2.4. BendableScore ..................................................................................... 129 5.2.5. Implementing a Custom Score .............................................................. 129 5.3. Calculate the Score ........................................................................................ 130 5.3.1. Score Calculation Types ....................................................................... 130 5.3.2. Easy Java Score Calculation ................................................................. 130 5.3.3. Incremental Java Score Calculation ....................................................... 132 5.3.4. Drools Score Calculation ....................................................................... 135 5.3.5. InitializingScoreTrend ...........................................................................