
Licence terms
=============

THIS SOURCE CODE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND, AND
ITS AUTHOR AND THE JOURNAL OF ARTIFICIAL INTELLIGENCE RESEARCH (JAIR)
AND JAIR'S PUBLISHERS AND DISTRIBUTORS DISCLAIM ANY AND ALL WARRANTIES,
INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE, AND ANY WARRANTIES OF NON
INFRINGEMENT. THE USER ASSUMES ALL LIABILITY AND RESPONSIBILITY FOR
USE OF THIS SOURCE CODE, AND NEITHER THE AUTHOR, NOR JAIR, NOR JAIR'S
PUBLISHERS AND DISTRIBUTORS WILL BE LIABLE FOR DAMAGES OF ANY KIND
RESULTING FROM ITS USE. Without limiting the generality of the
foregoing, neither the author, nor JAIR, nor JAIR's publishers and
distributors, warrant that the Source Code will be error-free, will
operate without interruption, or will meet the needs of the user.

The BDPO2 source code is licensed under a Creative Commons
Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0). You
are free to copy and redistribute the source code in any medium or
format, and transform or build upon it, for any purpose, even
commercially. However, if you do so, you must give appropriate credit
to the original authors, provide a link to the license, and indicate
if changes were made. If you transform or build upon this source code,
you must distribute your contributions under the same license as the
original (if you distribute them at all). You may not apply legal
terms or technological measures that legally restrict others from
doing anything the license permits.

For the full license terms, see
http://creativecommons.org/licenses/by-sa/4.0/legalcode


Instructions for compiling and running BDPO2
============================================

Note: The BDPO2 plan optimisation system invokes several other planners
and programs (including Fast Downward, Aras and VAL). For licence reasons,
these are not distributed together with the BDPO2 source code. You will
need to retrieve and compile/install them to run BDPO2.

The following is a step-by-step guide for configuring, compiling and
installing the necessary components. A standard unix build environment
and tool suite is assumed. It was tested on a computer running GNU/Linux
(Mint Debian Edition, 3.11).


1. Download a copy of hsp* [http://users.cecs.anu.edu.au/~patrik/un-hsps.html]
and unpack into main source directory. (This was tested with the hsp*
code as of 30/10/2015.)

2. Unpack/copy bdpo2 source files (bdpo2.cc, bandit.h) into main source
directory.

3. Configure hsp* as per instructions on download page. (Run "make" to
verify that it works.)

4. Configure bdpo2. The main config variables are the paths used to find
component programs invoked by bdpo2 (subplanners, plan validator and the
bdpo2 executable itself). These are defined by string constants in the
bdpo2.cc file:

  const std::string planner_location = ".";

planner_location is where the bdpo2 executable is located; this can be
set to an absolute path (which will allow it to be run in any working
directory) or relative path.

  const std::string fd_src_location = planner_location + "/downward/src";

Where to find components of the Fast Downward planner. The layout of the
FD source directory is assumed to be the standard one (i.e., with subdirs
for translator, preprocessor and search, and executables in those).

  const std::string validator_location = planner_location + "/downward/builds/release32/bin";

Where to find the PDDL plan validator (VAL). A copy is distributed with
the FD code, but the location of the executable in the FD source tree
(after building) is different between versions.

  const std::string aras_src_location = planner_location + "/aras/src";

Where to find the Aras postprocessor. As with FD, this is the path to the
main source directory; the postprocessor component is assumed to be in a
subdir called "search" within this.

To change any of these paths, edit the file and recompile (as below).

Alternatively, the commands used to invoke subplanners can be modified
directly. These are defined in an array of string constants called
planners_desc.

5. Add the following make target to makefile in main source directory:

bdpo2$(EXEEXT): bdpo2.o libhspsutil.a libhspsplan.a libhspspddl.a
	$(LINK) $(LFLAGS) bdpo2.o -lhspspddl -lhspsplan -lhspsutil $(LLIBS) -o bdpo2$(EXEEXT)

6. Run "make bdpo2".

7. Clone (or copy, or symlink) a copy of Fast Downward into a subdirectory
named "downward" in the main source directory. (This was tested with FD
revision 6938:9eda4a6ae3a9, updated on 30/10/2015.)

8. Apply the following patch to the Fast Downward code:

--- a/src/search/eager_search.cc        Thu Oct 29 10:47:19 2015 +0100
+++ b/src/search/eager_search.cc        Fri Oct 30 16:40:11 2015 +1100
@@ -155,6 +155,13 @@
                 statistics.inc_dead_ends();
                 continue;
             }
+           if (f_evaluator) {
+             if (eval_context.is_heuristic_infinite(f_evaluator))
+               continue;
+             int f_value = eval_context.get_heuristic_value(f_evaluator);
+             if (f_value >= bound)
+               continue;
+           }
             succ_node.open(node, op);

             open_list->insert(eval_context, succ_state.get_id());
@@ -432,6 +439,11 @@
     parser.add_option<int>(
         "boost",
         "boost value for preferred operator open lists", "0");
+    parser.add_option<ScalarEvaluator *>(
+        "f_eval",
+        "set evaluator for jump statistics. "
+        "(Optional; if no evaluator is used, jump statistics will not be displayed.)",
+        OptionParser::NONE);
     SearchEngine::add_options_to_parser(parser);


@@ -464,8 +476,6 @@
         opts.set("open", open);
         opts.set("reopen_closed", false);
         opts.set("mpd", false);
-        ScalarEvaluator *evaluator = nullptr;
-        opts.set("f_eval", evaluator);
         opts.set("preferred", preferred_list);
         engine = new EagerSearch(opts);
     }

9. Build Fast Downward. After successful build, rename the executable in
downward/src/search (by default called downward-release) to "downward".

10. Obtain a copy of the stand-alone postprocessor Aras.

Although the Aras postprocessor is built into the IPC 2011 Arvand and
IPC 2014 ArvandHed planners, their sources do not appear to include it
as a standalone program. We obtained this by asking the author of Aras,
Hootan Nakhost. For verification, the md5sum digest of the source package
is "c3046d5de9becd9310687fea3a7ab85d *aras.zip".

11. Compile the Aras code, and place (copy or symlink) in a subdirectory
named "aras" in the main source directory.

12. It should now be possible to run

  bdpo2 <domain> <problem> <input plan>

The planner writes several log files, and creates a subdirectory "temp"
for temporary files. Improved plans are saved as "bplan.N", where N is
a running counter (1, 2, etc). The main log of planner activity is called
run.log. Note that this log file is not automatically cleared when a new
planner run starts, so unless deleted between runs it will contain output
from earlier runs as well.
