PDDL Planning Domains (puxle.pddls)

PuXle supports the STRIPS subset of PDDL with automatic grounding and JAX-optimized state representation.

PDDL

class puxle.pddls.pddl.PDDL

Bases: Puzzle

PuXle wrapper that turns a PDDL domain + problem into a Puzzle.

Supports the STRIPS subset of PDDL:

• Positive and negative preconditions (conjunctive).

• Add / delete effects (no conditional or quantified effects).

• Conjunctive positive goals.

• Typed objects with type-hierarchy resolution.

The state is a packed boolean vector over grounded atoms (1 bit per atom via xtructure bitpacking). The solve-config stores a goal mask rather than a full target state, enabling partial-goal problems.

The class delegates heavy lifting to helper modules:

• type_system — type hierarchy extraction.

• grounding — predicate and action grounding.

• masks — JAX mask construction.

• formatting — pretty-printing utilities.

• state_defs — dynamic state/solve-config classes.

Parameters:

• domain (Union[str, Domain]) – Path to a PDDL domain file or a pddl.core.Domain object.

• problem (Union[str, Problem]) – Path to a PDDL problem file or a pddl.core.Problem object.

__init__(domain, problem, **kwargs)

Initialize PDDL puzzle from domain and problem (files or objects).

Parameters:

• domain (Union[str, Domain]) – Path to PDDL domain file OR pddl.core.Domain object.

• problem (Union[str, Problem]) – Path to PDDL problem file OR pddl.core.Problem object.

classmethod from_preset(domain, problem=None, *, problem_basename=None, **kwargs)

Create a PDDL instance by resolving absolute paths to data under puxle/data/pddls/.

This mirrors the absolute-path loading style used by puzzles like Sokoban.

Parameters:

• domain (str) – Domain folder name under puxle/data/pddls/ (e.g., “blocksworld”).

• problem (Optional[str]) – Problem filename within problems/ (with or without .pddl extension).

• problem_basename (Optional[str]) – Alternative to problem; basename without extension in problems/.

Returns:

Initialized PDDL environment.

Return type:

PDDL

data_init()

Initialize PDDL data: ground atoms and actions, build masks.

Return type:

None

define_state_class()

Define state class with packed atoms.

Return type:

PuzzleState

define_solve_config_class()

Define solve config with goal mask instead of target state.

Return type:

PuzzleState

get_initial_state(solve_config, key=None, data=None)

Return initial state.

Return type:

State

Parameters:

solve_config (SolveConfig)

get_solve_config(key=None, data=None)

Return solve config with goal mask.

Return type:

SolveConfig

get_actions(solve_config, state, action, filled=True)

Get the next state and cost for a given action using JAX.

Return type:

tuple[State, Union[Array, ndarray, bool, number]]

Parameters:

• solve_config (SolveConfig)

• state (State)

• action (Array | ndarray | bool | number)

• filled (bool)

is_solved(solve_config, state)

Check if state satisfies goal conditions.

Return type:

bool

Parameters:

• solve_config (SolveConfig)

• state (State)

get_string_parser()

Return string parser for states. If a solve_config is provided, annotate goal atoms.

Return type:

Callable

get_img_parser()

Return image parser for states. If a solve_config is provided, annotate goal atoms.

Return type:

Callable

action_to_string(action, colored=True)

Return string representation of action (delegated).

Return type:

str

Parameters:

• action (int)

• colored (bool)

property has_target: bool

Override to handle goal mask instead of target state.

property only_target: bool

Override to handle goal mask instead of target state.

property fixed_target: bool

Override to handle goal mask instead of target state.

get_solve_config_string_parser()

Return string parser for solve config with goal mask.

Return type:

Callable

get_solve_config_img_parser()

Return image parser for solve config with goal mask.

Return type:

Callable

state_to_atom_set(state)

Convert state to set of true atom strings for testing.

Return type:

set[str]

Parameters:

state (State)

static_predicate_profile(state, pred_name)

Get truth values of all grounded atoms for a predicate in given state.

Return type:

list[bool]

Parameters:

• state (State)

• pred_name (str)

Grounding

Predicate and action grounding for PDDL environments.

Generates the universe of grounded atoms and grounded actions by instantiating every typed predicate / action schema with all valid object combinations drawn from the problem’s typed-object pool.

puxle.pddls.grounding.ground_predicates(predicates, objects_by_type, type_hierarchy)

Grounds all predicates to create the set of all possible atoms.

Return type:

Tuple[List[str], Dict[str, int]]

Parameters:

• objects_by_type (Dict[str, List[str]])

