Chapter-Planner_configuration.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="plannerConfiguration" 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>Planner Configuration</title>

  <section xml:id="plannerConfigurationOverview">
    <title>Overview</title>

    <para>Solving a planning problem with Planner consists out of 5 steps:</para>

    <orderedlist>
      <listitem>
        <para><emphasis role="bold">Model your planning problem</emphasis> as a class that implements the interface
        <literal>Solution</literal>, for example the class <literal>NQueens</literal>.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Configure a <literal>Solver</literal></emphasis>, for example a First Fit and Tabu
        Search solver for any <literal>NQueens</literal> instance.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Load a problem data set</emphasis> from your data layer, for example a 4 Queens
        instance. That is the planning problem.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Solve it</emphasis> with <literal>Solver.solve(planningProblem)</literal> which
        returns the best solution found.</para>
      </listitem>
    </orderedlist>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/Chapter-Planner_configuration/inputOutputOverview.png"/>
      </imageobject>
    </mediaobject>
  </section>

  <section xml:id="solverConfiguration">
    <title>Solver Configuration</title>

    <section xml:id="solverConfigurationByXML">
      <title>Solver Configuration by XML</title>

      <para>Build a <literal>Solver</literal> instance with the <literal>SolverFactory</literal>. Configure the
      <literal>SolverFactory</literal> with a solver configuration XML file, provided as a classpath resource (as
      definied by <literal>ClassLoader.getResource()</literal>):</para>

      <programlisting language="java">       SolverFactory&lt;NQueens&gt; solverFactory = SolverFactory.createFromXmlResource(
               "org/optaplanner/examples/nqueens/solver/nqueensSolverConfig.xml");
       Solver&lt;NQueens&gt; solver = solverFactory.buildSolver();</programlisting>

      <para>In a typical project (following the Maven directory structure), that solverConfig XML file would be located
      at
      <literal>$PROJECT_DIR/src/main/resources/org/optaplanner/examples/nqueens/solver/nqueensSolverConfig.xml</literal>.
      Alternatively, a <literal>SolverFactory</literal> can be created from a <literal>File</literal>, an
      <literal>InputStream</literal> or a <literal>Reader</literal> with methods such as
      <literal>SolverFactory.createFromXmlFile()</literal>. However, for portability reasons, a classpath resource is
      recommended.</para>

      <note>
        <para>On some environments (<link linkend="integrationWithOSGi">OSGi</link>, <link
        linkend="integrationWithJBossModules">JBoss modules</link>, ...), classpath resources (such as the solver
        config, score DRL's and domain classes) in your jars might not be available to the default
        <literal>ClassLoader</literal> of the <literal>optaplanner-core</literal> jar. In those cases, provide the
        <literal>ClassLoader</literal> of your classes as a parameter:</para>

        <programlisting language="java">       SolverFactory&lt;NQueens&gt; solverFactory = SolverFactory.createFromXmlResource(
               ".../nqueensSolverConfig.xml", getClass().getClassLoader());</programlisting>
      </note>

      <note>
        <para>When using Workbench or Execution Server or to take advantage of Drools's <literal>KieContainer</literal>
        features, provide the <literal>KieContainer</literal> as a parameter:</para>

        <programlisting language="java">       KieServices kieServices = KieServices.Factory.get();
       KieContainer kieContainer = kieServices.newKieContainer(
               kieServices.newReleaseId("org.nqueens", "nqueens", "1.0.0"));
       SolverFactory&lt;NQueens&gt; solverFactory = SolverFactory.createFromKieContainerXmlResource(
               kieContainer, ".../nqueensSolverConfig.xml");</programlisting>

        <para>And use <link linkend="droolsScoreCalculationKsessionName">a ksessionName in the solver
        configuration</link>.</para>
      </note>

      <para>Both a <literal>Solver</literal> and a <literal>SolverFactory</literal> have a generic type called
      <literal>Solution_</literal>, which is the class representing a <link
      linkend="planningProblemAndPlanningSolution">planning problem and solution</link>.</para>

      <para>A solver configuration XML file looks like this:</para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;solver&gt;
  &lt;!-- Define the model --&gt;
  &lt;solutionClass&gt;org.optaplanner.examples.nqueens.domain.NQueens&lt;/solutionClass&gt;
  &lt;entityClass&gt;org.optaplanner.examples.nqueens.domain.Queen&lt;/entityClass&gt;

  &lt;!-- Define the score function --&gt;
  &lt;scoreDirectorFactory&gt;
    &lt;scoreDefinitionType&gt;SIMPLE&lt;/scoreDefinitionType&gt;
    &lt;scoreDrl&gt;org/optaplanner/examples/nqueens/solver/nQueensScoreRules.drl&lt;/scoreDrl&gt;
  &lt;/scoreDirectorFactory&gt;

  &lt;!-- Configure the optimization algorithms (optional) --&gt;
  &lt;termination&gt;
    ...
  &lt;/termination&gt;
  &lt;constructionHeuristic&gt;
    ...
  &lt;/constructionHeuristic&gt;
  &lt;localSearch&gt;
    ...
  &lt;/localSearch&gt;
&lt;/solver&gt;</programlisting>

      <para>Notice the three parts in it:</para>

      <itemizedlist>
        <listitem>
          <para>Define the model.</para>
        </listitem>

        <listitem>
          <para>Define the score function.</para>
        </listitem>

        <listitem>
          <para>Optionally configure the optimization algorithm(s).</para>
        </listitem>
      </itemizedlist>

      <para>These various parts of a configuration are explained further in this manual.</para>

      <para><emphasis role="bold">Planner makes it relatively easy to switch optimization algorithm(s) just by changing
      the configuration.</emphasis> There is even a <link linkend="benchmarker">Benchmarker</link> which allows you to
      play out different configurations against each other and report the most appropriate configuration for your use
      case.</para>
    </section>

    <section xml:id="solverConfigurationByJavaAPI">
      <title>Solver Configuration by Java API</title>

      <para>A solver configuration can also be configured with the <literal>SolverConfig</literal> API. This is
      especially useful to change some values dynamically at runtime. For example, to change the running time based on
      user input, before building the <literal>Solver</literal>:</para>

      <programlisting language="java">        SolverFactory&lt;NQueens&gt; solverFactory = SolverFactory.createFromXmlResource(
                "org/optaplanner/examples/nqueens/solver/nqueensSolverConfig.xml");

        TerminationConfig terminationConfig = new TerminationConfig();
        terminationConfig.setMinutesSpentLimit(userInput);
        solverFactory.getSolverConfig().setTerminationConfig(terminationConfig);

        Solver&lt;NQueens&gt; solver = solverFactory.buildSolver();</programlisting>

      <para>Every element in the solver configuration XML is available as a <literal>*Config</literal> class or a
      property on a <literal>*Config</literal> class in the package namespace
      <literal>org.optaplanner.core.config</literal>. These <literal>*Config</literal> classes are the Java
      representation of the XML format. They build the runtime components (of the package namespace
      <literal>org.optaplanner.core.impl</literal>) and assemble them into an efficient
      <literal>Solver</literal>.</para>

      <important>
        <para>The <literal>SolverFactory</literal> is only multi-thread safe after its configured. So the
        <literal>getSolverConfig()</literal> method is not thread-safe. To configure a <literal>SolverFactory</literal>
        dynamically for each user request, build a <literal>SolverFactory</literal> as base during initialization and
        clone it with the <literal>cloneSolverFactory()</literal> method for a user request:</para>

        <programlisting language="java">    private SolverFactory&lt;NQueens&gt; base;

    public void init() {
        base = SolverFactory.createFromXmlResource(
                "org/optaplanner/examples/nqueens/solver/nqueensSolverConfig.xml");
        base.getSolverConfig().setTerminationConfig(new TerminationConfig());
    }

    // Called concurrently from different threads
    public void userRequest(..., long userInput)
        SolverFactory&lt;NQueens&gt; solverFactory = base.cloneSolverFactory();
        solverFactory.getSolverConfig().getTerminationConfig().setMinutesSpentLimit(userInput);
        Solver&lt;NQueens&gt; solver = solverFactory.buildSolver();
        ...
    }</programlisting>
      </important>
    </section>

    <section xml:id="annotationsConfiguration">
      <title>Annotations Configuration</title>

      <section xml:id="automaticScanningForAnnotations">
        <title>Automatic Scanning for Annotations</title>

        <para>Instead of the declaring the classes that have a <literal>@PlanningSolution</literal> or
        <literal>@PlanningEntity</literal> manually:</para>

        <programlisting language="xml">&lt;solver&gt;
  &lt;!-- Define the model --&gt;
  &lt;solutionClass&gt;org.optaplanner.examples.nqueens.domain.NQueens&lt;/solutionClass&gt;
  &lt;entityClass&gt;org.optaplanner.examples.nqueens.domain.Queen&lt;/entityClass&gt;

  ...
&lt;/solver&gt;</programlisting>

        <para>Planner can find scan the classpath and find them automatically:</para>

        <programlisting language="xml">&lt;solver&gt;
  &lt;!-- Define the model --&gt;
  &lt;scanAnnotatedClasses/&gt;

  ...
&lt;/solver&gt;</programlisting>

        <para>This comes at a bootstrap performance cost.</para>

        <para>If there are multiple models in your classpath or to speed up scanning, specify the packages to
        scan:</para>

        <programlisting language="xml">&lt;solver&gt;
  &lt;!-- Define the model --&gt;
  &lt;scanAnnotatedClasses&gt;
    &lt;packageInclude&gt;org.optaplanner.examples.cloudbalancing&lt;/packageInclude&gt;
  &lt;/scanAnnotatedClasses&gt;

  ...
