Skip to content

Commit f71589b

Browse files
emugdanemugdan
authored
[issue1190] Update documentation on the Fast Downward website.
The online documentation for Fast Downward has been updated. Especially the steps for getting started with Fast Downward and running the planner should be clearer now.
1 parent 555cdab commit f71589b

48 files changed

Lines changed: 443 additions & 328 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/README.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,17 @@
11
# Fast Downward Documentation
22

3-
- [Getting started](quick-start.md) provides instructions to get you started
4-
as quickly as possible.
5-
- [Planner usage](planner-usage.md) explains more ways of invoking the
6-
planner.
7-
- [PDDL support](pddl-support.md) specifies the subset of PDDL that is
8-
supported by Fast Downward.
3+
- [Planner usage](planner-usage.md) explains ways of invoking the
4+
planner. For setting up Fast Downward see [Getting started](quick-start.md).
95
- [Search plugins](search/index.md) documents the different ingredients for the
106
search configuration, such as [search algorithms](search/SearchAlgorithm.md) and [heuristics](search/Evaluator.md).
117
- [Syntax for search plugins](search-plugin-syntax.md) defines the syntax for configuring the search
128
plugins.
13-
- [IPC planners](ipc-planners.md) explains how to run some planner
14-
configurations from IPC 2011 and 2018.
159
- [Exit Codes](exit-codes.md) describes the exit codes as returned by the
1610
planner.
11+
- [PDDL support](pddl-support.md) specifies the subset of PDDL that is
12+
supported by Fast Downward.
13+
- [IPC planners](ipc-planners.md) explains how to run some planner
14+
configurations from IPC 2011 and 2018.
1715
- [Translator output format](translator-output-format.md) documents the
1816
internal file format that is generated by the translator component and
19-
used as input by the search component.
17+
used as input by the search component.

‎docs/SUMMARY.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
This file controls the navigation below "documentation" on the website.
22

33
- [](README.md)
4-
- [Getting started](quick-start.md)
54
- [Planner usage](planner-usage.md)
6-
- [PDDL support](pddl-support.md)
75
- [Search plugins](search/)
86
- [Syntax for search plugins](search-plugin-syntax.md)
9-
- [IPC planners](ipc-planners.md)
107
- [Exit codes](exit-codes.md)
11-
- [Translator output format](translator-output-format.md)
8+
- [PDDL support](pddl-support.md)
9+
- [IPC planners](ipc-planners.md)
10+
- [Translator output format](translator-output-format.md)

‎docs/planner-usage.md‎

Lines changed: 91 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
# Usage
22

3-
To run Fast Downward, use the `fast-downward.py` driver script. At minimum, you
4-
need to specify the PDDL input files and search options consisting of a [search
5-
algorithm](search/SearchAlgorithm.md) with one or more [evaluator
6-
specifications](search/Evaluator.md). The driver script has many options to do
7-
things like running portfolios, running only the translation component of the
8-
planner, using a non-standard build, running a plan validator and various other
3+
Fast Downward is a domain-independent classical planning system that consists of two main components:
4+
5+
- a translation phase translates a PDDL input task into a SAS+ tasks.
6+
- a search phase perfoms a search on a SAS+ task to find a plan.
7+
8+
To run Fast Downward, use the `fast-downward.py` driver script.
9+
We will here give a short introduction into the basic usage of the main components.
10+
11+
Note that the driver script has many additional options to do things like running portfolios, using a non-standard build and various other
912
things. To see the complete list of options, run
1013

1114
./fast-downward.py --help
@@ -14,19 +17,94 @@ If you want to run any of the planners based on Fast Downward that
1417
participated in IPC 2011, please also check the page on
1518
[IPC planners](ipc-planners.md).
1619

