From 9bf02fff667c9e5de7085d3eaff2ba50f1b1a4d0 Mon Sep 17 00:00:00 2001 From: Mau Magnaguagno Date: Sat, 2 Mar 2024 03:59:42 -0300 Subject: [PATCH] Improve documentation [ci skip] --- docs/Custom.md | 8 +++---- docs/Representation.md | 4 ++-- docs/basic.jshop.dot.svg | 47 ++++++++++++++++++++-------------------- 3 files changed, 29 insertions(+), 30 deletions(-) diff --git a/docs/Custom.md b/docs/Custom.md index 9402b0f..af950ed 100644 --- a/docs/Custom.md +++ b/docs/Custom.md @@ -187,10 +187,10 @@ end It is impossible to propagate variables all the time, some variables must be bound during run-time. Free variables are created as empty strings, being used as pointers to their future values. A ``generate(precond_pos, precond_not, *free)`` method will do the hard work, using positive preconditions to find possible values for the free variables, only yielding values that satisfy the preconditions requested. -Therefore a positive precondition set that does not mention all free variables will generate zero unifications. +Therefore, a positive precondition set that does not mention all free variables will generate zero unifications. In classical planning it is possible to try the entire list of objects as values, but in HTN there may be an infinite number of values. It is possible to solve this problem adding each object possible to be used to the initial state, ``(object kiwi) (object banjo)``, in the initial state and add them in the preconditions, ``(object var)``. -Unifications only happen to methods in HyperTensioN, a method must be created to bound values for an operator if a free variable value is not know. +Unifications only happen to methods in HyperTensioN, a method must be created to bound values for an operator if a free variable value is not known. The following example goes beyond this specification, using an instance variable to avoid cached positions created by other decomposition paths. One can always use ``if-else`` constructs to speed-up problem solving. Here it is clear that no state memory is created by HyperTensioN, that is why ``@visited_at`` is used. @@ -265,7 +265,7 @@ end ``` The compilers use a less readable but optimized approach without generate and free variables. -Static analysis is able to determine that ``connected`` is a rigid predicate, never changes, which can be stored in a constant outside the state. +Static analysis is able to determine that ``connected`` is a rigid predicate, never changes, which can be stored as a constant outside the state. Both ``at`` and ``connected`` predicates are iterated, looking for a suitable set of values that satisfy the original method preconditions. ```Ruby @@ -285,7 +285,7 @@ end With the domain ready it is time for the problem, with an initial state and task list. The initial state is defined as an Array in which each index represent one predicate while the value is an array of possible terms. The task list follows the same principle, an array of each task to be solved. -Note that the names must match the ones defined in the domain and tasks are be decomposed in the same order they are described (in ordered mode). +Note that the names must match the ones defined in the domain and tasks to be decomposed in the same order they are described (in ordered mode). Even predicates that do not appear in the initial state must be declared, in this example nothing is reported so ``state[REPORTED]`` is declared as ``[]``. If the problem does not generate objects during run-time a speed improvement can be obtained moving them to constants, therefore the comparisons will be pointer-based. Goal states can be defined as an ``invisible_goal`` operator, that have the goal state as precondition and no effect, being the last task to be decomposed. diff --git a/docs/Representation.md b/docs/Representation.md index 6d0ae89..a74c5b2 100644 --- a/docs/Representation.md +++ b/docs/Representation.md @@ -153,7 +153,7 @@ pre_irrelevant = ['cookie', '?y'] ## States, Goals and Tasks The state represents how the objects are in the world in a moment. Anything not declared here is considered false, based on the [closed-world assumption](https://en.wikipedia.org/wiki/Closed-world_assumption). -Usually the initial and goal states are described in a classical planning problem, while initial state and tasks are described for HTN planning. +Usually the initial and goal states are described in classical planning problems, while initial state and tasks are described for HTN planning problems. Compare the following PDDL and JSHOP problem files: ```Lisp @@ -184,7 +184,7 @@ Compare the following PDDL and JSHOP problem files: JSHOP has an implicit goal, while PDDL has an explicit goal, which is reached by the application of the tasks (in an ordered or unordered fashion) it always maps to empty sets. The state is more compactly represented by a Hash ``{'predicate' => [['term1', 'term2'], ['other_term1', 'other_term2'], ...], 'other_predicate' => [...], ...}``, allowing simpler operations to obtain terms of a specific predicate. -Note that this state representation used by the parsing, extension and compiler modules differ from the one generated by the [Hyper_Compiler](../compilers/Hyper_Compiler.rb), which groups fluent predicates in a state Array ``HAVE = 0; [ [[:kiwi]] ]`` while keeping static predicates separate to speed-up state operations. +Note that this state representation used by the parser, extension and compiler modules differ from the one generated by the [Hyper_Compiler](../compilers/Hyper_Compiler.rb), which groups fluent predicates in a state Array ``HAVE = 0; [ [[:kiwi]] ]`` while keeping static predicates separate to speed-up state operations. The first element in the task list is a boolean that represents if the tasks are going to be decomposed in an orderly fashion or not. ```Ruby diff --git a/docs/basic.jshop.dot.svg b/docs/basic.jshop.dot.svg index 32ac451..e03785e 100644 --- a/docs/basic.jshop.dot.svg +++ b/docs/basic.jshop.dot.svg @@ -1,26 +1,26 @@ - - -basic + + +basic pickup - -pickup - -?a - -not (have ?a) - -(have ?a) + +pickup + +?a + +not (have ?a) + +(have ?a) drop - -drop - -?a - -(have ?a) - -not (have ?a) + +drop + +?a + +(have ?a) + +not (have ?a) swap @@ -35,10 +35,9 @@ swap_case_0 - -(have ?x) -not (have ?y) +(have ?x) +not (have ?y) drop ?x @@ -53,8 +52,8 @@ swap_case_1 -(have ?y) -not (have ?x) +(have ?y) +not (have ?x) drop ?y