<!--
  - Authors:
  -   Christian Schulte <schulte@ps.uni-sb.de>
  -   Gert Smolka <smolka@dfki.de>
  -   Jörg Würtz
  -
  - Contributors:
  -   Daniel Simon <dansim@ps.uni-sb.de>
  -   Andy Walter <anwalt@ps.uni-sb.de>
  -   
  - Copyright:
  -   Christian Schulte, 1998
  -   Gert Smolka, 1998
  -   Jörg Würtz, 1997
  -
  - Last change:
  -   $Date: 1999/09/10 12:00:30 $ by $Author: schulte $
  -   $Revision: 1.15 $
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<chapter id=chapter.problem>
  <title/Writing Problem Solvers in Oz/

<p>
We are now well-prepared to write and run our
first finite domain problem solvers in Oz.  For
running, analyzing, and debugging problem solvers
we will use the <Ref.extern to="ozdoc:explorer"/Explorer/, a graphical
tool of the 
Mozart programming environment.

<p>
A <def/script/ for a finite domain problem is a
program that can compute one or all solutions of
the problem.  In Oz, scripts will be run on
predefined search engines implementing the
propagate and distribute method just described.
Separating scripts from the search engines
running them is an important abstraction making it
possible to design scripts at a very high level.
To develop a script for a given problem, we start
by designing a model and a distribution strategy.
We then obtain an executable script by
implementing the model and distribution strategy
with the predefined abstractions available in Oz.

<section id="section.problem.script">
  <title/Format of Scripts/<p>

In Oz, a script takes the form of a
procedure
<<<
proc {Script Root}
   %% declare variables
in
   %% post constraints
   %% specify distribution strategy
end
>>>
The procedure declares the variables needed, posts
the constraints modeling the problem, and specifies
the distribution strategy.
<p>
The argument <<Root>> stands for the solutions of
the problem to be solved.  If the solutions of a
problem are given by more than one variable, say
<<X>>, <<Y>>, and <<Z>>, we may simply combine these
variables into one record by posting a constraint
like
<<<Root = solution(x:X y:Y z:Z)>>>
The procedure
<<<
{SearchAll Script ?Solutions}
>>>
will run the script <<Script>> until the entire
search tree is explored and return the list of
the solutions found. 

<p>
The procedure
<<<
{SearchOne Script ?Solutions}
>>>
will run the script <<Script>> until the first
solution is found.  If a solution is found, it
is returned as the single element of a list;
otherwise, the empty list is returned.
</section>

<section id="section.problem.money">
  <title/Example: Send More Money/<p>

We will now write a script for the Send
More Money Puzzle.

<subsection class=unnumbered>
  <title/Problem Specification/

<P>
The Send More Money Problem
consists in finding distinct digits for the letters
<math/D/, <math/E/, <math/M/, <math/N/, <math/O/, <math/R/, <math/S/,
<math/Y/ such that <math/S/ and <math/M/ are different from zero (no
leading zeros) and the equation
<math display>
SEND\;+\;MORE\;=\;MONEY
</math>
is satisfied.  The unique solution of the problem
is <math/9567+1085=10652/.

<subsection class=unnumbered>
  <title/Model/

<P>
We model the problem by having a variable for
every letter, where the variable stands for the
digit associated with the letter.  The
constraints are obvious from the problem
specification.

<subsection class=unnumbered>
  <title/Distribution Strategy/

<P>
We distribute on the variables for the letters
with a first-fail strategy.  The variables are
ordered according to the alphabetic order of the
letters.  The strategy tries the least possible
value of the selected variable.

<figure id="ProgMoney" class="Figure">
<caption/A script for the Send More Money Puzzle./
<chunk class=anonymous><title/Money/
proc {Money Root}
   S E N D M O R Y
in
   Root = sol(s:S e:E n:N d:D m:M o:O r:R y:Y)       % 1
   Root ::: 0#9                                      % 2
   {FD.distinct Root}                                % 3
   S \=: 0                                           % 4
   M \=: 0
                1000*S + 100*E + 10*N + D            % 5
   +            1000*M + 100*O + 10*R + E
   =: 10000*M + 1000*O + 100*N + 10*E + Y
   {FD.distribute ff Root}
end
</chunk>
</figure>

<subsection class=unnumbered>
  <title/Script/

