{"id":13762070,"url":"https://github.com/caelan/pddlstream","last_synced_at":"2025-05-10T14:31:24.434Z","repository":{"id":38074611,"uuid":"130253539","full_name":"caelan/pddlstream","owner":"caelan","description":"PDDLStream: Integrating Symbolic Planners and Blackbox Samplers","archived":false,"fork":false,"pushed_at":"2023-10-04T17:37:03.000Z","size":28167,"stargazers_count":381,"open_issues_count":8,"forks_count":100,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-11-16T20:31:13.672Z","etag":null,"topics":["artificial-intelligence","automated-planning","fastdownward","manipulation","motion-planning","pddl","pddlstream","planning-algorithms","pybullet","pybullet-planning","robotics","task-and-motion-planning"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/1802.08705","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caelan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-04-19T18:01:55.000Z","updated_at":"2024-11-15T09:10:59.000Z","dependencies_parsed_at":"2024-01-22T19:43:08.418Z","dependency_job_id":null,"html_url":"https://github.com/caelan/pddlstream","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelan%2Fpddlstream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelan%2Fpddlstream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelan%2Fpddlstream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelan%2Fpddlstream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caelan","download_url":"https://codeload.github.com/caelan/pddlstream/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253428290,"owners_count":21906888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","automated-planning","fastdownward","manipulation","motion-planning","pddl","pddlstream","planning-algorithms","pybullet","pybullet-planning","robotics","task-and-motion-planning"],"created_at":"2024-08-03T14:00:34.495Z","updated_at":"2025-05-10T14:31:21.818Z","avatar_url":"https://github.com/caelan.png","language":"Python","funding_links":[],"categories":["Packages"],"sub_categories":[],"readme":"# pddlstream\n\nPDDLStream is a planning framework comprised of an action language and suite of algorithms for Artificial Intelligence (AI) planning in the presence of sampling procedures.\nPDDLStream extends Planning Domain Definition Language (PDDL) by introducing streams, declarative specifications of sampling procedures.\nPDDLStream algorithms are domain independent and solve PDDLStream problems with only a blackbox description of each sampler.\nThe motivating application of PDDLStream was for general-purpose robot Task and Motion Planning (TAMP). \n\nThe [default](https://github.com/caelan/pddlstream) **pddlstream** branch ([main](https://github.com/caelan/pddlstream/tree/stable)) is the newest stable \"release\" of **pddlstream**.\nThe [downward](https://github.com/caelan/pddlstream/tree/master) **pddlstream** branch is the most recent and advanced version of **pddlstream** but also is somewhat experimental.\n\n\u003c!--https://www.markdownguide.org/basic-syntax/--\u003e\n\u003c!--https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet--\u003e\n\n## Publications\n\n* [PDDLStream: Integrating Symbolic Planners and Blackbox Samplers via Optimistic Adaptive Planning](https://arxiv.org/abs/1802.08705\n)\n\u003c!--* [STRIPStream: Planning In Infinite Domains](https://arxiv.org/abs/1701.00287)--\u003e\n\n## Citation\n\nCaelan R. Garrett, Tomás Lozano-Pérez, Leslie P. Kaelbling. PDDLStream: Integrating Symbolic Planners and Blackbox Samplers via Optimistic Adaptive Planning, International Conference on Automated Planning and Scheduling (ICAPS), 2020.\n\n## Contact\n\nCaelan Garrett: [username]@csail.mit.edu\n\n## History\n\nPDDLStream is the \"third version\" of the PDDLStream/STRIPStream planning framework, intended to supersede previous versions:\n\n1) https://github.com/caelan/stripstream\n2) https://github.com/caelan/ss\n\nPDDLStream makes several representational and algorithmic improvements over these versions.\nMost notably, it adheres to PDDL conventions and syntax whenever possible and contains several new algorithms. \n\u003c!--An implementation of STRIPStream that uses PDDL for the specifiation of actions and streams.--\u003e\n\u003c!--https://github.com/caelan/pddlstream/compare/master...stable--\u003e\n\n## Installation\n\n\u003c!--$ git clone --recursive --branch main https://github.com/caelan/pddlstream.git--\u003e\n```\n$ git clone --recursive --branch main git@github.com:caelan/pddlstream.git\n$ cd pddlstream\npddlstream$ git submodule update --init --recursive\npddlstream$ ./downward/build.py\n```\n\u003c!--```\n$ git clone --recursive https://github.com/caelan/pddlstream.git\n\nIf building fails, install FastDownward's dependencies using your package manager:\n* APT (Linux): `$ sudo apt-get install cmake g++ g++-multilib make python`\n\u003c!--* Homebrew (OS X): TBD\n* MacPorts (OS X): TBD\n* N/A (Windows): install each dependency manually--\u003e\n\nIf necessary, see FastDownward's [documentation](http://www.fast-downward.org/ObtainingAndRunningFastDownward) for more detailed installation instructions.\n\n\u003c!--My FastDownward \"fork\" is several years old. If you have trouble compiling FastDownward on a newer machine, try installing the experimental [downward](https://github.com/caelan/pddlstream/tree/downward) PDDLStream branch.--\u003e\n\nPDDLStream actively supports python2.7 as well as the most recent version of python3.\n\u003c!--(many robotics applications still require python2.7)--\u003e\n\nMake sure to recursively update **pddlstream**'s submodules when pulling new commits.\n```\npddlstream$ git pull --recurse-submodules\n```\n\n## Examples\n\nThis repository contains several robotic and non-robotic PDDLStream example domains.\n\n### PyBullet\n\nInstall PyBullet on OS X or Linux using: \n```\n$ pip install pybullet numpy scipy\n```\n\nExamples:\n* PR2 TAMP: `pddlstream$ python -m examples.pybullet.tamp.run`\n* PR2 Cleaning and Cooking: `pddlstream$ python -m examples.pybullet.pr2.run`\n* Turtlebot Rovers: `pddlstream$ python -m examples.pybullet.turtlebot_rovers.run`\n* PR2 Rovers: `pddlstream$ python -m examples.pybullet.pr2_rovers.run`\n* PR2 Planning and Execution: `pddlstream$ python -m examples.pybullet.pr2_belief.run`\n* Kuka Cleaning and Cooking: `pddlstream$ python -m examples.pybullet.kuka.run`\n\u003c!--* Turtlebot NAMO: `pddlstream$ python -m examples.pybullet.namo.run`--\u003e\n\u003c!--\n* Turtlebot Multi-Robot: `pddlstream$ python -m examples.pybullet.turtlebots.run`\nRequires Temporal FastDownward - https://github.com/caelan/TemporalFastDownward\n--\u003e\n\n\u003c!--[![Kuka IIWA](https://img.youtube.com/vi/3HJrkgIGK7c/0.jpg)](https://www.youtube.com/watch?v=3HJrkgIGK7c)--\u003e\n[\u003cimg src=\"https://img.youtube.com/vi/Uc0fogLsPMI/0.jpg\" height=\"200\"\u003e](https://www.youtube.com/watch?v=Uc0fogLsPMI)\n\u0026emsp;[\u003cimg src=\"https://img.youtube.com/vi/HVD8SpmguYs/0.jpg\" height=\"200\"\u003e](https://www.youtube.com/watch?v=HVD8SpmguYs)\n\u0026emsp;[\u003cimg src=\"https://img.youtube.com/vi/oWr6m12nXcM/0.jpg\" height=\"200\"\u003e](https://www.youtube.com/watch?v=oWr6m12nXcM)\n\u003cimg src=\"images/pybullet_belief.png\" height=\"150\"\u003e\n\u0026emsp;[\u003cimg src=\"https://img.youtube.com/vi/XcxsU0VuRUI/0.jpg\" height=\"200\"\u003e](https://www.youtube.com/watch?v=XcxsU0VuRUI)\n\u0026emsp;[\u003cimg src=\"https://img.youtube.com/vi/3HJrkgIGK7c/0.jpg\" height=\"200\"\u003e](https://www.youtube.com/watch?v=3HJrkgIGK7c)\n\nSee https://github.com/caelan/pybullet-planning for more information about my PyBullet planning primitives library.\n\n### Python TKinter\n\nInstall numpy and Python TKinter on Linux using: \n```\n$ sudo apt-get install python-tk\n$ pip install numpy\n```\n\nExamples:\n* 1D Continuous TAMP: `pddlstream$ python -m examples.continuous_tamp.run`\n* 2D Motion Planning: `pddlstream$ python -m examples.motion.run`\n* Discrete TAMP: `pddlstream$ python -m examples.discrete_tamp.run`\n* Discrete TAMP with pushing: `pddlstream$ python -m examples.discrete_tamp.run`\n\n\u003cimg src=\"images/discrete_tamp.png\" height=\"100\"\u003e\u0026emsp;\u003cimg src=\"images/continuous_tamp.png\" height=\"100\"\u003e\u0026emsp;\u003cimg src=\"images/motion.png\" height=\"100\"\u003e\n\n### Pure Python\n\nSimple examples that can be run without additional dependencies:\n* Blocksworld: `pddlstream$ python -m examples.blocksworld.run`\n* Blocksworld with Derived Predicates: `pddlstream$ python -m examples.blocksworld.run_derived`\n* Kitchen (debug streams): `pddlstream$ python -m examples.kitchen.run`\n\n\u003c!--* Discrete Belief: `pddlstream$ python -m examples.table_obs.run`\n* Discrete Belief Space: `pddlstream$ python -m examples.discrete_belief.run`\n`$ pip install numpy scipy`--\u003e\n\n### Advanced Functionality\n\nTest cases or advanced (and undocumented) functionality:\n* Action Description Language (ADL): `pddlstream$ python -m examples.advanced.adl.run`\n* Deferred streams (postponed evaluation): `pddlstream$ python -m examples.advanced.defer.run`\n* Exogenous streams (observations): `pddlstream$ python -m examples.advanced.exogenous.run`\n* Fluent streams (state constraints): `pddlstream$ python -m examples.advanced.fluent.run`\n* Constraint satisfaction: `pddlstream$ python -m examples.advanced.satisfy.run`\n* Wild streams (ad hoc certification): `pddlstream$ python -m examples.advanced.wild.run`\n\n### International Planning Competition (IPC)\n\nUnmodified PDDL IPC examples solved using PDDLStream's modified translator:\n* Rovers: `pddlstream$ python -m examples.ipc.rovers.run`\n* Satellites: `pddlstream$ python -m examples.ipc.satellites.run`\n\n## Applications\n\nExternal projects that make use of PDDLStream:\n* Online TAMP - https://github.com/caelan/SS-Replan\n* Automated Construction - https://github.com/caelan/pb-construction\n* Learning + TAMP (LTAMP) - https://github.com/caelan/LTAMP\n* pyrobosim - https://github.com/sea-bass/pyrobosim\n\u003c!--https://github.com/rachelholladay/ftamp--\u003e\n\n## Algorithms\n\nPDDLStream is a planning framework comprised of a **single** planning language but **multiple** planning algorithms.\nSome of the algorithms are radically different than others (e.g. Incremental vs Focused) and thus the planning time can also substantially vary.\nThe **Adaptive** algorithm typically performs best for domains with many possible sampling pathways, such as robot manipulation domains.\n\u003c!--For domains with few sampling pathways, the **Incremental** algorithm typically performs best (link to specific examples)--\u003e\n\nThe meta procedure [solve(...)](https://github.com/caelan/pddlstream/blob/da1e52aeeff9a22ef647e95b617dd71904cdbe49/pddlstream/algorithms/meta.py#L37) allows the user to toggle between avaliable algorithms using the keyword argument **algorithm={}**.\n\nProperty descriptions:\n* **Method**: the python function that calls the algorithm\n\u003c!--* **Subroutine**: TBD--\u003e\n* **Negated streams**: whether the algorithm supports inverting test streams\n* **Fluent streams**: whether the algorithm supports fluent streams that additionally condition on the fluent state\n* **Wild streams**: whether the algorithm supports streams that additionally can certify ad hoc facts\n\u003c!--* **Semantic attachments (SA)**: TBD--\u003e\n\n### Adaptive\n\n* **Method**: [solve_adaptive(...)](https://github.com/caelan/pddlstream/blob/da1e52aeeff9a22ef647e95b617dd71904cdbe49/pddlstream/algorithms/focused.py#L229)\n* **Negated streams**: supported \n* **Fluent streams**: supported \n* **Wild streams**: supported \n\u003c!--* **Semantic attachments (SA)**: TBD--\u003e\n\n### Binding\n\n* **Method**: [solve_binding(...)](https://github.com/caelan/pddlstream/blob/da1e52aeeff9a22ef647e95b617dd71904cdbe49/pddlstream/algorithms/focused.py#L215)\n* **Negated streams**: supported \n* **Fluent streams**: supported \n* **Wild streams**: supported \n\u003c!--* **Semantic attachments (SA)**: TBD--\u003e\n\n### Focused\n\n* **Method**: [solve_focused_original(...)](https://github.com/caelan/pddlstream/blob/da1e52aeeff9a22ef647e95b617dd71904cdbe49/pddlstream/algorithms/focused.py#L201)\n* **Negated streams**: supported \n* **Fluent streams**: supported \n* **Wild streams**: supported \n\u003c!--* **Semantic attachments (SA)**: TBD--\u003e\n\n### Incremental\n\n* **Method**: [solve_incremental(...)](https://github.com/caelan/pddlstream/blob/da1e52aeeff9a22ef647e95b617dd71904cdbe49/pddlstream/algorithms/incremental.py#L700)\n* **Negated streams**: not supported \n* **Fluent streams**: not supported \n* **Wild streams**: supported \n\u003c!--* **Semantic attachments (SA)**: TBD--\u003e\n\n## Search Subroutines\n\nMany (but not all) **pddlstream** algorithms have a discrete planning phase that can be implemented using any finite state-space search algorithm, such as Breadth-First Search (BFS) and Uniform-Cost Search (UCS).\nHowever, because **pddlstream** extends PDDL, this planning phase can also be implemented by state-of-the-art classical planning algorithms, which leverage the factored structure of action languages such as PDDL to vastly improve empirical planning efficiency.\nBest-first heuristic search algorithms, which automatically derive heursitics in a *domain-independent* manner, are one example class of these algorithms.\n\n### FastDownward\n\n**pddlstream** comes pre-packaged with [FastDownward](http://www.fast-downward.org/), a prolific library that contains many best-first heuristic search PDDL planning algorithms.\nI've preconfigured a small number of effective and general search algorithms in [SEARCH_OPTIONS](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L81), which can be toggled using the keyword argument [planner=?](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L391). I've roughly ranked them in order of least lazy (lowest cost) to most lazy (lowest runtime):\n* [Dijkstra/Uniform-Cost Search (UCS)](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L87) - optimal but slowest\n* [hmax A*](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L91) - optimal but slow\n* [lmcut A*](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L93) - optimal but slow\n* [ff eager astar](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L97)\n* [ff eager {1,...,5} weighted astar](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L138) - recommended (w=2)\n* [ff lazy {1,...,5} weighted astar](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L129)\n* [ff eager greedy](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L99)\n* [ff lazy greedy](https://github.com/caelan/pddlstream/blob/4914667a13a80831cadaf115a70938e9f93b021e/pddlstream/algorithms/downward.py#L103)\n\nThe runtime of the discrete planning phase varies depending on the selected search algorithm.\nFor many non-adversarial problems, these algorithms will either solve a problem instantenously or, if they aren't greedy enough, not terminate within 10 minutes.\nI recommend starting with a greedier configuration and moving torward a less greedy one if desired. \n\n### Other PDDL Planners\n\nAny PDDL planning algorithm could be used in the place of [FastDownward](http://www.fast-downward.org/); however, a caveat is that some of these planners are only implemented to support a limited set of representational features (e.g. no conditional effects, no derived predicates, etc.), which can make both modeling more difficult and ultimately planning less efficient in many real-world (non-IPC) planning domains.\nWhile I heavily recommend [FastDownward](http://www.fast-downward.org/), some PDDL planners that I've interfaced with in the past with some success include:\n\nClassical Planners\n* [FastDownward](http://www.fast-downward.org/)\n* [FastForward](https://github.com/caelan/FastForward-X)\n* [pyplanners](https://github.com/caelan/pyplanners)\n* [Cerberus](https://github.com/ctpelok77/fd-red-black-postipc2018)\n* [LAPTK](https://github.com/LAPKT-dev/LAPKT-public/)\n* [YSHAP](https://github.com/nojhan/descarwin) \u003c!--https://github.com/aldukeman/yahsp2--\u003e\n\u003c!--* [pyperplan](https://github.com/aibasel/pyperplan)--\u003e\n\u003c!-- https://github.mit.edu/caelan/stripstream/tree/master/stripstream/algorithms/search --\u003e\n\u003c!-- https://github.mit.edu/caelan/ss/tree/master/ss/algorithms --\u003e\n\nNumeric Planners:\n* [Metric FF](https://github.com/caelan/Metric-FF)\n* [SMTPlan](https://github.com/KCL-Planning/SMTPlan)\n\nTemporal Planners:\n* [Temporal FastDownward](https://github.com/caelan/TemporalFastDownward)\n* [TPSHE](https://github.com/aig-upf/temporal-planning)\n\nDiverse Planners:\n* [Forbid Iterative](https://github.com/IBM/forbiditerative)\n* [kstar](https://github.com/ctpelok77/kstar)\n* [symk](https://github.com/speckdavid/symk)\n\n\u003c!-- International Planning Competition (IPC) --\u003e\n\n## Resources\n\n* [Recent Talk](https://youtu.be/YfCh5qMYGuQ)\n* [Recent Overview](https://youtu.be/7xLPogztQss)\n* [Recent Tutorial](https://youtu.be/JNOk1rylDpU)\n* [PDDLStream Tutorial](https://web.mit.edu/caelan/www/presentations/6.881_19-11-12.pdf)\n* [The AI Planning \u0026 PDDL Wiki](https://planning.wiki/)\n* [Planning Domain Definition Language (PDDL)](http://users.cecs.anu.edu.au/~patrik/pddlman/writing.html)\n* [Derived Predicates](https://www.cs.cmu.edu/afs/cs/project/jair/pub/volume28/coles07a-html/node18.html)\n* [FastDownward](http://www.fast-downward.org/)\n\u003c!--* [PDDLStream Tutorial](https://web.mit.edu/caelan/www/presentations/6.881_TAMP.pdf)--\u003e\n\n## Retired\n\n\"Retired\" folders indicate code that no longer is continuously supported and thus is likely outdated.\n\n### Drake\n\nInstall Drake on OS X or Ubuntu by following the following instructions: http://drake.mit.edu/installation.html.\n\nAlternatively, install Drake through docker by following the following instructions: http://manipulation.csail.mit.edu/install_drake_docker.html. Use the appropriate docker_run_bash script with docker tag drake-20181128.\n\nExamples:\n* Kuka IIWA task and motion planning: `~/pddlstream$ python -m examples.drake.run`\n\u003c!--[![Kuka IIWA](https://img.youtube.com/vi/3HJrkgIGK7c/0.jpg)](https://www.youtube.com/watch?v=3HJrkgIGK7c)--\u003e\n\u003cimg src=\"images/drake_kuka.png\" height=\"150\"\u003e\n\nAdditional PDDLStream + Drake examples can be found at: https://github.com/RobotLocomotion/6-881-examples.\n\n\u003c!--https://drake.mit.edu/gallery.html#task-and-motion-planning--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaelan%2Fpddlstream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaelan%2Fpddlstream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaelan%2Fpddlstream/lists"}