
How to run the planner: 
======================

COPLAS is written in Sicstus prolog version 3. I has been tested in a
Ultra 1 station running Solaris System 2.5.1. Although the planner has
not been tested in other platforms it it should work in any system
running Sicstus 3.

Before running the planner is necessary to create a file with a domain
description. (See report for details).  In your domain description you
must include the goal for which you would like to find a plan. The
format for a goal of the form fl1,...,fln is:

    goal([fl1,...,fln]).

For example, in the first example above the goal will be:

goal([at(paycheck,home), at(dictionary,office), at(briefcase,home)]).

Order in the list is irrelevant. You must also add the following
heading to the domain file:

%==========HEADINGS===================================== 
:- multifile causes/3. 
:- multifile affects/3. 
:- multifile sensing/1. 
:- multifile initially/1. 
:- multifile initially.unknown/1. 
:- multifile axiom/2. 
%=======================================================


You must also define for each action symbol a heuristic function and
rewrite the executavility conditions in a special format. How these
functions can be defined and the re-writing rules will be explained in
the next section.

After you create your domain file do the following steps. Let assume
the file where the domain is stored is called domain.pl

1. Start your prolog interpreter.

2. Consult the planner: consult(planner).
The file planner.pl must be in your local directory in order for this
command to execute successfully.

3. Consult your domain description: consult('domain.pl'). 
The file domain.pl must be in your local directory in order for this
command to execute successfully.

4. Run the query: plan.

If you would like to run a new example with a new domain, let say,
domain1.pl, after you get the answer for the previous query do the
following.

1. Clean the environment by typing the query: clean all. 

2. Consult your new domain description: consult('domain1.pl'). 
The file domain1.pl must be in your local directory in order for this
command to execute successfully.

4.  Answer "y" to all the renamings, if any.

3. Run the query: plan.

If the planner is compiled before loading it the system will have much
better per performance. To compile using Sicstus execute the following
steps.

1. Start your prolog interpreter. 

2. Compile the planner: fcompile(planner).
The file planner.pl must be in your local directory in order for this
command to execute successfully.

3. Exit the the interpreter. 

This sequence of steps will generate a new file planner.ql the
compiled version of the planner. To run the example using the compiled
planner do the following steps.

1. Start your prolog interpreter. 

2. Load the planner: load(planner).
The file planner.ql must be in your local directory in order for this
command to execute successfully.

3. Consult your domain description: consult('domain.pl'). 
The file domain.pl must be in your local directory in order for this
command to execute successfully.

4. Run the query: plan. 

You can switch domains by following the same steps as above. Recall
that since the domain includes the goal, if you would like only to
change the goal, you should go to your domain file, change the file and
follow the steps for running the planner with a new domain.

Limitations and features of the current version: 
===============================================

Planning is a computational complex process. There will be very few
examples that will run without guiding the planner on how to search
for a plan in the search space. There several domain independent
heuristics that can be implemented. The most obvious is to avoid plans
that take you back to a previous visited situation. In the current
implementation there is only a simple check done. When an actions is
executed the planner verify that the actions does not take you back to
the previous state.

In addition to domain independent heuristics is also important to have
domain dependent heuristics. In the current version the user can add
heuristics by defined prolog predicates of the form:

heuristic(Action,Situation,Plan)

where Situation is the situation where the Action is about to be
applied and Plan is the plan where the Action will be added. In its
current version the parameter Plan has very little for non-sequential
plans (i.e. plans that includes if) because it does not identify to
which branch the Action will be added.

An example of heuristic functions in the briefcase domain is the following:

heuristic(move_b(_),_,_).

heuristic( take_out( X), Situation,_) :-
      goal( Goal),  
      location( L), 
      true_in_state( at( X, L), Situation),
      member( at( X, L), Goal). 

heuristic( put_in( X), Situation,_) :-
      object(X), location( L), 
      true_in_state( at( X, L), Situation), 
      goal( Goal), 
      \+ member( at( X, L), Goal).

The first rule defines no heuristic for the action move_b.  In
general, for an action symbol a of arity n, if no heuristic is defined
the domain description must include:

heuristic(a(_ ,...,_ ),_,_).

The second rule defines a heuristic for the action take out. An object
will be taken out from the briefcase only if that object must state at
its current location according to the goal. The last rule says that if
an object is not located in the place where the goal specifies the
object should be, the planner should put the object in the briefcase
(to be moved). Both heuristic functions use the predicate true in
state( Fluent, Situation). As the name suggests this predicate checks
if the Fluent is true in the Situation. The predicates false in state
and unknown in state are also available to the user for heuristic
definitions.

Executavility conditions: 
========================

To improve performance you must re-write the executavility conditions
of your domain into new prolog predicates. If you have a executavility
condition of the form:

possible(A,[P1,...,Pn])

write in your domain:

possible(A,Situation) :-
       fluentliteral(L1), 
       test(L1,Situation), 
       ..., 
       fluentliteral(Ln),
       test(Ln,Situation).

where Li is equal to Pi and test is true in state if Pi is positive
fluent literal. Otherwise, if Pi is of the form neg(F), Li is F and
test is false in state. For example, the condition

     possible(put_in(X),[neg(in(X)),at(brief_case,L),at(X,L)]) 

is translated into:

possible(put_in(X),Situation) :-
        fluentliteral(in(X)), 
        false_in_state(in(X), Situation), 
        fluentliteral(at(briefcase,L), 
        true_in_state(at(briefcase,L), Situation), 
        fluentliteral(at(X,L)),
        true_in_state( at(X,L), Situation).

For sensing action symbols we will restrict the domains to only one
knowledge law per action and no preconditions.  Thus, for a
executavility condition of the form:

sensing possible(A,[P1,...,Pn])

write in your domain:

sensing_possible(A,Situation) :-
         unknown_in_state(F,Situation), 
         fluentliteral(L1), 
         test(L1,Situation),
         ..., 
         fluentliteral(Ln),
         test(Ln,Situation).

where F is the fluent being sensed by the action A and the rest is
defined as above. For example, the condition sensing 

     possible(check_in(O),[]) 

is translated into:

sensing_possible(check_in(O),Situation) :-
        unknown_in_state(in(O),Situation).

If you are using the planner in classroom situation where you would
like to strictly separate the domain description from the planner
implementation you can make the following modifications to the
planner.

Find in the planner the two lines with the comment 

  % independent exec. conditions 

and remove the % symbol from the front of the line.  Find in the
planner the two lines with the comment

  % dependent exec. conditions 

and add the % symbol to the front of the line.

This modification to the coding of executavility conditions will slow
down the performance of the planner about 10%.

=====================================================================
For bugs send mail to jorge@eecs.uic.edu
Copyright: 1998, Jorge Lobo.
=====================================================================