<P>
<Ptr to="ProgMoney"> shows a script realizing the
model and distribution strategy just discussed.  The
script first declares a local variable for every
letter.  Then it posts the following constraints:
<list enum>
<item>
<<Root>> is a record that has a field for every
letter.  The fields of <<Root>> are the digits for
the corresponding letters.  This constraint is
basic.
<item>
The fields of <<Root>> are integers in the domain
<<0#9>>.  This constraint is basic.
<item>
The fields of <<Root>> are pairwise distinct.  This
constraint is nonbasic.
<item>
The values of the variables <<S>> and <<M>> are
different from zero (no leading zeros).  These
constraints are nonbasic.
<item>
The digits for the letters satisfy the equation
<<SEND+MORE=MONEY>>.  This constraint is nonbasic.
</list>

<subsection class=unnumbered>
  <title/Posting of constraints/

<P>
<def/posting of constraints/ is defined
differently for basic and nonbasic constraints.
Basic constraints are posted by telling them to
the constraint store.  Nonbasic constraints are
posted by creating propagators implementing them.

<p>
Note that the propagators for <<S\=:0>> and
<<M\=:0>> can immediately write their complete
information into the constraint store since the
store already knows domains for <<S>> and <<M>>.

<p>
The last line <<{FD.distribute ff Root}>> posts a
distributor that will distribute on the field of
<<Root>> with the first-fail strategy (specified by
the atom <<ff>>).  Equivalently, we could write
<<<
{FD.distribute ff [D E M N O R S Y]}
>>>
and thus specify the variables and their order
explicitly.  The order of the fields of ?{Root} is
given by the canonical ordering of the respective
features <<d>>, <<e>>, <<m>>, <<n>>, <<o>>, <<r>>, <<s>>,
and <<y>>.

<p>
The statement
<chunk class=anonymous><title/{SearchAll Money}/
{Browse {SearchAll Money}}
</chunk>
will compute and display the list of all solutions
of the Send More Money Puzzle:
<<<
[sol(d:7 e:5 m:1 n:6 o:0 r:8 s:9 y:2)]
>>>

<p>
To understand the search process defined by
<<Money>>, we need more information than just the
list of solutions found.  Obviously, it would be
useful to see a graphical representation of the
search tree.  It would also be nice if we could
see for every node of the search tree what
information about the solution was accumulated in
the constraint store when the respective space
became stable.  Finally, it would be nice to see
for every arc of the tree with which constraint it
was distributed.

<p>
<ptr to="figConMoneyTree"> shows the search tree
explored by <<Money>> together with the information
just mentioned.  This gives us a good understanding
of the search process defined by <<Money>>.  Note
that the search tree is quite small compared to the
<math/10^8/ candidates a naive generate and test method
would have to consider.
<p>

<figure id="figConMoneyTree">
<caption/The search tree explored by <<Money>>./
<picture latex>
\begin{center}
\psset{unit=10pt}
\begin{pspicture}(33,23)\footnotesize