&lt;/solver&gt;</programlisting>

        <para>This finds all solution and entity classes in that package or its subpackages.</para>

        <note>
          <para>If <literal>scanAnnotatedClasses</literal> is not specified, the <literal>org.reflections</literal>
          transitive maven dependency can be excluded.</para>
        </note>
      </section>

      <section xml:id="annotationAlternatives">
        <title>Annotation Alternatives</title>

        <para>Planner needs to be told which classes in your domain model are planning entities, which properties are
        planning variables, etc. There are several ways to deliver this information:</para>

        <itemizedlist>
          <listitem>
            <para>Add class annotations and JavaBean property annotations on the domain model (recommended). The
            property annotations must be the getter method, not on the setter method. Such a getter does not need to be
            public.</para>
          </listitem>

          <listitem>
            <para>Add class annotations and field annotations on the domain model. Such a field does not need to be
            public.</para>
          </listitem>

          <listitem>
            <para>No annotations: externalize the domain configuration in an XML file. This is <link
            xlink:href="https://issues.jboss.org/browse/PLANNER-151">not yet supported</link>.</para>
          </listitem>
        </itemizedlist>

        <para>This manual focuses on the first manner, but every features supports all 3 manners, even if it's not
        explicitly mentioned.</para>
      </section>
    </section>
  </section>

  <section xml:id="modelAPlanningProblem">
    <title>Model a Planning Problem</title>

    <section xml:id="isThisClassAProblemFactOrPlanningEntity">
      <title>Is This Class a Problem Fact or Planning Entity?</title>

      <para>Look at a dataset of your planning problem. You will recognize domain classes in there, each of which can be
      categorized as one of the following:</para>

      <itemizedlist>
        <listitem>
          <para>A unrelated class: not used by any of the score constraints. From a planning standpoint, this data is
          obsolete.</para>
        </listitem>

        <listitem>
          <para>A <emphasis role="bold">problem fact</emphasis> class: used by the score constraints, but does NOT
          change during planning (as long as the problem stays the same). For example: <literal>Bed</literal>,
          <literal>Room</literal>, <literal>Shift</literal>, <literal>Employee</literal>, <literal>Topic</literal>,
          <literal>Period</literal>, ... All the properties of a problem fact class are problem properties.</para>
        </listitem>

        <listitem>
          <para>A <emphasis role="bold">planning entity</emphasis> class: used by the score constraints and changes
          during planning. For example: <literal>BedDesignation</literal>, <literal>ShiftAssignment</literal>,
          <literal>Exam</literal>, ... The properties that change during planning are planning variables. The other
          properties are problem properties.</para>
        </listitem>
      </itemizedlist>

      <para>Ask yourself: <emphasis>What class changes during planning?</emphasis> <emphasis>Which class has variables
      that I want the <literal>Solver</literal> to change for me?</emphasis> That class is a planning entity. Most use
      cases have only one planning entity class. Most use cases also have only one planning variable per planning entity
      class.</para>

      <note>
        <para>In <link linkend="realTimePlanning">real-time planning</link>, even though the problem itself changes,
        problem facts do not really change during planning, instead they change between planning (because the Solver
        temporarily stops to apply the problem fact changes).</para>
      </note>

      <para>A good model can greatly improve the success of your planning implementation. Follow these guidelines to
      design a good model:</para>

      <itemizedlist>
        <listitem>
          <para>In a <emphasis>many to one</emphasis> relationship, it is normally the <emphasis>many</emphasis> side
          that is the planning entity class. The property referencing the other side is then the planning variable. For
          example in employee rostering: the planning entity class is <literal>ShiftAssignment</literal>, not
          <literal>Employee</literal>, and the planning variable is <literal>ShiftAssignment.getEmployee()</literal>
          because one <literal>Employee</literal> has multiple <literal>ShiftAssignment</literal>s but one
          <literal>ShiftAssignment</literal> has only one <literal>Employee</literal>.</para>
        </listitem>

        <listitem>
          <para>A planning entity class should have at least one problem property. A planning entity class with only
          planning variables can normally be simplified by converting one of those planning variables into a problem
          property. That heavily decreases <link linkend="searchSpaceSize">the search space size</link>. For example in
          employee rostering: the <literal>ShiftAssignment</literal>'s <literal>getShift()</literal> is a problem
          property and the <literal>getEmployee()</literal> is a planning variable. If both were a planning variable,
          solving it would be far less efficient.</para>

          <itemizedlist>
            <listitem>
              <para>A surrogate ID does not suffice as the required minimum of one problem property. It needs to be
              understandable by the business. A business key does suffice. This prevents an unassigned entity from being
              nameless (unidentifiable by the business).</para>
            </listitem>

            <listitem>
              <para>This way, there is no need to add a hard constraint to assure that two planning entities are
              different: they are already different due to their problem properties.</para>
            </listitem>

            <listitem>
              <para>In some cases, multiple planning entities have the same problem property. In such cases, it can be
              useful to create an extra problem property to distinguish them. For example in employee rostering:
              <literal>ShiftAssignment</literal> has besides the problem property <literal>Shift</literal> also the
              problem property <literal>indexInShift</literal>.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>The number of planning entities is recommended to be fixed during planning. When unsure of which
          property should be a planning variable and which should be a problem property, choose it so the number of
          planning entities is fixed. For example in employee rostering: if the planning entity class would have been
          <literal>EmployeeAssignment</literal> with a problem property <literal>getEmployee()</literal> and a planning
          variable <literal>getShift()</literal>, than it is impossible to accurately predict how many
          <literal>EmployeeAssignment</literal> instances to make per <literal>Employee</literal>.</para>
        </listitem>
      </itemizedlist>

      <para>For inspiration, take a look at <link linkend="designPatterns">typical design patterns</link> or how the
      examples modeled their domain:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/Chapter-Planner_configuration/entityVariableAndValueExamples.png"/>
        </imageobject>
      </mediaobject>

      <note>
        <para>Vehicle routing is special, because it uses a <link linkend="chainedPlanningVariable">chained planning
        variable</link>.</para>
      </note>

      <para><emphasis role="bold">In Planner, all problems facts and planning entities are plain old JavaBeans
      (POJOs).</emphasis> Load them from a database, an XML file, a data repository, a REST service, a noSQL cloud, ...
      (see <link linkend="integration">integration</link>): it doesn't matter.</para>
    </section>

    <section xml:id="problemFact">
      <title>Problem Fact</title>

      <para>A problem fact is any JavaBean (POJO) with getters that does not change during planning. Implementing the
      interface <literal>Serializable</literal> is recommended (but not required). For example in n queens, the columns
      and rows are problem facts:</para>

      <programlisting language="java">public class Column implements Serializable {

    private int index;

    // ... getters
}</programlisting>

      <programlisting language="java">public class Row implements Serializable {

    private int index;

    // ... getters
}</programlisting>

      <para>A problem fact can reference other problem facts of course:</para>

      <programlisting language="java">public class Course implements Serializable {

    private String code;

    private Teacher teacher; // Other problem fact
    private int lectureSize;
    private int minWorkingDaySize;

    private List&lt;Curriculum&gt; curriculumList; // Other problem facts
    private int studentSize;

    // ... getters
}</programlisting>

      <para>A problem fact class does <emphasis>not</emphasis> require any Planner specific code. For example, you can
      reuse your domain classes, which might have JPA annotations.</para>

      <note>
        <para>Generally, better designed domain classes lead to simpler and more efficient score constraints. Therefore,
        when dealing with a messy (denormalized) legacy system, it can sometimes be worthwhile to convert the messy
        domain model into a Planner specific model first. For example: if your domain model has two
        <literal>Teacher</literal> instances for the same teacher that teaches at two different departments, it is
        harder to write a correct score constraint that constrains a teacher's spare time on the original model than on
        an adjusted model.</para>

        <para>Alternatively, you can sometimes also introduce <link linkend="cachedProblemFact"><emphasis>a cached
        problem fact</emphasis></link> to enrich the domain model for planning only.</para>
      </note>
    </section>

    <section xml:id="planningEntity">
      <title>Planning Entity</title>

      <section xml:id="planningEntityAnnotation">
        <title>Planning Entity Annotation</title>

        <para>A planning entity is a JavaBean (POJO) that changes during solving, for example a <literal>Queen</literal>
        that changes to another row. A planning problem has multiple planning entities, for example for a single n
        queens problem, each <literal>Queen</literal> is a planning entity. But there is usually only one planning
        entity class, for example the <literal>Queen</literal> class.</para>

        <para>A planning entity class needs to be annotated with the <literal>@PlanningEntity</literal>
        annotation.</para>

        <para>Each planning entity class has one or more <emphasis>planning variables</emphasis>. It should also have
        one or more <emphasis>defining</emphasis> properties. For example in n queens, a <literal>Queen</literal> is
        defined by its <literal>Column</literal> and has a planning variable <literal>Row</literal>. This means that a
        Queen's column never changes during solving, while its row does change.</para>

        <programlisting language="java">@PlanningEntity
public class Queen {

    private Column column;

    // Planning variables: changes during planning, between score calculations.
    private Row row;

    // ... getters and setters
}</programlisting>

        <para>A planning entity class can have multiple planning variables. For example, a <literal>Lecture</literal> is
        defined by its <literal>Course</literal> and its index in that course (because one course has multiple
        lectures). Each <literal>Lecture</literal> needs to be scheduled into a <literal>Period</literal> and a
        <literal>Room</literal> so it has two planning variables (period and room). For example: the course Mathematics
        has eight lectures per week, of which the first lecture is Monday morning at 08:00 in room 212.</para>

        <programlisting language="java">@PlanningEntity
public class Lecture {

    private Course course;
    private int lectureIndexInCourse;

    // Planning variables: changes during planning, between score calculations.
    private Period period;
    private Room room;

    // ...
}</programlisting>

        <para>Without <link linkend="automaticScanningForAnnotations">automated scanning</link>, the solver
        configuration also needs to declare each planning entity class:</para>

        <programlisting language="java">&lt;solver&gt;
  ...
  &lt;entityClass&gt;org.optaplanner.examples.nqueens.domain.Queen&lt;/entityClass&gt;
  ...
&lt;/solver&gt;</programlisting>

        <para>Some uses cases have multiple planning entity classes. For example: route freight and trains into railway
        network arcs, where each freight can use multiple trains over its journey and each train can carry multiple
        freights per arc. Having multiple planning entity classes directly raises the implementation complexity of your
        use case.</para>

        <note>
          <para><emphasis>Do not create unnecessary planning entity classes.</emphasis> This leads to difficult
          <literal>Move</literal> implementations and slower score calculation.</para>

          <para>For example, do not create a planning entity class to hold the total free time of a teacher, which needs
          to be kept up to date as the <literal>Lecture</literal> planning entities change. Instead, calculate the free
          time in the score constraints (or as a <link linkend="shadowVariable">shadow variable</link>) and put the
          result per teacher into a logically inserted score object.</para>

          <para>If historic data needs to be considered too, then create problem fact to hold the total of the historic
          assignments up to, but <emphasis>not including</emphasis>, the planning window (so that it does not change
          when a planning entity changes) and let the score constraints take it into account.</para>
        </note>
      </section>

      <section xml:id="planningEntityDifficulty">
        <title>Planning Entity Difficulty</title>

        <para>Some optimization algorithms work more efficiently if they have an estimation of which planning entities
        are more difficult to plan. For example: in bin packing bigger items are harder to fit, in course scheduling
        lectures with more students are more difficult to schedule, and in n queens the middle queens are more difficult
        to fit on the board.</para>

        <note>
          <para><emphasis role="bold">Do not try to use planning entity difficulty to implement a business
          constraint.</emphasis> It will not affect the score function: if we have infinite solving time, the returned
          solution will be the same.</para>

          <para>To attain a schedule in which certain entities are scheduled earlier in the schedule, <link
          linkend="formalizeTheBusinessConstraints">add a score constraint</link> to change the score function so it
          prefers such solutions. Only consider adding planning entity difficulty too if it can make the solver more
          efficient.</para>
        </note>

        <para>To allow the heuristics to take advantage of that domain specific information, set a
        <literal>difficultyComparatorClass</literal> to the <literal>@PlanningEntity</literal> annotation:</para>

        <programlisting language="java">@PlanningEntity(difficultyComparatorClass = CloudProcessDifficultyComparator.class)
