README

COLIN
-----

This package contains COLIN, a planner for domains with continuous numeric
and/or duration dependent effects.  For more details, see the papers:

"COLIN: Planning with Continuous Linear Numeric Change", A. J. Coles,
A. I. Coles, M. Fox and D. Long, JAIR, 2012

"Temporal Planning in Domains with Linear Processes", A. J. Coles,
A. I. Coles, M. Fox and D. Long, IJCAI, 2009

Build Prerequisites
-------------------

In order to function, COLIN requires either CLP or CPLEX.  CLP is generally
faster, but CPLEX is also supported.  In both cases, you also need:

- cmake
- perl, bison and flex (used to build the parser)

Packages of these are available for most linux distributions. For Ubuntu, 
the following should install CLP and the other build pre-requisites:

sudo apt-get install cmake coinor-libcbc-dev coinor-libclp-dev \
                     coinor-libcoinutils-dev libbz2-dev bison flex
            

Compiling
---------

Compilation is in two stages:

1) Configure

Run one of:

run-cmake-debug, if you want to link against CLP, with debugging enabled

run-cmake-for-cplex-debug-x86, if you want to link against CLP and/or CPLEX,
  with debugging enabled.  It assumes you are using the 32-bit version of
  CPLEX, on Linux - if this is not the case, edit the script.

run-cmake-release, if you want to link against CLP, with debugging disabled,
  and producing a non-static binary.

run-cmake-static, if you want to link against CLP, with debugging disabled,
  and producing a statically linked binary

run-cmake-for-cplex-static-x86, if you want to link against CLP and/or CPLEX,
  and producing a statically linked binary.    It assumes you are using the
  32-bit version of CPLEX, on Linux - if this is not the case, edit the
  script.


Note that if you want to make static binaries with CLP, you must have static
versions of the CLP libraries installed.  This may mean downloading and
compiling CBC from source, making sure it makes static (not shared) libraries.
The advantage is that the binary produced does not require CLP to be installed
at run-time, which can be useful when running it on different machines.

*Users of 64-bit Machines*: it is almost certainly not worth compiling COLIN
in 64-bit mode.  To force 32-bit compilation, before running one of the
scripts above, type:

export CFLAGS=-m32
export CXXFLAGS=-m32
export LDFLAGS=-m32

In 32-bit mode, COLIN it is limited by the number of states it can
store in 4GB of memory.  To be able to store more states than this, with a
64-bit binary, considerably more memory is required, as e.g. ints and pointers
are twice the size.  (If you do have considerably more memory, then of course,
feel free to try.)

2) Build

If you ran one of the run-*-debug scripts, now run:

./build-debug

If you ran run-cmake-release, now run:

./build-release

If you ran one of the run-*-static scripts, now run:

./build-static


In all three cases, the binaries produced will be called colin-clp and/or
colin-cplex, and they will be located in either debug/colin, release/colin
or static/colin, respectively.


Running
-------

Once compiled, run, e.g.:

colin-clp domain.pddl problem.pddl

This runs COLIN on the given domain and problem file.

Note that the planner does not, itself, limit its time and/or memory usage.
Apply these by using the relevant shell commands beforehand, e.g.:

bash
ulimit -t 1800
ulimit -v 4000000
./colin-clp domain.pddl problem.pddl


...will limit the planner to 30 minutes of CPU and 4GiB of memory.


Feedback
--------

If you do something exciting with COLIN, do let us know.  If you tried to do 
something with it, but it failed, you may have found a bug.  In common with
POPF, the three most likely sources of bugs are:

The three most common causes of bugs (over 90% of bug reports) are:

- Using ADL. ADL is supported in the conditions of preferences, in the
  time-dependent costs of goal-collection actions, and one or two other niche
  cases.  We've attempted to make the planner degrade gracefully, but there are
  still cases where it will report problems using ADL as being unsolvable.
  Check there are no negative preconditions in your domain.
  
- Domain modelling bugs. COLIN and POPF support the full start--end semantics
  of PDDL 2.1, and self-overlapping actions, so errors in the temporal
  placement of preconditions and effects (at start, at end etc.) are more
  likely to cause issues with POPF than with other planners. For instance, if
  a 'move' action is written (erroneously) as deleting the old location at the
  end (rather than at the start), then POPF will consider concurrent move 
  actions for the same vehicle; whereas planners which do not make as clear a 
  distinction between the start and end-points of durative actions would not 
  consider this. Thus, in domains with errors such as this, POPF might have to
  consider a far larger search space than other temporal planners.

- If the plans don't validate, ensure you are passing the '-t 0.001' flag to
  VAL: the planner uses an epsilon value of 0.001, smaller than the default
  0.01 value used in VAL.

If none of those apply, email as small a possible domain and problem file
that cause the error you're observing to Andrew Coles:
firstname.lastname@kcl.ac.uk


Licence
-------

COLIN is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

COLIN is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.