\myNode{12.6}{21}{top}{\texttt{sol(d:[2\#8]\ e:[4\#7]\ m:1\ n:[5\#8]\ o:0\ r:[2\#8]\ s:9\ y:[2\#8])}}

\myNode{2}{15}{left}{{\texttt{failure}}}
\myNode{20.6}{15}{right}{\texttt{sol(d:[2\#8]\ %
e:[5\#7]\ m:1\ n:[6\#8]\ o:0\ r:[2\#8]\ s:9\ y:[2\#8])}}

\myNode{9.6}{9}{sol}{\texttt{sol(d:7\ e:5\ m:1\ n:6\ o:0\ r:8\ s:9\ y:2)}}

\myNode{20.6}{6}{middle}{\texttt{sol(d:[2\#8]\ %
e:[6\#7]\ m:1\ n:[7\#8]\ o:0\ r:[2\#8]\ s:9\ y:[2\#8])}}

\myNode{16.6}{0}{botleft}{\texttt{failure}}
\myNode{24.6}{0}{botright}{\texttt{failure}}

\myLine{top}{left}
\Bput{\texttt{E$=$4}}
\myLine{top}{right}
\Aput{\texttt{E$\neq$4}}
\myLine{right}{sol}
\Bput{\texttt{E$=$5}}
\myLine{right}{middle}
\Aput{\texttt{E$\neq$5}}
\myLine{middle}{botleft}
\Bput{\texttt{E$=$6}}
\myLine{middle}{botright}
\Aput{\texttt{E$\neq$6}}
\end{pspicture}
\end{center}
</picture>
</figure>
</section>

<section id="section.problem.explorer">
  <title/The Explorer/

<p>
The Explorer is a graphical tool of the Mozart
programming environment.  It can run scripts and
display the explored search trees.  It can also
display the information in the constraint stores
associated with the nodes of the search tree.

<p>
The statement
<chunk class=anonymous><title/{ExploreAll Money}/
{ExploreAll Money}
</chunk>
tells the Explorer to run the script <<Money>> and
explore the entire search tree.  The Explorer
will pop up a window and display the explored
nodes of the search tree (see left part of
<Ptr to="figConOzSolver">).  Choice nodes
appear as blue circles, failure
nodes as red boxes, and solution nodes as
green diamonds.  Fully explored
subtrees not containing solution nodes are
collapsed into a single red triangle.

<P>
<figure id="figConOzSolver">
<caption/The Explorer with the search tree of <<Money>>./
<table class=dyptic id="fig.conozsolver.table">
<tr><td><Picture.Extern id="pic.explorer-a" to="explorer-a.gif" type=gif></td> 
    <td><Picture.Extern id="pic.explorer-b" to="explorer-b.gif" type=gif></td>
</tr>
</table>
</figure>

<p>
You can select any node of the displayed search
tree by clicking it with the left mouse button.
Select the red triangle and type the command <KBD/h/
(hide/unhide).  This will replace the triangle with
the actual nodes of the tree (see right part of
<Ptr to="figConOzSolver">).  You now see the
full search tree of <<Money>>, which consists of
three choice nodes, three failure nodes, and one
solution node.  Typing the command <KBD/h/ once more
will switch back to the compact representation of
the failed subtree.

<Para><title/double clicking nodes/
Next, double click the green solution node with
the left mouse button.
<p>
This will display the unique solution
<<<
sol(d:7 e:5 m:1 n:6 o:0 r:8 s:9 y:2)
>>>
of the Money Puzzle in the Browser.  You can also
double click a blue choice node.  This will
display the information about the solution that
was accumulated in the constraint store before
the node was distributed.  Double clicking the
top node of the tree, for instance, will display
<<<
sol(d:_[2#8]  e:_[4#7]  m:1  n:_[5#8] 
    o:0       r:_[2#8]  s:9  y:_[2#8])
>>>
in the Browser.  This way, the Explorer and the
Browser can display the annotated search tree
shown in <Ptr to="figConMoneyTree">.

<para><title/open and closed choice nodes/
The statement
<chunk class=anonymous><title/{ExploreOne Money}/
{ExploreOne Money}
</chunk>
tells the Explorer to run the script <<Money>>
until the first solution is found.  This time the
Explorer will show a partial search tree that
contains the solution node in the rightmost
position, and also contains an open choice node.
An <def/open choice node/ is a choice node for which
not all direct descendents have been explored yet.
A <Def/closed choice node/ is a choice node for
which all direct descendents have been explored
already.  While closed choice nodes are displayed
in dark blue, open choice nodes are displayed in
light blue.  Not yet explored descendents of an
open choice node are not displayed.

<p>
To check whether there are further solutions, you
can resume the search process by selecting the
root node and typing the command <KBD/n/ (next).
This will resume the search until either the next
solution is found or all nodes of the search tree
are explored.

<para><title/stopping exploration/
You can stop the exploring Explorer at any time
by typing the command <kbd/C-g/.

<para><title/resuming exploration/
You can resume the exploration of a partial
search tree by
selecting any choice node and typing the command
<kbd/n/  or <kbd/a/.  The command <kbd/n/  (next) will
resume the exploration of the selected subtree
until a further solution is found or the subtree
is fully explored.  The command <kbd/a/  (all) will
resume the exploration of the selected subtree
until it is fully explored.

<para><title/resetting the Explorer/
The command <kbd/C-r/ will reset the Explorer and
show only the
root node of the search tree.  By double clicking
you can see in the Browser what is known about the
solution before the first distribution step.  You
can request the exploration of the seach tree by
typing <kbd/n/ or <kbd/a/.

<para><title/hand-guided exploration/
You can guide the search of the Explorer by
hand.  Reset
the Explorer by typing <kbd/C-r/.  This will select
the root node, which is an open choice node.  Now
type the command <kbd/o/ (one) to compute the first
descendent of the root.  Select the root once
more and type <kbd/o/ again.  This will compute the
second and final descendent of the root.  Note
that the root has now changed from light blue
indicating an open choice node to dark blue
indicating a closed choice node.

<para><title/zooming the search tree/
The right vertical scroll bar of the Explorer's
window zooms
the size of the displayed search tree.  You can
zoom the tree to fit the size of the window by
clicking the zoom bar with the right mouse button.
<p>

<Exercise id="problem.ex.a">
With the Explorer it is easy to observe the
effect of different distribution strategies.
Replace the first-fail distribution strategy in
<<Money>>  with the naive strategy
<<<
{FD.distribute naive Root}
>>>
which distributes on the leftmost undetermined
variable and its least possible value.  Draw the
new search tree with the Explorer and observe
that it is twice as large as the tree obtained
with first-fail distribution.
</Exercise>

<Answer to="problem.ex.a">
This does not really require to be answered. Just try it.
</Answer>

<Exercise id="problem.ex.b">
Write a script that finds distinct digits for the
letters <math/A/, <math/B/, <math/D/, <math/E/, <math/G/, <math/L/,
<math/N/, <math/O/,
<math/R/, and <math/T/ such that the equation
<math display/
DONALD+GERALD=ROBERT
/
holds without leading zeros.  Run the script with
the Explorer and study the search tree.  Try both
first-fail and naive distribution.  Observe that
first-fail distribution yields a search tree that
is by one order of magnitude smaller than the
search tree obtained with naive distribution.
</Exercise>

<Answer to="problem.ex.b">
<chunk class=anonymous><title/Donald/
proc {Donald Root}
   sol(a:A b:B d:D e:E g:G l:L n:N  o:O r:R t:T) = Root
in
   Root ::: 0#9
   {FD.distinct Root}
   D\=:0  R\=:0  G\=:0
      100000*D + 10000*O + 1000*N + 100*A + 10*L + D
   +  100000*G + 10000*E + 1000*R + 100*A + 10*L + D
   =: 100000*R + 10000*O + 1000*B + 100*E + 10*R + T
   {FD.distribute split Root}
end
</chunk>
</Answer>

</section>

<section id="section.problem.primitives">
  <title/New Primitives/<p>

This section gives you an idea of the new Oz
primitives needed to express search engines
and finite domain scripts.

<p>
The new primitives come in two orthogonal groups.
The first group provides the ability to create
and distribute spaces and to explore search
trees.  This ability is essential for the
implementation of search engines based on the
propagate and distribute paradigm.  As was
mentioned before, this paradigm is general and
applies also to constraints other than finite
domain constraints.

<p>
The second group of primitives provides the
ability to create finite domain propagators and
to tell domain constraints to the constraint
store.  It also provides the ability to access
the domain of a variable in the current
constraint store, an expressivity needed for
programming distribution strategies.

<para><title/first-class spaces/
Oz provides spaces as first-class citizens that can be created,
distributed, and killed, among other things.  A
<def/first-class space/ is almost like Oz's unique
top-level space, where regular computation takes
place.  Like the top-level space, first-class
spaces have a constraint store, a procedure store,
and a cell store and can host any number of
threads.  One important difference between the
top-level and first-class spaces is the treatment
of failure, which is considered an error at the
top level and a regular event in first-class
spaces (<em/this space has no solution/).

<para><title/attributes of global objects cannot be assigned/
The <def/parent/ of a first-class space is the
space that created it.  The constraint and the
procedure store of a first-class space inherit all
constraints and procedures in the respective
stores of the parent space.  However, a
first-class space has no write access to the cell
store of its parent space.  Consequently, it is impossible to assign in a
first-class space attributes of objects that
belong to an ancestor space.  On the other hand, a
first-class space can create its own objects and
apply them freely.

<p>
The details of first-class spaces need only concern
programmers who want to implement new search
engines.  For finite domain problems, the necessary
search engines are already available as
predefined functionality (&eg;, <<SearchOne>> and
<<SearchAll>>).

<p>
All functionality related to finite domain
constraints is provided through the procedures of
the module <<FD>>.  We have already seen
<<FD.distinct>>  (creates a propagator) and
<<FD.distribute>>  (creates a distributor) in the
script for the Send More Money Puzzle (see
<Ptr to="section.problem.money">).  

<para><title/infix notations/
For some of the procedures of the module <<FD>>,
Oz provides special
infix notations governed by the following
operators:
<<<
   ::    :::    =:    \=:    <:    >:    =<:    >=:
>>>
You have already seen examples of the use of
<<:::>>, <<\=:>>, and <<=:>> in the script <<Money>>.
An equivalent version of Money not using these
notational conveniences appears in
<Ptr to="ProgMoneyNoGadgets">

<p>
<figure class="Figure" id="ProgMoneyNoGadgets">
<caption/A script for Money that does not use the
infix notations <<=:>> and <<\=:>>./
<chunk class=anonymous><title/MoneyRaw/
proc {Money Root}
   S E N D M O R Y
in
   Root = sol(s:S e:E n:N d:D m:M o:O r:R y:Y)
   {FD.dom 0#9 Root}
   {FD.distinct Root}
   {FD.sum [S] '\\=:' 0}
   {FD.sum [M] '\\=:' 0}
   {FD.sumC
    [1000  100   10  1  1000  100  10  1  ~10000  ~1000  ~100  ~10  ~1]
    [   S    E    N  D     M    O   R  E       M      O     N    E   Y]
    '=:'
    0}
   {FD.distribute ff Root}
end
</chunk>
</figure>
</section>

<section id="section.problem.watching">
  <title/Watching Propagators/

<p>
It is illuminating to watch the effect of
one or several propagators with the Browser.
Enter the following statements line by line and
observe in the Browser the shrinking domains of
the variables <<X>>, <<Y>>, and <<Z>>:
<chunk class=anonymous><title/WatchingPropagators/
declare X Y Z 
{Browse [X Y Z]}         % [X Y Z]
X :: 1#13                % [X[1#13] Y Z]
Y :: 0#27                % [X[1#13] Y[0#27] Z]
Z :: 1#12                % [X[1#13] Y[0#27] Z[1#12]]
2*Y =: Z                 % [X[1#13] Y[1#6]  Z[2#12]]
X <: Y                   % [X[1#5]  Y[2#6]  Z[4#12]]
Z <: 7                   % [X[1#2]  Y[2#3]  Z[4#6]]
X \=: 1                  % [2 3 6]
</chunk>
The comments say what you will see in the Browser.
Note that the statement <<2*Y=:Z>> creates a
propagator that performs interval rather than
domain propagation.
</section>

<section id="section.problem.safe">
  <title/Example: Safe/<p>

<subsection class=unnumbered>
  <title/Problem Specification/

<P>
The code of Professor Smart's safe is a sequence of
<math/9/ distinct nonzero digits <math/C_1,\ldots,C_9/ such that the
following equations and inequations are satisfied:
<math display/
\begin{array}{rcl}
&   C_4 - C_6 = C_7\\
&   C_1 * C_2 * C_3 = C_8 + C_9\\
&   C_2 + C_3 + C_6 < C_8\\
&   C_9 < C_8\\
&   C_1\neq1,\ldots, C_9\neq9
\end{array}
/
Can you determine the code?

<subsection class=unnumbered>
  <title/Model and Distribution Strategy/

<p>
We choose the obvious model that has a variable
for every digit <math/C_1,\ldots,C_9/.  We distribute over
these variables with the standard first-fail
strategy.

<p>
<figure class="Figure" id="ProgSafe">
<caption/A script for the Safe Puzzle./
<chunk class=anonymous><title/Safe/
proc {Safe C}
   {FD.tuple code 9 1#9 C}
   {FD.distinct C}
   C.4 - C.6 =: C.7
   C.1 * C.2 * C.3 =: C.8 + C.9
   C.2 + C.3 + C.6 <: C.8
   C.9 <: C.8
   {For 1 9 1 proc {$ I} C.I \=: I end}
   {FD.distribute ff C}
end
</chunk>
</figure>

<subsection class=unnumbered>
  <title/Script/

<p>
<Ptr to="ProgSafe"> shows a script for the Safe
Puzzle.  The statement
<<<
{FD.tuple code 9 1#9 C}
>>>
constrains the root variable <<C>> to a tuple
with label <<code>> whose components are
integers in the domain <<1#9>>.  The statement
<<<
{For 1 9 1 proc {$ I} C.I \=: I end}
>>>
posts the constraint <math/c.i\neq i/ for every
<math/i=1,\ldots,9/.

<p>
The full search tree of <<Safe>> has 23 nodes and
contains the unique solution:
<<<code(4 3 1 8 9 2 6 7 5)>>>
</section>

<![ %EXTRA; [
<section><title/NONE/
<p>
<chunk><title/EXAMPLES/
%%%
%%% Chapter: Writing Problem Solvers in Oz
%%%

%%
%% Example: Send More Money
%%

declare
<chunk.ref/Money/

<chunk.ref/{SearchAll Money}/



%%
%% The Explorer
%%

<chunk.ref/{ExploreAll Money}/

<chunk.ref/{ExploreOne Money}/



%%
%% New Primitives
%%

declare
<chunk.ref/MoneyRaw/

{ExploreAll Money}



%%
%% Watching Propagators
%%

<chunk.ref/WatchingPropagators/



%%
%% Example: Safe
%%

declare
<chunk.ref/Safe/

{ExploreAll Safe}



</chunk>
<chunk><title/ANSWERS/
%%%
%%% Chapter: Writing Problem Solvers in Oz
%%%

%%
%% DONALD + GERALD = ROBERT
%%

declare
<chunk.ref/Donald/

{ExploreAll Donald}



</chunk>
]]>

</chapter>




