fond-utils 0.2.0

FOND Utilities and Helpers

FOND Utilities

Utilities for parsing and manipulating the FOND planning language (those containing non-deterministic oneof effects). At this point the system can:

• Check a file contains a legal FOND domain/problem.
• Normalize a FOND planning domain (i.e., have a single top-level oneof clause in the effect).
• Compute the all-outcome determinization of a FOND domain, where each non-deterministic action is replaced with a set of deterministic actions, each encoding one possible effect outcome of the action. A solution in the deterministic version amounts to a weak plan solution in the original FOND problem.
  • Note the determinizer produces another PDDL domain and does not deal with the problem itself, unlike the SAS-based determinizers used in other planners (like PRP, FONDSAT, or CFOND-ASP) that are are based on the SAS translator in Fast-Downard classical planner and produce a SAS encoding of the determinization of a specific instance planning problem. For these determinizers that output SAS encodings, please refer to the individual planners or the translator-fond repo.

[!IMPORTANT] The system accepts effects that are an arbitrary nesting of oneof, conditional effects, and and. See section Format allowed on effects at the bottom about format accepted.

Install

The fond-utils system can be installed (as a package) directly from its PyPi repository:

$ pip install fond-utils

Alternatively, it can be installed directly from the repo:

$ pip install git+https://github.com/AI-Planning/fond-utils

or, clone the repository and install:

$ git clone https://github.com/AI-Planning/fond-utils
$ cd fond-utils
$ pip install .

The system already includes a CLI console application fond-utils that will generally be the tool to use. To check the installation was successful just run:

$ fond-utils -h
usage: fond-utils [-h] --input INPUT [--output OUTPUT] [--outproblem OUTPROBLEM] [--prefix PREFIX] [--suffix SUFFIX]
                  [--console]
                  {check,determinize,normalize}

Utilities to process FOND PDDL

positional arguments:
  {check,determinize,normalize}

options:
  -h, --help            show this help message and exit
  --input INPUT         Input domain file
  --output OUTPUT       Output domain file
  --outproblem OUTPROBLEM
                        Optional output problem file
  --prefix PREFIX       Prefix for determinized action outcome identifier (Default: _DETDUP_)
  --suffix SUFFIX       Suffix for determinized action outcome identifier
  --console             Print the domain after processing

[!NOTE] The scripts on this system relies on the pddl parser, which can be easily installed via PyPi repository (pip install pddl). The pddl system relies itself on the lark parsing library. The fond-utils system, however, extends pddl to accept single files containing both the domain and the problem instance, and will be extended further to accept labelled outcomes in the effects.

Quickstart

You can use the fond-utils package in two ways: as a library, and as a CLI tool.

As a CLI application tool

To just check that the PDDL input file is parsed well, use the command check and report to console:

$ fond-utils check --input https://raw.githubusercontent.com/AI-Planning/fond-utils/refs/heads/main/tests/domain_03.pddl

Since the system is provided as a module fondutils, this would be equivalent to:

$ python -m fondutils check --input https://raw.githubusercontent.com/AI-Planning/fond-utils/refs/heads/main/tests/domain_03.pddl

Note this would work if you have cloned the repo rather than installed the actual package; for example:

$ git clone https://github.com/AI-Planning/fond-utils
$ cd fond-utils
$ python -m fondutils check --input tests/domain_03.pddl

Normalize a domain

To simply perform normalization (i.e., have a single top-level oneof clause in the effect):

$ fond-utils normalize --input tests/domain_05.pddl --output normalized-domain.pddl

Example test/domain_05.pddl includes some complex (nested) oneof effects. The name of the normalized domain will be the original name with suffix _NORM.

All-outcome determinization

To perform the determinization, use the command determinize:

$ fond-utils determinize --input tests/domain_03.pddl --output determinized-domain.pddl

The name of the determinized domain will be the original name with a possible suffix separated with an underscore (default _NEW). Use --suffix-domain "" to use no suffix (same name as original domain).

The deterministic versions of a non-deterministic action are enumerated (starting from 1) with possible prefix and suffix on the number, each part separated with an underscore _. For example, the third deterministic action of operator move would be named move_<PREFIX>_3_<SUFFIX>; if no prefix or suffix is set, it would be just move_3.

[!TIP] To change the default operator name prefix DETDUP use the options --prefix, and to add a suffix after the number, use --suffix. To set the suffix for the domain name use --suffix-domain. To get the resulting PDDL printed on console use --console:

