Chapter-Move_and_neighborhood_selection.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xml:id="moveAndNeighborhoodSelection" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title><literal>Move</literal> and neighborhood selection</title>

  <section xml:id="moveAndNeighborhoodSelectionIntroduction">
    <title><literal>Move</literal> and neighborhood introduction</title>

    <section xml:id="whatIsAMove">
      <title>What is a <literal>Move</literal>?</title>

      <para>A <literal>Move</literal> is a change (or set of changes) from a solution A to a solution B. For example,
      the move below changes queen <literal>C</literal> from row <literal>0</literal> to row
      <literal>2</literal>:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/singleMoveNQueens04.png"/>
        </imageobject>
      </mediaobject>

      <para>The new solution is called a <emphasis>neighbor</emphasis> of the original solution, because it can be
      reached in a single <literal>Move</literal>. Although a single move can change multiple queens, the neighbors of a
      solution should always be a very small subset of all possible solutions. For example, on that original solution,
      these are all possible <literal>changeMove</literal>'s:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/possibleMovesNQueens04.png"/>
        </imageobject>
      </mediaobject>

      <para>If we ignore the 4 <literal>changeMove</literal>'s that have not impact and are therefore not doable, we can
      see that number of moves is <literal>n * (n - 1) = 12</literal>. This is far less than the number of possible
      solutions, which is <literal>n ^ n = 256</literal>. As the problem scales out, the number of possible moves
      increases far less than the number of possible solutions.</para>

      <para>Yet, in 4 <literal>changeMove</literal>'s or less we can reach any solution. For example we can reach a very
      different solution in 3 <literal>changeMove</literal>'s:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/sequentialMovesNQueens04.png"/>
        </imageobject>
      </mediaobject>

      <note>
        <para>There are many other types of moves besides <literal>changeMove</literal>'s. Many move types are included
        out-of-the-box, but you can also implement custom moves.</para>

        <para>A <literal>Move</literal> can affect multiple entities or even create/delete entities. But it must not
        change the problem facts.</para>
      </note>

      <para>All optimization algorithms use <literal>Move</literal>'s to transition from one solution to a neighbor
      solution. Therefor, all the optimization algorithms are confronted with <literal>Move</literal> selection: the
      craft of creating and iterating moves efficiently and the art of finding the most promising subset of random moves
      to evaluate first.</para>
    </section>

    <section xml:id="whatIsAMoveSelector">
      <title>What is a <literal>MoveSelector</literal>?</title>

      <para>A <literal>MoveSelector</literal>'s main function is to create <literal>Iterator&lt;Move&gt;</literal> when
      needed. An optimization algorithm will iterate through a subset of those moves.</para>

      <para>Here's an example how to configure a <literal>changeMoveSelector</literal> for the optimization algorithm
      Local Search:</para>

      <programlisting language="xml">  &lt;localSearch&gt;
    &lt;changeMoveSelector/&gt;
    ...
  &lt;/localSearch&gt;</programlisting>

      <para>Out of the box, this works and all properties of the <literal>changeMoveSelector</literal> are defaulted
      sensibly (unless that fails fast due to ambiguity). On the other hand, the configuration can be customized
      significantly for specific use cases. For example: you might want to configure a filter to discard pointless
      moves.</para>
    </section>

    <section xml:id="subselectingOfEntitiesValuesAndOtherMoves">
      <title>Subselecting of entities, values and other moves</title>

      <para>To create a <literal>Move</literal>, a <literal>MoveSelector</literal> needs to select 1 or more planning
      entities and/or planning values to move. Just like <literal>MoveSelector</literal>s,
      <literal>EntitySelector</literal>s and <literal>ValueSelector</literal>s need to support a similar feature set
      (such as scalable just-in-time selection). Therefore, they all implement a common interface
      <literal>Selector</literal> and they are configured similarly.</para>

      <para>A MoveSelector is often composed out of <literal>EntitySelector</literal>s,
      <literal>ValueSelector</literal>s or even other <literal>MoveSelector</literal>s, which can be configured
      individually if desired:</para>

      <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;changeMoveSelector&gt;
        &lt;entitySelector&gt;
          ...
        &lt;/entitySelector&gt;
        &lt;valueSelector&gt;
          ...
        &lt;/valueSelector&gt;
        ...
      &lt;/changeMoveSelector&gt;
      &lt;swapMoveSelector&gt;
        ...
      &lt;/swapMoveSelector&gt;
    &lt;/unionMoveSelector&gt;</programlisting>

      <para>Together, this structure forms a <literal>Selector</literal> tree:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/selectorTree.png"/>
        </imageobject>
      </mediaobject>

      <para>The root of this tree is a <literal>MoveSelector</literal> which is injected into the optimization algorithm
      implementation to be (partially) iterated in every step.</para>
    </section>
  </section>

  <section xml:id="genericMoveSelectors">
    <title>Generic MoveSelectors</title>

    <section xml:id="changeMoveSelector">
      <title><literal>changeMoveSelector</literal></title>

      <para>For 1 planning variable, the <literal>ChangeMove</literal> selects 1 planning entity and 1 planning value
      and assigns the entity's variable to that value.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/changeMove.png"/>
        </imageobject>
      </mediaobject>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;changeMoveSelector/&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;changeMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;entitySelector&gt;
        &lt;entityClass&gt;...Lecture&lt;/entityClass&gt;
        ...
      &lt;/entitySelector&gt;
      &lt;valueSelector&gt;
        &lt;variableName&gt;room&lt;/variableName&gt;
        ...
      &lt;/valueSelector&gt;
    &lt;/changeMoveSelector&gt;</programlisting>

      <para>A <literal>ChangeMove</literal> is the finest grained move.</para>

      <important>
        <para>Almost every <literal>moveSelector</literal> configuration injected into a metaheuristic algorithm should
        include a changeMoveSelector or a custom implementation. This guarantees that every possible
        <literal>Solution</literal> can be reached through applying a number of moves in sequence (not taking <link
        linkend="scoreTrap">score traps</link> into account). Of course, normally it is unioned with other, more course
        grained move selectors.</para>
      </important>
    </section>

    <section xml:id="swapMoveSelector">
      <title>swapMoveSelector</title>

      <para>The <literal>SwapMove</literal> selects 2 different planning entities and swaps the planning values of all
      their planning variables.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/swapMove.png"/>
        </imageobject>
      </mediaobject>

      <para>Although a <literal>SwapMove</literal> on a single variable is essentially just 2
      <literal>ChangeMove</literal>s, it's often the winning step where the first of the 2
      <literal>ChangeMove</literal>s would not be the winning step because it leave the solution in a state with broken
      hard constraints. For example: swapping the room of 2 lectures doesn't bring the solution in a intermediate state
      where both lectures are in the same room which breaks a hard constraint.</para>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;swapMoveSelector/&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;swapMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;entitySelector&gt;
        &lt;entityClass&gt;...Lecture&lt;/entityClass&gt;
        ...
      &lt;/entitySelector&gt;
      &lt;secondaryEntitySelector&gt;
        ...
      &lt;/secondaryEntitySelector&gt;
      &lt;variableNameInclude&gt;room&lt;/variableNameInclude&gt;
      &lt;variableNameInclude&gt;...&lt;/variableNameInclude&gt;
    &lt;/swapMoveSelector&gt;</programlisting>

      <para>The <literal>secondaryEntitySelector</literal> is rarely needed: if it is not specified, entities from the
      same <literal>entitySelector</literal> are swapped.</para>

      <para>If one or more <literal>variableNameInclude</literal> properties are specified, not all planning variables
      will be swapped, but only those specified. For example for course scheduling, specifying only
      <literal>variableNameInclude</literal> room will make it only swap room, not period.</para>
    </section>

    <section xml:id="pillarSwapMoveSelector">
      <title>pillarSwapMoveSelector</title>

      <para>A <emphasis>pillar</emphasis> is a set of planning entities which have the same planning value(s) for each
      of their planning variables. The <literal>pillarSwapMove</literal> selects 2 different entity pillars and swaps
      the values of all their variables for all their entities.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/pillarSwapMove.png"/>
        </imageobject>
      </mediaobject>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;pillarSwapMoveSelector/&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;pillarSwapMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;pillarSelector&gt;
        &lt;entitySelector&gt;
          &lt;entityClass&gt;...Lecture&lt;/entityClass&gt;
          ...
        &lt;/entitySelector&gt;
      &lt;/pillarSelector&gt;
      &lt;secondaryPillarSelector&gt;
        &lt;entitySelector&gt;
          ...
        &lt;/entitySelector&gt;
      &lt;/secondaryPillarSelector&gt;
      &lt;variableNameInclude&gt;room&lt;/variableNameInclude&gt;
      &lt;variableNameInclude&gt;...&lt;/variableNameInclude&gt;
    &lt;/pillarSwapMoveSelector&gt;</programlisting>

      <para>The <literal>secondaryPillarSelector</literal> is rarely needed: if it is not specified, entities from the
      same <literal>pillarSelector</literal> are swapped.</para>

      <para>The other properties are explained in <link linkend="swapMoveSelector">swapMoveSelector</link>.</para>
    </section>

    <section xml:id="subChainChangeMoveSelector">
      <title>subChainChangeMoveSelector</title>

      <para>A <emphasis>subChain</emphasis> is a set of planning entities with a chained planning variable which form
      part of a chain. The <literal>subChainChangeMove</literal> selects a subChain and moves it to another place in a
      different or the same anchor chain.</para>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;subChainChangeMoveSelector/&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;subChainChangeMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;subChainSelector&gt;
        &lt;entitySelector&gt;
          &lt;entityClass&gt;...Customer&lt;/entityClass&gt;
          ...
        &lt;/entitySelector&gt;
        &lt;minimumSubChainSize&gt;2&lt;/minimumSubChainSize&gt;
        &lt;maximumSubChainSize&gt;40&lt;/maximumSubChainSize&gt;
      &lt;/subChainSelector&gt;
      &lt;valueSelector&gt;
        &lt;variableName&gt;previousStandstill&lt;/variableName&gt;
        ...
      &lt;/valueSelector&gt;
      &lt;selectReversingMoveToo&gt;true&lt;/selectReversingMoveToo&gt;
    &lt;/subChainChangeMoveSelector&gt;</programlisting>

      <para>The <literal>subChainSelector</literal> selects a number of entities, no less than
      <literal>minimumSubChainSize</literal> (defaults to 2) and no more than <literal>maximumSubChainSize</literal>
      (defaults to infinity).</para>

      <para>The property <literal>selectReversingMoveToo</literal> (defaults to true) enabled selecting the reverse of
      every subchain too.</para>
    </section>

    <section xml:id="subChainSwapMoveSelector">
      <title>subChainSwapMoveSelector</title>

      <para>The <literal>subChainSwapMove</literal> selects 2 different subChains and moves it to another place in a
      different or the same anchor chain.</para>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;subChainSwapMoveSelector/&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;subChainSwapMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;subChainSelector&gt;
        &lt;entitySelector&gt;
          &lt;entityClass&gt;...Customer&lt;/entityClass&gt;
          ...
        &lt;/entitySelector&gt;
        &lt;minimumSubChainSize&gt;2&lt;/minimumSubChainSize&gt;
        &lt;maximumSubChainSize&gt;40&lt;/maximumSubChainSize&gt;
      &lt;/subChainSelector&gt;
      &lt;secondarySubChainSelector&gt;
        &lt;entitySelector&gt;
          &lt;entityClass&gt;...Customer&lt;/entityClass&gt;
          ...
        &lt;/entitySelector&gt;
        &lt;minimumSubChainSize&gt;2&lt;/minimumSubChainSize&gt;
        &lt;maximumSubChainSize&gt;40&lt;/maximumSubChainSize&gt;
      &lt;/secondarySubChainSelector&gt;
      &lt;selectReversingMoveToo&gt;true&lt;/selectReversingMoveToo&gt;
    &lt;/subChainSwapMoveSelector&gt;</programlisting>

      <para>The <literal>secondarySubChainSelector</literal> is rarely needed: if it is not specified, entities from the
      same <literal>subChainSelector</literal> are swapped.</para>

      <para>The other properties are explained in <link
      linkend="subChainChangeMoveSelector">subChainChangeMoveSelector</link>.</para>
    </section>
  </section>

  <section xml:id="combiningMultipleMoveSelectors">
    <title>Combining multiple <literal>MoveSelector</literal>s</title>

    <section xml:id="unionMoveSelector">
      <title>unionMoveSelector</title>

      <para>A <literal>unionMoveSelector</literal> selects a <literal>Move</literal> by selecting 1 of its child
      <literal>MoveSelector</literal>s to supply the next <literal>Move</literal>.</para>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;...MoveSelector/&gt;
      &lt;...MoveSelector/&gt;
      &lt;...MoveSelector/&gt;
      ...
    &lt;/unionMoveSelector&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;unionMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;selectorProbabilityWeightFactoryClass&gt;...ProbabilityWeightFactory&lt;/selectorProbabilityWeightFactoryClass&gt;
      &lt;changeMoveSelector&gt;
        &lt;fixedProbabilityWeight&gt;...&lt;/fixedProbabilityWeight&gt;
        ...
      &lt;/changeMoveSelector&gt;
      &lt;swapMoveSelector&gt;
        &lt;fixedProbabilityWeight&gt;...&lt;/fixedProbabilityWeight&gt;
        ...
      &lt;/swapMoveSelector&gt;
      &lt;...MoveSelector&gt;
        &lt;fixedProbabilityWeight&gt;...&lt;/fixedProbabilityWeight&gt;
        ...
      &lt;/...MoveSelector&gt;
      ...
    &lt;/unionMoveSelector&gt;</programlisting>

      <para>The <literal>selectorProbabilityWeightFactory</literal> determines in <literal>selectionOrder</literal>
      <literal>RANDOM</literal> how often a child MoveSelector is selected to supply the next Move. By default, each
      child <literal>MoveSelector</literal> has the same chance of being selected.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/selectorProbabilityInUnion.png"/>
        </imageobject>
      </mediaobject>

      <para>Change the fixedProbabilityWeight of such a child to select it more often. For example, the
      <literal>unionMoveSelector</literal> can return a <literal>SwapMove</literal> twice as often as a
      <literal>ChangeMove</literal>:</para>

      <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;changeMoveSelector&gt;
        &lt;fixedProbabilityWeight&gt;1.0&lt;/fixedProbabilityWeight&gt;
        ...
      &lt;/changeMoveSelector&gt;
      &lt;swapMoveSelector&gt;
        &lt;fixedProbabilityWeight&gt;2.0&lt;/fixedProbabilityWeight&gt;
        ...
      &lt;/swapMoveSelector&gt;
    &lt;/unionMoveSelector&gt;</programlisting>

      <para>The number of possible <literal>ChangeMove</literal>s is very different from the number of possible
      <literal>SwapMove</literal>s and furthermore it's problem dependent. To give each individual
      <literal>Move</literal> the same selection chance (as opposed to each <literal>MoveSelector</literal>), use the
      <literal>FairSelectorProbabilityWeightFactory</literal>:</para>

      <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;selectorProbabilityWeightFactoryClass&gt;org.optaplanner.core.impl.heuristic.selector.common.decorator.FairSelectorProbabilityWeightFactory&lt;/selectorProbabilityWeightFactoryClass&gt;
      &lt;changeMoveSelector/&gt;
      &lt;swapMoveSelector/&gt;
    &lt;/unionMoveSelector&gt;</programlisting>
    </section>

    <section xml:id="cartesianProductMoveSelector">
      <title>cartesianProductMoveSelector</title>

      <para>A <literal>cartesianProductMoveSelector</literal> selects a new <literal>CompositeMove</literal>. It builds
      that <literal>CompositeMove</literal> by selecting 1 <literal>Move</literal> per child
      <literal>MoveSelector</literal> and adding it to the <literal>CompositeMove</literal>.</para>

      <para>Simplest configuration:</para>

      <programlisting language="xml">    &lt;cartesianProductMoveSelector&gt;
      &lt;...MoveSelector/&gt;
      &lt;...MoveSelector/&gt;
      &lt;...MoveSelector/&gt;
      ...
    &lt;/cartesianProductMoveSelector&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;cartesianProductMoveSelector&gt;
      ... &lt;!-- Normal selector properties --&gt;
      &lt;ignoreEmptyChildIterators&gt;true&lt;/ignoreEmptyChildIterators&gt;
      &lt;changeMoveSelector&gt;
        ...
      &lt;/changeMoveSelector&gt;
      &lt;swapMoveSelector&gt;
        ...
      &lt;/swapMoveSelector&gt;
      &lt;...MoveSelector&gt;
        ...
      &lt;/...MoveSelector&gt;
      ...
    &lt;/cartesianProductMoveSelector&gt;</programlisting>

      <para>The propery <literal>ignoreEmptyChildIterators</literal> (true by default) will ignore every empty
      <literal>childMoveSelector</literal> to avoid returning no moves. For example: a cartesian product of
      <literal>changeMoveSelector</literal> A and B, for which B is empty (because all it's entities are immovable)
      returns no moves if <literal>ignoreEmptyChildIterators</literal> is <literal>false</literal> and the moves of A if
      <literal>ignoreEmptyChildIterators</literal> is <literal>true</literal>.</para>
    </section>
  </section>

  <section xml:id="entitySelector">
    <title>EntitySelector</title>

    <para>Simplest configuration:</para>

    <programlisting language="xml">      &lt;entitySelector/&gt;</programlisting>

    <para>Advanced configuration:</para>

    <programlisting language="xml">      &lt;entitySelector&gt;
        ... &lt;!-- Normal selector properties --&gt;
        &lt;entityClass&gt;org.optaplanner.examples.curriculumcourse.domain.Lecture&lt;/entityClass&gt;
      &lt;/entitySelector&gt;</programlisting>

    <para>The <literal>entityClass</literal> property is only required if it cannot be deduced automatically because
    there are multiple entity classes.</para>
  </section>

  <section xml:id="valueSelector">
    <title>ValueSelector</title>

    <para>Simplest configuration:</para>

    <programlisting language="xml">      &lt;valueSelector/&gt;</programlisting>

    <para>Advanced configuration:</para>

    <programlisting language="xml">      &lt;valueSelector&gt;
        ... &lt;!-- Normal selector properties --&gt;
        &lt;variableName&gt;room&lt;/variableName&gt;
      &lt;/valueSelector&gt;</programlisting>

    <para>The <literal>variableName</literal> property is only required if it cannot be deduced automatically because
    there are multiple variables (for the related entity class).</para>
  </section>

  <section xml:id="generalSelectorFeatures">
    <title>General <literal>Selector</literal> features</title>

    <section xml:id="cacheType">
      <title><literal>CacheType</literal>: Create moves ahead of time or Just In Time</title>

      <para>A <literal>Selector</literal>'s <literal>cacheType</literal> determines when a selection (such as a
      <literal>Move</literal>, an entity, a value, ...) is created and how long it lives.</para>

      <para>Almost every <literal>Selector</literal> supports setting a <literal>cacheType</literal>:</para>

      <programlisting language="xml">    &lt;changeMoveSelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      ...
    &lt;/changeMoveSelector&gt;</programlisting>

      <para>The following <literal>cacheType</literal>s are supported:</para>

      <itemizedlist>
        <listitem>
          <para><literal>JUST_IN_TIME</literal> (default): Not cached. Construct each selection
          (<literal>Move</literal>, ...) just before it's used. This scales up well in memory footprint.</para>
        </listitem>

        <listitem>
          <para><literal>STEP</literal>: Cached. Create each selection (<literal>Move</literal>, ...) at the beginning
          of a step and cache them in a list for the remainder of the step. This scales up badly in memory
          footprint.</para>
        </listitem>

        <listitem>
          <para><literal>PHASE</literal>: Cached. Create each selection (<literal>Move</literal>, ...) at the beginning
          of a <literal>SolverPhase</literal> and cache them in a list for the remainder of the
          <literal>SolverPhase</literal>. Some selections cannot be phase cached because the list changes every step.
          This scales up badly in memory footprint, but has a slight performance gain.</para>
        </listitem>

        <listitem>
          <para><literal>SOLVER</literal>: Cached. Create each selection (<literal>Move</literal>, ...) at the beginning
          of a <literal>Solver</literal> and cache them in a list for the remainder of the <literal>Solver</literal>.
          Some selections cannot be solver cached because the list changes every step. This scales up badly in memory
          footprint, but has a slight performance gain.</para>
        </listitem>
      </itemizedlist>

      <para>A <literal>cacheType</literal> can be set on composite selectors too:</para>

      <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;changeMoveSelector/&gt;
      &lt;swapMoveSelector/&gt;
      ...
    &lt;/unionMoveSelector&gt;</programlisting>

      <para>Nested selectors of a cached selector cannot be configured to be cached themselves, unless it's a higher
      <literal>cacheType</literal>. For example: a <literal>STEP</literal> cached <literal>unionMoveSelector</literal>
      can hold a <literal>PHASE</literal> cached <literal>changeMoveSelector</literal>, but not a
      <literal>STEP</literal> cached <literal>changeMoveSelector</literal>.</para>
    </section>

    <section xml:id="selectionOrder">
      <title>SelectionOrder: original, sorted, random, shuffled or probabilistic</title>

      <para>A <literal>Selector</literal>'s <literal>selectionOrder</literal> determines the order in which the
      selections (such as <literal>Move</literal>s, entities, values, ...) are iterated. An optimization algorithm will
      usually only iterate through a subset of its <literal>MoveSelector</literal>'s selections, starting from the
      start, so the <literal>selectionOrder</literal> is critical to decide which <literal>Move</literal>s are actually
      evaluated.</para>

      <para>Almost every <literal>Selector</literal> supports setting a <literal>selectionOrder</literal>:</para>

      <programlisting language="xml">    &lt;changeMoveSelector&gt;
      ...
      &lt;selectionOrder&gt;RANDOM&lt;/selectionOrder&gt;
      ...
    &lt;/changeMoveSelector&gt;</programlisting>

      <para>The following <literal>selectionOrder</literal>s are supported:</para>

      <itemizedlist>
        <listitem>
          <para><literal>ORIGINAL</literal>: Select the selections (<literal>Move</literal>s, entities, values, ...) in
          default order. Each selection will be selected only once.</para>

          <itemizedlist>
            <listitem>
              <para>For example: A0, A1, A2, A3, ..., B0, B1, B2, B3, ..., C0, C1, C2, C3, ...</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>SORTED: Select the selections (<literal>Move</literal>s, entities, values, ...) in sorted order. Each
          selection will be selected only once. Requires <literal>cacheType &gt;= STEP</literal>. Mostly used on an
          <literal>entitySelector</literal> or <literal>valueSelector</literal> for construction heuristics. See <link
          linkend="sortedSelection">sorted selection</link>.</para>

          <itemizedlist>
            <listitem>
              <para>For example: A0, B0, C0, ..., A2, B2, C2, ..., A1, B1, C1, ...</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>RANDOM (default): Select the selections (<literal>Move</literal>s, entities, values, ...) in
          non-shuffled random order. A selection might be selected multiple times. This scales up well in performance
          because it does not require caching.</para>

          <itemizedlist>
            <listitem>
              <para>For example: C2, A3, B1, C2, A0, C0, ...</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>SHUFFLED: Select the selections (<literal>Move</literal>s, entities, values, ...) in shuffled random
          order. Each selection will be selected only once. Requires <literal>cacheType &gt;= STEP</literal>. This
          scales up badly in performance, not just because it requires caching, but also because a random number is
          generated for each element, even if it's not selected (which is the grand majority when scaling up).</para>

          <itemizedlist>
            <listitem>
              <para>For example: C2, A3, B1, A0, C0, ...</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>PROBABILISTIC: Select the selections (<literal>Move</literal>s, entities, values, ...) in random order,
          based on the selection probability of each element. A selection with a higher probability has a higher chance
          to be selected than elements with a lower probability. A selection might be selected multiple times. Requires
          <literal>cacheType &gt;= STEP</literal>. Mostly used on an <literal>entitySelector</literal> or
          <literal>valueSelector</literal>. See <link linkend="probabilisticSelection">probabilistic
          selection</link>.</para>

          <itemizedlist>
            <listitem>
              <para>For example: B1, B1, A1, B2, B1, C2, B1, B1, ...</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>A <literal>selectionOrder</literal> can be set on composite selectors too.</para>

      <note>
        <para>When a <literal>Selector</literal> is cached, all of its nested <literal>Selector</literal>s will
        naturally default to <literal>selectionOrder</literal> <literal>ORIGINAL</literal>. Avoid overwriting the
        <literal>selectionOrder</literal> of those nested <literal>Selector</literal>s.</para>
      </note>
    </section>

    <section xml:id="recommendedCombinationsOfCacheTypeAndSelectionOrder">
      <title>Recommended combinations of <literal>CacheType</literal> and <literal>SelectionOrder</literal></title>

      <section xml:id="justInTimeRandomSelection">
        <title>Just in time random selection (default)</title>

        <para>This combination is great for big use cases (10 000 entities or more), as it scales up well in memory
        footprint and performance. Other combinations are often not even viable on such sizes. It works for smaller use
        cases too, so it's a good way to start out. It's the default, so this explicit configuration of
        <literal>cacheType</literal> and <literal>selectionOrder</literal> is actually obsolete:</para>

        <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;cacheType&gt;JUST_IN_TIME&lt;/cacheType&gt;
      &lt;selectionOrder&gt;RANDOM&lt;/selectionOrder&gt;

      &lt;changeMoveSelector/&gt;
      &lt;swapMoveSelector/&gt;
    &lt;/unionMoveSelector&gt;</programlisting>

        <para>Here's how it works. When <literal>Iterator&lt;Move&gt;.next()</literal> is called, a child
        <literal>MoveSelector</literal> is randomly selected (1), which creates a random <literal>Move</literal> is
        created (2, 3, 4) and is then returned (5):</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/jitRandomSelection.png"/>
          </imageobject>
        </mediaobject>

        <para>Notice that <emphasis role="bold">it never creates a list of <literal>Move</literal>s</emphasis> and it
        generates random numbers only for <literal>Move</literal>s that are actually selected.</para>
      </section>

      <section xml:id="cachedShuffledSelection">
        <title>Cached shuffled selection</title>

        <para>This combination often wins for small and medium use cases (5000 entities or less). Beyond that size, it
        scales up badly in memory footprint and performance.</para>

        <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SHUFFLED&lt;/selectionOrder&gt;

      &lt;changeMoveSelector/&gt;
      &lt;swapMoveSelector/&gt;
    &lt;/unionMoveSelector&gt;</programlisting>

        <para>Here's how it works: At the start of the phase (or step depending on the <literal>cacheType</literal>),
        all moves are created (1) and cached (2). When <literal>MoveSelector.iterator()</literal> is called, the moves
        are shuffled (3). When <literal>Iterator&lt;Move&gt;.next()</literal> is called, the next element in the
        shuffled list is returned (4):</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/cachedShuffledSelection.png"/>
          </imageobject>
        </mediaobject>

        <para>Notice that <emphasis role="bold">each <literal>Move</literal> will only be selected once</emphasis>, even
        though they are selected in random order.</para>

        <para>Use cacheType PHASE if none of the (possibly nested) Selectors require <literal>STEP</literal>. Otherwise,
        do something like this:</para>

        <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;cacheType&gt;STEP&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SHUFFLED&lt;/selectionOrder&gt;

      &lt;changeMoveSelector&gt;
        &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;/changeMoveSelector&gt;
      &lt;swapMoveSelector/&gt;
        &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;/swapMoveSelector&gt;
      &lt;pillarSwapMoveSelector/&gt;&lt;!-- Does not support cacheType PHASE --&gt;
    &lt;/unionMoveSelector&gt;</programlisting>
      </section>

      <section xml:id="cachedRandomSelection">
        <title>Cached random selection</title>

        <para>This combination is often a worthy competitor for medium use cases, especially with fast stepping
        optimization algorithms (such as simulated annealing). Unlike cached shuffled selection, it doesn't waste time
        shuffling the move list at the beginning of every step.</para>

        <programlisting language="xml">    &lt;unionMoveSelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;RANDOM&lt;/selectionOrder&gt;

      &lt;changeMoveSelector/&gt;
      &lt;swapMoveSelector/&gt;
    &lt;/unionMoveSelector&gt;</programlisting>
      </section>
    </section>

    <section xml:id="filteredSelection">
      <title>Filtered selection</title>

      <para>There can be certain moves that you don't want to select, because:</para>

      <itemizedlist>
        <listitem>
          <para>The move is pointless and would only waste CPU time. For example, swapping 2 lectures of the same course
          will result in the same score and the same schedule because all lectures of 1 course are interchangeable (same
          teacher, same students, same topic).</para>
        </listitem>

        <listitem>
          <para>Doing the move would break <link linkend="buildInHardConstraint">a build-in hard constraint</link>, so
          the solution would be infeasible but the score function doesn't check build-in hard constraints (for
          performance gain). For example, don't change a gym lecture to a room which is not a gym room.</para>

          <itemizedlist>
            <listitem>
              <para>Note that any build-in hard constraint must usually be filtered on every move type. For example,
              also don't swap the room of a gym lecture with another lecture if the other lecture's original room isn't
              a gym room.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>Filtered selection can happen on any Selector in the selector tree, including any
      <literal>MoveSelector</literal>, <literal>EntitySelector</literal> or <literal>ValueSelector</literal>. It works
      with any <literal>cacheType</literal> and <literal>selectionOrder</literal>.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/filteredSelection.png"/>
        </imageobject>
      </mediaobject>

      <para>Filtering uses the interface <literal>SelectionFilter</literal>:</para>

      <programlisting language="java">public interface SelectionFilter&lt;T&gt; {

    boolean accept(ScoreDirector scoreDirector, T selection);

}</programlisting>

      <para>Implement the method <literal>accept</literal> to return <literal>false</literal> on a discarded
      <literal>selection</literal>. Unaccepted moves will not be selected and will therefore never have their method
      <literal>doMove</literal> called.</para>

      <programlisting language="java">public class DifferentCourseSwapMoveFilter implements SelectionFilter&lt;SwapMove&gt; {

    public boolean accept(ScoreDirector scoreDirector, SwapMove move) {
        Lecture leftLecture = (Lecture) move.getLeftEntity();
        Lecture rightLecture = (Lecture) move.getRightEntity();
        return !leftLecture.getCourse().equals(rightLecture.getCourse());
    }

}</programlisting>

      <para>Apply the filter on the lowest level possible. In most cases, you 'll need to know both the entity and the
      value involved and you'll have to apply a <literal>filterClass</literal> on the
      <literal>moveSelector</literal>:</para>

      <programlisting language="xml">    &lt;swapMoveSelector&gt;
      &lt;filterClass&gt;org.optaplanner.examples.curriculumcourse.solver.move.DifferentCourseSwapMoveFilter&lt;/filterClass&gt;
    &lt;/swapMoveSelector&gt;</programlisting>

      <para>But if possible, apply it on a lower levels, such as a <literal>filterClass</literal> on the
      <literal>entitySelector</literal> or <literal>valueSelector</literal>:</para>

      <programlisting language="xml">    &lt;changeMoveSelector&gt;
      &lt;entitySelector&gt;
        &lt;filterClass&gt;...EntityFilter&lt;/filterClass&gt;
      &lt;/entitySelector&gt;
    &lt;/changeMoveSelector&gt;</programlisting>

      <para>You can configure multiple <literal>filterClass</literal> elements on a single selector.</para>
    </section>

    <section xml:id="sortedSelection">
      <title>Sorted selection</title>

      <para>Sorted selection can happen on any Selector in the selector tree, including any
      <literal>MoveSelector</literal>, <literal>EntitySelector</literal> or <literal>ValueSelector</literal>. It does
      not work with <literal>cacheType</literal> <literal>JUST_IN_TIME</literal> and <literal>it only works with
      selectionOrder</literal> <literal>SORTED</literal>.</para>

      <para>It's mostly used in construction heuristics.</para>

      <note>
        <para>If the choosen construction heuristic implies sorting, for example <literal>FIRST_FIT_DECREASING</literal>
        implies that the <literal>EntitySelector</literal> is sorted, there is no need to explicitly configure a
        <literal>Selector</literal> with sorting. If you do explicitely configure the <literal>Selector</literal>, it
        overwrites the default settings of that construction heuristic.</para>
      </note>

      <section xml:id="sortedSelectionBySorterManner">
        <title>Sorted selection by <literal>SorterManner</literal></title>

        <para>Some <literal>Selector</literal> types implement a <literal>SorterManner</literal> out of the box:</para>

        <itemizedlist>
          <listitem>
            <para><literal>EntitySelector</literal> supports:</para>

            <itemizedlist>
              <listitem>
                <para><literal>DECREASING_DIFFICULTY</literal>: Sorts the planning entities according to decreasing
                <link linkend="planningEntityDifficulty">planning entity difficulty</link>. Requires that planning
                entity difficulty is annotated on the domain model.</para>

                <programlisting language="xml">    &lt;entitySelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SORTED&lt;/selectionOrder&gt;
      &lt;sorterManner&gt;DECREASING_DIFFICULTY&lt;/sorterManner&gt;
    &lt;/entitySelector&gt;</programlisting>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><literal>ValueSelector</literal> supports:</para>

            <itemizedlist>
              <listitem>
                <para><literal>INCREASING_STRENGTH</literal>: Sorts the planning values according to increasing <link
                linkend="planningValueStrength">planning value strength</link>. Requires that planning value strength is
                annotated on the domain model.</para>

                <programlisting language="xml">    &lt;valueSelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SORTED&lt;/selectionOrder&gt;
      &lt;sorterManner&gt;INCREASING_STRENGTH&lt;/sorterManner&gt;
    &lt;/valueSelector&gt;</programlisting>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </section>

      <section xml:id="sortedSelectionByComparator">
        <title>Sorted selection by <literal>Comparator</literal></title>

        <para>An easy way to sort a <literal>Selector</literal> is with a plain old
        <literal>Comparator</literal>:</para>

        <programlisting language="java">public class CloudProcessDifficultyComparator implements Comparator&lt;CloudProcess&gt; {

    public int compare(CloudProcess a, CloudProcess b) {
        return new CompareToBuilder()
                .append(a.getRequiredMultiplicand(), b.getRequiredMultiplicand())
                .append(a.getId(), b.getId())
                .toComparison();
    }

}</programlisting>

        <para>You 'll also need to configure it (unless it's annotated on the domain model and automatically applied by
        the optimization algorithm):</para>

        <programlisting language="xml">    &lt;entitySelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SORTED&lt;/selectionOrder&gt;
      &lt;sorterComparatorClass&gt;...CloudProcessDifficultyComparator&lt;/sorterComparatorClass&gt;
      &lt;sorterOrder&gt;DESCENDING&lt;/sorterOrder&gt;
    &lt;/entitySelector&gt;</programlisting>
      </section>

      <section xml:id="sortedSelectionBySelectionSorterWeightFactory">
        <title>Sorted selection by <literal>SelectionSorterWeightFactory</literal></title>

        <para>If you need the entire <literal>Solution</literal> to sort a <literal>Selector</literal>, use a
        <literal>SelectionSorterWeightFactory</literal> instead:</para>

        <programlisting language="java">public interface SelectionSorterWeightFactory&lt;Sol extends Solution, T&gt; {

    Comparable createSorterWeight(Sol solution, T selection);

}</programlisting>

        <programlisting language="java">public class QueenDifficultyWeightFactory implements SelectionSorterWeightFactory&lt;NQueens, Queen&gt; {

    public Comparable createSorterWeight(NQueens nQueens, Queen queen) {
        int distanceFromMiddle = calculateDistanceFromMiddle(nQueens.getN(), queen.getColumnIndex());
        return new QueenDifficultyWeight(queen, distanceFromMiddle);
    }

    // ...

    public static class QueenDifficultyWeight implements Comparable&lt;QueenDifficultyWeight&gt; {

        private final Queen queen;
        private final int distanceFromMiddle;

        public QueenDifficultyWeight(Queen queen, int distanceFromMiddle) {
            this.queen = queen;
            this.distanceFromMiddle = distanceFromMiddle;
        }

        public int compareTo(QueenDifficultyWeight other) {
            return new CompareToBuilder()
                    // The more difficult queens have a lower distance to the middle
                    .append(other.distanceFromMiddle, distanceFromMiddle) // Decreasing
                    // Tie breaker
                    .append(queen.getColumnIndex(), other.queen.getColumnIndex())
                    .toComparison();
        }

    }

}</programlisting>

        <para>You 'll also need to configure it (unless it's annotated on the domain model and automatically applied by
        the optimization algorithm):</para>

        <programlisting language="xml">    &lt;entitySelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SORTED&lt;/selectionOrder&gt;
      &lt;sorterWeightFactoryClass&gt;...QueenDifficultyWeightFactory&lt;/sorterWeightFactoryClass&gt;
      &lt;sorterOrder&gt;DESCENDING&lt;/sorterOrder&gt;
    &lt;/entitySelector&gt;</programlisting>
      </section>

      <section xml:id="sortedSelectionBySelectionSorter">
        <title>Sorted selection by <literal>SelectionSorter</literal></title>

        <para>Alternatively, you can also use the interface <literal>SelectionSorter</literal> directly:</para>

        <programlisting language="java">public interface SelectionSorter&lt;T&gt; {

    void sort(ScoreDirector scoreDirector, List&lt;T&gt; selectionList);

}</programlisting>

        <programlisting language="xml">    &lt;entitySelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;SORTED&lt;/selectionOrder&gt;
      &lt;sorterClass&gt;...MyEntitySorter&lt;/sorterClass&gt;
    &lt;/entitySelector&gt;</programlisting>
      </section>
    </section>

    <section xml:id="probabilisticSelection">
      <title>Probabilistic selection</title>

      <para>Probabilistic selection can happen on any Selector in the selector tree, including any
      <literal>MoveSelector</literal>, <literal>EntitySelector</literal> or <literal>ValueSelector</literal>. It does
      not work with <literal>cacheType</literal> <literal>JUST_IN_TIME</literal> and <literal>it only works with
      selectionOrder</literal> <literal>PROBABILISTIC</literal>.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Move_and_neighborhood_selection/probabilisticSelection.png"/>
        </imageobject>
      </mediaobject>

      <para>Each selection has a <literal>probabilityWeight</literal>, which determines the chance that's that selection
      will be selected:</para>

      <programlisting language="java">public interface SelectionProbabilityWeightFactory&lt;T&gt; {

    double createProbabilityWeight(ScoreDirector scoreDirector, T selection);

}</programlisting>

      <programlisting language="xml">    &lt;entitySelector&gt;
      &lt;cacheType&gt;PHASE&lt;/cacheType&gt;
      &lt;selectionOrder&gt;PROBABILISTIC&lt;/selectionOrder&gt;
      &lt;probabilityWeightFactoryClass&gt;...MyEntityProbabilityWeightFactoryClass&lt;/probabilityWeightFactoryClass&gt;
    &lt;/entitySelector&gt;</programlisting>

      <para>For example, if there are 3 entities: process A (probabilityWeight 2.0), process B (probabilityWeight 0.5)
      and process C (probabilityWeight 0.5), then process A will be selected 4 times more than B and C.</para>
    </section>

    <section xml:id="mimicSelection">
      <title>Mimic selection (record/replay)</title>

      <para>During mimic selection, 1 normal selector records its selection and 1 or multiple other special selectors
      replay that selection. The recording selector acts as a normal selector and supports all other configuration
      properties. A replaying selector mimics the recording selection and support no other configuration
      properties.</para>

      <para>The recording selector needs an <literal>id</literal>. A replaying selector must reference a recorder's id
      with a <literal>mimicSelectorRef</literal>:</para>

      <programlisting language="xml">      &lt;cartesianProductMoveSelector&gt;
        &lt;changeMoveSelector&gt;
          &lt;entitySelector id="entitySelector"/&gt;
          &lt;valueSelector&gt;
            &lt;variableName&gt;period&lt;/variableName&gt;
          &lt;/valueSelector&gt;
        &lt;/changeMoveSelector&gt;
        &lt;changeMoveSelector&gt;
          &lt;entitySelector mimicSelectorRef="entitySelector"/&gt;
          &lt;valueSelector&gt;
            &lt;variableName&gt;room&lt;/variableName&gt;
          &lt;/valueSelector&gt;
        &lt;/changeMoveSelector&gt;
      &lt;/cartesianProductMoveSelector&gt;</programlisting>

      <para>Mimic selection is usefull to create a composite move from 2 moves that affect the same entity.</para>
    </section>

    <section xml:id="limitedSelection">
      <title>Limited selection</title>

      <para>Selecting all possible moves sometimes does not scale well enough, especially for construction heuristics
      (which don't support <link linkend="acceptedCountLimit">acceptedCountLimit</link>).</para>

      <para>To limit the number of selected moves per step, apply a <literal>selectedCountLimit</literal> on the
      selector:</para>

      <programlisting language="xml">    &lt;changeMoveSelector&gt;
      &lt;selectedCountLimit&gt;100&lt;/selectedCountLimit&gt;
    &lt;/changeMoveSelector&gt;</programlisting>

      <note>
        <para>To scale Local Search, setting <link linkend="acceptedCountLimit">acceptedCountLimit</link> is usually
        better than using <literal>selectedCountLimit</literal>.</para>
      </note>
    </section>
  </section>

  <section xml:id="customMoves">
    <title>Custom moves</title>

    <section>
      <title>Which move types might be missing in my implementation?</title>

      <para>To determine which move types might be missing in your implementation, run a <link
      linkend="benchmarkingAndTweaking">Benchmarker</link> <emphasis>for a short amount of time</emphasis> and <link
      linkend="writingTheOutputSolutionOfTheBenchmarkRuns">configure it to write the best solutions to disk</link>. Take
      a look at such a best solution: it will likely be a local optima. Try to figure out if there's a move that could
      get out of that local optima faster.</para>

      <para>If you find one, implement that course-grained move, mix it with the existing moves and benchmark it against
      the previous configurations to see if you want to keep it.</para>
    </section>

    <section>
      <title>Custom moves introduction</title>

      <para>Instead of reusing the generic <literal>Move</literal>s (such as <literal>ChangeMove</literal>) you can also
      implement your own <literal>Move</literal>s. Generic and custom <literal>MoveSelector</literal>s can be combined
      as desired.</para>

      <para>A custom <literal>Move</literal> can be tailored to work to the advantage of your constraints. For example,
      in examination scheduling, changing the period of an exam A also changes te period of all the exams that need to
      coincide with exam A.</para>

      <para>A custom <literal>Move</literal> is also slightly faster than a generic <literal>Move</literal>. However,
      it's far more work to implement and much harder to avoid bugs. After implementing a custom
      <literal>Move</literal>, make sure to turn on <literal>environmentMode</literal> <literal>FULL_ASSERT</literal> to
      check for score corruptions.</para>
    </section>

    <section xml:id="theInterfaceMove">
      <title>The interface <literal>Move</literal></title>

      <para>Your custom moves must implement the <literal>Move</literal> interface:</para>

      <programlisting language="java">public interface Move {

    boolean isMoveDoable(ScoreDirector scoreDirector);

    Move createUndoMove(ScoreDirector scoreDirector);
    void doMove(ScoreDirector scoreDirector);

    Collection&lt;? extends Object&gt; getPlanningEntities();
    Collection&lt;? extends Object&gt; getPlanningValues();

}</programlisting>

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

      <programlisting language="java">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

}</programlisting>

      <para>An instance of <literal>RowChangeMove</literal> moves a queen from its current row to a different
      row.</para>

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

      <programlisting language="java">    public void doMove(ScoreDirector scoreDirector) {
        scoreDirector.beforeVariableChanged(queen, "row"); // before changes are made to the queen.row
        queen.setRow(toRow);
        scoreDirector.afterVariableChanged(queen, "row"); // after changes are made to the queen.row
    }</programlisting>

      <para>You need to call the methods <literal>scoreDirector.beforeVariableChanged(Object, String)</literal> and
      <literal>scoreDirector.afterVariableChanged(Object, String)</literal> directly before and after modifying the
      entity.</para>

      <note>
        <para>You can alter multiple entities in a single move and effectively create a big move (also known as a
        coarse-grained move).</para>
      </note>

      <warning>
        <para>A <literal>Move</literal> can only change/add/remove planning entities, it must not change any of the
        problem facts.</para>
      </warning>

      <para>Planner automatically filters out <emphasis>non doable moves</emphasis> by calling the
      <literal>isMoveDoable(ScoreDirector)</literal> method on a move. A <emphasis>non doable move</emphasis> is:</para>

      <itemizedlist>
        <listitem>
          <para>A move that changes nothing on the current solution. For example, moving queen B0 to row 0 is not
          doable, because it is already there.</para>
        </listitem>

        <listitem>
          <para>A move that is impossible to do on the current solution. For example, moving queen B0 to row 10 is not
          doable because it would move it outside the board limits.</para>
        </listitem>
      </itemizedlist>

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

      <programlisting language="java">    public boolean isMoveDoable(ScoreDirector scoreDirector) {
        return !ObjectUtils.equals(queen.getRow(), toRow);
    }</programlisting>

      <para>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 <literal>Solution</literal> of a later
      step.</para>

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

      <programlisting language="java">    public Move createUndoMove(ScoreDirector scoreDirector) {
        return new RowChangeMove(queen, queen.getRow());
    }</programlisting>

      <para>Notice that if C0 would have already been moved to C2, the undo move would create the move <emphasis>C2 to
      C2</emphasis>, instead of the move <emphasis>C2 to C0</emphasis>.</para>

      <para>A solver phase might do and undo the same <literal>Move</literal> more than once. In fact, many solver
      phases will iteratively do an undo a number of moves to evaluate them, before selecting one of those and doing
      that move again (without undoing it this time).</para>

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

      <programlisting language="java">    public List&lt;? extends Object&gt; getPlanningEntities() {
        return Collections.singletonList(queen);
    }

    public Collection&lt;? extends Object&gt; getPlanningValues() {
        return Collections.singletonList(toRow);
    }</programlisting>

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

      <programlisting language="java">    public Collection&lt;? extends Object&gt; getPlanningEntities() {
        return Arrays.asList(leftCloudProcess, rightCloudProcess);
    }

    public Collection&lt;? extends Object&gt; getPlanningValues() {
        return Arrays.asList(leftCloudProcess.getComputer(), rightCloudProcess.getComputer());
    }</programlisting>

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

      <programlisting language="java">    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();
    }</programlisting>

      <para>Notice that it checks if the other move is an instance of the same move type. This
      <literal>instanceof</literal> 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.</para>

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

      <programlisting language="java">    public String toString() {
        return queen + " =&gt; " + toRow;
    }</programlisting>

      <para>Now that we can implement a single custom <literal>Move</literal>, let's take a look at generating such
      custom moves.</para>
    </section>

    <section xml:id="moveListFactory">
      <title><literal>MoveListFactory</literal>: the easy way to generate custom moves</title>

      <para>The easiest way to generate custom moves is by implementing the interface
      <literal>MoveListFactory</literal>:</para>

      <programlisting language="java">public interface MoveListFactory&lt;S extends Solution&gt; {

    List&lt;Move&gt; createMoveList(S solution);

}</programlisting>

      <para>For example:</para>

      <programlisting language="java">public class RowChangeMoveFactory implements MoveListFactory&lt;NQueens&gt; {

    public List&lt;Move&gt; createMoveList(NQueens nQueens) {
        List&lt;Move&gt; moveList = new ArrayList&lt;Move&gt;();
        for (Queen queen : nQueens.getQueenList()) {
            for (Row toRow : nQueens.getRowList()) {
                moveList.add(new RowChangeMove(queen, toRow));
            }
        }
        return moveList;
    }

}</programlisting>

      <para>Simple configuration (which can be nested in a <literal>unionMoveSelector</literal> just like any other
      <literal>MoveSelector</literal>):</para>

      <programlisting language="xml">    &lt;moveListFactory&gt;
      &lt;moveListFactoryClass&gt;org.optaplanner.examples.nqueens.solver.move.factory.RowChangeMoveFactory&lt;/moveListFactoryClass&gt;
    &lt;/moveListFactory&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;moveListFactory&gt;
      ... &lt;!-- Normal moveSelector properties --&gt;
      &lt;moveListFactoryClass&gt;org.optaplanner.examples.nqueens.solver.move.factory.RowChangeMoveFactory&lt;/moveListFactoryClass&gt;
    &lt;/moveListFactory&gt;</programlisting>

      <para>Because the <literal>MoveListFactory</literal> generates all moves at once in a List&lt;Move&gt;, it does
      not support <literal>cacheType</literal> <literal>JUST_IN_TIME</literal>. Therefore,
      <literal>moveListFactory</literal> uses <literal>cacheType</literal> <literal>STEP</literal> by default and it
      scales badly in memory footprint.</para>
    </section>

    <section xml:id="moveIteratorFactory">
      <title><literal>MoveIteratorFactory</literal>: generate custom moves just in time</title>

      <para>Use this advanced form to generate custom moves by implementing the interface
      <literal>MoveIteratorFactory</literal>:</para>

      <programlisting language="java">public interface MoveIteratorFactory {

    long getSize(ScoreDirector scoreDirector);

    Iterator&lt;Move&gt; createOriginalMoveIterator(ScoreDirector scoreDirector);

    Iterator&lt;Move&gt; createRandomMoveIterator(ScoreDirector scoreDirector, Random workingRandom);

}</programlisting>

      <para>The method <literal>getSize()</literal> must give an estimation of the size. It doesn't need to be correct.
      The method <literal>createOriginalMoveIterator</literal> is called if the <literal>selectionOrder is</literal>
      <literal>ORIGINAL</literal> or if it is cached. The method <literal>createRandomMoveIterator</literal> is called
      for <literal>selectionOrder</literal> <literal>RANDOM</literal> combined with cacheType
      <literal>JUST_IN_TIME</literal>.</para>

      <important>
        <para>Don't create a collection (list, array, map, set) of <literal>Move</literal>s when creating the
        <literal>Iterator&lt;Move&gt;</literal>: the whole purpose of <literal>MoveIteratorFactory</literal> over
        <literal>MoveListFactory</literal> is giving you the ability to create a <literal>Move</literal> just in time in
        the <literal>Iterator</literal>'s method <literal>next()</literal>.</para>
      </important>

      <para>Simple configuration (which can be nested in a <literal>unionMoveSelector</literal> just like any other
      <literal>MoveSelector</literal>):</para>

      <programlisting language="xml">    &lt;moveIteratorFactory&gt;
      &lt;moveIteratorFactoryClass&gt;...&lt;/moveIteratorFactoryClass&gt;
    &lt;/moveIteratorFactory&gt;</programlisting>

      <para>Advanced configuration:</para>

      <programlisting language="xml">    &lt;moveIteratorFactory&gt;
      ... &lt;!-- Normal moveSelector properties --&gt;
      &lt;moveIteratorFactoryClass&gt;...&lt;/moveIteratorFactoryClass&gt;
    &lt;/moveIteratorFactory&gt;</programlisting>
    </section>
  </section>
</chapter>