• type_hierarchy (Tuple[Dict[str, str], Dict[str, Set[str]], Dict[str, Set[str]]])

puxle.pddls.grounding.ground_actions(actions, objects_by_type, type_hierarchy)

Grounds all actions.

Return type:

Tuple[List[Dict], Dict[str, int]]

Parameters:

• objects_by_type (Dict[str, List[str]])

• type_hierarchy (Tuple[Dict[str, str], Dict[str, Set[str]], Dict[str, Set[str]]])

Masks

JAX boolean-mask construction for PDDL preconditions, effects, and goals.

Each grounded action is encoded as four boolean vectors over the atom universe: positive preconditions, negative preconditions, add effects, and delete effects. Initial-state and goal masks are also built here.

puxle.pddls.masks.extract_goal_conditions(goal)

Extract atomic conditions from a goal formula object.

Return type:

List[str]

puxle.pddls.masks.build_masks(grounded_actions, atom_to_idx, num_atoms)

Builds JAX masks for preconditions (pos/neg) and effects.

Return type:

Tuple[Array, Array, Array, Array]

Parameters:

• grounded_actions (List[Dict])

• atom_to_idx (Dict[str, int])

• num_atoms (int)

puxle.pddls.masks.build_initial_state(problem, atom_to_idx, num_atoms)

Build initial state as boolean array from PDDL problem init facts.

Return type:

Array

Parameters:

• atom_to_idx (Dict[str, int])

• num_atoms (int)

puxle.pddls.masks.build_goal_mask(problem, atom_to_idx, num_atoms)

Build goal mask for conjunctive positive goals.

Return type:

Array

Parameters:

• atom_to_idx (Dict[str, int])

• num_atoms (int)

Formatting

Pretty-printing utilities for PDDL states, actions, and solve configs.

Provides colour-coded terminal output (via termcolor and optional rich) for debugging and visualisation of grounded atoms and actions.

puxle.pddls.formatting.split_atom(atom_str)

Return type:

tuple[str, list[str]]

Parameters:

atom_str (str)

puxle.pddls.formatting.build_label_color_maps(domain)

Return type:

Tuple[Dict[str, str], Dict[str, str]]

puxle.pddls.formatting.action_to_string(grounded_actions, index, label_termcolor_map, colored=True)

Return type:

str

Parameters:

• grounded_actions (List[Dict])

• index (int)

• label_termcolor_map (Dict[str, str])

• colored (bool)

puxle.pddls.formatting.build_state_string_parser(env)

Return type:

Callable

puxle.pddls.formatting.build_solve_config_string_parser(env)

Return type:

Callable

Type System

PDDL type-hierarchy extraction and object grouping.

Builds parent/ancestor/descendant maps from a domain’s :types block and uses them to group problem objects by the most specific type, propagating objects to supertypes as needed for grounding.

puxle.pddls.type_system.collect_type_hierarchy(domain)

Extract best-effort type hierarchy from a PDDL domain object.

Returns (parent, ancestors, descendants). - parent: type -> immediate parent - ancestors: type -> transitive set of ancestors - descendants: type -> transitive set of descendants

Return type:

Tuple[Dict[str, str], Dict[str, Set[str]], Dict[str, Set[str]]]

puxle.pddls.type_system.select_most_specific_types(type_tags, hierarchy)

Keep the most specific types using the hierarchy.

Drops ‘object’ when more specific tags are present and removes any tag that is an ancestor of another tag in the same set.

Return type:

list[str]

Parameters:

• type_tags (Iterable[str])

• hierarchy (Tuple[Dict[str, str], Dict[str, Set[str]], Dict[str, Set[str]]])

puxle.pddls.type_system.extract_objects_by_type(problem, hierarchy, domain=None)

Extract objects grouped by types, respecting hierarchy if available.

Return type:

Dict[str, list[str]]

Parameters:

hierarchy (Tuple[Dict[str, str], Dict[str, Set[str]], Dict[str, Set[str]]])

State Definitions

Dynamic state and solve-config class builders for PDDL environments.

Constructs xtructure-backed State (packed boolean atom vector) and SolveConfig (goal mask) dataclasses tailored to a specific grounded PDDL problem.

puxle.pddls.state_defs.build_state_class(env, num_atoms, init_state, string_parser)

Return type:

PuzzleState

Parameters:

• num_atoms (int)

• init_state (Array)

• string_parser (Callable)

puxle.pddls.state_defs.build_solve_config_class(env, goal_mask, string_parser)

Return type:

PuzzleState

Parameters:

• goal_mask (Array)

• string_parser (Callable)

PDDLFuse (Domain Fusion)

puxle.pddls.fusion.api.fuse_and_load(domain_paths, params=None, name='fused-domain', **kwargs)

Fuses multiple PDDL domains and returns a PuXle PDDL environment.

Parameters:

• domain_paths (List[str]) – List of paths to PDDL domain files.

• params (Optional[FusionParams]) – Fusion and modification parameters.

• name (str) – Name of the resulting domain.

• **kwargs – Additional arguments for PDDL constructor.

Return type:

PDDL

Returns:

A PDDL instance with the fused domain and a simple/empty problem.

puxle.pddls.fusion.api.generate_benchmark(domain_paths, output_dir, count=10, params=None, difficulty_depth_range=(5, 20))

Generates a suite of PDDL domain/problem files for external benchmarks.

Return type:

None

Parameters:

• domain_paths (List[str])

• output_dir (str)

• count (int)

• params (FusionParams | None)

• difficulty_depth_range (Tuple[int, int])

puxle.pddls.fusion.api.iterative_fusion(base_domains, depth, params, name_prefix='fused')

Performs iterative fusion to increase complexity.

Parameters:

• base_domains (List[str]) – Initial domain paths

• depth (int) – Number of fusion iterations (1 = basic fusion)

• params (FusionParams) – Fusion and modification parameters

• name_prefix (str) – Prefix for generated domain names

Return type:

Domain

Returns:

Final fused domain after ‘depth’ iterations

puxle.pddls.fusion.api.generate_benchmark_with_varying_depth(base_domains, output_dir, depth_range=(1, 3), problems_per_depth=10, params=None)

Generates benchmarks across a range of fusion depths.

Parameters:

• base_domains (List[str]) – List of PDDL domain file paths

• output_dir (str) – Root directory for output

• depth_range (Tuple[int, int]) – (min_depth, max_depth) inclusive

• problems_per_depth (int) – Number of problems per depth

• params (Optional[FusionParams]) – Fusion parameters

Return type:

None

class puxle.pddls.fusion.domain_fusion.DomainFusion

Bases: object

Engine for fusing multiple PDDL domains into a single domain.

fuse_domains(domains, name='fused-domain')

Fuses a list of domains into a single domain using disjoint union.

Parameters:

• domains (List[Domain]) – List of pddl.Domain objects to fuse.

• name (str) – Name of the resulting domain.

Return type:

Domain

Returns:

A new pddl.Domain object containing the disjoint union of components.

class puxle.pddls.fusion.action_modifier.ActionModifier

Bases: object

Modifies actions by stochastically adding preconditions and effects.

__init__(params)

Parameters:

params (FusionParams)

modify_actions(actions, all_predicates, types_map)

Apply stochastic modifications to a list of actions.

Return type:

List[Action]

Parameters:

• actions (List[pddl.core.Action])

• all_predicates (List[pddl.logic.predicates.Predicate])

• types_map (Dict[str, Any])

class puxle.pddls.fusion.action_modifier.FusionParams

Bases: object

FusionParams(prob_add_pre: float = 0.1, prob_add_eff: float = 0.1, prob_rem_pre: float = 0.05, prob_rem_eff: float = 0.05, prob_neg: float = 0.1, rev_flag: bool = True, seed: int = 42)

prob_add_pre: float = 0.1

prob_add_eff: float = 0.1

prob_rem_pre: float = 0.05

prob_rem_eff: float = 0.05

prob_neg: float = 0.1

rev_flag: bool = True

seed: int = 42

__init__(prob_add_pre=0.1, prob_add_eff=0.1, prob_rem_pre=0.05, prob_rem_eff=0.05, prob_neg=0.1, rev_flag=True, seed=42)

Parameters:

• prob_add_pre (float)

• prob_add_eff (float)

• prob_rem_pre (float)

• prob_rem_eff (float)

• prob_neg (float)

• rev_flag (bool)

• seed (int)

Return type:

None

class puxle.pddls.fusion.problem_generator.ProblemGenerator

Bases: object

Generates solvable problems by simulating valid execution traces.

__init__(seed=42)

Parameters:

seed (int)

generate_problem(domain, num_objects=5, walk_length=10, problem_name='generated-problem')

Generates a random problem for the given domain.

Parameters:

• domain (Domain) – The PDDL domain.

• num_objects (int) – Number of objects to create.

• walk_length (int) – Number of steps to simulate for goal generation.

• problem_name (str)

Return type:

Problem

Returns:

A pddl.Problem instance.