JBoss.org Community Documentation

- Prev
- Next

## Chapter 1. Planner introduction

## 1.1. What is Drools Planner?

Drools Planner optimizes automated planning by combining a search algorithm with the power of the Drools rule engine. Use cases of planning problems include:

- Employee shift rostering, such as nurse rostering

- Vehicle routing, freight routing and people routing, such as The traveling salesman problem and The traveling tournament problem

- Educational timetabling, such as lesson scheduling, course schedule, exam scheduling and conference scheduling

- Bin packing, stock sorting and storage organizing

- Machine queue planning

- Miss manners too (although the Drools Planner example solves this differently than the pure Drools Expert example)

A planning problem consists out of a number of constraints. Generally, there are 3 types of constraints:

- A (negative) hard constraint must not be broken. For example: 1 teacher can not teach 2 different lessons at the same time.

- A (negative) soft constraint should not be broken if it can be avoided. For example: Teacher A does not like to teach on Friday afternoon.

- A positive constraint (or reward) should be fulfilled if possible. For example: Teacher B likes to teach on Monday morning.

These constraints define the score function of a planning problem. This is where the drools rule engine comes into play: adding constraints with score rules is easy and scalable.

A planning problem has a number of solutions. Each solution has a score. There are 3 categories of solutions:

- A possible solution is a solution that does or does not break any number of constraints. Planning problems tend to have a incredibly large number of possible solutions. Most of those solutions are worthless.

- A feasible solution is a solution that does not break any (negative) hard constraints. The number of feasible solutions tends to be relative to the number of possible solutions. Sometimes there are no feasible solutions. Every feasible solution is a possible solution.

- An optimal solution is a solution with the highest score. Planning problems tend to have 1 or a few optimal solutions. There is always at least 1 optimal solution, even in the remote case that it's not a feasible solution because there are no feasible solutions.

Drools Planner supports several search algorithms to efficiently wade through the incredibly large number of possible solutions. It makes it easy to switch the search algorithm, by simply changing the solver configuration.

## 1.2. Status of Drools Planner

Drools Planner is production ready. The API is almost stable but backward incompatible changes can occur. With the recipe called `UpgradeFromPreviousVersionRecipe.txt` you can easily upgrade and deal with any backwards incompatible changes between versions. This recipe is included in every release.

Drools Planner, like Drools, is open source software under the Apache Software License.

## 1.3. Getting Drools Planner and running the examples

### 1.3.1. Getting the release package and running the examples

You can download a release of Drools Planner from the drools download site. To run an example, just open the directory `examples` and run the script (`runExamples.sh` on linux or `runExamples.bat` on windows) and pick an example:

    $ cd examples
    $ ./runExamples.sh

    $ cd examples
    $ runExamples.bat

### 1.3.2. Get it with maven

The Drools Planner jars are available on the jboss maven repository. If you use maven 2 or 3, just add a dependency to `drools-planner-core` in your project's `pom.xml`:

        <dependency>

            <groupId>org.drools.planner</groupId>

            <artifactId>drools-planner-core</artifactId>

            <version>5.x</version>

        </dependency>

You might also need to add the jboss repository in your repository manager (nexus, archiva, ...) or your `~/settings.xml`:

        <repositories>

            <repository>

                <id>jboss-public-repository-group</id>

                <name>JBoss Public Maven Repository Group</name>

                <url>https://repository.jboss.org/nexus/content/groups/public/</url>

                <releases>

                    <enabled>true</enabled>

                </releases>

                <snapshots>

                    <enabled>true</enabled>

                </snapshots>

            </repository>

            ...

        </repositories>

### 1.3.3. Build it from source

You can also easily build it from source yourself. Clone drools from GitHub and do a maven 2 build:

    $ git clone git@github.com:droolsjbpm/drools-planner.git drools-planner
    ...
    $ cd drools-planner
    $ mvn -DskipTests clean install
    ...

After that, you can run any example directly from the command line, just run this command and pick an example:

    $ cd drools-planner-examples
    $ mvn exec:exec
    ...

## 1.4. Questions, issues and blogs

Your questions and remarks 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 Drools Planner code or for this manual to the drools issue tracker. Select the component `drools-planner`.

Pull requests (and patches) are very welcome and get priority treatment! Attach them to a JIRA issue and optionally send a mail to the dev mailing list to get the issue fixed fast. By open sourcing your improvements, you 'll benefit from our peer review, improvements made upon your improvements and maybe even a thank you on our blog.

Check our blog and twitter (Geoffrey De Smet) for news. If Drools Planner helps you, don't forget to blog or to twitter about it!

- Prev
- Top of page
- Front page
- NextChapter 2. Use cases and examples