public class CloudProcess {
    // ...
}</programlisting>

        <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>Alternatively, you can also set a <literal>difficultyWeightFactoryClass</literal> to the
        <literal>@PlanningEntity</literal> annotation, so that you have access to the rest of the problem facts from the
        <literal>Solution</literal> too:</para>

        <programlisting language="java">@PlanningEntity(difficultyWeightFactoryClass = QueenDifficultyWeightFactory.class)
public class Queen {
    // ...
}</programlisting>

        <para>See <link linkend="sortedSelection">sorted selection</link> for more information.</para>

        <important>
          <para>Difficulty should be implemented ascending: easy entities are lower, difficult entities are higher. For
          example, in bin packing: small item &lt; medium item &lt; big item.</para>

          <para>Although most algorithms start with the more difficult entities first, they just reverse the
          ordering.</para>
        </important>

        <para><emphasis>None of the current planning variable states should be used to compare planning entity
        difficulty.</emphasis> During Construction Heuristics, those variables are likely to be <literal>null</literal>
        anyway. For example, a <literal>Queen</literal>'s <literal>row</literal> variable should not be used.</para>
      </section>
    </section>

    <section xml:id="planningVariable">
      <title>Planning Variable</title>

      <section xml:id="planningVariableAnnotation">
        <title>Planning Variable Annotation</title>

        <para>A planning variable is a JavaBean property (so a getter and setter) on a planning entity. It points to a
        planning value, which changes during planning. For example, a <literal>Queen</literal>'s <literal>row</literal>
        property is a planning variable. Note that even though a <literal>Queen</literal>'s <literal>row</literal>
        property changes to another <literal>Row</literal> during planning, no <literal>Row</literal> instance itself is
        changed.</para>

        <para>A planning variable getter needs to be annotated with the <literal>@PlanningVariable</literal> annotation,
        which needs a non-empty <literal>valueRangeProviderRefs</literal> property.</para>

        <programlisting language="java">@PlanningEntity
public class Queen {
    ...

    private Row row;

    @PlanningVariable(valueRangeProviderRefs = {"rowRange"})
    public Row getRow() {
        return row;
    }

    public void setRow(Row row) {
        this.row = row;
    }

}</programlisting>

        <para>The <literal>valueRangeProviderRefs</literal> property defines what are the possible planning values for
        this planning variable. It references one or more <literal>@ValueRangeProvider</literal>
        <literal>id</literal>'s.</para>

        <note>
          <para>A @PlanningVariable annotation needs to be on a member in a class with a @PlanningEntity annotation. It
          is ignored on parent classes or subclasses without that annotation.</para>
        </note>

        <para><link linkend="annotationAlternatives">Annotating the field</link> instead of the property works
        too:</para>

        <programlisting language="java">@PlanningEntity
public class Queen {
    ...

    @PlanningVariable(valueRangeProviderRefs = {"rowRange"})
    private Row row;

}</programlisting>
      </section>

      <section xml:id="nullablePlanningVariable">
        <title>Nullable Planning Variable</title>

        <para>By default, an initialized planning variable cannot be <literal>null</literal>, so an initialized solution
        will never use <literal>null</literal> for any of its planning variables. In an over-constrained use case, this
        can be counterproductive. For example: in task assignment with too many tasks for the workforce, we would rather
        leave low priority tasks unassigned instead of assigning them to an overloaded worker.</para>

        <para>To allow an initialized planning variable to be <literal>null</literal>, set <literal>nullable</literal>
        to <literal>true</literal>:</para>

        <programlisting language="java">    @PlanningVariable(..., nullable = true)
    public Worker getWorker() {
        return worker;
    }</programlisting>

        <important>
          <para>Planner will automatically add the value <literal>null</literal> to the value range. There is no need to
          add <literal>null</literal> in a collection used by a <literal>ValueRangeProvider</literal>.</para>
        </important>

        <note>
          <para>Using a nullable planning variable implies that your score calculation is responsible for punishing (or
          even rewarding) variables with a null value.</para>
        </note>

        <para><link linkend="repeatedPlanning">Repeated planning</link> (especially <link
        linkend="realTimePlanning">real-time planning</link>) does not mix well with a nullable planning variable. Every
        time the Solver starts or a problem fact change is made, the <link linkend="constructionHeuristics">Construction
        Heuristics</link> will try to initialize all the <literal>null</literal> variables again, which can be a huge
        waste of time. One way to deal with this, is to change when a planning entity should be reinitialized with an
        <literal>reinitializeVariableEntityFilter</literal>:</para>

        <programlisting language="java">    @PlanningVariable(..., nullable = true, reinitializeVariableEntityFilter = ReinitializeTaskFilter.class)
    public Worker getWorker() {
        return worker;
    }</programlisting>
      </section>

      <section xml:id="whenIsAPlanningVariableInitialized">
        <title>When is a Planning Variable Considered Initialized?</title>

        <para>A planning variable is considered initialized if its value is not <literal>null</literal> or if the
        variable is <literal>nullable</literal>. So a nullable variable is always considered initialized, even when a
        custom <literal>reinitializeVariableEntityFilter</literal> triggers a reinitialization during construction
        heuristics.</para>

        <para>A planning entity is initialized if all of its planning variables are initialized.</para>

        <para>A <literal>Solution</literal> is initialized if all of its planning entities are initialized.</para>
      </section>
    </section>

    <section xml:id="planningValueAndPlanningValueRange">
      <title>Planning Value and Planning Value Range</title>

      <section xml:id="planningValue">
        <title>Planning Value</title>

        <para>A planning value is a possible value for a planning variable. Usually, a planning value is a problem fact,
        but it can also be any object, for example a <literal>double</literal>. It can even be another planning entity
        or even a interface implemented by both a planning entity and a problem fact.</para>

        <para>A planning value range is the set of possible planning values for a planning variable. This set can be a
        countable (for example row <literal>1</literal>, <literal>2</literal>, <literal>3</literal> or
        <literal>4</literal>) or uncountable (for example any <literal>double</literal> between <literal>0.0</literal>
        and <literal>1.0</literal>).</para>
      </section>

      <section xml:id="planningValueRangeProvider">
        <title>Planning Value Range Provider</title>

        <section xml:id="planningValueRangeProviderOverview">
          <title>Overview</title>

          <para>The value range of a planning variable is defined with the <literal>@ValueRangeProvider</literal>
          annotation. A <literal>@ValueRangeProvider</literal> annotation always has a property <literal>id</literal>,
          which is referenced by the <literal>@PlanningVariable</literal>'s property
          <literal>valueRangeProviderRefs</literal>.</para>

          <para>This annotation can be located on 2 types of methods:</para>

          <itemizedlist>
            <listitem>
              <para>On the Solution: All planning entities share the same value range.</para>
            </listitem>

            <listitem>
              <para>On the planning entity: The value range differs per planning entity. This is less common.</para>
            </listitem>
          </itemizedlist>

          <note>
            <para>A @ValueRangeProvider annotation needs to be on a member in a class with a @PlanningSolution or a
            @PlanningEntity annotation. It is ignored on parent classes or subclasses without those annotations.</para>
          </note>

          <para>The return type of that method can be 2 types:</para>

          <itemizedlist>
            <listitem>
              <para><literal>Collection</literal>: The value range is defined by a <literal>Collection</literal>
              (usually a <literal>List</literal>) of its possible values.</para>
            </listitem>

            <listitem>
              <para><literal>ValueRange</literal>: The value range is defined by its bounds. This is less common.</para>
            </listitem>
          </itemizedlist>
        </section>

        <section xml:id="valueRangeProviderOnSolution">
          <title><literal>ValueRangeProvider</literal> on the <literal>Solution</literal></title>

          <para>All instances of the same planning entity class share the same set of possible planning values for that
          planning variable. This is the most common way to configure a value range.</para>

          <para>The <literal>Solution</literal> implementation has method that returns a <literal>Collection</literal>
          (or a <literal>ValueRange</literal>). Any value from that <literal>Collection</literal> is a possible planning
          value for this planning variable.</para>

          <programlisting language="java">    @PlanningVariable(valueRangeProviderRefs = {"rowRange"})
    public Row getRow() {
        return row;
    }</programlisting>

          <programlisting language="java">@PlanningSolution
public class NQueens {
    ...

    @ValueRangeProvider(id = "rowRange")
    public List&lt;Row&gt; getRowList() {
        return rowList;
    }

}</programlisting>

          <important>
            <para>That <literal>Collection</literal> (or <literal>ValueRange</literal>) must not contain the value
            <literal>null</literal>, not even for a <link linkend="nullablePlanningVariable">nullable planning
            variable</link>.</para>
          </important>

          <para><link linkend="annotationAlternatives">Annotating the field</link> instead of the property works
          too:</para>

          <programlisting language="java">@PlanningSolution
public class NQueens {
    ...

