[jboss-svn-commits] JBL Code SVN: r15155 - labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Sep 16 15:37:54 EDT 2007
Author: ge0ffrey
Date: 2007-09-16 15:37:54 -0400 (Sun, 16 Sep 2007)
New Revision: 15155
Modified:
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml
Log:
more examples in the manual
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml 2007-09-16 15:13:59 UTC (rev 15154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml 2007-09-16 19:37:54 UTC (rev 15155)
@@ -32,8 +32,112 @@
</section>
<section>
- <title>Getting started</title>
+ <title>A Move</title>
<para></para>
</section>
+
+ <section>
+ <title>A step</title>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>Deciding the next step</title>
+
+ <para></para>
+
+ <section>
+ <title>Selector</title>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>Accepter</title>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>Forager</title>
+
+ <para></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Finish</title>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>ggg</title>
+
+ <para>ggg</para>
+
+ <figure>
+ <title>A single move (4 queens example)</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="singleMoveNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="singleMoveNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>ggg</para>
+
+ <figure>
+ <title>Possible moves at step 0 (4 queens example)</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="possibleMovesNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="possibleMovesNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>ggg</para>
+
+ <figure>
+ <title>Decide the next step at step 0 (4 queens example)</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="decideNextStepNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="decideNextStepNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>ggg</para>
+
+ <figure>
+ <title>All steps (4 queens example)</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="allStepsNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="allStepsNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
</section>
\ No newline at end of file
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml 2007-09-16 15:13:59 UTC (rev 15154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml 2007-09-16 19:37:54 UTC (rev 15155)
@@ -7,7 +7,7 @@
<para>Score calculation of a planning problem is based on constraints
(such as hard constraints, soft constraints, rewards, ...). A rules
- engine, such as drools, make it easy to implement those constraints as
+ engine, such as drools, makes it easy to implement those constraints as
<emphasis>score rules</emphasis>.</para>
<para>Here's an example of a constraint implemented as a score rule in
@@ -26,28 +26,58 @@
end</programlisting>
</example>
- <para>This score rule will fire once for each 2 queens with the same
+ <para>This score rule will fire once for every 2 queens with the same
<literal>y</literal>. The <literal>(id > $id)</literal> condition is
needed to assure that for 2 queens a and b, it can only fire for (a,b) and
- not for (b,a), (a,a) or (b,b).</para>
+ not for (b,a), (a,a) or (b,b). Let's take a closer look at this score rule
+ on the starting solution of 4 queens:</para>
+ <figure>
+ <title>Starting solution for the 4 queens puzzle</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="unsolvedNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="unsolvedNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In this starting solution the multipleQueensHorizontal score rule
+ will fire for 6 queen couples: (a, b), (a, c), (a, d), (b, c), (b, d) and
+ (c, d). Because none of the queens are on the same vertical or diagonal
+ line, this starting solution will have a score of <literal>-6</literal>.
+ An optimal solution of 4 queens has a score of <literal>0</literal>. More
+ on that later.</para>
+
+ <para>You need to add your score rules drl files in the solver
+ configuration, for example:</para>
+
+ <programlisting> <scoreDrl>/org/drools/solver/examples/nqueens/solver/nQueensScoreRules.drl</scoreDrl></programlisting>
+
+ <para>You can add multiple <literal><scoreDrl></literal> entries if
+ needed.</para>
+
<para>It's recommended to use drools in forward-chaining mode (which is
- the default), as for most solver implementations this will create the
- effect of a <emphasis>delta based score calculation</emphasis> instead of
- a full score calculation on each solution evaluation. For example, if
- queen a moves from y <literal>0</literal> to <literal>3</literal>, it
- won't bother to recalculate the "multiple queens on the same horizontal
- line" constraint for queens with y <literal>1</literal> or
- <literal>2</literal>. This is a huge performance gain. <emphasis
- role="bold">Drools-solver gives you this huge performance gain without
- forcing you to write very complicated delta based score calculation
- algorithms.</emphasis> Just let the drools rule engine do the hard
- work.</para>
+ the default behaviour), as for most solver implementations this will
+ create the effect of a <emphasis>delta based score calculation</emphasis>
+ instead of a full score calculation on each solution evaluation. For
+ example, if a single queen moves from y <literal>0</literal> to
+ <literal>3</literal>, it won't bother to recalculate the "multiple queens
+ on the same horizontal line" constraint for queens with y
+ <literal>1</literal> or <literal>2</literal>. This is a huge performance
+ gain. <emphasis role="bold">Drools-solver gives you this huge performance
+ gain without forcing you to write a very complicated delta based score
+ calculation algorithm.</emphasis> Just let the drools rule engine do the
+ hard work.</para>
<para><emphasis role="bold">Adding more constraints is scalable and
easy</emphasis> (if you understand the drools rule syntax). This allows
you to add it a bunch of soft constraint score rules on top of the hard
- constraints score rules with few effort. For example, for a freight
+ constraints score rules with little effort. For example, for a freight
routing problem you could add a soft constraint to avoid the certain
flagged highways at rush hour.</para>
</section>
@@ -61,10 +91,15 @@
<literal>Double</literal> or <literal>Integer</literal>) must be stable
through the problem.</para>
- <para>The solver aims to find the solution with the highest score. Most
- planning problems tend to use negative scores (the amount of negative
- constraints being broken) with an impossible perfect score of 0.</para>
+ <para>The solver aims to find the solution with the highest score.
+ <emphasis>The best solution</emphasis> is the solution with the highest
+ score that it encounters during its solving.</para>
+ <para>Most planning problems tend to use negative scores (the amount of
+ negative constraints being broken) with an impossible perfect score of 0.
+ This is why the score of a solution of 4 queens is the negative of the
+ number of queen couples that can attack each other.</para>
+
<para>A <literal>ScoreCalculator</literal> instance is configured in the
solver configuration:</para>
@@ -93,7 +128,7 @@
<listitem>
<para>DYNAMIC_HARD_AND_SOFT_CONSTRAINTS: A special
<literal>HardAndSoftConstraintScoreCalculator</literal> instance, for
- more information see the javadocs. </para>
+ more information see the javadocs.</para>
</listitem>
</itemizedlist>
@@ -124,12 +159,12 @@
rule "constraintsBroken"
when
- $hardCount : Number() from accumulate(
+ $hardConstraintCount : Number() from accumulate(
$w : ...,
count($w)
);
then
- scoreCalculator.setScore(- $hardCount);
+ scoreCalculator.setScore(- $hardConstraintCount);
end</programlisting>
</section>
@@ -141,7 +176,8 @@
<para>If you know a certain constraint can never be broken, don't
bother writing a score rule for it. For example the NQueens example
doesn't have a "multipleQueensVertical" rule because a queen's
- <literal>x</literal> never changes. </para>
+ <literal>x</literal> never changes. This gives a performance gain,
+ because </para>
</listitem>
<listitem>
@@ -149,6 +185,17 @@
type. If you're making the sum of nothing but integer values, don't
let drools use Double's or your performance will hurt.</para>
</listitem>
+
+ <listitem>
+ <para>In case you haven't figured it out yet: performance (and
+ scalability) is very important for solving planning problems. What
+ good is a real-time freight routing solver that takes a day to find a
+ feasible solution? Even small and innocent looking problems can hide
+ an enormous problem size. For example, they probably still don't know
+ the optimal solution of the traveling tournament problem for as little
+ as 10 traveling teams. But always remember that premature optimization
+ is the root of all evil.</para>
+ </listitem>
</itemizedlist>
</section>
</section>
\ No newline at end of file
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml 2007-09-16 15:13:59 UTC (rev 15154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml 2007-09-16 19:37:54 UTC (rev 15155)
@@ -104,9 +104,26 @@
<para>You need to present the problem as a starting
<literal>Solution</literal> instance to the Solver. Usually you will make
- that starting solution with a simple filler algorithm, for example: all
- queens on a different x and all on y = 0. It will probably be far from
- optimal, but that's ok, as it's the solver's job to find a much better
+ that starting solution with a simple filler algorithm. For example for 4
+ queens we use a starting solution with all queens on a different x and on
+ the same y (with y = 0).</para>
+
+ <figure>
+ <title>Starting solution for the 4 queens puzzle</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="unsolvedNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="unsolvedNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The starting solution will probably be far from optimal (or even
+ feasible), but that's ok, as it's the solver's job to find a much better
solution.</para>
<para>Here is the <literal>Solution</literal> interface:</para>
@@ -167,8 +184,28 @@
Solution bestSolution = solver.getBestSolution();</programlisting>
<para>The <literal>solve()</literal> method will take a long time
- (depending on the problem size and the solver configuration). After a
- problem is solved, you can reuse the same solver to solve another problem
- (of the same problem type).</para>
+ (depending on the problem size and the solver configuration). The solver
+ will remember (actually clone) the best solution it encounters during its
+ solving. Depending on a number factors (including problem size, how long
+ you allow the solver to work, which solver type you use, ...), that best
+ solution will be a feasible or even an optimal solution.</para>
+
+ <figure>
+ <title>Best solution for the 4 queens puzzle (also an optimal
+ solution)</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="solvedNQueens04.svg" />
+ </imageobject>
+
+ <imageobject>
+ <imagedata fileref="solvedNQueens04.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>After a problem is solved, you can reuse the same solver instance to
+ solve another problem (of the same problem type).</para>
</section>
</section>
\ No newline at end of file
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml 2007-09-16 15:13:59 UTC (rev 15154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml 2007-09-16 19:37:54 UTC (rev 15155)
@@ -25,10 +25,12 @@
<programlisting>$ cd drools-solver/drools-solver-examples/
$ mvn exec:java -Dexec.mainClass="org.drools.solver.examples.nqueens.app.NQueensApp"
+$ mvn exec:java -Dexec.mainClass="org.drools.solver.examples.lessonschedule.app.LessonScheduleApp"
+$ mvn exec:java -Dexec.mainClass="org.drools.solver.examples.travelingtournament.app.smart.SmartTravelingTournamentApp"
...</programlisting>
- <para>Here's a screenshot of the NQueens example, which is the simplest of
- all the examples:</para>
+ <para>Here's a screenshot of the NQueens example, which is a simple
+ example:</para>
<mediaobject>
<imageobject>
More information about the jboss-svn-commits
mailing list