A move can have a small or large impact. In the above example, the move of queen C0 to C2 is a small move. Some moves are the same move type. These are some possibilities for move types in n queens:

Because we have decided that all queens will be on the board at all times and each queen has an appointed column (for performance reasons), only the first 2 move types are usable in our example. Furthermore, we 're only using the first move type in the example because we think it gives the best performance, but you are welcome to prove us wrong.

Each of your move types will be an implementation of the Move interface:

public interface Move {


    boolean isMoveDoable(ScoreDirector scoreDirector);


    Move createUndoMove(ScoreDirector scoreDirector);


    void doMove(ScoreDirector scoreDirector);


}

Let's take a look at the Move implementation for 4 queens which moves a queen to a different row:

public class RowChangeMove implements Move {


    private Queen queen;

    private Row toRow;


    public RowChangeMove(Queen queen, Row toRow) {

        this.queen = queen;

        this.toRow = toRow;

    }


    // ... see below


}

An instance of RowChangeMove moves a queen from its current row to a different row.

Planner calls the doMove(ScoreDirector) method to do a move. The Move implementation must notify the ScoreDirector of any changes it make to the planning entities's variables:

    public void doMove(ScoreDirector scoreDirector) {

        scoreDirector.beforeVariableChanged(queen, "row"); // before changes are made

        queen.setRow(toRow);

        scoreDirector.afterVariableChanged(queen, "row"); // after changes are made

    }

You need to call the methods scoreDirector.beforeVariableChanged(Object, String) and scoreDirector.afterVariableChanged(Object, String) before and after modifying the entity. Alternatively, you can also call the methods scoreDirector.beforeAllVariablesChanged(Object) and scoreDirector.afterAllVariablesChanged(Object).

Planner automatically filters out non doable moves by calling the isDoable(ScoreDirector) method on a move. A non doable move is:

In the n queens example, a move which moves the queen from its current row to the same row isn't doable:

    public boolean isMoveDoable(ScoreDirector scoreDirector) {

        return !ObjectUtils.equals(queen.getRow(), toRow);

    }

Because we won't generate a move which can move a queen outside the board limits, we don't need to check it. A move that is currently not doable could become doable on the working Solution of a later step.

Each move has an undo move: a move (normally of the same type) which does the exact opposite. In the example above the undo move of C0 to C2 would be the move C2 to C0. An undo move is created from a Move, before the Move has been done on the current solution.

    public Move createUndoMove(ScoreDirector scoreDirector) {

        return new RowChangeMove(queen, queen.getRow());

    }

Notice that if C0 would have already been moved to C2, the undo move would create the move C2 to C2, instead of the move C2 to C0.

The local search solver phase might do and undo the same Move more than once, even on different (successive) solutions.

A Move must implement the getPlanningEntities() and getPlanningValues() methods. They are used by entity tabu and value tabu respectively. When they are called, the Move has already been done.

    public List<? extends Object> getPlanningEntities() {

        return Collections.singletonList(queen);

    }


    public Collection<? extends Object> getPlanningValues() {

        return Collections.singletonList(toRow);

    }

If your Move changes multiple planning entities, return all them in getPlanningEntities() and return all their values (to which they are changing) in getPlanningValues().

    public Collection<? extends Object> getPlanningEntities() {

        return Arrays.asList(leftCloudProcess, rightCloudProcess);

    }


    public Collection<? extends Object> getPlanningValues() {

        return Arrays.asList(leftCloudProcess.getComputer(), rightCloudProcess.getComputer());

    }

A Move must implement the equals() and hashCode() methods. 2 moves which make the same change on a solution, should be equal.

    public boolean equals(Object o) {

        if (this == o) {

            return true;

        } else if (o instanceof RowChangeMove) {

            RowChangeMove other = (RowChangeMove) o;

            return new EqualsBuilder()

                    .append(queen, other.queen)

                    .append(toRow, other.toRow)

                    .isEquals();

        } else {

            return false;

        }

    }


    public int hashCode() {

        return new HashCodeBuilder()

                .append(queen)

                .append(toRow)

                .toHashCode();

    }