    @ValueRangeProvider(id = "rowRange")
    private List&lt;Row&gt; rowList;

}</programlisting>
        </section>

        <section xml:id="valueRangeProviderOnPlanningEntity">
          <title><literal>ValueRangeProvider</literal> on the Planning Entity</title>

          <para>Each planning entity has its own value range (a set of possible planning values) for the planning
          variable. For example, if a teacher can <emphasis role="bold">never</emphasis> teach in a room that does not
          belong to his department, lectures of that teacher can limit their room value range to the rooms of his
          department.</para>

          <programlisting language="java">    @PlanningVariable(valueRangeProviderRefs = {"departmentRoomRange"})
    public Room getRoom() {
        return room;
    }

    @ValueRangeProvider(id = "departmentRoomRange")
    public List&lt;Room&gt; getPossibleRoomList() {
        return getCourse().getTeacher().getDepartment().getRoomList();
    }</programlisting>

          <para>Never use this to enforce a soft constraint (or even a hard constraint when the problem might not have a
          feasible solution). For example: <emphasis>Unless there is no other way</emphasis>, a teacher can not teach in
          a room that does not belong to his department. In this case, the teacher should <emphasis>not</emphasis> be
          limited in his room value range (because sometimes there is no other way).</para>

          <note>
            <para>By limiting the value range specifically of one planning entity, you are effectively creating a
            <emphasis>built-in hard constraint</emphasis>. This can have the benefit of severely lowering the number of
            possible solutions; however, it can also away the freedom of the optimization algorithms to temporarily
            break that constraint in order to escape from a local optimum.</para>
          </note>

          <para>A planning entity should <emphasis>not</emphasis> use other planning entities to determinate its value
          range. That would only try to make the planning entity solve the planning problem itself and interfere with
          the optimization algorithms.</para>

          <para>Every entity has its own <literal>List</literal> instance, unless multiple entities have the same value
          range. For example, if teacher A and B belong to the same department, they use the same
          <literal>List&lt;Room&gt;</literal> instance. Furthermore, each <literal>List</literal> contains a subset of
          the same set of planning value instances. For example, if department A and B can both use room X, then their
          <literal>List&lt;Room&gt;</literal> instances contain the same <literal>Room</literal> instance.</para>

          <note>
            <para>A <literal>ValueRangeProvider</literal> on the planning entity consumes more memory than
            <literal>ValueRangeProvider</literal> on the Solution and disables certain automatic performance
            optimizations.</para>
          </note>

          <warning>
            <para>A <literal>ValueRangeProvider</literal> on the planning entity is not currently compatible with a
            <link linkend="chainedPlanningVariable">chained</link> variable.</para>
          </warning>
        </section>

        <section xml:id="valueRangeFactory">
          <title><literal>ValueRangeFactory</literal></title>

          <para>Instead of a <literal>Collection</literal>, you can also return a <literal>ValueRange</literal> or
          <literal>CountableValueRange</literal>, build by the <literal>ValueRangeFactory</literal>:</para>

          <programlisting language="java">    @ValueRangeProvider(id = "delayRange")
    public CountableValueRange&lt;Integer&gt; getDelayRange() {
        return ValueRangeFactory.createIntValueRange(0, 5000);
    }</programlisting>

          <para>A <literal>ValueRange</literal> uses far less memory, because it only holds the bounds. In the example
          above, a <literal>Collection</literal> would need to hold all <literal>5000</literal> ints, instead of just
          the two bounds.</para>

          <para>Furthermore, an <literal>incrementUnit</literal> can be specified, for example if you have to buy stocks
          in units of 200 pieces:</para>

          <programlisting language="java">    @ValueRangeProvider(id = "stockAmountRange")
    public CountableValueRange&lt;Integer&gt; getStockAmountRange() {
         // Range: 0, 200, 400, 600, ..., 9999600, 9999800, 10000000
        return ValueRangeFactory.createIntValueRange(0, 10000000, 200);
    }</programlisting>

          <note>
            <para>Return <literal>CountableValueRange</literal> instead of <literal>ValueRange</literal> whenever
            possible (so Planner knows that it's countable).</para>
          </note>

          <para>The <literal>ValueRangeFactory</literal> has creation methods for several value class types:</para>

          <itemizedlist>
            <listitem>
              <para><literal>boolean</literal>: A boolean range.</para>
            </listitem>

            <listitem>
              <para><literal>int</literal>: A 32bit integer range.</para>
            </listitem>

            <listitem>
              <para><literal>long</literal>: A 64bit integer range.</para>
            </listitem>

            <listitem>
              <para><literal>double</literal>: A 64bit floating point range which only supports random selection
              (because it does not implement <literal>CountableValueRange</literal>).</para>
            </listitem>

            <listitem>
              <para><literal>BigInteger</literal>: An arbitrary-precision integer range.</para>
            </listitem>

            <listitem>
              <para><literal>BigDecimal</literal>: A decimal point range. By default, the increment unit is the lowest
              non-zero value in the scale of the bounds.</para>
            </listitem>

            <listitem>
              <para><literal>Temporal</literal> (such as <literal>LocalDate</literal>, <literal>LocalDateTime</literal>,
              ...): A time range.</para>
            </listitem>
          </itemizedlist>
        </section>

        <section xml:id="combineValueRangeProviders">
          <title>Combine ValueRangeProviders</title>

          <para>Value range providers can be combined, for example:</para>

          <programlisting language="java">    @PlanningVariable(valueRangeProviderRefs = {"companyCarRange", "personalCarRange"})
    public Car getCar() {
        return car;
    }</programlisting>

          <programlisting language="java">    @ValueRangeProvider(id = "companyCarRange")
    public List&lt;CompanyCar&gt; getCompanyCarList() {
        return companyCarList;
    }

    @ValueRangeProvider(id = "personalCarRange")
    public List&lt;PersonalCar&gt; getPersonalCarList() {
        return personalCarList;
    }</programlisting>
        </section>
      </section>

      <section xml:id="planningValueStrength">
        <title>Planning Value Strength</title>

        <para>Some optimization algorithms work a bit more efficiently if they have an estimation of which planning
        values are stronger, which means they are more likely to satisfy a planning entity. For example: in bin packing
        bigger containers are more likely to fit an item and in course scheduling bigger rooms are less likely to break
        the student capacity constraint. Usually, the efficiency gain of planning value strength is far less than that
        of <link linkend="planningEntityDifficulty">planning entity difficulty</link>.</para>

        <note>
          <para><emphasis role="bold">Do not try to use planning value strength to implement a business
          constraint.</emphasis> It will not affect the score function: if we have infinite solving time, the returned
          solution will be the same.</para>

          <para>To affect the score function, <link linkend="formalizeTheBusinessConstraints">add a score
          constraint</link>. Only consider adding planning value strength too if it can make the solver more
          efficient.</para>
        </note>

        <para>To allow the heuristics to take advantage of that domain specific information, set a
        <literal>strengthComparatorClass</literal> to the <literal>@PlanningVariable</literal> annotation:</para>

        <programlisting language="java">    @PlanningVariable(..., strengthComparatorClass = CloudComputerStrengthComparator.class)
    public CloudComputer getComputer() {
        return computer;
    }</programlisting>

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

    public int compare(CloudComputer a, CloudComputer b) {
        return new CompareToBuilder()
                .append(a.getMultiplicand(), b.getMultiplicand())
                .append(b.getCost(), a.getCost()) // Descending (but this is debatable)
                .append(a.getId(), b.getId())
                .toComparison();
    }

}</programlisting>

        <note>
          <para>If you have multiple planning value classes in the <emphasis>same</emphasis> value range, the
          <literal>strengthComparatorClass</literal> needs to implement a <literal>Comparator</literal> of a common
          superclass (for example <literal>Comparator&lt;Object&gt;</literal>) and be able to handle comparing instances
          of those different classes.</para>
        </note>

        <para>Alternatively, you can also set a <literal>strengthWeightFactoryClass</literal> to the
        <literal>@PlanningVariable</literal> annotation, so you have access to the rest of the problem facts from the
        solution too:</para>

        <programlisting language="java">    @PlanningVariable(..., strengthWeightFactoryClass = RowStrengthWeightFactory.class)
    public Row getRow() {
        return row;
    }</programlisting>

        <para>See <link linkend="sortedSelection">sorted selection</link> for more information.</para>

        <important>
          <para>Strength should be implemented ascending: weaker values are lower, stronger values are higher. For
          example in bin packing: small container &lt; medium container &lt; big container.</para>
        </important>

        <para><emphasis>None of the current planning variable state in any of the planning entities should be used to
        compare planning values.</emphasis> During construction heuristics, those variables are likely to be
        <literal>null</literal>. For example, none of the <literal>row</literal> variables of any
        <literal>Queen</literal> may be used to determine the strength of a <literal>Row</literal>.</para>
      </section>

      <section xml:id="chainedPlanningVariable">
        <title>Chained Planning Variable (TSP, VRP, ...)</title>

        <para>Some use cases, such as TSP and Vehicle Routing, require <emphasis>chaining</emphasis>. This means the
        planning entities point to each other and form a chain. By modeling the problem as a set of chains (instead of a
        set of trees/loops), the search space is heavily reduced.</para>

        <para>A planning variable that is chained either:</para>

        <itemizedlist>
          <listitem>
            <para>Directly points to a problem fact (or planning entity), which is called an
            <emphasis>anchor</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Points to another planning entity with the same planning variable, which recursively points to an
            anchor.</para>
          </listitem>
        </itemizedlist>

        <para>Here are some example of valid and invalid chains:</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/chainPrinciples.png"/>
          </imageobject>
        </mediaobject>

        <para><emphasis role="bold">Every initialized planning entity is part of an open-ended chain that begins from an
        anchor.</emphasis> A valid model means that:</para>

        <itemizedlist>
          <listitem>
            <para>A chain is never a loop. The tail is always open.</para>
          </listitem>

          <listitem>
            <para>Every chain always has exactly one anchor. The anchor is a problem fact, never a planning
            entity.</para>
          </listitem>

          <listitem>
            <para>A chain is never a tree, it is always a line. Every anchor or planning entity has at most one trailing
            planning entity.</para>
          </listitem>

          <listitem>
            <para>Every initialized planning entity is part of a chain.</para>
          </listitem>

          <listitem>
            <para>An anchor with no planning entities pointing to it, is also considered a chain.</para>
          </listitem>
        </itemizedlist>

        <warning>
          <para>A planning problem instance given to the <literal>Solver</literal> must be valid.</para>
        </warning>

        <note>
          <para>If your constraints dictate a closed chain, model it as an open-ended chain (which is easier to persist
          in a database) and implement a score constraint for the last entity back to the anchor.</para>
        </note>

        <para>The optimization algorithms and built-in <literal>Move</literal>s do chain correction to guarantee that
        the model stays valid:</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/chainCorrection.png"/>
          </imageobject>
        </mediaobject>

        <warning>
          <para>A custom <literal>Move</literal> implementation must leave the model in a valid state.</para>
        </warning>

        <para>For example, in TSP the anchor is a <literal>Domicile</literal> (in vehicle routing it is
        <literal>Vehicle</literal>):</para>

        <programlisting language="java">public class Domicile ... implements Standstill {
    ...

    public City getCity() {...}

}</programlisting>

        <para>The anchor (which is a problem fact) and the planning entity implement a common interface, for example
        TSP's <literal>Standstill</literal>:</para>

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

    City getCity();

}</programlisting>

        <para>That interface is the return type of the planning variable. Furthermore, the planning variable is chained.
        For example TSP's <literal>Visit</literal> (in vehicle routing it is <literal>Customer</literal>):</para>

        <programlisting language="java">@PlanningEntity
public class Visit ... implements Standstill {
    ...

    public City getCity() {...}

    @PlanningVariable(graphType = PlanningVariableGraphType.CHAINED,
        valueRangeProviderRefs = {"domicileRange", "visitRange"})
    public Standstill getPreviousStandstill() {
        return previousStandstill;
    }

