$Id: HELLOWORLD,v 1.5 2005/12/09 18:40:13 pjarvis Exp $

Note: Please first see the file README in this directory for details
      on how to checkout, build, and test Europa2 before attempting
      to create your own project. 

      Each section of this document builds on the next. These step 
      by step instructions for creating, running, and visualizing
      a plan MUST be completed in order.


A. Creating your own project

A script is available to get you started with your own project. It
will create a directory for your project as a sibling directory to
PLASMA and populate it with a build setup, initial model, initial
state, and a main executable to use a standard Europa2 assembly,
including a planner.  We will illustrate its use with a sample
project called HelloWorld:

        cd PLASMA
        makeproject HelloWorld
        cd ../HelloWorld
        jam HelloWorld

You will observe that an executable is built and executed, resulting
in a plan.  Also, observe that a shared library libHelloWorld_g.so
is built. This library file is used instead of the executable when 
planner execution is controlled from PlanWorks. (See section C below.)

The results of the plan are found in the file:

     RUN_HelloWorld-planner_g_rt.HelloWorld-initial-state.xml.output

You may now change the model and initial state and simply
retype 'jam HelloWorld' to rebuild as necessary and rerun.


B. Visualizing Your Plan in PlanWorks

1. Installing PlanWorks

   Follow the directions in the PlanWorks README and GETTING_STARTED
   files found in the PlanWorks directory to install and use PlanWorks
   before attempting the remaining steps.

2. Configuring the Europa2 transaction logger:

   Before using PlanWorks to visualize a plan, the planner must be run
   with the logger (PartialPlanWriter) enabled and properly configured.
   A default PartialPlanWriter configuration file is supplied with
   Europa2 but is not accessed unless the environment variable PPW_CONFIG
   is set to the location of this file. The file can be renamed and moved
   to another location as long as PPW_CONFIG is updated.

   If you created the HelloWorld in section A above, the default
   configuration file is called: 

   PlanWorks.cfg

   Otherwise, a sample PPW configuration file can be found at:

   /home/me/PLASMA/CBPlanner/component/PlanWorks.cfg
   Where:
     /home/me is the full path to the PLASMA directory.

   Here is an example for the csh shell of how PPW_CONFIG is set:

   setenv PPW_CONFIG /home/me/HelloWorld/PlanWorks.cfg

   Of course, "/home/me" must be changed to the full path to the PLASMA
   directory that was created by the PLASMA CVS checkout.

   To enable planner logging, edit the line in PlanWorks.cfg that configures
   AutoWrite. Set it to 'AutoWrite=1'. Notice the line 'WriteDest=./plans'.
   This directs the logger output to the directory './plans' (plans will be
   a subdirectory of the directory the planner was run from.) WriteDest
   may be set to whatever path you want as long as you have write access.

   The PartialPlanWriter can generate large amounts of information if the
   plans have many steps. Besides using a lot of disk space, the logger
   seriously slows the planner's performance. When debugging large plans
   you might at first want to look at the final plan step or the last step
   before the planner timed out. To enable writing only the last step, 
   uncomment and set 'WriteFinalStep=1' and set 'AutoWrite=0' in the 
   PlanWorks.cfg file.

   Once the logger has been configured, rerun the plan as specified in
   section A 'Creating your own project' by entering:

        jam HelloWorld

   When the run completes, check that you now have a "plans" subdirectory
   before going on to the next step.

3. Creating a PlanWorks Project and Selecting a Planning Sequence

   Once you have run your plan with logging properly enabled you can
   create a PlanWorks Project and add a Project Sequence. Details of
   using PlanWorks are found in the PlanWorks GETTING_STARTED file.

        cd ../PlanWorks
        ant

   Once in PlanWorks select "Project--->Create" from the top level menu bar.
   This will bring up a Create Project window. Type "HelloWorld" in the
   "name" field (any name will work). In the "working directory" field, enter
   the full path of the directory that contains your plan sequences. This
   directory will be something like /home/me/HelloWorld/plans. Click on
   the "Enter" button. A "Select Planning Sequence Directory" window will
   appear. Sequence directory(ies) created for your plan by the 
   PartialPlanWriter are found in this directory. Select a plan directory
   and click the "OK" button.

4. Visualizing your plan

   Once a PlanWorks project has been created and a sequence directory has
   been selected you are ready to visualize your plan. Select 
   "PlanningSequence" from the top level menu bar. Now select your sequence,
   if you have been using the names in this example, the name of your
   sequence will be "HelloWorld-model". Click on this.

   A window called "SequenceStepsView of HelloWorld-model" should appear.
   Note the sequence of vertical bars in the window. Each vertical bar
   represents a partial plan. If the planner found a plan, the vertical
   bar on the far right will represent your completed plan. A yellow dot 
   above this bar indicates that planner data was logged for this step. 
   A red dot indicates that no plan data was logged and implies that your 
   PlanWorks.cfg file may not be properly configured. Scroll to the 
   vertical bar on the far right and right click anywhere on this bar.A 
   menu will appear with a list of items that you can now visualize.

   You can select these item one at a time or you can select them all at
   once with the "Open all Views" menu item at the bottom of the list.
   Once a view has been opened the yellow dot will turn green indicating
   that the data for this step has been loaded in the PlanWorks database.

   For more details on using PlanWorks to visualize your model, see the
   GETTING_STARTED file in the PlanWorks home directory.


C. Running a plan from PlanWorks

   The CBPlanner supplied in the Europa2 Standard Assembly implements a
   planner control interface that allows a client such as PlanWorks to 
   control planner execution on a per plan step basis.

