diff --git a/EXTENDING.md b/EXTENDING.md index 77dd0fa..55036e4 100644 --- a/EXTENDING.md +++ b/EXTENDING.md @@ -7,12 +7,12 @@ Add a domain PDDL file to the `planetarium/domains/` directory, where the filena ### 2. Add an Oracle -Every domain in Planetarium requires an [`Oracle`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/oracles/oracle.py#L8) object and file tied to it. +Every domain in Planetarium requires an [`Oracle`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/oracles/oracle.py#L8) object and file tied to it. There are three fundamental components to the Oracle: -- [`.reduce()`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/oracles/oracle.py#L11) function, which takes a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/graph.py#L430) or [`SceneGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/graph.py#L391) object and returns a [`ReducedProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L80) or [`ReducedSceneGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L48) object, respectively. -- [`.inflate()`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/oracles/oracle.py#L26) function, which takes a [`ReducedProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L80) or [`ReducedSceneGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L48) object and returns a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/graph.py#L430) or [`SceneGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/graph.py#L391) object, respectively. -- [`.fully_specify()`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/oracles/oracle.py#L40) function, which takes a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/graph.py#L430) and returns either a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/graph.py#L430) or a [`ReducedProblemGraph`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L80) with all possible predicates added to the goal scene without changing the original definition of the problem. +- [`.reduce()`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/oracles/oracle.py#L11) function, which takes a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/graph.py#L430) or [`SceneGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/graph.py#L391) object and returns a [`ReducedProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L80) or [`ReducedSceneGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L48) object, respectively. +- [`.inflate()`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/oracles/oracle.py#L65) function, which takes a [`ReducedProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L80) or [`ReducedSceneGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L48) object and returns a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/graph.py#L430) or [`SceneGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/graph.py#L391) object, respectively. +- [`.fully_specify()`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/oracles/oracle.py#L125) function, which takes a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/graph.py#L430) and returns either a [`ProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/graph.py#L430) or a [`ReducedProblemGraph`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L80) with all possible predicates added to the goal scene without changing the original definition of the problem. We refer to these predicates as "trivial predicates" in our paper. The `fully_specify` function is used to ensure that the problem is fully specified before evaluation. @@ -47,9 +47,9 @@ Some predicates require special care for reducing and inflating. The key idea behind our reduced representation is to represent our PDDL problem in a domain-specific manner with as few graph nodes and edges as possible to reduce the search space for our equivalence check. The reduced representation also allows us to perform higher-level graph manipulations and searches more efficiently. -**[`ReducedNode`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L9)**: +**[`ReducedNode`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L9)**: -A [`ReducedNode`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L9) is a domain-specific set of nodes that will be added to every `ReducedSceneGraph` or `ReducedProblemGraph` object on construction. They help hold metadata for specific types of predicates (non-binary predicates, 0-ary predicates, etc.) that are defined by the domain. +A [`ReducedNode`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L9) is a domain-specific set of nodes that will be added to every `ReducedSceneGraph` or `ReducedProblemGraph` object on construction. They help hold metadata for specific types of predicates (non-binary predicates, 0-ary predicates, etc.) that are defined by the domain. Here is an example on how to reduce different -ary predicates using `ReducedNode`s: @@ -66,7 +66,7 @@ There is no easy way to reduce these predicates, so the best way to keep track o Make sure to set the `position=` argument when adding the edge to the reduced graph to ensure you can reverse this action in your `inflate` function. **To register your `ReducedNode`**: -At the top of your oracle script, you can call the [`ReducedNode.register`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/reduced_graph.py#L12) method, like the following: +At the top of your oracle script, you can call the [`ReducedNode.register`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/reduced_graph.py#L12) method, like the following: ```python ReducedNode.register( @@ -85,6 +85,6 @@ ReducedNode.register( This will let you use your `ReducedNode` like any other enum throughout your oracle script (e.g. `ReducedNode.ROOMS`). #### 2.3 Implementing `.plan()` (Optional) -If you would like to evaluate whether or not a problem is _solvable_, you can implement the [`.plan()`](https://github.com/BatsResearch/planetarium/blob/main/planetarium/oracles/oracle.py#L56) function in your `Oracle`. +If you would like to evaluate whether or not a problem is _solvable_, you can implement the [`.plan()`](https://github.com/BatsResearch/planetarium/blob/4ca530982baec33ebe332f62b48a622f24b0dfb2/planetarium/oracles/oracle.py#L141) function in your `Oracle`. You will still be able to evaluate whether or not a problem is solvable without implementing this function, but it will rely on running the FastDownward planner to solve your problem, which may be *significantly* slower than using a domain-specific planner. (Note that you should try using the `lama-first` alias if possible, as this planner does not look for the optimal plan, just a satisficing plan.) \ No newline at end of file