PDB REFERENCE MANUAL

Version 4.0
HTML version by David Christianson and Chung Kwok

© 1990-1995 Copyright © University of Washington
Originally written by Tony Barrett.
Version (3.0) by David Christianson
Version (4.0) by Chung Kwok

This research was funded in part by Office of Naval Research Grants 90-J-1904s and N00014-94-1-0060, by National Science Foundation Grants IRI-8957302 and IRI-9303461 and by a donation from Apple Computer.

All rights reserved. Use of this software is permitted for non-commercial research purposes, and it may be copied only for that use. All copies must include this copyright message. This software is made available AS IS, and neither the authors nor the University of Washington make any warranty about the software or its performance.

When you first acquire this software please send mail to bug-ucpop@cs.washington.edu; the same address should be used for problems."

This document is best viewed with an HTML browser that supports tables.

Table of Contents

  1. Introduction
  2. Running PDB
  3. General window layouts
  4. Planning system overview
  5. Graphic plan space display
  6. Individual plan display
  7. PDB browsers
  8. A simple example
  9. Customizations and options
  10. Known bugs
  11. Porting PDB

Introduction

The primary function of PDB is to allow the user to schedule planning problems to be run by the planner, record the actions taken by the planner, and then reconstruct that information in a meaningful way. Since UCPOP does extensive search in plan-space, PDB focuses on recording and presenting plan-space search trees generated by the planner.

PDB is an interactive application which makes the UCPOP planning process more accessible to the user by the use of graphical interfaces to the planning process. It is intended to be used in several ways:

PDB exists because of the difficulty involved in performing planner research without adequate visualization tools. In the case of UCPOP, users who were trying to use the planner as well as programmers trying to improve and debug the system were having to wade through extensive trace information generated by the planner. PDB evolved as a way of presenting this information in a graphical format in order to make these tasks easier.

Running PDB

Recording Plans From The Lisp Listener To start PDB, just run (pdb-setup) in the UCPOP package. To start recording planning sessions, use PDB-RECORD:

(pdb-record &key (record-firings nil))

Then invoke the UCPOP planner. To stop recording, use PDB-STOP:

(pdb-stop)

If you use the def-searchprocedure to wrap around search functions, all planning sessions will be recorded when even the Recording toggle button in the shell. You can turn off the recording by clicking on the Recording toggle button in the shell (please refer to the Shell window).

General window layout

Menu and Menubar


All windows has a menubar. On all menubars there is a menu labelled "Windows". The menu has the following items:
Windows Refresh Redisplays the window contents.
Find Displays a list of active subwindows. Selecting a window will bring it to the front of the screen.
Remove all Closes all active subwindows.
Quit Close this window.
Note: the "Remove all" item is only available in the shell window.

Commands

You can click on buttons or objects on the screen highlighted by boxes. The effects will be discussed in subsequent sections.

Planning system overview

The Shell Window

The first window opened by PDB is the Plan System Overview Window. The right hand side of this window maintains a list of recorded planning sessions while the left hand side displays the state of the planner.

Specifying a Problem

In order to start a new planning session, select New Session from the Debugger menu. You will then be asked to specify the problem you want to solve and the search method to use via a dialog box. On the top left of the dialog box is a list of domains. Next to it is a list of problems. When the item ``Any'' is selected from the domain list, all problems are listed: otherwise this list only contains problems from the currently selected domain. Once a problem is selected, a complete description of the problem is presented in the area below the domain and problem lists.

Setting the Search Control Options

The controls beneath the problem description allow you to specify various search control options. The first button selects the type of search to use. When it is pushed in, the planner uses search control rules to guide search. When it is pushed out, the planner uses a specific search function. In the latter case, the user must use the box below this button to specify the search function to be used, whereas in the former case you will use this box to specify a search controller. The other controls allow you to specify whether or not to record the planning session, whether or not to record search control rule firings(this slows down planning considerably), as well as the maximum number of nodes to search.

Viewing the Results of Planning