    public void setPreviousStandstill(Standstill previousStandstill) {
        this.previousStandstill = previousStandstill;
    }

}</programlisting>

        <para>Notice how two value range providers are usually combined:</para>

        <itemizedlist>
          <listitem>
            <para>The value range provider that holds the anchors, for example <literal>domicileList</literal>.</para>
          </listitem>

          <listitem>
            <para>The value range provider that holds the initialized planning entities, for example
            <literal>visitList</literal>.</para>
          </listitem>
        </itemizedlist>
      </section>
    </section>

    <section xml:id="shadowVariable">
      <title>Shadow Variable</title>

      <section xml:id="shadowVariableIntroduction">
        <title>Introduction</title>

        <para>A shadow variable is a variable whose correct value can be deduced from the state of the genuine planning
        variables. Even though such a variable violates the principle of normalization by definition, in some use cases
        it can be very practical to use a shadow variable, especially to express the constraints more naturally. For
        example in vehicle routing with time windows: the arrival time at a customer for a vehicle can be calculated
        based on the previously visited customers of that vehicle (and the known travel times between two
        locations).</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/planningVariableListener.png"/>
          </imageobject>
        </mediaobject>

        <para>When the customers for a vehicle change, the arrival time for each customer is automatically adjusted. For
        more information, see the <link linkend="vehicleRoutingDomainModel">vehicle routing domain model</link>.</para>

        <para>From a score calculation perspective, a shadow variable is like any other planning variable. From an
        optimization perspective, Planner effectively only optimizes the genuine variables (and mostly ignores the
        shadow variables): it just assures that when a genuine variable changes, any dependent shadow variables are
        changed accordingly.</para>

        <important>
          <para><emphasis role="bold">Any class that has at least one shadow variable, is a planning entity
          class</emphasis>, even if it has no genuine planning variables. That entity class needs to be defined in the
          solver configuration (unless classes are <link linkend="automaticScanningForAnnotations">automatically
          scanned</link>) and be annotated accordingly.</para>

          <para>An genuine planning entity class has at least one genuine planning variable. A shadow planning entity
          class has no genuine planning variables and at least one shadow planning variable.</para>
        </important>

        <para>There are several build-in shadow variables:</para>
      </section>

      <section xml:id="bidirectionalVariable">
        <title>Bi-directional Variable (Inverse Relation Shadow Variable)</title>

        <para>Two variables are bi-directional if their instances always point to each other (unless one side points to
        <literal>null</literal> and the other side does not exist). So if A references B, then B references A.</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/bidirectionalVariable.png"/>
          </imageobject>
        </mediaobject>

        <para>For a non-chained planning variable, the bi-directional relationship must be a many to one relationship.
        To map a bi-directional relationship between two planning variables, annotate the master side (which is the
        genuine side) as a normal planning variable:</para>

        <programlisting language="java">@PlanningEntity
public class CloudProcess {

    @PlanningVariable(...)
    public CloudComputer getComputer() {
        return computer;
    }
    public void setComputer(CloudComputer computer) {...}

}</programlisting>

        <para>And then annotate the other side (which is the shadow side) with a
        <literal>@InverseRelationShadowVariable</literal> annotation on a <literal>Collection</literal> (usually a
        <literal>Set</literal> or <literal>List</literal>) property:</para>

        <programlisting language="java">@PlanningEntity
public class CloudComputer {

    @InverseRelationShadowVariable(sourceVariableName = "computer")
    public List&lt;CloudProcess&gt; getProcessList() {
        return processList;
    }

}</programlisting>

        <para>The <literal>sourceVariableName</literal> property is the name of the genuine planning variable on the
        return type of the getter (so the name of the genuine planning variable on the <emphasis>other</emphasis>
        side).</para>

        <note>
          <para>The shadow property, which is a <literal>Collection</literal>, can never be <literal>null</literal>. If
          no genuine variable is referencing that shadow entity, then it is an empty <literal>Collection</literal>.
          Furthermore it must be a mutable <literal>Collection</literal> because once the Solver starts initializing or
          changing genuine planning variables, it will add and remove to the <literal>Collection</literal>s of those
          shadow variables accordingly.</para>
        </note>

        <para>For a chained planning variable, the bi-directional relationship must be a one to one relationship. In
        that case, the genuine side looks like this:</para>

        <programlisting language="java">@PlanningEntity
public class Customer ... {

    @PlanningVariable(graphType = PlanningVariableGraphType.CHAINED, ...)
    public Standstill getPreviousStandstill() {
        return previousStandstill;
    }
    public void setPreviousStandstill(Standstill previousStandstill) {...}

}</programlisting>

        <para>And the shadow side looks like this:</para>

        <programlisting language="java">@PlanningEntity
public class Standstill {

    @InverseRelationShadowVariable(sourceVariableName = "previousStandstill")
    public Customer getNextCustomer() {
         return nextCustomer;
    }
    public void setNextCustomer(Customer nextCustomer) {...}

}</programlisting>

        <warning>
          <para>The input planning problem of a <literal>Solver</literal> must not violate bi-directional relationships.
          If A points to B, then B must point to A. Planner will not violate that principle during planning, but the
          input must not violate it.</para>
        </warning>
      </section>

      <section xml:id="anchorShadowVariable">
        <title>Anchor Shadow Variable</title>

        <para>An anchor shadow variable is the anchor of <link linkend="chainedPlanningVariable">a chained
        variable</link>.</para>

        <para>Annotate the anchor property as a <literal>@AnchorShadowVariable</literal> annotation:</para>

        <programlisting language="java">@PlanningEntity
public class Customer {

    @AnchorShadowVariable(sourceVariableName = "previousStandstill")
    public Vehicle getVehicle() {...}
    public void setVehicle(Vehicle vehicle) {...}

}</programlisting>

        <para>The <literal>sourceVariableName</literal> property is the name of the chained variable on the same entity
        class.</para>
      </section>

      <section xml:id="customVariableListener">
        <title>Custom <literal>VariableListener</literal></title>

        <para>To update a shadow variable, Planner uses a <literal>VariableListener</literal>. To define a custom shadow
        variable, write a custom <literal>VariableListener</literal>: implement the interface and annotate it on the
        shadow variable that needs to change.</para>

        <programlisting language="java">    @PlanningVariable(...)
    public Standstill getPreviousStandstill() {
        return previousStandstill;
    }

    @CustomShadowVariable(variableListenerClass = VehicleUpdatingVariableListener.class,
            sources = {@CustomShadowVariable.Source(variableName = "previousStandstill")})
    public Vehicle getVehicle() {
        return vehicle;
    }</programlisting>

        <para>The <literal>variableName</literal> is the variable that triggers changes in the shadow
        variable(s).</para>

        <note>
          <para>If the class of the trigger variable is different than the shadow variable, also specify the
          <literal>entityClass</literal> on <literal>@CustomShadowVariable.Source</literal>. In that case, make sure
          that that <literal>entityClass</literal> is also properly configured as a planning entity class in the solver
          config, or the <literal>VariableListener</literal> will simply never trigger.</para>
        </note>

        <para>For example, the <literal>VehicleUpdatingVariableListener</literal> assures that every
        <literal>Customer</literal> in a chain has the same <literal>Vehicle</literal>, namely the chain's
        anchor.</para>

        <programlisting language="java">public class VehicleUpdatingVariableListener implements VariableListener&lt;Customer&gt; {

    public void afterEntityAdded(ScoreDirector scoreDirector, Customer customer) {
        updateVehicle(scoreDirector, customer);
    }

    public void afterVariableChanged(ScoreDirector scoreDirector, Customer customer) {
        updateVehicle(scoreDirector, customer);
    }

    ...

    protected void updateVehicle(ScoreDirector scoreDirector, Customer sourceCustomer) {
        Standstill previousStandstill = sourceCustomer.getPreviousStandstill();
        Vehicle vehicle = previousStandstill == null ? null : previousStandstill.getVehicle();
        Customer shadowCustomer = sourceCustomer;
        while (shadowCustomer != null &amp;&amp; shadowCustomer.getVehicle() != vehicle) {
            scoreDirector.beforeVariableChanged(shadowCustomer, "vehicle");
            shadowCustomer.setVehicle(vehicle);
            scoreDirector.afterVariableChanged(shadowCustomer, "vehicle");
            shadowCustomer = shadowCustomer.getNextCustomer();
        }
    }

}</programlisting>

        <warning>
          <para>A <literal>VariableListener</literal> can only change shadow variables. It must never change a genuine
          planning variable or a problem fact.</para>
        </warning>

        <warning>
          <para>Any change of a shadow variable must be told to the <literal>ScoreDirector</literal>.</para>
        </warning>

        <para>If one <literal>VariableListener</literal> changes two shadow variables (because having two separate
        <literal>VariableListener</literal>s would be inefficient), then annotate only the first shadow variable with
        the <literal>variableListenerClass</literal> and let the other shadow variable(s) reference the first shadow
        variable:</para>

        <programlisting language="java">    @PlanningVariable(...)
    public Standstill getPreviousStandstill() {
        return previousStandstill;
    }

    @CustomShadowVariable(variableListenerClass = TransportTimeAndCapacityUpdatingVariableListener.class,
            sources = {@CustomShadowVariable.Source(variableName = "previousStandstill")})
    public Integer getTransportTime() {
        return transportTime;
    }

    @CustomShadowVariable(variableListenerRef = @PlanningVariableReference(variableName = "transportTime"))
    public Integer getCapacity() {
        return capacity;
    }</programlisting>
      </section>

      <section xml:id="variableListenerTriggeringOrder">
        <title>VariableListener triggering order</title>

        <para>All shadow variables are triggered by a <literal>VariableListener</literal>, regardless if it's a build-in
        or a custom shadow variable. The genuine and shadow variables form a graph, that determines the order in which
        the <literal>afterEntityAdded()</literal>, <literal>afterVariableChanged()</literal> and
        <literal>afterEntityRemoved()</literal> methods are called:</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/shadowVariableOrder.png"/>
          </imageobject>
        </mediaobject>

        <note>
          <para>In the example above, D could have also been ordered after E (or F) because there is no direct or
          indirect dependency between D and E (or F).</para>
        </note>

        <para>Planner guarantees that:</para>

        <itemizedlist>
          <listitem>
            <para>The first <literal>VariableListener</literal>'s <literal>after*()</literal> methods trigger
            <emphasis>after</emphasis> the last genuine variable has changed. Therefore the genuine variables (A and B
            in the example above) are guaranteed to be in a consistent state across all its instances (with values A1,
            A2 and B1 in the example above) because the entire <literal>Move</literal> has been applied.</para>
          </listitem>

          <listitem>
            <para>The second <literal>VariableListener</literal>'s <literal>after*()</literal> methods trigger
            <emphasis>after</emphasis> the last first shadow variable has changed. Therefore the first shadow variable
            (C in the example above) are guaranteed to be in consistent state across all its instances (with values C1
            and C2 in the example above). And of course the genuine variables too.</para>
          </listitem>

          <listitem>
            <para>And so forth.</para>
          </listitem>
        </itemizedlist>

        <para>Planner does not guarantee the order in which the <literal>after*()</literal> methods are called for the
        <emphasis>same</emphasis> <literal>VariableListener</literal> with different parameters (such as A1 and A2 in
        the example above), although they are likely to be in the order in which they were affected.</para>
      </section>
    </section>

    <section xml:id="planningProblemAndPlanningSolution">
      <title>Planning Problem and Planning Solution</title>

      <section xml:id="planningProblemInstance">
        <title>Planning Problem Instance</title>

        <para>A dataset for a planning problem needs to be wrapped in a class for the <literal>Solver</literal> to
        solve. That solution class represents both the planning problem and (if solved) a solution. It is annotated with
        a <literal>@PlanningSolution</literal> annotation. For example in n queens, the solution class is the
        <literal>NQueens</literal> class, which contains a <literal>Column</literal> list, a <literal>Row</literal>
        list, and a <literal>Queen</literal> list.</para>

        <para>A planning problem is actually an unsolved planning solution or - stated differently - an uninitialized
        solution. For example in n queens, that <literal>NQueens</literal> class has the
        <literal>@PlanningSolution</literal> annotation, yet every <literal>Queen</literal> in an unsolved
        <literal>NQueens</literal> class is not yet assigned to a <literal>Row</literal> (their <literal>row</literal>
        property is <literal>null</literal>). That's not a feasible solution. It's not even a possible solution. It's an
        uninitialized solution.</para>
      </section>

      <section xml:id="solutionClass">
        <title>Solution Class</title>

        <para>A solution class holds all problem facts, planning entities and a score. It is annotated with a<literal>
        @PlanningSolution</literal> annotation. For example, an <literal>NQueens</literal> instance holds a list of all
        columns, all rows and all <literal>Queen</literal> instances:</para>

        <programlisting language="java">@PlanningSolution
