Hide menu

Planning Domains and Problem Instances in PDDL

These instructions were adapted by Jonas Kvarnström
from an earlier version written by Patrik Haslum.

What is PDDL?

PDDL, the Planning Domain Definition Language, was developed with the aim of generating a standard to replace or augment a variety of existing planning domain and problem description languages. It was created mainly to make a series of International Planning Competitions possible.

PDDL supports the full expressivity of STRIPS and ADL, as well as a large set of extensions of varying complexity. Providing full support for all aspects of PDDL is a very complex task. In fact, many planners support only the STRIPS subset, possibly with a few extensions. The most important of these extensions are indicated in the list of available planners.

We will now give a brief introduction to PDDL. If you want more details, the International Planning Competition web pages contain a list of papers related to PDDL, including definitions of PDDL 1.2, 2.1, 2.2, and 3.0.

Don't miss the list of warnings at the end of this page!

Examples

Several examples of PDDL domain and problem definitions may be found, using either the STRIPS subset of PDDL or types and some ADL features. There are also several variants of the Satellite domain (used in IPC 2002), which illustrate the extended features of PDDL 2.1.

Parts of a PDDL Problem Definition

A PDDL definition consists of two parts: The domain definition and the problem definition. Although not required by the PDDL standard, many planners require that the two parts are in separate files.

Comments

Comments in a PDDL file start with a semicolon (";") and last to the end of the line.

Requirements

Because PDDL is a very general language and most planners support only a subset, domains may declare requirements. The most commonly used requirements are:

:strips
The most basic subset of PDDL, consisting of STRIPS only.
:equality
The domain uses the predicate =, interpreted as equality.
:typing
The domain uses types (see typing below).
:adl
The domain uses some or all of ADL (i.e. disjunctions and quantifiers in preconditions and goals, quantified and conditional effects).

Unfortunately, most planners' parsers are quite simple and often written under the assumption that you already know which parts of PDDL the planner supports. They often ignore the :restrictions clause – if you use a feature of PDDL they don't support, they give you a parse error without further information. Nevertheless, you should declare the correct requirements in any domain you write.

The Domain Definition

The domain definition contains the domain predicates and operators (called actions in PDDL). It may also contain types (see typing, below), constants, static facts and many other things, but these are not supported by the majority of planners.

The format of a (simple) domain definition is:

(define (domain DOMAIN_NAME)
  (:requirements [:strips] [:equality] [:typing] [:adl] ...)
  (:predicates (PREDICATE_1_NAME [?A1 ?A2 ... ?AN])
               (PREDICATE_2_NAME [?A1 ?A2 ... ?AN])
	       ...)

  (:action ACTION_1_NAME
    [:parameters (?P1 ?P2 ... ?PN)]
    [:precondition PRECOND_FORMULA]
    [:effect EFFECT_FORMULA]
   )

  (:action ACTION_2_NAME
    ...)

  ...)

Elements in []'s are optional, for those not familiar with formal grammars.

Names (of domains, predicates, actions, etc.) can usually contain alphanumeric characters, hyphens ("-") and underscores ("_"). There may be planners that allow less. Some planners use the same namespace for different items, so that you cannot (for example) use the same name for a domain and for a type.

Parameters of predicates and actions are distinguished by beginning with a question mark ("?").

For untyped domains, the parameters used in predicate declarations (the :predicates part) have no other function than to specify the number of arguments that the predicate should have, i.e. the parameter names do not matter (as long as they are distinct). Predicates can have zero parameters, but the predicate name still has to be written within parentheses.

Action Definitions

All parts of an action definition except the name are, according to the spec, optional (although, of couse, an action without effects is pretty useless). However, for an action that has no preconditions some planners may require an "empty" precondition, on the form :precondition (). Some planners may also require an empty :parameter list for actions without parameters.

Note: Some planners require that the arguments to an action are all different, i.e. the same object may not be used to instantiate two parameters. This ensures that the planner never tries pointless actions such as move(robot,locA,locA) which would move a robot from a location to the same location. At the same time there are cases where one does want the same argument to be used. For example, if we represent coordinates in a grid as the objects p1,p2,p3,p4,..., the planner should (but might not) allow actions such as move-to(p2,p2).

This may cause some difficulties (e.g. problems becoming unsolvable) if one is not aware of it. See the domain definition slidetile.pddl and the two problem definitions eight01.pddl and eight01x.pddl for an example of this problem and how to fix it.

Actions: Precondition Formulas

