# <img src="./misc/images/scrambledCube.png" width="50"> DeepXube <img src="./misc/images/solvedCube.png" width="50">
![Tests](https://github.com/forestagostinelli/deepxube/actions/workflows/test.yml/badge.svg)
--------------------------------------------------------------------------------
DeepXube (pronounced "Deep Cube") aims to solve classical planning problems in an explainable manner using deep reinforcement learning,
heuristic search, and formal logic. The current project can:
1) Train a heuristic function to estimate the cost-to-go between state/goal pairs,
where a goal represents a set of states considered goal states. The representation of the goal can come
in any form: i.e. a state, a set of ground atoms in first-order logic, natural language, an image/sketch, etc.
2) Specify goals with answer set programming, a robust form of logic programming, in the case where goals are represented as a set of ground atoms in first-order logic.
DeepXube is a generalization of DeepCubeA ([code](https://github.com/forestagostinelli/DeepCubeA/),[paper](https://cse.sc.edu/~foresta/assets/files/SolvingTheRubiksCubeWithDeepReinforcementLearningAndSearch_Final.pdf)).
For any issues, you can create a GitHub issue or contact Forest Agostinelli (foresta@cse.sc.edu).
**Overview**:\
<img src="./misc/images/overview.png" width="500">
**Outline**:
- [Installation](#installation)
- [Environment](#environment-implementation)
- [Training Heuristic Function](#training-heuristic-function)
- [Heuristic Search](#heuristic-search)
- [Answer Set Programming Specification](#specifying-goals-with-answer-set-programming)
- [Examples](#examples)
## Installation
`pip install deepxube`
See [INSTALL.md](INSTALL.md) for more details
## Environment
The environment includes a state object that defines states, a goal object that defines goals (a set of states considered goal states),
and an environment object that generate start states, define state transitions, when a state a goal state, and the neural network that takes states as an input.
See [ENVIRONMENT.md](ENVIRONMENT.md) for more details
## Training Heuristic Function
Once an environment has been implemented, a heuristic function can be trained to map states and goals to heuristic
values (estimates of the cost-to-go from a given start state to a given goal).
See [TRAIN.md](TRAIN.md) for more details.
## Heuristic Search
Given a trained heuristic function, a start state, and a goal, heuristic search is used to find a path from the start state
to the goal.
See [HEURSEARCH.md](HEURSEARCH.md) for more details.
## Specifying Goals with Answer Set Programming
Coming soon.
## Examples
Raw data
{
"_id": null,
"home_page": "",
"name": "deepxube",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "DeepXube,DeepCubeA,DeepCube,deep learning,reinforcement learning,search,heuristic search,pathfinding,planning,Rubik's Cube,Sliding Tile Puzzle,Sokoban",
"author": "",
"author_email": "Forest Agostinelli <foresta@cse.sc.edu>",
"download_url": "https://files.pythonhosted.org/packages/b0/55/15358b322be84dabbd185c8368e6581acb798fbd736a6142277924949bad/deepxube-0.1.1.tar.gz",
"platform": null,
"description": "# <img src=\"./misc/images/scrambledCube.png\" width=\"50\"> DeepXube <img src=\"./misc/images/solvedCube.png\" width=\"50\">\n![Tests](https://github.com/forestagostinelli/deepxube/actions/workflows/test.yml/badge.svg)\n\n--------------------------------------------------------------------------------\n\nDeepXube (pronounced \"Deep Cube\") aims to solve classical planning problems in an explainable manner using deep reinforcement learning, \nheuristic search, and formal logic. The current project can:\n\n1) Train a heuristic function to estimate the cost-to-go between state/goal pairs, \nwhere a goal represents a set of states considered goal states. The representation of the goal can come \nin any form: i.e. a state, a set of ground atoms in first-order logic, natural language, an image/sketch, etc.\n2) Specify goals with answer set programming, a robust form of logic programming, in the case where goals are represented as a set of ground atoms in first-order logic.\n\nDeepXube is a generalization of DeepCubeA ([code](https://github.com/forestagostinelli/DeepCubeA/),[paper](https://cse.sc.edu/~foresta/assets/files/SolvingTheRubiksCubeWithDeepReinforcementLearningAndSearch_Final.pdf)).\n\nFor any issues, you can create a GitHub issue or contact Forest Agostinelli (foresta@cse.sc.edu).\n\n**Overview**:\\\n<img src=\"./misc/images/overview.png\" width=\"500\">\n\n**Outline**:\n\n- [Installation](#installation)\n- [Environment](#environment-implementation)\n- [Training Heuristic Function](#training-heuristic-function)\n- [Heuristic Search](#heuristic-search)\n- [Answer Set Programming Specification](#specifying-goals-with-answer-set-programming)\n- [Examples](#examples)\n\n\n\n## Installation\n\n`pip install deepxube`\n\nSee [INSTALL.md](INSTALL.md) for more details\n\n## Environment\nThe environment includes a state object that defines states, a goal object that defines goals (a set of states considered goal states),\nand an environment object that generate start states, define state transitions, when a state a goal state, and the neural network that takes states as an input.\n\nSee [ENVIRONMENT.md](ENVIRONMENT.md) for more details\n\n\n## Training Heuristic Function\nOnce an environment has been implemented, a heuristic function can be trained to map states and goals to heuristic \nvalues (estimates of the cost-to-go from a given start state to a given goal).\n\nSee [TRAIN.md](TRAIN.md) for more details.\n\n## Heuristic Search\nGiven a trained heuristic function, a start state, and a goal, heuristic search is used to find a path from the start state \nto the goal.\n\nSee [HEURSEARCH.md](HEURSEARCH.md) for more details.\n\n## Specifying Goals with Answer Set Programming\nComing soon.\n\n## Examples\n",
"bugtrack_url": null,
"license": "",
"summary": "Solving pathfinding problems in an explainable manner with deep learning, reinforcement learning, heuristic search, and logic",
"version": "0.1.1",
"project_urls": {
"Repository": "https://github.com/forestagostinelli/DeepXube/"
},
"split_keywords": [
"deepxube",
"deepcubea",
"deepcube",
"deep learning",
"reinforcement learning",
"search",
"heuristic search",
"pathfinding",
"planning",
"rubik's cube",
"sliding tile puzzle",
"sokoban"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f80bdd8beb04056c1d167c006619526cc75569b978a6a377f751a0981917625",
"md5": "adb149150a2ff28d6cf6e58a839f1038",
"sha256": "342bc0d79c273fcd3590cb1c8f759e0f079563d459032fbd3415689dc7bebc71"
},
"downloads": -1,
"filename": "deepxube-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "adb149150a2ff28d6cf6e58a839f1038",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 3422,
"upload_time": "2024-03-18T18:53:17",
"upload_time_iso_8601": "2024-03-18T18:53:17.654255Z",
"url": "https://files.pythonhosted.org/packages/4f/80/bdd8beb04056c1d167c006619526cc75569b978a6a377f751a0981917625/deepxube-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b05515358b322be84dabbd185c8368e6581acb798fbd736a6142277924949bad",
"md5": "8c76e11c990d36fea5f067ab5e7de7aa",
"sha256": "1f48f31cafbc93e238c6d7f393e69a67bef6772f28a320c66a8e25dbdbfe9021"
},
"downloads": -1,
"filename": "deepxube-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8c76e11c990d36fea5f067ab5e7de7aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4675,
"upload_time": "2024-03-18T18:53:19",
"upload_time_iso_8601": "2024-03-18T18:53:19.547834Z",
"url": "https://files.pythonhosted.org/packages/b0/55/15358b322be84dabbd185c8368e6581acb798fbd736a6142277924949bad/deepxube-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-18 18:53:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "forestagostinelli",
"github_project": "DeepXube",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "deepxube"
}