public class NQueens {

    // Problem facts
    private int n;
    private List&lt;Column&gt; columnList;
    private List&lt;Row&gt; rowList;

    // Planning entities
    private List&lt;Queen&gt; queenList;

    private SimpleScore score;

    ...
}</programlisting>

        <para>Without <link linkend="automaticScanningForAnnotations">automated scanning</link>, the solver
        configuration also needs to declare the planning solution class:</para>

        <programlisting language="java">&lt;solver&gt;
  ...
  &lt;solutionClass&gt;org.optaplanner.examples.nqueens.domain.NQueens&lt;/solutionClass&gt;
  ...
&lt;/solver&gt;</programlisting>
      </section>

      <section xml:id="planningEntitiesOfASolution">
        <title>Planning Entities of a Solution (@PlanningEntityCollectionProperty)</title>

        <para>Planner needs to extract the entity instances from the solution instance. It gets those collection(s) by
        calling every getter (or field) that is annotated with
        <literal>@PlanningEntityCollectionProperty</literal>:</para>

        <programlisting language="java">@PlanningSolution
public class NQueens {
    ...

    private List&lt;Queen&gt; queenList;

    @PlanningEntityCollectionProperty
    public List&lt;Queen&gt; getQueenList() {
        return queenList;
    }

}</programlisting>

        <para>There can be multiple <literal>@PlanningEntityCollectionProperty</literal> annotated members. Those can
        even return a <literal>Collection</literal> with the same entity class type.</para>

        <note>
          <para>A @PlanningEntityCollectionProperty annotation needs to be on a member in a class with a
          @PlanningSolution annotation. It is ignored on parent classes or subclasses without that annotation.</para>
        </note>

        <para>In rare cases, a planning entity might be a singleton: use <literal>@PlanningEntityProperty</literal> on
        its getter (or field) instead.</para>
      </section>

      <section xml:id="scoreOfASolution">
        <title><literal>Score</literal> of a Solution (<literal>@PlanningScore</literal>)</title>

        <para>A <literal>Solution</literal> requires a score property, which is annotated with a
        <literal>@PlanningScore</literal> annotation. The score property is <literal>null</literal> if the the score
        hasn't been calculated yet. The <literal>score</literal> property is typed to the specific
        <literal>Score</literal> implementation of your use case. For example, <literal>NQueens</literal> uses a <link
        linkend="simpleScore">SimpleScore</link>:</para>

        <programlisting language="java">@PlanningSolution
public class NQueens {
    ...

    private SimpleScore score;

    @PlanningScore
    public SimpleScore getScore() {
        return score;
    }
    public void setScore(SimpleScore score) {
        this.score = score;
    }

}</programlisting>

        <para>Most use cases use a <link linkend="hardSoftScore">HardSoftScore</link> instead:</para>

        <programlisting language="java">@PlanningSolution
public class CloudBalance {
    ...

    private HardSoftScore score;

    @PlanningScore
    public HardSoftScore getScore() {
        return score;
    }

    public void setScore(HardSoftScore score) {
        this.score = score;
    }

}</programlisting>

        <para>Some use cases use <link linkend="scoreDefinition">other <literal>Score</literal> types</link>.</para>
      </section>

      <section xml:id="getProblemFacts">
        <title>Problem Facts of a Solution (<literal>@ProblemFactCollectionProperty</literal>)</title>

        <para>For <link linkend="droolsScoreCalculation">Drools score calculation</link>, Planner needs to extract the
        problem fact instances from the solution instance. It gets those collection(s) by calling every method (or
        field) that is annotated with <literal>@ProblemFactCollectionProperty</literal>. All objects returned by those
        methods will be inserted into the Drools session, so the score rules can access them. For example in
        <literal>NQueens</literal> all <literal>Column</literal> and <literal>Row</literal> instances are problem
        facts.</para>

        <programlisting language="java">@PlanningSolution
public class NQueens {
    ...

    private List&lt;Column&gt; columnList;
    private List&lt;Row&gt; rowList;

    @ProblemFactCollectionProperty
    public List&lt;Column&gt; getColumnList() {
        return columnList;
    }

    @ProblemFactCollectionProperty
    public List&lt;Row&gt; getRowList() {
        return rowList;
    }

}</programlisting>

        <para>All planning entities are automatically inserted into the Drools working memory. Do note add an annotation
        on their properties.</para>

        <note>
          <para>The problem facts methods are not called often: at most only once per solver phase per solver
          thread.</para>
        </note>

        <para>There can be multiple <literal>@ProblemFactCollectionProperty</literal> annotated members. Those can even
        return a <literal>Collection</literal> with the same class type, but they shouldn't return the same instance
        twice.</para>

        <note>
          <para>A @ProblemFactCollectionProperty annotation needs to be on a member in a class with a @PlanningSolution
          annotation. It is ignored on parent classes or subclasses without that annotation.</para>
        </note>

        <para>In rare cases, a problem fact might be a singleton: use <literal>@ProblemFactProperty</literal> on its
        method (or field) instead.</para>

        <section xml:id="cachedProblemFact">
          <title>Cached Problem Fact</title>

          <para>A cached problem fact is a problem fact that does not exist in the real domain model, but is calculated
          before the <literal>Solver</literal> really starts solving. The problem facts methods have the opportunity to
          enrich the domain model with such cached problem facts, which can lead to simpler and faster score
          constraints.</para>

          <para>For example in examination, a cached problem fact <literal>TopicConflict</literal> is created for every
          two <literal>Topic</literal>s which share at least one <literal>Student</literal>.</para>

          <programlisting language="java">    @ProblemFactCollectionProperty
    private List&lt;TopicConflict&gt; calculateTopicConflictList() {
        List&lt;TopicConflict&gt; topicConflictList = new ArrayList&lt;TopicConflict&gt;();
        for (Topic leftTopic : topicList) {
            for (Topic rightTopic : topicList) {
                if (leftTopic.getId() &lt; rightTopic.getId()) {
                    int studentSize = 0;
                    for (Student student : leftTopic.getStudentList()) {
                        if (rightTopic.getStudentList().contains(student)) {
                            studentSize++;
                        }
                    }
                    if (studentSize &gt; 0) {
                        topicConflictList.add(new TopicConflict(leftTopic, rightTopic, studentSize));
                    }
                }
            }
        }
        return topicConflictList;
    }</programlisting>

          <para>Where a score constraint needs to check that no two exams with a topic that shares a student are
          scheduled close together (depending on the constraint: at the same time, in a row, or in the same day), the
          <literal>TopicConflict</literal> instance can be used as a problem fact, rather than having to combine every
          two <literal>Student</literal> instances.</para>
        </section>
      </section>

      <section xml:id="cloningASolution">
        <title>Cloning a Solution</title>

        <para>Most (if not all) optimization algorithms clone the solution each time they encounter a new best solution
        (so they can recall it later) or to work with multiple solutions in parallel.</para>

        <note>
          <para>There are many ways to clone, such as a shallow clone, deep clone, ... This context focuses on
          <emphasis>a planning clone</emphasis>.</para>
        </note>

        <para>A planning clone of a solution must fulfill these requirements:</para>

        <itemizedlist>
          <listitem>
            <para>The clone must represent the same planning problem. Usually it reuses the same instances of the
            problem facts and problem fact collections as the original.</para>
          </listitem>

          <listitem>
            <para>The clone must use different, cloned instances of the entities and entity collections. Changes to an
            original <literal>Solution</literal> entity's variables must not affect its clone.</para>
          </listitem>
        </itemizedlist>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/solutionCloning.png"/>
          </imageobject>
        </mediaobject>

        <para><emphasis role="bold">Implementing a planning clone method is hard, therefore you do not need to implement
        it.</emphasis></para>

        <section xml:id="fieldAccessingSolutionCloner">
          <title><literal>FieldAccessingSolutionCloner</literal></title>

          <para>This <literal>SolutionCloner</literal> is used by default. It works well for most use cases.</para>

          <warning>
            <para>When the <literal>FieldAccessingSolutionCloner</literal> clones your entity collection, it may not
            recognize the implementation and replace it with <literal>ArrayList</literal>,
            <literal>LinkedHashSet</literal> or <literal>TreeSet</literal> (whichever is more applicable). It recognizes
            most of the common JDK <literal>Collection</literal> implementations.</para>
          </warning>

          <para>The <literal>FieldAccessingSolutionCloner</literal> does not clone problem facts by default. If any of
          your problem facts needs to be deep cloned for a planning clone, for example if the problem fact references a
          planning entity or the planning solution, mark it with a <literal>@DeepPlanningClone</literal>
          annotation:</para>

          <programlisting language="java">@DeepPlanningClone