In a STRIPS domain, a precondition formula may be:

  • An atomic formula:
    (PREDICATE_NAME ARG1 ... ARG_N)
    The predicate arguments must be parameters of the action (or constants declared in the domain, if the domain has constants).
  • A conjunction of atomic formulas:
    (and ATOM1 ... ATOM_N)

If the domain uses :equality, an atomic formula may also be of the form (= ARG1 ARG2). Many planners that support equality also allow negated equality, which is written (not (= ARG1 ARG2)), even if they do not allow negation in any other part of the definition.

In an ADL domain, a precondition may in addition be:

  • A general negation, conjunction or disjunction:
    (not CONDITION_FORMULA)
    (and CONDITION_FORMULA1 ... CONDITION_FORMULA_N)
    (or CONDITION_FORMULA1 ... CONDITION_FORMULA_N)
  • A quantified formula:
    (forall (?V1 ?V2 ...) CONDITION_FORMULA)
    (exists (?V1 ?V2 ...) CONDITION_FORMULA)

Some planners can't handle negated preconditions correctly. You should try to avoid them in your domains.

Actions: Effect Formulas

In PDDL, the effects of an action are not explicitly divided into "adds" and "deletes". Instead, negative effects (deletes) are denoted by negation.

In a STRIPS domain, an effect formula may consist of:

  • An added atom:
    (PREDICATE_NAME ARG1 ... ARG_N)
    The predicate arguments must be parameters of the action (or constants declared in the domain, if the domain has constants).
  • A deleted atom:
    (not (PREDICATE_NAME ARG1 ... ARG_N))
  • A conjunction of atomic effects:
    (and ATOM1 ... ATOM_N)

The equality predicate (=) can of course not occur in an effect formula; no action can make two identical objects be not identical or vice versa!

Note that you can't use "exists" in action effects, since that would correspond to non-deterministic effects.

In an ADL domain, an effect formula may in addition contain:

  • A conditional effect:
    (when CONDITION_FORMULA EFFECT_FORMULA)
    The interpretation is that the specified effect takes place only if the specified condition formula is true in the state where the action is executed. Conditional effects are usually placed within quantifiers.
  • A universally quantified formula:
    (forall (?V1 ?V2 ...) EFFECT_FORMULA)

Note that nested use of "when" and "and" will confuse some planners. In general, don't nest conditions more than necessary, and try to keep your expressions simple and readable. Most operators can be written using a single list of effects with a single level of nesting: "(and (p1) (p2) (when (p3) (p4)) (p5) (p6))".

The Problem Definition

The problem definition contains the objects present in the problem instance, the initial state description, and the goal.

The format of a (simple) problem definition is:

(define (problem PROBLEM_NAME)
  (:domain DOMAIN_NAME)
  (:objects OBJ1 OBJ2 ... OBJ_N)
  (:init ATOM1 ATOM2 ... ATOM_N)
  (:goal CONDITION_FORMULA)
  )

The initial state description (the :init section) is simply a list of all the ground atoms that are true in the initial state. All other atoms are by definition false.

The goal description is a formula of the same form as an action precondition. All predicates used in the initial state and goal description should naturally be declared in the corresponding domain. Goals are generally specified as a single conjunction: (and (something) (somethingelse)). Few planners handle complex formulas as goals, even though this is technically allowed in ADL.

In difference to action preconditions, the initial state and goal descriptions should be ground, meaning that all predicate arguments should be object or constant names rather than parameters. (An exception is quantified goals in ADL domains, where of course the quantified variables may be used within the scope of the quantifier. However, even some planners that claim to support ADL do not allow quantifiers in goals.)

Typing

PDDL has a (very) special syntax for declaring parameter and object types. If types are to be used in a domain, the domain should first of all declare the requirement :typing.

Second, the type names have to be declared before they are used (which usually means before the :predicates declaration). This is done with the declaration

  (:types NAME1 ... NAME_N)

Then, to declare the type of a parameter of a predicate or action one writes ?X - TYPE_OF_X. A list of parameters of the same type can be abbreviated to ?X ?Y ?Z - TYPE_OF_XYZ. Note that the hyphen between parameter and type name has to be "free-standing", i.e. surrounded by whitespace.

The syntax is the same for declaring types of objects in the problem definition.

Warnings and Hints

  • Planners often add their own assumptions about the format of a planning domain. For example, they may require preconditions to be on the form "(and ...)", even if the precondition only consists of a single atom. If you have problems getting a planner to parse your domain definition, please first try some alternatives. If this does not help, ask the lab assistant.
  • Some planners can't handle negated preconditions correctly. You should try to avoid them in your domains.


Page responsible: Jonas Kvarnström
Last updated: 2014-03-19