Release Notes for O-Plan version 2.3 ------------------------------------ Contents -------- Introduction Installation Running O-Plan Differences from version 2.2 TF syntax checking Dealing with Lisp errors Introduction ------------ Version 2.2 is the third CPE release of O-Plan. In most ways, it is very similar to the first two releases, version 2.1 and version 2.2. This note briefly describes the main differences. Please bear in mind that this is still a fairly early version of O-Plan. A number of improvements are planned for later releases, but there has not been time to include them in this one. Installation ------------ You should install version 2.3 in a directory different from any directory used for an earlier version of O-Plan to avoid any confusion between files from different versions. The installation procedure is described in the file "source/INSTALL". Running O-Plan --------------- In the remainder of this document it will sometimes be assumed that there is a shell command, "oplan", that can be used to invoke O-Plan. A suitable shell script is provided: see the installation instructions. The "oplan" command can be given a number of command-line arguments that affect how O-Plan behaves. The argument options currently available are described in the file "source/doc/command-line-arguments" relative to the main O-Plan directory. Most command-line arguments set the value of a "parameter". Parameters can also be set by Lisp code in an "oplan-init" file. The current set of user-settable parameters and the Lisp procedures for manipulating them are described in the file "source/doc/parameters". Further information on running O-Plan can be found in the User Guide. However, these release notes take precedence over the User Guide. Differences from version 2.2 ---------------------------- * Execution-monitoring and plan-repair mechanisms have been implemented. The demonstration environment lets the user execute plans using a simple execution agent and a "world simulator" that tracks the effects produced by actions in the plan. The simulator allows the user to control whether actions succeed or fail and to specify "unexpected" world events that can interfere with the plan. When action failures or unexpected events are reported, the planner determines what parts of the plan (if any) are affected and allows the user to select ways of repairing the plan. * The planner has been extended to allow new requirements to be added to a plan while it is being executed. * O-Plan is now able to run non-interactively, under program control, and a program interface has been defined. This interface is for procedures that are in the same Lisp image as O-Plan. An interface for external programs already existed, but it has been extended to provide a greater range of services. The internal interface can be used to create new external interfaces, which is how the next item was implemented. * O-Plan can now be run using the Common Gateway Interface (CGI) of the World-Wide Web, and a number of demonstration pages have been created. Among them is an HTML version of the O-Plan Demonstration Guide, containing links that run O-Plan to produce plans for the tasks being described in the text. * A new form of textual "plan view" has been defined: a plan can be viewed as "narrative". At present, this is essentially an execution trace using earliest start times, but other forms of linear, textual description could be added. * The PostScript grapher used for plan views is now capable of removing dummy nodes when that would simplify the graph of the plan. * The controller (agenda manager) now supports the "Process any agenda entry" option of the "Single Step" menu. It also uses better algorithms for evaluating and selecting alternatives. This has allowed O-plan to handle some tasks and domains that were too difficult before. * The Plan State Variable (PSV) manager now makes greater use of not-same constraints to detect cases where variables cannot be bound or are forced to take particular values. * O-Plan is now called "O-Plan" rather than "O-Plan2". This change is reflected throughout the system. If you notice any instances of "O-Plan2", please report them to . TF compiler ----------- * The compiler now provides "include " so that one TF file can include the contents of another. * The "initially", "initial_resources", and "initial_time" statements have all been implemented. * Schema variables can now appear in "resources" and "time_windows" clauses. * The compiler now supports integer range types that can be used for both schema variables and PSVs. For instance, a domain definition might contain: types index = (1..3), Then, a schema could define a variable of that type: vars ?i = ?{type index}, ... Syntax: types = | , ... ; ::= ::= ( ... ) ::= ( .. ) ::= [ ] * Action-ordering constraints can now be specified in the "nodes" clause of a schema using a notation for sequential and parallel blocks. (The "orderings" clause can also specify ordering constraints, and it continues to work as before.) Here's an example: nodes sequential 1 action {fly_transport Honolulu Delta}, parallel 2 action {evacuate Abyss 50}, 3 action {evacuate Barnacle 100}, 4 action {evacuate Calypso 20} end_parallel, 5 dummy, parallel 6 action {fly_passengers Delta Honolulu}, 7 action {fly_transport Delta Honolulu} end_parallel end_sequential; TF syntax checking ------------------ O-Plan be run as a TF syntax-checker ("tfc"). This can be useful when writing a new domain description. O-Plan performs the same checks when a TF file is loaded, but it's sometimes easier if you can check without starting up the whole planner. "tfc" also lets you ask for a level analysis to be printed which normally happens only when there are level errors. O-Plan will run as the syntax-checker if it's given "-tfc" as a command-line argument. Arguments after "-tfc" are interpreted by the syntax-checker. They can take the following forms: [-q] [-l] filename [-q] [-l] -d directory where the square brackets surround optional items. At present, the items must appear in the order given. The "-q" is for "quiet" and suppresses progress reports. The "-l" is for "levels" and produces a level analysis. When "-d" is used, all files in the directory are checked and a report is produced at the end. If the filename is the single character "-", TF forms will be read from standard-input. Progress reports will be turned off automatically. If no additional arguments are supplied after "-tfc", the checker enters a loop in which you can type tfc commands. E.g shell% oplan -tfc tfc> -q -l snark.tf tfc> To exit, type "q" (not "-q") as a command. Here is an example of a level analysis: shell% oplan -tfc -q -l demo/tf/pacifica-1 Levels for domain "pacifica-1" There are 0 strongly connected components in the action graph that have length greater than one. Action levels: 0 task_operation_castaway task_operation_paradise task_operation_blue_lagoon 1 fly_passengers transport fly_transport 2 load unload drive Effect levels: 0 country 1 nationals people_at_poe_from 2 in_use_for at Dealing with Lisp errors ------------------------ Version 2.3 makes it easier to deal with Lisp errors than it was before. By "a Lisp error" we mean that O-Plan or the Lisp system invokes the Lisp error signalling mechanism rather than, say, just printing a message. Unless the error is caused by an erroneous command typed into the Lisp interaction window, it is usually due to a bug in O-Plan and should be reported. Your options for dealing with the Lisp error depend on what O-Plan was doing when it occurred. When a Lisp error occurs in the TF compiler, a menu will appear to make sure you notice the error. There will be only one option, "ok". Select "ok" to continue. The TF compiler will exit and report that the file contained an error. That is, a Lisp error is treated as if it were a single syntax error that applied to the whole TF file. When the error occurs in some other part of the planner, there is typically no neat way to recover from it, and a more complex menu appears. It will look something like this: Lisp error in process ------------------------------------ Allow the error Return to scheduler Force global reset will be replaced by the name of the process that was running when the error occurred: :AM, :DM, :KP-1, etc. You should look in the window associated with that process to see the error message. The meanings of the options are as follows: Allow the error Allow Lisp to handle the error. This will usually result in a "break loop" as described below. Select this option if you plan to report the bug, because the bug report should include a "backtrace" (also described below). Return to scheduler Exit the process in which the error occurred so that the system can continue running. In most cases, this will not work very well, because the process in which the error occurred needed to finish some task that was interrupted by the error. This sort of recovery can also be attempted from a break loop, as described below (again). Force global reset Attempt to reinitialise O-Plan. This will abandon the attempt to find a plan (or whatever O-Plan was doing) and start over as if you had selected the "Initialise planner" option in the TA. It is equivalent to evaluating the Lisp expression (force-reset). When the Lisp system handles an error, Lisp usually enters a "break loop" in one of the O-Plan windows. Ordinarily, you will see a menu first, as described above. In any case, you can tell that Lisp has entered a break by the following signs: 1. O-Plan will stop producing any output. 2. The one-line "running processes" window will stop changing. 3. There will be an error message in a window associated with the rightmost name in the "running processes" window. 4. The window will be displaying the ">" prompt. The first two can also happen when O-Plan is merely taking a long time to do something; the others cannot. In a break loop, the normal ways of exiting O-Plan by using the control panel or the TA menu will not work. However, you can type Lisp debugger commands and Lisp expressions in the the window, after the ">" prompt. Typing (exit-oplan) should cause O-Plan to exit. (force-reset) attempts to reset the system by wiping out all pending messages, sending itself an :INIT message, and returning to the process scheduler. If you're planing to report a bug, you should get a "backtrace" before exiting. It shows the nested Lisp procedure calls that led up to the error. Get a backtrace by typing ":b" after the ">" prompt. Grab the resulting output and the error message with the mouse and put them both in the bug report. In some cases you can (and may want to) get O-Plan to continue after an error. This is most likely to be so when the error is in a relatively peripheral part of the planner, such as the PW viewer, but it can happen in other cases too. In some cases, the Lisp system will offer you a reasonable way to continue from the error, so always look at the options that appear after the error message. Another form of recovery that sometimes makes sense is to get O-Plan to abandon its current activity and allow other parts of the system to run. You can accomplish this by selecting "Return to round-robin scheduler" from the restart options presented after the Lisp error message. (This is equivalent to choosing "Return to scheduler" from the menu appears when the error is first noticed.) This approach should be tried only when the error occurs during a relatively self-contained activity. An example might be a Lisp error when the PlanWorld Viewer tried to display a plan. By returning control the the scheduler, you could get the viewer to abandon this attempt This would work fairly well because nothing else in the system depends very strongly on the viewer succeeding. On the other hand, it would not work very well if, for instance, the DM ran into an error somewhere deep in the TOME/GOST manager. In such cases, you might try typing the command (force-reset) instead. ----------------------------------------------------------------------