\ignore{
\documentstyle[11pt]{report}
\textwidth 13.7cm
\textheight 21.5cm
\newcommand{\myimp}{\verb+ :- +}
\newcommand{\ignore}[1]{}
\def\definitionname{Definition}

\makeindex
\begin{document}
}
\chapter{\label{chapter:planner}The \texttt{planner} Module}
The \texttt{planner} module provides several predicates for solving planning problems. Given an initial state, a final state, and a set of possible actions, a planning problem is to find a plan that transforms the initial state to the final state. In order to use the \texttt{planner} module to solve a planning problem, users have to provide the condition for the final states and the state transition diagram through the following global predicates:\index{planning}\index{planner}
\begin{itemize}
\item \texttt{final($S$)}\index{\texttt{final/1}}: This predicate succeeds if $S$ is a final state.
\item \texttt{final($S$,$Plan$,$Cost$)}\index{\texttt{final/3}}: A final state can be reached from $S$ by the action sequence in $Plan$ with $Cost$. If this predicate is not given, then the system assumes the following definition:
\begin{verbatim}
    final(S,Plan,Cost) => Plan = [], Cost = 0, final(S).
\end{verbatim}

\item \texttt{action($S$,$NextS$,$Action$,$ActionCost$)}\index{\texttt{action/4}}: This predicate encodes the state transition diagram of the planning problem. The state $S$ can be transformed into $NextS$ by performing $Action$. The cost of $Action$ is $ActionCost$. If the plan's length is the only interest, then $ActionCost$ should be 1.
\end{itemize}

A state is normally a ground term. As all states are tabled during search, it is of paramount importance to find a good representation for states such that terms among states can be shared as much as possible.

In addition to the two required predicates given above, users can optionally provide the following global procedures to assist Picat in searching for plans:
\begin{itemize}
\item \texttt{heuristic($S$)}\index{\texttt{heuristic/1}}: This function returns an estimation of the resource amount needed to transform $S$ into a goal state. This estimation is said to be \textit{admissible} if it never exceeds the real cost. All heuristic estimations must be admissible in order for the planner to find optimal plans. This function is used by the planner to check the heuristic estimation before each state expansion.

\item \texttt{sequence($P$,$Action$)}\index{\texttt{sequence/2}}: This predicate binds $Action$ to a viable action form based on the current partial plan $P$. Note that the actions in list $P$ are in reversed order, with the most recent action occurring first in the list, and the first action occurring last in the list. The planner calls \texttt{sequence/2} to find an action for expanding the current state before calling \texttt{action/4}. For example,
\begin{verbatim}
sequence([move(R,X,Y)|_], Action) ?=> Action = $move(R,Y,_).
sequence([move(R,_,_)|_], Action) ?=> Action = $jump(R).
sequence([move(R,_,_)|_], Action) => Action = $wait(R).
sequence(_, _) => true.
\end{verbatim}
These sequence rules ban robots from moving in an interleaving fashion; a robot must continue to move until it takes the action \texttt{jump} or \texttt{wait} before another robot can start moving. The last rule \texttt{sequence(\_, \_) => true} is necessary; it permits any action to be taken if the partial plan is empty, or if the most recent action in the partial plan is not \texttt{move}.
\end{itemize}

\section{Depth-Bounded Search}
Depth-bounded search amounts to exploring the search space, taking into account the current available resource amount. A new state is only explored if the available resource amount is non-negative. When depth-bounded search is used, the function {\tt current\_resource()} can be used to retrieve the current resource amount. If the heuristic estimate of the cost to travel from the current state to the final state is greater than the available resource amount, then the current state fails.