$ fond-utils  determinize --input tests/domain_03.pddl --prefix "PRE" --suffix "SUF"  --suffix-domain "NEW" --console
(define (domain blocks-domain_NEW)
    (:requirements :equality :typing)
    (:types block)
    (:predicates (clear ?b - block)  (emptyhand) (holding ?b - block)  (on ?b1 - block ?b2 - block)  (on-table ?b - block))
    (:action pick-up_PRE_1_SUF
        :parameters (?b1 - block ?b2 - block)
        :precondition (and (not (= ?b1 ?b2)) (emptyhand) (clear ?b1) (on ?b1 ?b2))
        :effect (and (holding ?b1) (clear ?b2) (not (emptyhand)) (not (clear ?b1)) (not (on ?b1 ?b2)))
    )
     (:action pick-up_PRE_2_SUF
        :parameters (?b1 - block ?b2 - block)
        :precondition (and (not (= ?b1 ?b2)) (emptyhand) (clear ?b1) (on ?b1 ?b2))
        :effect (and (clear ?b2) (on-table ?b1) (not (on ?b1 ?b2)))
    )
     (:action pick-up_PRE_3_SUF
        :parameters (?b1 - block ?b2 - block)
        :precondition (and (not (= ?b1 ?b2)) (emptyhand) (clear ?b1) (on ?b1 ?b2))
        :effect (and )
    )
     (:action put-down
        :parameters (?b - block)
        :precondition (holding ?b)
        :effect (and (on-table ?b) (emptyhand) (clear ?b) (not (holding ?b)))
    )
)

This resulting PDDL domain is now deterministic and can then be used as input to the original Fast-Downward SAS translator.

[!WARNING] If the new domain is named with a suffix (as in the default case), existing problem instances may not be compatible with the new domain, as they will still refer to the original domain in the :domain section. If these problem instances will be used with the new PDDL encoding, either use no suffix for the domain name (so it will keep the same name as the original) or change the :domain section in the problem instances to match the new name that includes the suffix (by setting private property _domain_name). Note that if the file parsed included the problem as well, the CLI tool will do such update so that the resulting problem will have its domain name matching the new domain.

As a library

This is an example of how we can normalize and determinize a PDDL non-deterministic domain programmatically:

import io
import inspect
from pathlib import Path
import requests

from pddl import parse_domain
from pddl.formatter import domain_to_string
from fondutils.determizer import determinize
from fondutils.normalizer import normalize

# get a domain from AI-Planning/fond-domains repo
URL_DOMAIN = "https://raw.githubusercontent.com/AI-Planning/fond-domains/refs/heads/main/benchmarks/blocksworld-2/domain.pddl"
r = requests.get(URL_DOMAIN)
domain_file = io.StringIO(r.content.decode("utf-8"))

domain = parse_domain(domain_file)

# compute the normalization of the domain and print it on console
domain_norm = normalize(domain)
print(domain_to_string(domain_norm))

# compute the determinization of the domain and print it on console
domain_det = determinize(domain)
print(domain_to_string(domain_det))

To parse parse files that contain both domain and problem together, we can use function parse_domain_problem in fondutils.pddl. Note how the following code also sets explicit domain suffix and operators prefixes and suffixes, and how we update the domain name in the problem to match the new one:

import io
import inspect
from pathlib import Path
import requests

from pddl.formatter import domain_to_string, problem_to_string
from fondutils.pddl import parse_domain_problem
from fondutils.determizer import determinize
from fondutils.normalizer import normalize

# get a domain from AI-Planning/fond-domains repo
URL_DOMAIN = "https://raw.githubusercontent.com/AI-Planning/fond-utils/refs/heads/main/tests/domprob_03.pddl"
r = requests.get(URL_DOMAIN)
domain_file = io.StringIO(r.content.decode("utf-8"))

domain, problem = parse_domain_problem(domain_file)

# compute the determinization of the domain and print it on console
domain_det = determinize(domain, dom_suffix="XYZ", op_prefix="PRE", op_suffix="SUF")
print(domain_to_string(domain_det))

# update domain name in problem to match new domain name and print updated problem
problem._domain_name = domain_det.name
print(problem_to_string(problem))

Format allowed on effects

The determinizer accepts effects that are an arbitrary nesting of oneof, conditional effects, and and.

If the effect is just one oneof clause, then it corresponds to the Unary Nondeterminism (1ND) Normal Form without conditionals in:

• Jussi Rintanen: Expressive Equivalence of Formalisms for Planning with Sensing. ICAPS 2003: 185-194

When there are many oneof clauses in a top-level and effect, the cross-product of all the oneof clauses will determine the deterministic actions.

Authors

• Sebastian Sardina (ssardina) - RMIT University
• Christian Muise (haz) - Queen's University