public class SeatDesignationDependency {
    private SeatDesignation leftSeatDesignation; // planning entity
    private SeatDesignation rightSeatDesignation; // planning entity
    ...
}</programlisting>

          <para>In the example above, because <literal>SeatDesignation</literal> is a planning entity (which is deep
          planning cloned automatically), <literal>SeatDesignationDependency</literal> must also be deep planning
          cloned.</para>

          <para>Alternatively, the <literal>@DeepPlanningClone</literal> annotation can also be used on a getter
          method.</para>
        </section>

        <section xml:id="customCloning">
          <title>Custom Cloning: Make <literal>Solution</literal> Implement <literal>PlanningCloneable</literal></title>

          <para>If your <literal>Solution</literal> implements <literal>PlanningCloneable</literal>, Planner will
          automatically choose to clone it by calling the <literal>planningClone()</literal> method.</para>

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

    T planningClone();

}</programlisting>

          <para>For example: If <literal>NQueens</literal> implements <literal>PlanningCloneable</literal>, it would
          only deep clone all <literal>Queen</literal> instances. When the original solution is changed during planning,
          by changing a <literal>Queen</literal>, the clone stays the same.</para>

          <programlisting language="java">public class NQueens PlanningCloneable&lt;NQueens&gt; {
    ...

    /**
     * Clone will only deep copy the {@link #queenList}.
     */
    public NQueens planningClone() {
        NQueens clone = new NQueens();
        clone.id = id;
        clone.n = n;
        clone.columnList = columnList;
        clone.rowList = rowList;
        List&lt;Queen&gt; clonedQueenList = new ArrayList&lt;Queen&gt;(queenList.size());
        for (Queen queen : queenList) {
            clonedQueenList.add(queen.planningClone());
        }
        clone.queenList = clonedQueenList;
        clone.score = score;
        return clone;
    }
}</programlisting>

          <para><emphasis>The <literal>planningClone()</literal> method should only deep clone the planning
          entities.</emphasis> Notice that the problem facts, such as <literal>Column</literal> and
          <literal>Row</literal> are <emphasis>not</emphasis> normally cloned: even their <literal>List</literal>
          instances are <emphasis>not</emphasis> cloned. If you were to clone the problem facts too, then you would have
          to make sure that the new planning entity clones also refer to the new problem facts clones used by the
          solution. For example, if you were to clone all <literal>Row</literal> instances, then each
          <literal>Queen</literal> clone and the <literal>NQueens</literal> clone itself should refer to those new
          <literal>Row</literal> clones.</para>

          <warning>
            <para>Cloning an entity with a <link linkend="chainedPlanningVariable">chained</link> variable is devious: a
            variable of an entity A might point to another entity B. If A is cloned, then its variable must point to the
            clone of B, not the original B.</para>
          </warning>
        </section>
      </section>

      <section xml:id="createAnUninitializedSolution">
        <title>Create an Uninitialized Solution</title>

        <para>Create a <literal>Solution</literal> instance to represent your planning problem's dataset, so it can be
        set on the <literal>Solver</literal> as the planning problem to solve. For example in n queens, an
        <literal>NQueens</literal> instance is created with the required <literal>Column</literal> and
        <literal>Row</literal> instances and every <literal>Queen</literal> set to a different <literal>column</literal>
        and every <literal>row</literal> set to <literal>null</literal>.</para>

        <programlisting language="java">    private NQueens createNQueens(int n) {
        NQueens nQueens = new NQueens();
        nQueens.setId(0L);
        nQueens.setN(n);
        nQueens.setColumnList(createColumnList(nQueens));
        nQueens.setRowList(createRowList(nQueens));
        nQueens.setQueenList(createQueenList(nQueens));
        return nQueens;
    }

    private List&lt;Queen&gt; createQueenList(NQueens nQueens) {
        int n = nQueens.getN();
        List&lt;Queen&gt; queenList = new ArrayList&lt;Queen&gt;(n);
        long id = 0L;
        for (Column column : nQueens.getColumnList()) {
            Queen queen = new Queen();
            queen.setId(id);
            id++;
            queen.setColumn(column);
            // Notice that we leave the PlanningVariable properties on null
            queenList.add(queen);
        }
        return queenList;
    }</programlisting>

        <figure>
          <title>Uninitialized Solution for the 4 Queens Puzzle</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/Chapter-Planner_configuration/uninitializedNQueens04.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Usually, most of this data comes from your data layer, and your <literal>Solution</literal> implementation
        just aggregates that data and creates the uninitialized planning entity instances to plan:</para>

        <programlisting language="java">        private void createLectureList(CourseSchedule schedule) {
            List&lt;Course&gt; courseList = schedule.getCourseList();
            List&lt;Lecture&gt; lectureList = new ArrayList&lt;Lecture&gt;(courseList.size());
            long id = 0L;
            for (Course course : courseList) {
                for (int i = 0; i &lt; course.getLectureSize(); i++) {
                    Lecture lecture = new Lecture();
                    lecture.setId(id);
                    id++;
                    lecture.setCourse(course);
                    lecture.setLectureIndexInCourse(i);
                    // Notice that we leave the PlanningVariable properties (period and room) on null
                    lectureList.add(lecture);
                }
            }
            schedule.setLectureList(lectureList);
        }</programlisting>
      </section>
    </section>
  </section>

  <section xml:id="useTheSolver">
    <title>Use the <literal>Solver</literal></title>

    <section xml:id="theSolverInterface">
      <title>The <literal>Solver</literal> Interface</title>

      <para>A <literal>Solver</literal> implementation will solve your planning problem.</para>

      <programlisting language="java">public interface Solver&lt;Solution_&gt; {

    Solution_ solve(Solution_ planningProblem);

    ...
}</programlisting>

      <para>A <literal>Solver</literal> can only solve one planning problem instance at a time. A
      <literal>Solver</literal> should only be accessed from a single thread, except for the methods that are
      specifically javadocced as being thread-safe. It is built with a <literal>SolverFactory</literal>, there is no
      need to implement it yourself.</para>
    </section>

    <section xml:id="solvingAProblem">
      <title>Solving a Problem</title>

      <para>Solving a problem is quite easy once you have:</para>

      <itemizedlist>
        <listitem>
          <para>A <literal>Solver</literal> built from a solver configuration</para>
        </listitem>

        <listitem>
          <para>A <literal>Solution</literal> that represents the planning problem instance</para>
        </listitem>
      </itemizedlist>

      <para>Just provide the planning problem as argument to the <literal>solve()</literal> method and it will return
      the best solution found:</para>

      <programlisting language="java">    NQueens bestSolution = solver.solve(planningProblem);</programlisting>

      <para>For example in n queens, the <literal>solve()</literal> method will return an <literal>NQueens</literal>
      instance with every <literal>Queen</literal> assigned to a <literal>Row</literal>.</para>

      <figure>
        <title>Best Solution for the 4 Queens Puzzle in 8ms (Also an Optimal Solution)</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/Chapter-Planner_configuration/solvedNQueens04.png"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The <literal>solve(Solution)</literal> method can take a long time (depending on the problem size and the
      solver configuration). The <literal>Solver</literal> intelligently wades through <link
      linkend="searchSpaceSize">the search space</link> of possible solutions and remembers the best solution it
      encounters during solving. Depending on a number factors (including problem size, how much time the
      <literal>Solver</literal> has, the solver configuration, ...), <link
      linkend="doesPlannerFindTheOptimalSolution">that best solution might or might not be an optimal
      solution</link>.</para>

      <note>
        <para>The <literal>Solution</literal> instance given to the method <literal>solve(Solution)</literal> is changed
        by the <literal>Solver</literal>, but do not mistake it for the best solution.</para>

        <para>The <literal>Solution</literal> instance returned by the methods <literal>solve(Solution)</literal> or
        <literal>getBestSolution()</literal> is most likely <link linkend="cloningASolution">a planning clone</link> of
        the instance given to the method <literal>solve(Solution)</literal>, which implies it is a different
        instance.</para>
      </note>

      <note>
        <para>The <literal>Solution</literal> instance given to the <literal>solve(Solution)</literal> method does not
        need to be uninitialized. It can be partially or fully initialized, which is often the case in <link
        linkend="repeatedPlanning">repeated planning</link>.</para>
      </note>
    </section>

    <section xml:id="environmentMode">
      <title>Environment Mode: Are There Bugs in my Code?</title>

      <para>The environment mode allows you to detect common bugs in your implementation. It does not affect the logging
      level.</para>

      <para>You can set the environment mode in the solver configuration XML file:</para>

      <programlisting language="xml">&lt;solver&gt;
  &lt;environmentMode&gt;FAST_ASSERT&lt;/environmentMode&gt;
  ...
