Questions about fast-downward.py driver

[Robert P. Goldman]

Now that I have FD working again, I was updating a bunch of my existing code that invokes FD.  I was excited to replace the old-multi-step invocation with a single invocation of fast-downward.py.  But... I simply have not been able to make that work.

The descriptions on the "Planner Usage" page still stick to the multi-step process.  When I have tried to take the arguments suggested for the three-step process and merge them into a single step process, I find that I simply get errors.

For example, if I do

fast-downward.py --search --alias seq-sat-lama-2011 output

all is well.

But if I try to put a --alias to a top level call to fast-downward with a problem and domain file as arguments, I get "argument error: unknown option --alias"

fast-downward.py --plan-file /tmp/plan.pddl domain.pddl p01.pddl --alias seq-sat-lama-2011 

When I tried the ff configuration, I get "ScalarEvaluator hff not found at:

hff

Usage error occurred

fast-downward.py --plan-file /tmp/plan.pddl domain.pddl p01.pddl --search 'lazy_greedy([hff,hcea], preferred=[hff,hcea])' --heuristic 'hff=ff()' --heuristic 'hcea=cea()'

When I replace "--search" above with "--search-options" I get 

argument error: unknown option lazy_greedy([hff,hcea], preferred=[hff,hcea])

I will revert to using the three stage process, but I thought this worth a mention.  Maybe there are issues with the parsing of the command line when there are multiple steps in the chain?

Also, the pattern of usage for fast-downward described on the Usage web page does not fully agree with the pattern in the fast-downward.py help.  E.g., for the FF example, the output file comes first, rather than at the end, but the usage string clearly specifies "--search" before INPUT_FILE.  When I try to put the output in the pattern seemingly dictated by the fast-downward help string, I get the error "search needs exactly one input file."

./fast-downward.py --plan-file plan.pddl --search output 'lazy_greedy([hff,hcea], preferred=[hff,hcea])' 'hff=ff()'  'hcea=cea()'

Similarly, if the search options precede the heuristic options, I get an error.

I suspect that there's a notion of how different sorts of options need to be ordered, but it doesn't really come through in the available help strings.

This is what seems to work for me

./fast-downward.py <driver options> --translate <domain file> <problem file> --preprocess --search [--heuristic <opt>]* <search-config>

But it took quite a bit of trial and error to figure this out.

Probably this is obvious to anyone who has spent a bunch of time with FD lately, but I thought I would mention it in the hopes that other clueless users can be brought up to speed faster!

[Robert P. Goldman]

On Thursday, May 26, 2016 at 1:20:20 PM UTC-5, Robert P. Goldman wrote:

This is what seems to work for me

./fast-downward.py <driver options> --translate <domain file> <problem file> --preprocess --search [--heuristic <opt>]* <search-config>

OK, I was wrong about that.  When I do that, I get only the translator run -- the other operations don't get executed.  I was confused by the old files that were left around.

 

[Malte Helmert]

On 26.05.2016 20:20, Robert P. Goldman wrote:
> Now that I have FD working again, I was updating a bunch of my existing
> code that invokes FD. I was excited to replace the old-multi-step
> invocation with a single invocation of fast-downward.py. But... I
> simply have not been able to make that work.

Hi Robert,

sorry about that! The syntax is arcane indeed. There is some logic to
the way the driver script works, and I think it's completely described
in the output of

./fast-downward.py --help

which is worth studying in depth at least once. By comparison, the wiki
documentation lags behind and is in need of some TL&C.

> The descriptions on the "Planner Usage" page still stick to the
> multi-step process. When I have tried to take the arguments suggested
> for the three-step process and merge them into a single step process, I
> find that I simply get errors.

The main piece of information to be aware of is argument order, which
matters a lot. The driver script requires its arguments to be given in a
certain order:

- First, *driver options*. These are options handled directly by the
driver rather than any of the three planner components. These are the
options shown in the help string of "./fast-downward.py --help". In most
basic use cases, there are no driver options. The major exception as
aliases (see below).

- Second, *inputs*. These are usually PDDL files. (They can also be
things like "output.sas" or "output" if you want to run the three
components individually. But that's not really recommended as it's more
complicated, and there's usually not a strong reason why the three
components cannot be run in sequence.)

- Third, arguments that are passed on to the individual components.
Usually, these are arguments to the search component, but there are also
some arguments these days that affect the translator and one argument
that affects the preprocessor.

To understand better which component is called how, it may help to pay
attention to the output lines that start with "INFO", which list (among
other things) with which arguments the individual components are called.
For even more info, you can try adding "--log-level debug" before all
arguments and studying the output line that starts with "DEBUG".