Once you've specified the planning options and clicked the Plan button, PDB calls UCPOP to begin planning. The Plan System Overview Window displays a progress report on planning and returns the results of planning when done. These results include a short description of the last plan searched, which will be the solution if the planner was successful. PDB prints plans in the following manner: the initial state is printed first, then the steps in order to the goal state. Only the preconditions of the steps are displayed. Each precondition has a number to its left representing the step which supports that precondition. If the plan is not complete, any unsupported preconditions appear with question marks instead of numbers on the left, while threats are identified by the step number of the threatening step, shown to the right of the threatened condition.

Menu Commands

WindowsPlease refer to General window layout
Debug New Session Execute a new planning problem. This brings up a dialog window containing the following options:
Domain Domain to take problems from.
Problem Problem to execute.
Search Limit Number of nodes to search before stopping.
Search Control Yes or no. If yes, you must specify a controller. If no, you must specify a search function.
Record Debugging Yes if you want to record this as a session.
Record Firings Yes is you want to record all search control rule firings(slow).
New Browser Browse domains, problems, and search control.
Open Session Open a VCR window on a session.
Delete Session Delete a session so that it will no longer appear in the window.
Clear Session Delete all sessions. All sessions will be lost.
Options Reset Options Reads back the defaults saved in .plandebugrc
Save Options Writes defaults out to .plandebugrc

Plan System Overview Commands

The Sessions window (right) shows the sessions recorded by the system. The PlannerStatus window (left) shows various information about the session selected.
Info Display the result of the current session.
VCR Display a trace of the current session.
Remove Remove the current session.
Recording Toggle plan recording on/off.

Mouse Commands

Sessions
L Find Window Clicking the left mouse button on a session will select that session.

Graphic plan space display

The VCR Window

VCR Windows provide the user with a graphical depiction of the search space explored by the planner during a given planning session. Once the user has seleted a session in the Plan System Overview Window, they can create a VCR Window for that session either by selecting New VCR Window from the Debug menu, or by pressing the VCR button in the window itself.


Anatomy of the Search Tree

Most of the VCR Window is taken up by a graphical depiction of the planning trace in the form of a tree (we will refer to this as either the planning tree or the search tree). Each node in the tree is a partial plan; the root node plan contains only the start and goal states, while each subsequent generation represents one application of the UCPOP algorithm. The children of a given node represent individual solutions or refinements generated in the support or protection of a precondition. The type of refinement is printed beneath each node. Accordingly, each branch of the tree is associated with an unsupported or threatened precondition(known as a flaw), which is denoted by a label printed along the branch. Figure \ref{tree} gives a breakdown of these conventions.

The tree is formatted so that the left hand side of the tree leads to the last node encountered by the planner. If the solution was found, this will be the solution path. Note that the formatting algorithm puts nodes near the root of the tree farther apart than nodes at the leaves, so that sometimes you will have trouble using the VCR Window to view all the children of some nodes. You can solve some of these problems by changing or restricting the display of various nodes in the tree via the Tree and Options menus.

The label below nodes refers to the reason for which the plan is made. For example in the figure above "S:PUTON" means a new step "PUTON" is added, "L:0" means a new link to step 0 is added, and finally "3<1" means an ordering constraint (from promotion or demotion) is added.

The red node is the currently selected node. You can press the left or middle button.

L Select Node: Centers the cursor over this node. If the cursor is already at this node, PDB will open a plan window on that node.
M Describe object: If Composer is running, PDB will open a Composer window on the partial plan associated with this node.

The green is a visited node. A node (plan) is visited if the plan refined it during planning.

The white node is an unvisited node. The planner has not refined the plan during planning.

The word "CLEAR" above the horizontal line represents the open condition being resolved by the different siblings plans connected by the line.

Menu Commands