\begin{itemize}
\item \texttt{plan($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{plan/4}}: This predicate, if it succeeds, binds $Plan$ to a plan that can transform state $S$ to a final state that satisfies the condition given by {\tt final/1} or {\tt final/3}. $Cost$ is the cost of $Plan$, which cannot exceed $Limit$, which is a given non-negative integer. 

\item \texttt{plan($S$,$Limit$,$Plan$)}: If the second argument is an integer, then this predicate is the same as the \texttt{plan/4} predicate, except that the plan's cost is not returned. 

\item \texttt{plan($S$,$Plan$,$Cost$)}:\index{\texttt{plan/3}} If the second argument is a variable, then this predicate is the same as the \texttt{plan/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{plan($S$,$Plan$)}\index{\texttt{plan/2}}: This predicate is the same as the \texttt{plan/4} predicate, except that the limit is assumed to be 268435455, and that the plan's cost is not returned.

\item \texttt{best\_plan($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{best\_plan/4}}: This predicate finds an optimal plan by using the following algorithm:  It first calls {\tt plan/4} to find a plan of 0 cost. If no plan is found, then it increases the cost limit to 1 or double the cost limit. Once a plan is found, the algorithm uses binary search to find an optimal plan.

\item \texttt{best\_plan($S$,$Limit$,$Plan$)}: If the second argument is an integer, then this predicate is the same as the \texttt{best\_plan/4} predicate, except that the plan's cost is not returned. 

\item \texttt{best\_plan($S$,$Plan$,$Cost$)}\index{\texttt{best\_plan/3}}: If the second argument is a variable, then this predicate is the same as the \texttt{best\_plan/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{best\_plan($S$,$Plan$)}\index{\texttt{best\_plan/2}}: This predicate is the same as the \texttt{best\_plan/4} predicate, except that the limit is assumed to be 268435455, and that the plan's cost is not returned.

\item \texttt{best\_plan\_bb($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_bb/4}}: 
This predicate, if it succeeds, binds $Plan$ to an optimal plan that can transform state $S$ to a final state. $Cost$ is the cost of $Plan$, which cannot exceed $Limit$, which is a given non-negative integer. The branch-and-bound algorithm is used to find an optimal plan.

\item \texttt{best\_plan\_bb($S$,$Limit$,$Plan$)}: If the second argument is an integer, then this predicate is the same as the \texttt{best\_plan\_bb/4} predicate, except that the plan's cost is not returned. 

\item \texttt{best\_plan\_bb($S$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_bb/3}}: If the second argument is a variable, then this predicate is the same as the \texttt{best\_plan\_bb/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{best\_plan\_bb($S$,$Plan$)}\index{\texttt{best\_plan\_bb/2}}: 
This predicate is the same as the \texttt{best\_plan\_bb/4} predicate, except that the limit is assumed to be 268435455, and that the plan's cost is not returned.

\item \texttt{best\_plan\_bin($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_bin/4}}: 
This predicate, if it succeeds, binds $Plan$ to an optimal plan that can transform state $S$ to a final state. $Cost$ is the cost of $Plan$, which cannot exceed $Limit$, which is a given non-negative integer. The branch-and-bound algorithm is used with binary search to find an optimal plan.

\item \texttt{best\_plan\_bin($S$,$Limit$,$Plan$)}: If the second argument is an integer, then this predicate is the same as the \texttt{best\_plan\_bin/4} predicate, except that the plan's cost is not returned. 

\item \texttt{best\_plan\_bin($S$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_bin/3}}: If the second argument is a variable, then this predicate is the same as the \texttt{best\_plan\_bin/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{best\_plan\_bin($S$,$Plan$)}\index{\texttt{best\_plan\_bin/2}}: 
This predicate is the same as the \texttt{best\_plan\_bin/4} predicate, except that the limit is assumed to be 268435455, and that the plan's cost is not returned.

\item \texttt{current\_resource()=$Amount$}\index{\texttt{current\_resource/0}}: This function returns the current available resource amount of the current node. If the current execution path was not initiated by one of the calls that performs resource-bounded search, then 268435455 is returned. This function can be used to check the heuristics. If the heuristic estimate of the cost to travel from the current state to a final state is greater than the available resource amount, then the current state can be failed.

\item \texttt{current\_plan()=$Plan$}\index{\texttt{current\_plan/0}}: This function returns the current plan that has transformed the initial state to the current state. If the current execution path was not initiated by one of the calls that performs resource-bounded search, then [] is returned.

\item \texttt{current\_resource\_plan\_cost($Amount$,$Plan$,$Cost$)}\index{\texttt{current\_resource\_plan\_cost/3}}: This predicate retrieves the attributes of the current node in the search tree, including the resource amount, the path to the node, and its cost.

\item \texttt{is\_tabled\_state($S$)}\index{\texttt{is\_tabled\_state/1}}: This predicate succeeds if the state $S$ has been explored before and has been tabled.
\end{itemize}

\section{Depth-Unbounded Search}
In contrast to depth-bounded search, depth-unbounded search does not take into account the available resource amount. A new state can be explored even if no resource is available for the exploration. The advantage of depth-unbounded search is that failed states are never re-explored.

\begin{itemize}
\item \texttt{best\_plan\_nondet($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_nondet/4}}: This predicate is the same as \\\texttt{best\_plan($S$,$Limit$,$Plan$,$Cost$)}, except that it allows multiple best plans to be returned through backtracking.

\item \texttt{best\_plan\_nondet($S$,$Limit$,$Plan$)}: If the second argument is an integer, then this predicate is the same as the \texttt{best\_plan\_nondet/4} predicate, except that the plan's cost is not returned. 

\item \texttt{best\_plan\_nondet($S$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_nondet/3}}: If the second argument is a variable, then this predicate is the same as the \texttt{best\_plan\_nondet/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{best\_plan\_nondet($S$,$Plan$)}\index{\texttt{best\_plan\_nondet/2}}: This predicate is the same as the \texttt{best\_plan\_nondet/4} predicate, except that the limit is assumed to be 268435455, and that the plan's cost is not returned.

\item \texttt{plan\_unbounded($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{plan\_unbounded/4}}: This predicate, if it succeeds, binds $Plan$ to a plan that can transform state $S$ to a final state. $Cost$ is the cost of $Plan$, which cannot exceed $Limit$, which is a given non-negative integer.

\item \texttt{plan\_unbounded($S$,$Limit$,$Plan$)} If the second argument is an integer, then this predicate is the same as the \texttt{plan\_unbounded/4} predicate, except that the plan's cost is not returned. 

\item \texttt{plan\_unbounded($S$,$Plan$,$Cost$)}\index{\texttt{plan\_unbounded/3}}: If the second argument is a variable, then this predicate is the same as the \texttt{plan\_unbounded/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{plan\_unbounded($S$,$Plan$)}\index{\texttt{plan\_unbounded/2}}: This predicate is the same as the above predicate, except that the limit is assumed to be 268435455.

\item \texttt{best\_plan\_unbounded($S$,$Limit$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_unbounded/4}}: This predicate, if it succeeds, binds $Plan$ to an optimal plan that can transform state $S$ to a final state. $Cost$ is the cost of $Plan$, which cannot exceed $Limit$, which is a given non-negative integer.

\item \texttt{best\_plan\_unbounded($S$,$Limit$,$Plan$)} If the second argument is an integer, then this predicate is the same as the \texttt{best\_plan\_unbounded/4} predicate, except that the plan's cost is not returned.

\item \texttt{best\_plan\_unbounded($S$,$Plan$,$Cost$)}\index{\texttt{best\_plan\_unbounded/3}}: If the second argument is a variable, then this predicate is the same as the \texttt{best\_plan\_unbounded/4} predicate, except that the limit is assumed to be 268435455.

\item \texttt{best\_plan\_unbounded($S$,$Plan$)}\index{\texttt{best\_plan\_unbounded/2}}: This predicate is the same as the above predicate, except that the limit is assumed to be 268435455.
\end{itemize}

\section{Examples}
The program shown in Figure \ref{fig:farmer2} solves the Farmer's problem by using the \texttt{planner} module. 

\begin{figure}
\begin{center}
\begin{verbatim}
    import planner.

    go =>
        S0 = [s,s,s,s],
        best_plan(S0,Plan),
        writeln(Plan).

    final([n,n,n,n]) => true.

    action([F,F,G,C],S1,Action,ActionCost) ?=>
        Action = farmer_wolf,
        ActionCost = 1,        
        opposite(F,F1),
        S1 = [F1,F1,G,C],
        not unsafe(S1).
    action([F,W,F,C],S1,Action,ActionCost) ?=>
        Action = farmer_goat,
        ActionCost = 1,        
        opposite(F,F1),
        S1 = [F1,W,F1,C],
        not unsafe(S1).
    action([F,W,G,F],S1,Action,ActionCost) ?=>
        Action = farmer_cabbage,
        ActionCost = 1,        
        opposite(F,F1),
        S1 = [F1,W,G,F1],
        not unsafe(S1).
    action([F,W,G,C],S1,Action,ActionCost) =>
        Action = farmer_alone,
        ActionCost = 1,        
        opposite(F,F1),
        S1 = [F1,W,G,C],
        not unsafe(S1).

    index (+,-) (-,+)
    opposite(n,s).
    opposite(s,n).

    unsafe([F,W,G,_C]), W == G, F !== W => true.
    unsafe([F,_W,G,C]), G == C, F !== G => true.
\end{verbatim}
\end{center}
\caption{\label{fig:farmer2}A program for the Farmer's problem using \texttt{planner}.}
\end{figure}

Figure \ref{fig:15puzzlesol} gives a program for the 15-puzzle problem. A state is represented as a list of sixteen locations, each of which takes the form \texttt{($R_i$,$C_i$)}, where $R_i$ is a row number and $C_i$ is a column number. The first element in the list gives the position of the empty square, and the remaining elements in the list give the positions of the numbered tiles from 1 to 15. The function \texttt{heuristic(Tiles)} returns the Manhattan distance between the current state and the final state.

\begin{figure}[t]
\begin{center}
\begin{verbatim}
import planner.

main =>
    InitS = [(1,2),(2,2),(4,4),(1,3),
             (1,1),(3,2),(1,4),(2,4),
             (4,2),(3,1),(3,3),(2,3),
             (2,1),(4,1),(4,3),(3,4)],
    best_plan(InitS,Plan),
    foreach (Action in Plan)
       println(Action)
    end.

final(State) => State = [(1,1),(1,2),(1,3),(1,4),
                         (2,1),(2,2),(2,3),(2,4),
                         (3,1),(3,2),(3,3),(3,4),
                         (4,1),(4,2),(4,3),(4,4)].

action([P0@(R0,C0)|Tiles],NextS,Action,Cost) =>
    Cost = 1,
    (R1 = R0-1, R1 >= 1, C1 = C0, Action = up;
     R1 = R0+1, R1 =< 4, C1 = C0, Action = down;
     R1 = R0, C1 = C0-1, C1 >= 1, Action = left;
     R1 = R0, C1 = C0+1, C1 =< 4, Action = right),
    P1 = (R1,C1),
    slide(P0,P1,Tiles,NTiles),
    NextS = [P1|NTiles].

% slide the tile at P1 to the empty square at P0
slide(P0,P1,[P1|Tiles],NTiles) =>
    NTiles = [P0|Tiles].
slide(P0,P1,[Tile|Tiles],NTiles) =>
    NTiles = [Tile|NTilesR],
    slide(P0,P1,Tiles,NTilesR).

heuristic([_|Tiles]) = Dist =>
    final([_|FTiles]),
    Dist = sum([abs(R-FR)+abs(C-FC) : 
                {(R,C),(FR,FC)} in zip(Tiles,FTiles)]).
\end{verbatim}
\end{center}
\caption{\label{fig:15puzzlesol}A program for the 15-puzzle}
\end{figure}



