-
Notifications
You must be signed in to change notification settings - Fork 38
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #517 from aiplan4eu/docs
Various improvements to documentation
- Loading branch information
Showing
34 changed files
with
2,236 additions
and
169 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| engines/* | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| Contributor's Guide | ||
| =================== | ||
|
|
||
|
|
||
|
|
||
| Documentation | ||
| ------------- | ||
|
|
||
| The documentation is maintained in the `docs/` folder of the `main repository <https://github.com/aiplan4eu/unified-planning/tree/master/docs>`_ | ||
| It consists of a collection of reStructuredText documents and python notebooks that rendered to HTML and published on `readthedocs <https://unified-planning.readthedocs.io/en/latest/>`_ on each release. | ||
|
|
||
|
|
||
| Building the documentation | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
|
|
||
| The documentation can be built locally like so:: | ||
|
|
||
| cd docs/ # enter the documentation folder | ||
| pip install -r requirements.txt # install documentation toolchain | ||
| make html | ||
|
|
||
| After this, the documentation will be available as a set of HTML pages in the `_build/html` folder and can be visualized with a regular web browser. | ||
|
|
||
|
|
||
| Updating the Reference API | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| The reference API part of the documentation is built automatically by the `docs/generate_api_doc.py <https://github.com/aiplan4eu/unified-planning/blob/master/docs/generate_api_doc.py>`_ script. | ||
| The script contains the list of classes that will appear in the documentation. | ||
| If you contribute a new *user-facing* class, the list of classes should be updated to make it appear in the API reference. | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| Issue Tracking | ||
| -------------- | ||
|
|
||
| Issue tracking is done in GitHub issues: https://github.com/aiplan4eu/unified-planning/issues |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
|
|
||
| Available Engines | ||
| ================= | ||
|
|
||
|
|
||
|
|
||
| The tables below give a high-level overview of the planning engines integrated with the UP. | ||
|
|
||
| The characterization of the planning systems is deliberately kept very broad and is mainly intended to help identify which planners are relevant for a given class of problem. We redirect you to the specific documentation of each planner for a more in depth characterization of their features and limitations. | ||
|
|
||
| In this page only appear solvers that are *officially integrated* in the unified planning library, for which we have reasonable confidence that they will not give you incorrect results (i.e. they successfully pass all :ref:`engine tests <testing_engines>`), now and in the future (i.e. they have a clearly identified maintainer). | ||
| We do mention some solvers whose integration is partial, but that may be nevertheless of interest in some special cases. | ||
|
|
||
| Action-Based Planning | ||
| ^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| .. list-table:: | ||
|
|
||
| * - Engine | ||
| - Operation modes | ||
| - Classical | ||
| - Numeric | ||
| - Temporal | ||
| - Metrics | ||
| * - `Fast-Downward`_ | ||
| - OneShot, Anytime | ||
| - Y | ||
| - | ||
| - | ||
| - plan length, action costs | ||
| * - `ENHSP`_ | ||
| - OneShot, Anytime | ||
| - Y | ||
| - Y | ||
| - | ||
| - action costs, final value | ||
| * - `Tamer`_ | ||
| - OneShot | ||
| - Y | ||
| - Y | ||
| - Y | ||
| - | ||
| * - `Aries`_ [#aries-actions]_ | ||
| - OneShot, Anytime | ||
| - Y | ||
| - Y (integers) | ||
| - Y | ||
| - plan length, makespan, action costs | ||
| * - `Pyperplan`_ [#pyperplan-note]_ | ||
| - OneShot | ||
| - Y | ||
| - | ||
| - | ||
| - | ||
|
|
||
| .. [#aries-actions] Aries' focus is on hierarchical planning and scheduling and is likely not competitive with other planners in action-based planning. | ||
| .. [#pyperplan-note] Pyperplan is mostly intended for education purposes and cannot be expected to scale to non-trivial problems. | ||
| Plan Validation | ||
| ^^^^^^^^^^^^^^^ | ||
|
|
||
| .. list-table:: | ||
|
|
||
| * - Engine | ||
| - Action-Based planning | ||
| - Numeric | ||
| - Temporal | ||
| - Hierarchical | ||
| - Scheduling | ||
| * - `UP (builtin)` | ||
| - Y | ||
| - Y | ||
| - | ||
| - | ||
| - | ||
| * - `Tamer`_ | ||
| - Y | ||
| - Y | ||
| - Y | ||
| - | ||
| - | ||
| * - `Aries`_ | ||
| - Y | ||
| - Y | ||
| - Y | ||
| - Y | ||
| - Y | ||
|
|
||
|
|
||
| Hierarchical Planning | ||
| ^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| .. list-table:: | ||
|
|
||
| * - Engine | ||
| - Operation modes | ||
| - Total-Order | ||
| - Partial-Order | ||
| - Numeric | ||
| - Temporal | ||
| - Metrics | ||
| * - `Aries`_ | ||
| - OneShot, Anytime | ||
| - Y | ||
| - Y (integers) | ||
| - Y | ||
| - Y | ||
| - plan length, makespan, action costs | ||
|
|
||
| A WIP integration is known for `SIADEX <https://github.com/UGR-IntelligentSystemsGroup/up-siadex/>`_. | ||
|
|
||
| Scheduling | ||
| ^^^^^^^^^^ | ||
|
|
||
| The only planner with full support for scheduling is `Aries`_. Integration work is known for the `discrete-optimization suite <https://github.com/aiplan4eu/up-discreteoptimization>`_ and for `PPS <https://github.com/aiplan4eu/up-pps>`_. | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| .. _`aries`: https://github.com/plaans/aries/blob/master/planning/unified/plugin/README.md | ||
| .. _`fast-downward`: https://github.com/aiplan4eu/up-fast-downward/blob/main/README.md | ||
| .. _`tamer`: https://github.com/aiplan4eu/up-tamer/blob/master/README.md | ||
| .. _`enhsp`: https://github.com/aiplan4eu/up-enhsp/blob/master/README.md | ||
| .. _`spiderplan`: https://github.com/aiplan4eu/up-spiderplan/blob/master/README.md | ||
| .. _`fmap`: https://github.com/aiplan4eu/up-fmap/blob/master/README.md | ||
| .. _`lpg`: https://github.com/aiplan4eu/up-lpg/blob/master/README.md | ||
| .. _`pyperplan`: https://github.com/aiplan4eu/up-pyperplan/blob/master/README.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
|
|
||
| Engine selection and preference list | ||
| ==================================== | ||
|
|
||
| The UP library instantiates planning engines via the ``unified_planning.engines.Factory`` class. A single instance of ``Factory`` is needed for each environment and can be retrieved by the factory property of an ``Environment`` object. This class maintains a set of known engines each with a unique name, and offers methods to add new engines by specifying the name and the python class, to instantiate and retrieve planning engines by name and to read configuration files in custom locations. | ||
|
|
||
| If operation modes are invoked without specifying the name of an engine to use, the UP library will filter the list of engines known to the ``Factory`` by checking which engine supports the given ``problem kind`` with the given operation mode. If more than one engine passes the check, the ``Factory`` uses a `customizable` preference list to select the engine to retrieve. The default preference list is a simple heuristic we developed, but a user can override it by setting the ``preference_list`` property of the ``Factory``. | ||
|
|
||
| A user can set a custom preference list and add external engines to the library by creating a configuration file called either ``up.ini`` or ``.up.ini`` and located in any of the parent directories from which the program code was called. Alternatively also ``~/up.ini``, ``~/.up.ini``, ``~/.uprc`` are valid files that the library checks by default. The syntax of the configuration files is straightforward and depicted below. | ||
|
|
||
| .. code-block:: | ||
| :caption: Preference List structure | ||
| [global] | ||
| engine_preference_list: <engine-name> <engine-name> <engine-name> | ||
| [engine <engine-name>] | ||
| module_name: <module-name> | ||
| class_name: <class-name> | ||
| Plug-in system | ||
| -------------- | ||
|
|
||
| As mentioned at the beginning, one of key characteristics of the UP library is the engine plug-in system. The idea is that the set of planning engines is not fixed a-priori and can be easily extended. In this section we detail this mechanism together with the concept of “meta-engine”, which is an engine using another engine as a service to achieve a certain operation mode. An overview of the engines integrated throughout the project by the consortium partners is available in this section. | ||
|
|
||
| Meta-Engines | ||
| ------------ | ||
| In addition to plain planning engines, the UP library embeds the concept of “meta-engine”. A meta-engine is a planning engine that needs access to another engine (or meta-engine) services to provide its own services. For example, the ``NaiveReplanner`` meta-engine (partially reported in the snippet below) implements the ``Replanner`` OperationMode by repeatedly calling any ``OneshotPlanner`` engine internally. | ||
|
|
||
| .. code-block:: | ||
| :caption: NaiveReplanner partial implementation and usage | ||
| class NaiveReplanner(MetaEngine, mixins.ReplannerMixin): | ||
| ... | ||
| def _resolve(self, timeout, output_stream): | ||
| return self.engine.solve(self._problem, timeout, output_stream) | ||
| def _update_initial_value(self, fluent, value): | ||
| self._problem.set_initial_value(fluent, value) | ||
| def _add_goal(self, goal): | ||
| self._problem.add_goal(goal) | ||
| def _add_action(self, action): | ||
| self._problem.add_action(action) | ||
| ... | ||
| factory.add_meta_engine("naive-replanner", __name__, "NaiveReplanner") | ||
| problem = … | ||
| with Replanner(name="naive-replanner[tamer]", problem=problem) as replanner: | ||
| result = replanner.resolve() | ||
| ... | ||
| The general idea of a meta-engine is to implement algorithms relying on planning engines to implement certain operation modes. The library uses a special naming convention for meta engines; if the meta engine is called ``meta``, its instantiation with the engine ``e`` is called ``meta[e]``. One can add meta-engine to the library via the ``Factory`` class, similarly to engines, the ``add_meta_engine(name: str, module_name: str, class_name: str)`` method allows the user to add new meta engines, which are automatically instantiated with all the compatible engines. Compatibility between an engine and a meta-engine is determined by the UP thanks to the MetaEngine class that is the base of every meta-engine: each meta-engine must implement the ``is_compatible_engine(engine: Type[Engine])`` method, which checks if a given engine is compatible with the meta-engine at hand. This schema allows the creation of very general algorithms whose capability varies depending on the engine they are instantiated with. | ||
|
|
||
|
|
||
|
|
Oops, something went wrong.