1. Reconfiguring PlanWorks.cfg

   Before using PlanWorks to control the planner, a modification to your 
   PlanWorks.cfg file may be required. First, if you are still in PlanWorks 
   from the previous step, exit out using the "File" menu selection.
   Return to your HelloWorld directory and edit the PlanWorks.cfg file as
   follows:
   
        Set WriteDest=/home/me/HelloWorld/plans 

   This change is required since PlanWorks will be running from a directory
   other than HelloWorld, so "WriteDest=./plans" is no longer appropriate
   to describe the path to HelloWorld/plans.

   Next, uncomment the two lines of the RuleConfigSection and set the SourcePath
   to the project directory. This tells the PPW where to look for the nddl files
   that contain the rules source code.

        RuleConfigSection:
        SourcePath=/home/me/HelloWorld

   Once the logger has been reconfigured, rerun the plan as specified in
   section A 'Creating your own project' by entering:

        jam HelloWorld

   When the run completes, check that you now have an additional plan in your
   "plans" subdirectory before going on to the next step.

2. Selecting a PlanWorks Project 

   Return to your PlanWorks directory. NOTE: If you did not run "ant createJNI"
   when you first built PlanWorks, run it now before starting PlanWorks. 

        cd ../PlanWorks
        ant createJNI
        ant

   Once in PlanWorks select "Project--->Open" from the top level menu bar.
   This assumes you previously created a PlanWorks project in section B.
   This will bring up an "Open Project" window. Select "HelloWorld" if
   not already selected. Click on the "OK" button.

3. Configuring a PlanWorks Project 

   You need to create a controller for Planworks. Type
   
   /home/me/Helloworld/jam HelloWorldController 

   Once a project has been opened, select "Project--->Configure" from the 
   top level menu bar. This will bring up a "Configure Project" window with
   "HelloWorld" in the "name" field. The "working directory" field, should
   have the full path of the directory that contains your plan sequences.
   If not, enter it now. The browse button may be used to assist in finding
   the path.

   In the "planner library path" enter the full path to the controller in your 
   project. e.g.

   /home/me/HelloWorld/libHelloWorldControllor_g.so

   In the "model library path" field, enter the full path to the model 
   shared library in HelloWorld.This is the model shared library that was 
   created in your HelloWorld directory. The full path will look like:

   /home/me/HelloWorld/libHelloWorld_g.so

   In the "model initial state path" field, enter the full path to the model 
   initial state xml file in HelloWorld. The full path will look like:

   /home/me/HelloWorld/HelloWorld-initial-state.xml

   In the "model output destination directory" field, enter the full path to 
   the plans directory. The full path will look like:

   /home/me/HelloWorld/plans

   In the "planner config path" field, enter the full path and name to
   planner config file. It will look like:

   /home/me/HelloWorld/PlannerConfig.xml

   Once all of the fields have been entered, click on the "Enter" button.

   Set the heuristics to 

   /home/me/plasma/HeuristicsEngine/test/DefaultHeuristics.xml

4. Getting a Planner Controller Window

   Once a project has been configured, you are ready to run your plan from
   PlanWorks. Select "Project--->New Sequence" from the top level menu bar. 
   This will bring up a "Create New Sequence" window. All of the fields will
   be already filled in by PlanWorks using the information  you provided
   above. Check all fields are correct and then click on the "Start" button.

   If PlanWorks successfully finds all of your required files, a "Transaction 
   Types to Log" window will appear. (If it does not appear after a few seconds, 
   you can check the terminal window for troubleshooting information.) The check 
   list of Transaction Types allows you to disable logging certain transactions 
   in order to speed plan execution. Click on the "OK" button.

   A new window titled "PlannerController for HelloWorld" will come up. From
   this window you have the following options:
   
     a. Skip to step number N  - the planner will run to step N and log data
                                 for only that step.
     b. Write next N steps ----- the planner will run for the next N steps
                                 logging data for each step.
     c. WriteFinalStep --------- the planner will run to completion logging
                                 data for only the last step of the plan.
     d. TerminatePlanner ------- the planner will terminate and unload the 
                                 model.

   To try out these options enter "5" in the "Skip to step number" field and 
   click on the adjacent "Go" button. Note that the SequenceStepsView contains
   six vertical bars with the last bar indicating that data was logged for step
   five. You can right click on this bar and a menu will appear with items 
   that you can now visualize for this step.

   Now enter "4" in the "Write next N steps" field and click on the adjacent 
   "Go" button. Note that four more vertical bars have appeared all indicating
   that data was logged. You can now right click on any of these bars to 
   visualize the steps.

   To complete the plan click on the "Write Final Step" button. The Planner 
   status in the upper left hand corner of the PlannerController will change
   from "Ready" to "Running" while the Europa2 CBPlanner has control. 

   Once the plan completes a "Planner Status" window should come up. Unless 
   you have modified the model it should report that the planner "Found a plan."
   Click on the "OK" button. The vertical bar on the far write of the
   SequenceStepsView represents the final plan and should have a yellow dot. 
   Right click on this bar to visualize the final plan.

5. Rerunning the Same Plan from PlanWorks

   Once a plan has been run to completion or terminated, it can be rerun 
   without exiting PlanWorks. You can make changes to your plan in a 
   terminal window outside of PlanWorks and create new model library
   and initial state files using "jam libHelloWorld_g.so" in the 
   HelloWorld directory.

   To rerun a plan from PlanWorks select "Project--->New Sequence" from the 
   top level menu bar. All of the fields should be filled in and should be OK
   as long as none of the names have changed for your model. Click on the
   "Start" button as before. Click the "OK" button of the "Transaction Types
   to Log" window and a new PlannerController window will appear.