WindowsPlease refer to General window layout
Tree Print Print the current window. Asks for filename via dialog.
All Nodes Display all nodes in the tree.
Steps Only Display nodes for plans with newly added steps.
Searched Only Display only those nodes that have been searched.
Solution Only Display solution node only (if found).
Solution Path Only Display nodes on solution path (if found).
Expand Node Display the children of the current plan.
Contract Node Do not display the children of the current plan.
Expand Branch Display the branch rooted at the current plan.
Contract Branch Do not display the branch rooted at the current plan.
Options View Change the node picture of the tree nodes to one of the following
Order Color the nodes from dark to light green depending on visitation order.
Rank Color the nodes from dark to light green depending on the absolute rank.
Labels Label the node branches with conditions branched on:
all: Label all branches.
multiple: Label only branches with multiple children.
none: Don't label.
Resize Shrink or enlarge the displayed search tree by a constant factor.

VCR traversal buttons


These buttons are for navigating through the plan space and visualizing the planning process.

Backup the VCR until stop button is pressed.
Backup the VCR to the plan visited just prior to the current one.
Stops the VCR traversal animations.
Progress the VCR to the next visited plan.
Progress the VCR until a mouse button is pressed.

Mouse Commands

Plan Tree Nodes
Plan Window Markers
L: Select Window: Moves the window to another node. This is done by clicking once on the marker to move and once on the node to move to.

Individual plan display

The Plan Window

Clicking on a selected node produces a Plan Window, which provides a more detailed view of the plan associated with that node. The upper part of this window shows the parent, siblings, and children of the current node, while the lower part describes the plan at that node. The plan can be viewed in one of two ways: in textual format the plan is printed in the same way that the results of planning are returned by UCPOP, while in graphic format the steps are drawn in a partial order from left to right, with lines representing links connecting effects with preconditions.

Navigating the Plan Window

The small tree at the top of the Plan Window represents the immediate ``family'' of the current node: its parent, siblings, and children. It also allows you to navigate the planning tree simply by selecting any of these nodes: the Plan Window will immediately update itself using the node you selected as the new current node.

Moving the Plan Window from the VCR

Whenever a Plan Window is opened, a unique ID number is assigned to it and drawn next to the node in the VCR Window at which it is pointing. You can move the Plan Window to point at a different node just by selecting this number once and then selecting the new node.

Menu Commands

WindowsPlease refer to General window layout
Plan Refine Refine the current plan. Brings up a dialog with search options.
Search Limit Number of nodes to search before stopping.
Choose Flaw If yes, the user must select from a list of current flaws. Search limit will be set to 1.
Record Firings Yes to record all search control rule firings(slow).
Print Print the current window. Asks for filename via dialog.
Inspect Inspect the current node.
Options Graphics Change the representation of the plan
Graphics Graphical, partial-order view.
Text Textual View
Verbosity Control detail or representation
Verbose Print out conditions and steps fully
Terse Show only steps

Mouse Commands

Plan Tree Nodes
L Select Node Pressing the left button on a node causes the window to display the plan associated with that node. The navigational display is updated, as is the VCR window associated with the plan window.
M Describe object If Composer is running, a Composer window will be opened on the plan associated with the selected node.
Plan Structures
L Choose Flaw Pressing the left button on a flaw(shown in red) will bring up a plan refinement dialog with the selected flaw already chosen for refinement. Clicking the left button on other structures has no effect.
M Describe object If Composer is running, a Composer window will be opened on the structure associated with the highlighted graphic.
Shift-L Move Object Pressing Shift-L over a step in graphic display mode will let you drag the step to a new position. This allows you to view the plan in a more reasonable manner than the automatic layout provides.

History

On the bottom of the window is a simple history mechanism. It records the nodes visited and allows one to follow the path of plan exploration by the user in the plan window.

Go to the previous visited node.
Go to the next visited node.

PDB browsers

Browser Window

The PDB browser is used to provide an organized view and uniform frontend to inspect different objects related to planning problems, for example, domains, problems, axioms, facts, operators and sessions.

Menu Commands

WindowsPlease refer to General window layout
Object
Print Print the current window.
Inspect Inspect the current object.

Browser Commands

Scroll the browser menus towards the top of the heirarchy.
Scroll the browser menus towards the bottom of the heirarchy.

Mouse Commands

L Select Object Clicking on an item in one of the browser menus will bring up the menu associated with that item(if any) in the pane to the right of the selection, as well as the object associated with that item(if any).