&lt;/solver&gt;</programlisting>

      <para>A solver has a single <literal>Random</literal> instance. Some solver configurations use the
      <literal>Random</literal> instance a lot more than others. For example Simulated Annealing depends highly on
      random numbers, while Tabu Search only depends on it to deal with score ties. The environment mode influences the
      seed of that <literal>Random</literal> instance.</para>

      <para>These are the environment modes:</para>

      <section xml:id="environmentModeFullAssert">
        <title>FULL_ASSERT</title>

        <para>The FULL_ASSERT mode turns on all assertions (such as assert that the incremental score calculation is
        uncorrupted for each move) to fail-fast on a bug in a Move implementation, a score rule, the rule engine itself,
        ...</para>

        <para>This mode is reproducible (see the reproducible mode). It is also intrusive because it calls the method
        <literal>calculateScore()</literal> more frequently than a non-assert mode.</para>

        <para>The FULL_ASSERT mode is horribly slow (because it does not rely on incremental score calculation).</para>
      </section>

      <section xml:id="environmentModeNonIntrusiveFullAssert">
        <title>NON_INTRUSIVE_FULL_ASSERT</title>

        <para>The NON_INTRUSIVE_FULL_ASSERT turns on several assertions to fail-fast on a bug in a Move implementation,
        a score rule, the rule engine itself, ...</para>

        <para>This mode is reproducible (see the reproducible mode). It is non-intrusive because it does not call the
        method <literal>calculateScore()</literal> more frequently than a non assert mode.</para>

        <para>The NON_INTRUSIVE_FULL_ASSERT mode is horribly slow (because it does not rely on incremental score
        calculation).</para>
      </section>

      <section xml:id="environmentModeFastAssert">
        <title>FAST_ASSERT</title>

        <para>The FAST_ASSERT mode turns on most assertions (such as assert that an undoMove's score is the same as
        before the Move) to fail-fast on a bug in a Move implementation, a score rule, the rule engine itself,
        ...</para>

        <para>This mode is reproducible (see the reproducible mode). It is also intrusive because it calls the method
        <literal>calculateScore()</literal> more frequently than a non assert mode.</para>

        <para>The FAST_ASSERT mode is slow.</para>

        <para>It is recommended to write a test case that does a short run of your planning problem with the FAST_ASSERT
        mode on.</para>
      </section>

      <section xml:id="environmentModeReproducible">
        <title>REPRODUCIBLE (default)</title>

        <para>The reproducible mode is the default mode because it is recommended during development. In this mode, two
        runs in the same Planner version will execute the same code in the same order. <emphasis role="bold">Those two
        runs will have the same result at every step</emphasis>, except if the note below applies. This enables you to
        reproduce bugs consistently. It also allows you to benchmark certain refactorings (such as a score constraint
        performance optimization) fairly across runs.</para>

        <note>
          <para>Despite the reproducible mode, your application might still not be fully reproducible because of:</para>

          <itemizedlist>
            <listitem>
              <para>Use of <literal>HashSet</literal> (or another <literal>Collection</literal> which has an
              inconsistent order between JVM runs) for collections of planning entities or planning values (but not
              normal problem facts), especially in the <literal>Solution</literal> implementation. Replace it with
              <literal>LinkedHashSet</literal>.</para>
            </listitem>

            <listitem>
              <para>Combining a time gradient dependent algorithms (most notably Simulated Annealing) together with time
              spent termination. A sufficiently large difference in allocated CPU time will influence the time gradient
              values. Replace Simulated Annealing with Late Acceptance. Or instead, replace time spent termination with
              step count termination.</para>
            </listitem>
          </itemizedlist>
        </note>

        <para>The reproducible mode is slightly slower than the production mode. If your production environment requires
        reproducibility, use this mode in production too.</para>

        <para>In practice, this mode uses the default, fixed <link linkend="randomNumberGenerator">random seed</link> if
        no seed is specified, and it also disables certain concurrency optimizations (such as work stealing).</para>
      </section>

      <section xml:id="environmentModeProduction">
        <title>PRODUCTION</title>

        <para>The production mode is the fastest, but it is not reproducible. It is recommended for a production
        environment, unless reproducibility is required.</para>

        <para>In practice, this mode uses no fixed <link linkend="randomNumberGenerator">random seed</link> if no seed
        is specified.</para>
      </section>
    </section>

    <section xml:id="logging">
      <title>Logging Level: What is the <literal>Solver</literal> Doing?</title>

      <para>The best way to illuminate the black box that is a <literal>Solver</literal>, is to play with the logging
      level:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">error</emphasis>: Log errors, except those that are thrown to the calling code as
          a <literal>RuntimeException</literal>.</para>

          <note>
            <para><emphasis role="bold">If an error happens, Planner normally fails fast</emphasis>: it throws a
            subclass of <literal>RuntimeException</literal> with a detailed message to the calling code. It does not log
            it as an error itself to avoid duplicate log messages. Except if the calling code explicitly catches and
            eats that <literal>RuntimeException</literal>, a <literal>Thread</literal>'s default
            <literal>ExceptionHandler</literal> will log it as an error anyway. Meanwhile, the code is disrupted from
            doing further harm or obfuscating the error.</para>
          </note>
        </listitem>

        <listitem>
          <para><emphasis role="bold">warn</emphasis>: Log suspicious circumstances.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">info</emphasis>: Log every phase and the solver itself. See <link
          linkend="scopeOverview">scope overview</link>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">debug</emphasis>: Log every step of every phase. See <link
          linkend="scopeOverview">scope overview</link>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">trace</emphasis>: Log every move of every step of every phase. See <link
          linkend="scopeOverview">scope overview</link>.</para>

          <note>
            <para>Turning on <literal>trace</literal> logging, will slow down performance considerably: it is often four
            times slower. However, it is invaluable during development to discover a bottleneck.</para>

            <para>Even debug logging can slow down performance considerably for fast stepping algorithms (such as Late
            Acceptance and Simulated Annealing), but not for slow stepping algorithms (such as Tabu Search).</para>
          </note>
        </listitem>
      </itemizedlist>

      <para>For example, set it to <literal>debug</literal> logging, to see when the phases end and how fast steps are
      taken:</para>

      <programlisting>INFO  Solving started: time spent (3), best score (uninitialized/0), random (JDK with seed 0).
DEBUG     CH step (0), time spent (5), score (0), selected move count (1), picked move (Queen-2 {null -&gt; Row-0}).
DEBUG     CH step (1), time spent (7), score (0), selected move count (3), picked move (Queen-1 {null -&gt; Row-2}).
DEBUG     CH step (2), time spent (10), score (0), selected move count (4), picked move (Queen-3 {null -&gt; Row-3}).
DEBUG     CH step (3), time spent (12), score (-1), selected move count (4), picked move (Queen-0 {null -&gt; Row-1}).
INFO  Construction Heuristic phase (0) ended: step total (4), time spent (12), best score (-1).
DEBUG     LS step (0), time spent (19), score (-1),     best score (-1), accepted/selected move count (12/12), picked move (Queen-1 {Row-2 -&gt; Row-3}).
DEBUG     LS step (1), time spent (24), score (0), new best score (0), accepted/selected move count (9/12), picked move (Queen-3 {Row-3 -&gt; Row-2}).
INFO  Local Search phase (1) ended: step total (2), time spent (24), best score (0).
INFO  Solving ended: time spent (24), best score (0), average calculate count per second (1625).</programlisting>

      <para>All time spent values are in milliseconds.</para>

      <para>Everything is logged to <link xlink:href="http://www.slf4j.org/">SLF4J</link>, which is a simple logging
      facade which delegates every log message to Logback, Apache Commons Logging, Log4j or java.util.logging. Add a
      dependency to the logging adaptor for your logging framework of choice.</para>

      <para>If you are not using any logging framework yet, use Logback by adding this Maven dependency (there is no
      need to add an extra bridge dependency):</para>

      <programlisting language="xml">    &lt;dependency&gt;
      &lt;groupId&gt;ch.qos.logback&lt;/groupId&gt;
      &lt;artifactId&gt;logback-classic&lt;/artifactId&gt;
      &lt;version&gt;1.x&lt;/version&gt;
    &lt;/dependency&gt;</programlisting>

      <para>Configure the logging level on the <literal>org.optaplanner</literal> package in your
      <filename>logback.xml</filename> file:</para>

      <programlisting language="xml">&lt;configuration&gt;

  &lt;logger name="org.optaplanner" level="debug"/&gt;

  ...

&lt;configuration&gt;</programlisting>

      <para>If instead, you are still using Log4J 1.x (and you do not want to switch to its faster successor, Logback),
      add the bridge dependency:</para>

      <programlisting language="xml">    &lt;dependency&gt;
      &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
      &lt;artifactId&gt;slf4j-log4j12&lt;/artifactId&gt;
      &lt;version&gt;1.x&lt;/version&gt;
    &lt;/dependency&gt;</programlisting>

      <para>And configure the logging level on the package <literal>org.optaplanner</literal> in your
      <filename>log4j.xml</filename> file:</para>

      <programlisting language="xml">&lt;log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"&gt;

  &lt;category name="org.optaplanner"&gt;
    &lt;priority value="debug" /&gt;
  &lt;/category&gt;

  ...

&lt;/log4j:configuration&gt;</programlisting>

      <note>
        <para>In a multitenant application, multiple <literal>Solver</literal> instances might be running at the same
        time. To separate their logging into distinct files, surround the <literal>solve()</literal> call with an <link
        xlink:href="http://logback.qos.ch/manual/mdc.html">MDC</link>:</para>

        <programlisting language="java">        MDC.put("tenant.name",tenantName);
        MySolution bestSolution = solver.solve(planningProblem);
        MDC.remove("tenant.name");</programlisting>

        <para>Then configure your logger to use different files for each <literal>${tenant.name}</literal>. For example
        in Logback, use a <literal>SiftingAppender</literal> in <literal>logback.xml</literal>:</para>

        <programlisting language="xml">  &lt;appender name="fileAppender" class="ch.qos.logback.classic.sift.SiftingAppender"&gt;
    &lt;discriminator&gt;
      &lt;key&gt;tenant.name&lt;/key&gt;
      &lt;defaultValue&gt;unknown&lt;/defaultValue&gt;
    &lt;/discriminator&gt;
    &lt;sift&gt;
      &lt;appender name="fileAppender.${tenant.name}" class="...FileAppender"&gt;
        &lt;file&gt;local/log/optaplanner-${tenant.name}.log&lt;/file&gt;
        ...
      &lt;/appender&gt;
    &lt;/sift&gt;
  &lt;/appender&gt;</programlisting>
      </note>
    </section>

    <section xml:id="randomNumberGenerator">
      <title>Random Number Generator</title>

      <para>Many heuristics and metaheuristics depend on a pseudorandom number generator for move selection, to resolve
      score ties, probability based move acceptance, ... During solving, the same <literal>Random</literal> instance is
      reused to improve reproducibility, performance and uniform distribution of random values.</para>

      <para>To change the random seed of that <literal>Random</literal> instance, specify a
      <literal>randomSeed</literal>:</para>

      <programlisting language="xml">&lt;solver&gt;
  &lt;randomSeed&gt;0&lt;/randomSeed&gt;
  ...
&lt;/solver&gt;</programlisting>

      <para>To change the pseudorandom number generator implementation, specify a <literal>randomType</literal>:</para>

      <programlisting language="xml">&lt;solver&gt;
  &lt;randomType&gt;MERSENNE_TWISTER&lt;/randomType&gt;
  ...
&lt;/solver&gt;</programlisting>

      <para>The following types are supported:</para>

      <itemizedlist>
        <listitem>
          <para><literal>JDK</literal> (default): Standard implementation (<literal>java.util.Random</literal>).</para>
        </listitem>

        <listitem>
          <para><literal>MERSENNE_TWISTER</literal>: Implementation by <link
          xlink:href="http://commons.apache.org/proper/commons-math/userguide/random.html">Commons Math</link>.</para>
        </listitem>

        <listitem>
          <para><literal>WELL512A</literal>, <literal>WELL1024A</literal>, <literal>WELL19937A</literal>,
          <literal>WELL19937C</literal>, <literal>WELL44497A</literal> and <literal>WELL44497B</literal>: Implementation
          by <link xlink:href="http://commons.apache.org/proper/commons-math/userguide/random.html">Commons
          Math</link>.</para>
        </listitem>
      </itemizedlist>

      <para>For most use cases, the randomType has no significant impact on the average quality of the best solution on
      multiple datasets. If you want to confirm this on your use case, use the <link
      linkend="benchmarker">benchmarker</link>.</para>
    </section>
  </section>
</chapter>