# 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:

- Domain Construction
- Search Control Development
- Planner Modification

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

To start PDB, just run

`(pdb-setup)`

in the UCPOP package. Please wait until the window pops up before you issue any UCPOP-related commands. `(pdb-setup)` will also start up composer if you have Allegro Composer v.2.0 and it is not already started. If you don't want to start composer automatically, run `(pdb-setup :composer nil)` instead.

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-search` procedure to wrap around search functions, all planning sessions will be recorded when the Recording toggle button is in the "on" state in the shell window. You can turn off the recording by clicking on the Recording toggle button in the shell (please refer to the Shell window).

If the search is going on too long, you may want to interrupt the search (e.g. by typing "C-c C-c" in emacs). In this case PDB can still display the plans explored so far, but you have to save the plan trace first, using:

`(pdb-save)`

then refresh the shell window by choosing "Refresh" from the Windows menu. The session will then appear. If PDB crashes, you can use

`(pdb-restart)`

to restart PDB. However all previous planning sessions are lost.

## 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

Windows | Please 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

Windows | Please 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

Windows | Please 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

Windows | Please 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:

Variable | Description | Default | 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
*vcr-update-after-replan* | After replanning from plan window, the corresponding vcr window will be refreshed if this variable is set to t. | t | If set to nil, the replanning is much faster because the vcr window is not redrawn. But this also means the vcr window is not updated and future plan traversals may mess up the vcr display a bit.

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.

- Launching composer with many windows open could hang the X server (have to kill the ACL process). Sometimes this also happen if you random click on CLIM windows when composer windows are being mapped.
- Transient window/dialog boxes can sometimes disappear/abort after user move the window.
- In choose flaw dialog, the flaw actually appears multiple times e.g. (clear ?x3) & (clear ?x3). But they're both selected. Can be confusing.
- Iconify and deiconify doesn't work in our CLIM2.0 implementation. As a result if you iconify a plan window, they cannot be brought back automatically by clicking on the node as intended.
- When exiting a VCR window, all its children plan windows should be exiting too. However this behavior cannot be achieved by the CLIM2.0 implementation on our system.
- The shell window does not resize correctly vertically because of CLIM2.0 gadget limitations.
- Plan nodes will not be highlighted (boxed) if Num Lock or Scroll Lock key is on.
- Synchronization problem: asking PDB to display output before the window shows up will fail.
- This is likely a CLIM bug. When the shell window refreshes the first time, pressing random buttons will cause a "medium-transformation" error. Just continue with the top-level option in ACL.
- Help documents are slightly outdated and not very helpful.

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-restart)`. 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.