> For example, if I do
>
> fast-downward.py --search --alias seq-sat-lama-2011 output
>
> all is well.
>
> But if I try to put a --alias to a top level call to fast-downward with
> a problem and domain file as arguments, I get "argument error: unknown
> option --alias"
>
> fast-downward.py --plan-file /tmp/plan.pddl domain.pddl p01.pddl --alias
> seq-sat-lama-2011

This is because "--alias" is a driver option and hence needs to be given
before the PDDL files. The following should work:

./fast-downward.py --plan-file /tmp/plan.pddl --alias seq-sat-lama-2011
domain.pddl p01.pddl

> When I tried the ff configuration, I get "ScalarEvaluator hff not found at:
> hff
> Usage error occurred
>
> fast-downward.py --plan-file /tmp/plan.pddl domain.pddl p01.pddl
> --search 'lazy_greedy([hff,hcea], preferred=[hff,hcea])' --heuristic
> 'hff=ff()' --heuristic 'hcea=cea()'

The reason for this is that the arguments for the search component are
processed sequentially, and identifiers like "hff" and "hcea" must be
defined before being used. So here the problem is that hff and hcea are
referenced before they are defined. Changing the order like this works
for me:

./fast-downward.py --plan-file /tmp/plan.pddl domain.pddl p01.pddl
--heuristic 'hff=ff()' --heuristic 'hcea=cea()' --search

'lazy_greedy([hff,hcea], preferred=[hff,hcea])'

Now hff and hcea are introduced before they are used.

Taking this apart:

* "--plan-file /tmp/plan.pddl" is a driver option.
* "domain.pddl p01.pddl" are the input files used.
* "--heuristic 'hff=ff()' --heuristic 'hcea=cea()' --search
'lazy_greedy([hff,hcea], preferred=[hff,hcea])' are the options passed
to the search component

> When I replace "--search" above with "--search-options" I get
>
> argument error: unknown option lazy_greedy([hff,hcea], preferred=[hff,hcea])

This is because the search component requires that the search algorithm
is specified as "--search SEARCH_ENGINE" rather than just
"SEARCH_ENGINE". To be honest, I'm not really sure if there is a good
global description of the search component option syntax on the wiki or
elsewhere. This needs to be improved.

> Also, the pattern of usage for fast-downward described on the Usage web
> page does not fully agree with the pattern in the fast-downward.py help.
> E.g., for the FF example, the output file comes first, rather than at
> the end, but the usage string clearly specifies "--search" before
> INPUT_FILE. When I try to put the output in the pattern seemingly
> dictated by the fast-downward help string, I get the error "search needs
> exactly one input file."
>
> ./fast-downward.py --plan-file plan.pddl --search output
> 'lazy_greedy([hff,hcea], preferred=[hff,hcea])' 'hff=ff()' 'hcea=cea()'

I think there is confusion here because "--search" can be an option for
the driver script (meaning "I want to manually select the search
component"), but also an option for the search component (meaning "I'll
specify the search algorithm next"). The disambiguation is by position,
as explained above. So here, you use the argument "--search" to tell the
driver that you want to run the search component only, and then the
search component complains about invalid options because it expects the
argument "--search" before "lazy_greedy". (Also, hff and hcea need to be
specified earlier and with "--heuristic", as above.)

> Similarly, if the search options precede the heuristic options, I get an
> error.
>
> I suspect that there's a notion of how different sorts of options need
> to be ordered, but it doesn't really come through in the available help
> strings.

Does rereading the first paragraphs of fast-downward.py --help after
reading the explanations in this email? Again, sorry for the poor
documentation.


In summary, the most common use case is to run the whole planner (all
components) on two given PDDL files while passing some options to the
search component, but no particular options to the other components. The
syntax for this is:

./fast-downward.py domain.pddl problem.pddl SEARCH_OPTIONS...

where SEARCH_OPTIONS are the options for the search component. These
will *always* include something like "--search SEARCH_ENGINE" and often
things like "--heuristic XXX" before that. Examples:

./fast-downward.py domain.pddl problem.pddl --search "astar(blind())"

./fast-downward.py domain.pddl problem.pddl --heuristic "h=ff()"
--search "eager_greedy(h,preferred=[h])"

The only other major "basic" use case is when you want to use an alias.
Aliases are driver options and hence go before the PDDL files. With an
alias, no "manual" search options can be given because the point of the
alias is to specify the search options. (Fortunately, combining an alias
with search component options will result in an error which explains why
this doesn't work.) Alias example:

./fast-downward.py --alias seq-sat-lama-2011 domain.pddl problem.pddl

Hope this helps somewhat. Please be sure to report back if there are
further things that don't seem to work as expected. We should use this
opportunity to improve the documentation.

Cheers,
Malte