17-
## Caveats
20+
## Translation component
21+
To translate a PDDL input task into a SAS+ task without performing a search run the following:
22+
23+
./fast-downward.py --translate [<domain.pddl>] <task.pddl>
24+
25+
Note:
26+
27+
- Giving the domain file as input is optional.
28+
In case no domain file is specified, the component will search for a file called `domain.pddl` located in the same directory as the task file.
29+
- Translator component options can be specified after the input files following the `--translator-options` flag.
30+
31+
## Search component
32+
To run a search on a PDDL input task run the following:
33+
34+
./fast-downward.py [<domain.pddl>] <task.pddl> \
35+
--search "<some-search-algorithm>(<algorithm-parameters>)"
36+
37+
Note:
38+
39+
- The PDDL task is translated into a SAS+ task internally without the need to explicitly call the `translate` component.
40+
Instead of a PDDL task a SAS+ translator output file could be given as input. In this case the translation step is omitted.
41+
- Giving the domain file as input is optional.
42+
In case no domain file is specified, the component will search for a file called `domain.pddl` located in the same directory as the task file.
43+
- `<some-search-algorithm>` can be any of the [search algorithms](search/SearchAlgorithm.md) with corresponding `<algorithm-parameters>` as input.
44+
- Search component options can be specified anywhere after the input files.
45+
Search component options following translator component options need to first be escaped with the `--search-options` flag.
46+
47+
### Example
48+
49+
The following example is a recommended search algorithm configuration:
50+
[A* algorithm](search/SearchAlgorithm/#a_search_eager) with the [LM-cut heuristic](search/Evaluator/#landmark-cut_heuristic), which can be run as follows:
51+
52+
./fast-downward.py [<domain.pddl>] <task.pddl> --search "astar(lmcut())"
53+
54+
As this is a common search configuration an alias (`seq-opt-lmcut`) exists that results in the same execution and can be used as follows:
55+
56+
./fast-downward.py --alias seq-opt-lmcut [<domain.pddl>] <task.pddl>
1857

19-
The **search options** are built with flexibility in mind, not ease of
58+
### Aliases
59+
60+
Many other common search configurations are also specified as aliases. To see the full list of aliases call:
61+
62+
./fast-downward.py --show-aliases
63+
64+
To find out which actual search options the aliases corresponds to, check the source code of the `src/driver/aliases.py` module.
65+
66+
For example to run the "LAMA 2011 configuration" of the planner, call:
67+
68+
./fast-downward.py --alias seq-sat-lama-2011 [<domain.pddl>] <task.pddl>
69+
70+
Note:
71+
72+
- This is not really the same as "LAMA 2011" as it participated at IPC 2011
73+
because there have been bug fixes and other changes to the planner since 2011.
74+
See ["IPC planners"](ipc-planners.md) for more information.
75+
76+
### Caveats
77+
78+
The search options are built with flexibility in mind, not ease of
2079
use. It is very easy to use option settings that look plausible, yet
2180
introduce significant inefficiencies. For example, an invocation like
2281

23-
```
24-
./fast-downward.py domain.pddl problem.pddl --search "lazy_greedy([ff()], preferred=[ff()])"
25-
```
82+
./fast-downward.py [<domain.pddl>] <task.pddl> \
83+
--search "lazy_greedy([ff()], preferred=[ff()])"
2684

2785
looks plausible, yet is hugely inefficient since it will compute the FF
28-
heuristic twice per state. See the [examples](#examples) at the bottom of this
29-
page to see how to call the planner properly. If in doubt, ask.
86+
heuristic twice per state. To circumvent this a [`let`-expression](search-plugin-syntax.md#variables_as_parameters) could be used:
87+
88+
./fast-downward.py [<domain.pddl>] <task.pddl> \
89+
--search "let(hff, ff(), lazy_greedy([hff], preferred=[hff]))"
90+
91+
## Validating plans
92+
To validate a plan found by some search algorithm using [VAL](https://github.com/KCL-Planning/VAL) run the following:
93+
94+
./fast-downward.py --validate [<domain.pddl>] <task.pddl> \
95+
--search "<some-search-algorithm>(<algorithm-parameters>)"
96+
97+
Note:
98+
99+
- [VAL](https://github.com/KCL-Planning/VAL) must be available locally and added to the PATH (see [Plan Validator](https://github.com/aibasel/downward/blob/main/BUILD.md#optional-plan-validator)).
100+
- The search algorithm must be specified (see [Search component](#search_component)).
101+
102+
## Exit codes
103+
104+
The driver exits with 0 if no errors are encountered. Otherwise, it
105+
returns the exit code of the first component that failed (cf. [documentation of
106+
exit codes](exit-codes.md)).
107+
30108

31109
## Different builds
32110

@@ -45,11 +123,6 @@ whether to do a debug or release build and creates subdirectories in the
45123
output folder. Use the full path to the binaries as the value of
46124
`--build` (e.g., `--build=path/to/visual/studio/project/bin/Debug/`).
47125

48-
## Exit codes
49-
50-
The driver exits with 0 if no errors are encountered. Otherwise, it
51-
returns the exit code of the first component that failed (cf. [documentation of
52-
exit codes](exit-codes.md)).
53126

54127
## LP support
55128

@@ -62,62 +135,3 @@ discussion of the relative performance of CPLEX and SoPlex.
62135
Note that SoPlex is not a MIP solver, so using it for configurations
63136
that require integer variables will result in an error. Please use CPLEX
64137
for such cases.
65-
66-
## Examples
67-
68-
### A* search
69-
70-
# landmark-cut heuristic
71-
./fast-downward.py domain.pddl task.pddl --search "astar(lmcut())"
72-
73-
# iPDB heuristic with default settings
74-
./fast-downward.py domain.pddl task.pddl --search "astar(ipdb())"
75-
76-
# blind heuristic
77-
./fast-downward.py domain.pddl task.pddl --search "astar(blind())"
78-
79-
### Lazy greedy best-first search with preferred operators and the queue alternation method
80-
81-
## using FF heuristic and context-enhanced additive heuristic (previously: "fFyY")
82-
./fast-downward.py domain.pddl task.pddl \
83-
--search "let(hff, ff(), let(hcea, cea(), lazy_greedy([hff, hcea], preferred=[hff, hcea])))"
84-
85-
86-
## using FF heuristic (previously: "fF")
87-
./fast-downward.py domain.pddl task.pddl \
88-
--search "let(hff, ff(), lazy_greedy([hff], preferred=[hff]))"
89-
90-
91-
## using context-enhanced additive heuristic (previously: "yY")
92-
./fast-downward.py domain.pddl task.pddl \
93-
--search "let(hcea, cea(), lazy_greedy([hcea], preferred=[hcea]))"
94-
95-
96-
### LAMA 2011
97-
98-
```
99-
./fast-downward.py --alias seq-sat-lama-2011 domain.pddl task.pddl
100-
```
101-
102-
runs the "LAMA 2011 configuration" of the planner. (Note that this is
103-
not really the same as "LAMA 2011" as it participated at IPC 2011
104-
because there have been bug fixes and other changes to the planner since
105-
2011. See ["IPC planners"](ipc-planners.md) for more information.)
106-
To find out which actual search options the LAMA 2011 configuration
107-
corresponds to, check the source code of the `src/driver/aliases.py` module.
108-
109-
110-
## 64-bit mode
111-
112-
Older planner versions built the planner in 32-bit mode by default
113-
because of lower memory consumption. As part of the meta issue
114-
[issue213](http://issues.fast-downward.org/issue213) we
115-
decreased the memory consumption of 64-bit builds to the point where
116-
there should be no difference between 32- and 64-bit builds for most
117-
configurations. Therefore, we use the native bitwidth of the operating
118-
system since January 2019.
119-
120-
## Other questions?
121-
122-
Please get in touch! See the [home page](https://www.fast-downward.org) for various
123-
contact options.

0 commit comments

Comments
 (0)