Creating planners

UPMurphi generates planners as standalone executables. The input model can be either

  • a pair of (domain, problem) PDDL files
  • a precompiled model in the Murphi format.

In the former case, UPMurphi will automatically call the PDDL-to-Murphi compiler to obtain the Murphi model corresponding to the given PDDL domain and problem, and then compile it to create the planner. This is the default behaviour of UPMurphi. Advanced users may directly write the Murphi model or make modifications to a PDDL-derived model. To this aim, please refer to the Murphi_User_Manual.txt and Murphi_User_Manual.txt files in the 'doc' folder.

Note that some models have an associated library (.c file and possibly the corresponding header file .h) which define functions to be called by the model during its execution.

To compile a PDDL domain/problem to an UPMurphi planner, invoke the UPMurphi compiler (upmc) as follows:

upmc <domain.pddl> <problem.pddl>

This will call several tools (including the g++ compiler) and generate the following files:

  • domain.m, the compiled planner model
  • domain.h / domain.c, the extenral funzions for the model (see below)
  • domain.cpp, the C++ planner source
  • problem_planner(.exe), the planner

You can pass several options to upmc. Type upmc --help for a full list.

  • the compiler will skip the compilation steps whose input appears not modified since last execution. To force a full recompilation, use the --force switch.
  • if your model uses variable rule durations and weights (i.e., the duration and/or weight of a rule depends also from the state the rule is applied on), you MUST add the --varweight and/or --varduration switches. to notify the planner of this. Otherwise, the planning results will be incorrect. Note that each of these switches increase the planner memory and disk requirements, so use them only if you need them!
  • to create a debug-mode planner (see below) use the --debug switch.
  • to override the default discretization used to compile the PDDL domain, you can specify the --custom X Y switch, or the --prompt switch to enter it interactively during the compilation process.

Executing planners

Once the executable planner has been generated, you can run it to start the planning process. By default, the planner will search for a feasible plan and write it to the file <problem_name>_plan.pddl.

If you compiled a debug mode planner, then it will stop every time a model rule can be executed (i.e, an action can be taken, an event can occur, the clock can tick, etc.) and ask the user if it should be actually fired, displaying the rule name and the corresponding PDDL action/event name, if available. You can then allow its execution writing y (yes, the default), or deny the execution with n (no, in this case the planning will continue as the rule was never encountered). You can also decide to always fire a particular rule (answering a), or never fire it again (answering e).

The memory given to the planner is 1Gb. Many options areavailable to change the planner's default behaviour:

General

  • -noclear do not delete working disk files.

If -noclear is NOT specified, the planner will remove all its temporary files from disk after its execution. You can use -noclear to save the planner files for further processing: these include a full (binary) dump of the plant states, the complete set of transitions, the inverted plant graph, the optimal actions chosen in each state, etc.

  • -m<n> give the planner n megabytes of memory default 1000).
  • -val validate plans

To use this option, VAL must be installed on your system and its path configured in the UPMurphi makefile.

Algorithm

  • -search:o create an optimal plan for each startstate.
  • -search:u create an universal plan.
  • -search:uo create an universal optimal plan.
  • -search:f create a feasible plan for each startstate (default).

The -search:* options set the planning algorithm to use.

  • -cdl check for deadlock.

Deadlock detection is DISABLED by default. You can activate it with -cdl.

  • -l<n> maximum bfs level (default: unlimited).

The number of BFS levels to explore can be specified through the -l option. If this option is set, the planner will work only on the states found on these levels, otherwise it will try to explore the entire domain before starting the optimisation and planning phases.

  • -lt<n> maximum plan length (default: unlimited).

You can use this option to limit the plans to a maximum number of clock ticks. Plans longer than this limit will be ignored.

Output

  • -output file write output in file (default: <problem_name>_plan.pddl).
  • -print also print output to console.

By default, final output is written to an output file <problem_name>_plan.pddl. If you want to specify a different filename, use the -output option. Using the option -print will cause such file to be copied to stdout, too.

  • -format:pddl output plans in pddl format (default).
  • -format:pddlv output plans in pddl format with verbose comments.
  • -format:pddlvv output plans in pddl format with very verbose comments.
  • -format:text output plans/actions in text format.
  • -format:verbose output plans/actions in verbose text format.
  • -format:raw output actions in binary format.
  • -format:csv output actions in csv format.

Output formats, specified through the -format:* options, are:

  • pddl: standard PDDL plan format. This is the default
  • pddlv: PDDL plan format with comments that show the execution of 'invisible actions' such as events, durative action terminations, clock ticks, etc.
  • pddlvv: as pddlv but, after each step, prints also a comment with the current domain variables value.
  • text: textual format useful for diagnostic purposes.
  • verbose: as text, but prints the system state after each step.
  • raw: prints the control actions in binary format. Useful to generate controllers instead of universal plans.
  • csv: prints the control actions in csv format. Each row contains the description of a state (i.e., the list of its variables) and the name of the rule to apply in such state. Values are separated by a colon. Warning: only variables marked with a pddlname are included is the state output!