PDDL syntax

A reference to the parts of a PDDL domain and problem file. PDDL is written in parentheses, in the style of Lisp: everything is a list, and ; starts a comment.

The domain file

A domain opens with its name and then lists its parts in order.

(define (domain courier)
  (:requirements :strips :typing)
  (:types van parcel location)
  (:constants ...)
  (:predicates ...)
  (:functions ...)
  (:action ...)
  ...)

Requirements

:requirements declares which language features the domain uses, so that a planner can tell at once whether it can take the domain on. The main ones are:

Flag	Allows	Since
`:strips`	Basic add and delete effects	1.2
`:typing`	Types on objects and parameters	1.2
`:equality`	The predicate `=` between objects	1.2
`:disjunctive-preconditions`	`or` in conditions	1.2
`:quantified-preconditions`	`exists` and `forall` in conditions	1.2
`:conditional-effects`	`when` and `forall` in effects	1.2
`:adl`	All of the above, as one flag	1.2
`:negative-preconditions`	`not` in conditions and goals	2.1
`:fluents`	Numeric functions (see 3.1 for its later meaning)	2.1
`:durative-actions`	Actions that take time	2.1
`:duration-inequalities`	Durations chosen within bounds	2.1
`:continuous-effects`	Values that change over a duration	2.1
`:derived-predicates`	Predicates defined by rules	2.2
`:timed-initial-literals`	Facts that change at known times	2.2
`:constraints`	Constraints on the whole plan	3.0
`:preferences`	Soft goals and constraints	3.0
`:action-costs`	A cost per action	3.1
`:numeric-fluents`	The new name for numeric functions	3.1
`:object-fluents`	Functions whose value is an object	3.1

"Since" is the first version we found with the flag in this meaning. Which of these a given planner reads is on the features page.

Types

Types form a hierarchy. Names before a - are subtypes of the name after it, and anything without a parent is a subtype of object.

(:types truck van - vehicle
        vehicle parcel location)

Predicates

Predicates are the facts that can be true or false. A variable starts with ?, and a type after - applies to the names before it.

(:predicates
  (road ?from ?to - location)
  (van-at ?v - van ?l - location))

A state is the set of facts that are true. Anything not listed is false.

Functions

Functions hold numbers, such as fuel, distance or money. They need :fluents. Since PDDL 3.1 a declaration may say - number.

(:functions
  (distance ?from ?to - location)
  (fuel ?v - van))

Actions

An action has parameters, a precondition that must hold for it to apply, and an effect saying what changes.

(:action drive
  :parameters (?v - van ?from ?to - location)
  :precondition (and (van-at ?v ?from) (road ?from ?to))
  :effect (and (not (van-at ?v ?from)) (van-at ?v ?to)))

Conditions

Form	Holds when
`(and a b)`	Both hold
`(or a b)`	At least one holds
`(not a)`	`a` does not hold
`(imply a b)`	If `a` holds, so does `b`
`(exists (?x - t) a)`	`a` holds for some `?x`
`(forall (?x - t) a)`	`a` holds for every `?x`
`(= ?x ?y)`	They are the same object
`(>= (fuel ?v) 5)`	A comparison of numbers, also `<=`, `<`, `>`, `=`

Effects

Form	Does
`(p ?x)`	Makes a fact true
`(not (p ?x))`	Makes a fact false
`(when c e)`	Applies `e` only if `c` holds
`(forall (?x - t) e)`	Applies `e` for every `?x`
`(assign f v)`	Sets a number
`(increase f v)`, `(decrease f v)`	Adds to it or subtracts from it
`(scale-up f v)`, `(scale-down f v)`	Multiplies or divides it

Durative actions

A durative action has a duration, and every condition and effect says when it applies: at start, at end, or, for conditions, over all. See PDDL 2.1.

(:durative-action drive
  :parameters (?v - van ?from ?to - location)
  :duration (= ?duration (distance ?from ?to))
  :condition (and (at start (van-at ?v ?from))
                  (over all (road ?from ?to)))
  :effect (and (at start (not (van-at ?v ?from)))
               (at end (van-at ?v ?to))))

The problem file

(define (problem two-parcels)
  (:domain courier)
  (:objects van1 - van  book lamp - parcel  depot market - location)
  (:init (van-at van1 depot) (parcel-at book depot) (road depot market)
         (= (fuel van1) 40))
  (:goal (and (parcel-at book market)))
  (:metric minimize (total-time)))

:domain names the domain this problem belongs to.
:objects lists what exists, with types.
:init lists every fact true at the start and sets every number with =.
:goal is a condition, which must hold in the final state.
:metric, optional, says what makes a plan better: minimize or maximize an expression, which may use total-time, the length of the schedule.

Common mistakes

An undeclared requirement. Using not in a precondition needs :negative-preconditions, or :adl. Planners differ on how strict they are about this.
Forgetting the delete. A drive that adds the new location but does not remove the old one leaves the van in two places.
One-way roads by accident. (road a b) does not imply (road b a). Facts are exactly what you list.
An unset number. A function without a value in :init is undefined, not zero.
Time on the wrong end. In a durative action, an over all condition does not cover the end points. To hold across the whole action, it needs at start and at end as well.

Autoplan Studio checks files as you type and reports problems with their line and column. Anything the planner cannot handle is refused, never quietly ignored.