WORKSWORLD - Automated Planning and Scheduling of Permanent Pipelined Workflows

IMPORTANT: This repository is the home of the WORKSWORLD domain and the tools for using it. It contains the PDDL domain definition, problem generation scripts, and visualization utilities.

Benchmarks & Experiments: For repeating the experiments presented in the ICAPS-26 paper, please refer to the WORKSWORLD Benchmark Repository. That repository contains the full CI/CD pipeline, solver configurations, and post-processing scripts needed to reproduce the results.

This repository contains the PDDL domain, problem generator, planning scripts, validation and visualization tools for the WORKSWORLD research project; all run in standalone docker containers. It focuses on optimizing component placement and connectivity in distributed systems.

🚀 Quick Start

The easiest way to run a planner and visualize the result is using the top-level compile-plan-val-vis.sh which will:

1. (Optional) Compile a PDDL problem from a YAML config file using the pddl-generator Docker container.
2. Run the ENHSP planner on the specified problem with configurable timeout.
3. Capture and validate each intermediate solution during anytime planning.
4. Generate D2 diagrams and SVG visualizations for each solution incrementally.
5. Log all output with timestamps to both console and log files for debugging.

# Build the required containers for the steps below:
cd containers/
make build-all
cd ../  # For Next Steps!

# Generate PDDL problem from config, then plan, validate and visualize
./compile-plan-val-vis.sh \
  -D benchmarks/icaps-26-benchmarks/batch-01/problems \
  -c benchmarks/icaps-26-benchmarks/batch-01/configs/2f.yaml \
  -p 2f.pddl \
  -o benchmarks/icaps-26-benchmarks/batch-01/plans \
  -O "-planner sat-hmrph"

# Search for better plans for an existing problem.pddl 
#  with custom timeout (300s) and planner options
./compile-plan-val-vis.sh \
  -D benchmarks/icaps-26-benchmarks/batch-01/problems \
  -p easy.pddl \
  -o benchmarks/icaps-26-benchmarks/batch-01/plans \
  -t 300 \
  -O "-planner sat-hmrph -anytime"

# Only compile a PDDL problem from config (no planning/viz)
./compile-plan-val-vis.sh \
  -D benchmarks/icaps-26-benchmarks/batch-01/problems \
  -c benchmarks/icaps-26-benchmarks/batch-01/configs/2f.yaml \
  -p 2f.pddl \
  --compile-only

# See help message for details and additional flags:
./compile-plan-val-vis.sh -h

Repository Structure

Below is an overview of the key directories and files:

• worksworld-domain.pddl: The PDDL domain definition file containing the model for the planning domain.

• compile-plan-val-vis.sh: The main orchestration script to generate problems, plan, validate, and visualize in one go.

• containers/: Contains Dockerfiles (Dockerfile-ENHSP, Dockerfile-pddl-generator, etc.) and a Makefile to build the container images required for the toolchain.

• planning-tools/: Helper scripts for running the planner (specifically ENHSP) and validating plans.

• problem-generator/: Source code for generating PDDL problems and configurations.

  • generate-yaml-configs/: Scripts to create experiment configurations (yaml files).
  • generate_problems.py: Main entry point for generating yaml configs and compiling them into PDDL.
  • jinja-templates/: Templates used to construct the PDDL files from the yaml configurations.

• visualization/: Tools to visualize the generated plans.

  • plan_to_d2.py: Converts output plans to D2 diagram (text) format.
  • visualize.sh: Automation script to run plan_to_d2.py and then render diagrams to SVG with d2 library.

• benchmarks/: Benchmark problem instances used in experiments.

  • icaps-26-benchmarks/: Problems, configurations, and plans for the ICAPS 2026 paper experiments (Batches 01–05 and grounding comparison instances).

Detailed Documentation

For more detailed information about specific components, see the following READMEs:

• Containers - Docker container setup for PDDL generator, ENHSP planner, and visualization tools. Includes Makefile commands for building and managing images.

• Problem Generator - Templating solution for generating PDDL problems using Jinja2 templates and YAML configurations. Covers the complete workflow from config generation to PDDL compilation.

  • Configuration Generator - Detailed guide for creating YAML experiment configurations with custom parameters (workflow sizes, infrastructure topology, resource constraints, etc.).

• Planning Tools - Scripts for running the ENHSP planner, batch-processing experiments, and validating plans.

• Benchmarks — ICAPS 2026 - Benchmark problem instances for the ICAPS 2026 paper. Covers five batches testing component/network scalability (Batches 01–04), complex multi-site scenarios (Batch 05), and grounding comparison instances (Table 4).

• Visualization - Plan visualization pipeline that converts PDDL plans into D2 diagrams and SVG images. Shows component placement, data flow, and network topology.

Citation

If you use this repository or the WORKSWORLD benchmark in your work, please cite:

@inproceedings{paul2026worksworld,
  title     = {WORKSWORLD: A Domain for Integrated Numeric Planning and Scheduling of Distributed Pipelined Workflows},
  author    = {Paul, Taylor and Regli, William},
  booktitle = {Proceedings of the International Conference on Automated Planning and Scheduling},
  volume = {36},
  year      = {2026},
  note      = {[to appear]}
}