A Simple Example

Specify a Problem

Select New Session from the Debugger menu. You will then be able to specify the domain and problem to use. Try selecting the uget-paid problem used in the previous section. Once you have done this, you are ready to specify the search control options.

Set the Search Control Options

Using the New Session dialog, set the search function to ucpop::bf-control. This is the same search function used for this problem in the previous example. For purposes of this example, you do not need to set any of the other options.

View the Results of Planning

When you click on the Plan button, UCPOP will begin planning. The Plan System Overview window will display a progress report, and return the results of planning when done. At this time, you will be able to see the solution generated by the planner.

Open a VCR Window

The session you just created should be listed in the Plan System Overview Window. Select this session with the left button and press the VCR button. This will bring up a VCR Window. You are now able to view the actual search tree explored by the planner.

Use the VCR Window

Experiment with the VCR Buttons, as well as with scrolling the tree around using the scrollbars.

Open a Plan Window

Scroll to the top left corner of the tree and select the node labeled START.
If you click on this node again, a Plan Window will appear. In this case, you will see that the plan has only the goal step and initial state in it. This is the first plan created by the planner. Now scroll down to the bottom left node (the solution), and open a new window on it. To see just how much work went into the uget-paid solution, go to the Options menu, from which you can select a graphical view of the plan. This view shows each step in the plan, with preconditions on the left and postconditions on the right. Links are drawn as lines between the steps. These links were inserted into the plan one at a time, each one represented by a branch in the tree.

Use the Plan Window

Explore the area around the START node using the Plan Window. Note how much easier it is to see the relationships between the various nodes compared to the VCR Window, where the whole tree is being displayed at once.

Customizations and options

Display types

Some of the defaults used by PDB are not appropriate for monochrome or grayscale displays. On such systems, PDB provides a set of defaults that are suitable.

You can define (setf *pdb-use-colors* nil) in your Lisp startup file (e.g. .clinit.cl on Allegro Common Lisp), or anytime before loading PDB. This will cause PDB to adopt monochrome defaults for its windows.

Variables

The following are some user customizable variables. You can customize PDB by defining a function and setf it to *pdb-startup-hook*. You can define this function in your Lisp initialization file; PDB will call this function when you run pdb-setup. For example: (defun my-pdb-init-function () (setf *shell-width* 900) (setf *plan-height* 1000)) (setf *pdb-startup-hook* #'my-pdb-init-function) The table below lists some of the variables that can be set:

VariableDescriptionDefault Note
*shell-width*
*shell-height*		 Width and height of the shell window. 600
400		 It is best not to set these variables below the defaults.
*vcr-width*
*vcr-height*		 Width and height of the VCR window. 800
600
*plan-height*
*plan-width*		 Width and height of the plan window. 500
400
*browser-height*
*browser-width*		 Width and height of the browser window. 500
400
*vcr-show-progress* When drawing the VCR window, a window indicating drawing progress will be displayed if this variable is set to t. t

There are other variables that customize colors and fonts as well. Please refer to the file "pdb/shell.lisp".

Known bugs

Some of these problems are resulted from bugs in CLIM2.0 implementation on AllegroCL 4.2. When you send bug reports, please check the list below first.

If PDB should ever crash, you can either continue by choosing one of the several continue options provided by your lisp system, or restart PDB. You can simply restart by issuing (pdb-setup) again. Restarting will erase all previous sessions. Please also include a stack trace (for example using :zoom in Allegro CL) and send a message to bug-ucpop@cs.washington.edu.

Porting PDB

PDB is written with flexibility in mind, and could be adopted to other partial order planners that is similar to UCPOP. PDB has already been ported to a descendent of UCPOP, XII. Work is under way to port PDB to other partial order planners such as Buridan.

If the planner is very similar to UCPOP, only functions specific to the planner need to be redefined. The file vcr-external.lisp contains the interface functions called by PDB to display plan components. You just need to redefine these functions for your planner. To change the PDB- Lisp-interpreter interface for your planner, modify the file vcr-interface.lisp.