JBoss.orgCommunity Documentation
OptaPlanner is a lightweight, embeddable planning engine that optimizes planning problems. It solves use cases, such as:
Employee shift rostering: timetabling nurses, repairmen, ...
Agenda scheduling: scheduling meetings, appointments, maintenance jobs, advertisements, ...
Educational timetabling: scheduling lessons, courses, exams, conference presentations, ...
Vehicle routing: planning vehicles (trucks, trains, boats, airplanes, ...) with freight and/or people
Bin packing: filling containers, trucks, ships and storage warehouses, but also cloud computers nodes, ...
Job shop scheduling: planning car assembly lines, machine queue planning, workforce task planning, ...
Cutting stock: minimizing waste while cutting paper, steel, carpet, ...
Sport scheduling: planning football leagues, baseball leagues, ...
Financial optimization: investment portfolio optimization, risk spreading, ...
Every organization faces planning problems: provide products or services with a limited set of constrained resources (employees, assets, time and money). OptaPlanner optimizes such planning to do more business with less resources. This is known as Constraint Satisfaction Programming (which is part of the discipline Operations Research).
OptaPlanner helps normal JavaTM programmers solve constraint satisfaction problems efficiently. Under the hood, it combines optimization heuristics and metaheuristics with very efficient score calculation.
OptaPlanner is open source software, released under the Apache Software License 2.0. This license is very liberal and allows reuse for commercial purposes. Read the layman's explanation. OptaPlanner is 100% pure JavaTM, runs on any JVM and is available in the Maven Central Repository too.
All the use cases above are probably NP-complete. In layman's terms, this means:
It's easy to verify a given solution to a problem in reasonable time.
There is no silver bullet to find the optimal solution of a problem in reasonable time (*).
(*) At least, none of the smartest computer scientists in the world have found such a silver bullet yet. But if they find one for 1 NP-complete problem, it will work for every NP-complete problem.
In fact, there's a $ 1,000,000 reward for anyone that proves if such a silver bullet actually exists or not.
The implication of this is pretty dire: solving your problem is probably harder than you anticipated, because the 2 common techniques won't suffice:
A brute force algorithm (even a smarter variant) will take too long.
A quick algorithm, for example in bin packing, putting in the largest items first, will return a solution that is usually far from optimal.
By using advanced optimization algorithms, Planner does find a good solution in reasonable time for such planning problems.
Usually, a planning problem has at least 2 levels of constraints:
Download a release zip of OptaPlanner from the OptaPlanner website.
Unzip it.
Open the directory examples
and run the script.
Linux or Mac:
$ cd examples $ ./runExamples.sh
Windows:
$ cd examples $ runExamples.bat
The Examples GUI application will open. Just pick an example:
OptaPlanner itself has no GUI dependencies. It runs just as well on a server or a mobile JVM as it does on the desktop.
The OptaPlanner jars are also available in the central maven repository (and also in the JBoss maven repository).
If you use Maven, add a dependency to optaplanner-core
in your project's
pom.xml
:
<dependency>
<groupId>org.optaplanner</groupId>
<artifactId>optaplanner-core</artifactId>
</dependency>
This is similar for Gradle, Ivy and Buildr. To identify the latest version, check the central maven repository.
Because you might end up using other optaplanner modules too, it's recommended to import the
optaplanner-bom
in Maven's dependencyManagement
so the optaplanner version
is specified only once:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.optaplanner</groupId>
<artifactId>optaplanner-bom</artifactId>
<type>pom</type>
<version>...</version>
<scope>import</scope>
</dependency>
...
</dependencies>
</dependencyManagement>
If you're still using ANT (without Ivy), copy all the jars from the download zip's
binaries
directory and manually verify that your classpath doesn't contain duplicate
jars.
The download zip's binaries
directory contains far more jars then
optaplanner-core
actually uses. It also contains the jars used by other modules, such as
optaplanner-benchmark
.
Check the maven repository pom.xml
files to determine the minimal dependency set for
a specific version of a specific module.
It's easy to build OptaPlanner from source:
Set up Git and clone
optaplanner
from GitHub (or alternatively, download the zipball):
$ git clone git@github.com:droolsjbpm/optaplanner.git optaplanner ...
If you don't have a GitHub account or your local Git installation isn't configured with it, use this command instead, to avoid an authentication issue:
$ git clone https://github.com/droolsjbpm/optaplanner.git optaplanner ...
Build it with Maven:
$ cd optaplanner $ mvn clean install -DskipTests ...
The first time, Maven might take a lot time, because it needs to download jars.
Run the examples:
$ cd optaplanner-examples $ mvn exec:exec ...
Edit the sources in your favorite IDE.
Optional: use a Java profiler.
Impl classes: All classes in the package namespace org.optaplanner.core.impl are not backwards compatible: they might change in future
releases. The recipe called UpgradeFromPreviousVersionRecipe.txt
describes every such change and on how to quickly deal with it when upgrading to a newer version. That recipe
file is included in every release zip.
XML configuration: The XML solver configuration is backwards compatible for all elements, except for elements that require the use of non public API classes. The XML solver configuration is defined by the classes in the package namespace org.optaplanner.core.config.
This documentation covers some impl classes too. Those documented impl classes are reliable and safe to use (unless explicitly marked as experimental in this documentation), but we're just entirely comfortable yet to write their signatures in stone.
Your questions and comments are welcome on the user
mailing list. Start the subject of your mail with [planner]
. You can read/write to the
user mailing list without littering your mailbox through this web forum or this newsgroup.
Feel free to report an issue (such as a bug, improvement or a new feature request) for the OptaPlanner code or for this manual to our issue tracker.
Pull requests are very welcome and get priority treatment! By open sourcing your improvements, you 'll benefit from our peer review and from our improvements made upon your improvements.
Check our blog, Google+ (OptaPlanner, Geoffrey De Smet) and twitter (Geoffrey De Smet) for news and articles. If OptaPlanner helps you solve your problem, don't forget to blog or tweet about it!