In the above example, the Queen class uses the default Object equals() and hashCode() implementations. Notice that it checks if the other move is an instance of the same move type. This instanceof check is important because a move will be compared to a move with another move type if you're using more then 1 move type.

It's also recommended to implement the toString() method as it allows you to read Planner's logging more easily:

    public String toString() {

        return queen + " => " + toRow;

    }

Now that we can make a single move, let's take a look at generating moves.

As you can see, not all the moves are doable. At the starting solution we have 12 doable moves (n * (n - 1)), one of which will be move which changes the starting solution into the next solution. Notice that the number of possible solutions is 256 (n ^ n), much more that the amount of doable moves. Don't create a move to every possible solution. Instead use moves which can be sequentially combined to reach every possible solution.

It's highly recommended that you verify all solutions are connected by your move set. This means that by combining a finite number of moves you can reach any solution from any solution. Otherwise you're already excluding solutions at the start. Especially if you're using only big moves, you should check it. Just because big moves outperform small moves in a short test run, it doesn't mean that they will outperform them in a long test run.

You can mix different move types. Usually you're better off preferring small (fine-grained) moves over big (course-grained) moves because the score delta calculation will pay off more. However, as the traveling tournament example proves, if you can remove a hard constraint by using a certain set of big moves, you can win performance and scalability. Try it yourself: run both the simple (small moves) and the smart (big moves) version of the traveling tournament example. The smart version evaluates a lot less unfeasible solutions, which enables it to outperform and outscale the simple version.

Move generation currently happens with a MoveFactory:

public class RowChangeMoveFactory extends CachedMoveListMoveFactory {


    public List<Move> createMoveList(Solution solution) {

        NQueens nQueens = (NQueens) solution;

        List<Move> moveList = new ArrayList<Move>();

        for (Queen queen : nQueens.getQueenList()) {

            for (Row toRow : nQueens.getRowList()) {

                moveList.add(new RowChangeMove(queen, toRow));

            }

        }

        return moveList;

    }


}

Future versions might also support move generation by DRL.

Because the move B0 to B3 has the highest score (-3), it is picked as the next step. Notice that C0 to C3 (not shown) could also have been picked because it also has the score -3. If multiple moves have the same highest score, one is picked randomly, in this case B0 to B3.

The step is made and from that new solution, the local search solver tries all the possible moves again, to decide the next step after that. It continually does this in a loop, and we get something like this:

Notice that the local search solver doesn't use a search tree, but a search path. The search path is highlighted by the green arrows. At each step it tries all possible moves, but unless it's the step, it doesn't investigate that solution further. This is one of the reasons why local search is very scalable.

As you can see, the local search solver solves the 4 queens problem by starting with the starting solution and make the following steps sequentially:

If we turn on DEBUG logging for the category org.drools.planner, then those steps are shown into the log:

INFO  Solving started: time spend (0), score (-6), new best score (-6), random seed (0).
DEBUG     Step index (0), time spend (20), score (-3), new best score (-3), accepted move size (12) for picked step (col1@row0 => row3).
DEBUG     Step index (1), time spend (31), score (-1), new best score (-1), accepted move size (12) for picked step (col0@row0 => row1).
DEBUG     Step index (2), time spend (40), score (0), new best score (0), accepted move size (12) for picked step (col3@row0 => row2).
INFO  Phase localSearch ended: step total (3), time spend (41), best score (0).
INFO  Solving ended: time spend (41), best score (0), average calculate count per second (1780).

Notice that the logging uses the toString() method of our Move implementation: col1@row0 => row3.

The local search solver solves the 4 queens problem in 3 steps, by evaluating only 37 possible solutions (3 steps with 12 moves each + 1 starting solution), which is only fraction of all 256 possible solutions. It solves 16 queens in 31 steps, by evaluating only 7441 out of 18446744073709551616 possible solutions. Note: with construction heuristics it's even a lot more efficient.