Getting Started

System requirement

Phillip works under Linux, Mac OS X, or Windows.
Before installing Phillip, the following softwares / libraries should be installed.

• C++ compiler supporting C++11
• Python 2.7
• ILP solver (Gurobi Optimizer ver.6.0 or LPSolve 5.5.X)

Since Phillip is compiled as a 32 bit binary on Windows, even if you use 64bit Windows, install ILP solvers for 32bit Windows.

Installation

Linux, Max OS X

1. Get a clone of Phillip from Github.
   • If you have installed git, execute the command $ git clone https://github.com/kazeto/phillip.git.
2. Move to the directory where Phillip is installed.
3. Execute the command $ python tools/configure.py. It creates a makefile on the current directory.
4. Configure environment variables.
   • If you use LPSolve, add the path of the header directory of LP-Solve to CPLUS_INCLUDE_PATH.
   • If you use Gurobi Optimizer;
     • Add the path of directory of Gurobi Optimizer to GUROBI_HOME.
     • Add $GUROBI_HOME/include to CPLUS_INCLUDE_PATH.
     • Add $GUROBI_HOME/lib to LIBRARY_PATH and LD_LIBRARY_PATH.
5. Execute the command $ make. Then Phillip is compiled as ./bin/phil.
6. (Optional) Execute the command $ make test for a test run.

Windows

1. Get a clone of Phillip from Github.
2. Open the solution file of Visual C++ at vs/phillip.sln.
3. Configure the solution.
   • If you use LPSolve;
     • Add the path of the header directory of LPSolve to Additional Include Directories.
   • Add the path of the library directory of LPSolve to Additional Library Directories.
     • Add the symbol USE_LP_SOLVE to Preprocessor Definitions.
   • Add liblpsolve55d.lib to Additional Dependencies for Debug Build.
   • Add liblpsolve55.lib to Additional Dependencies for Release Build.
   • If you use Gurobi Optimizer;
     • Add the path of the header directory of LPSolve to Additional Include Directories.
   • Add the path of the library directory of LPSolve to Additional Library Directories.
     • Add the symbol USE_GUROBI to Preprocessor Definitions.
   • Add gurobi60.lib and gurobi_c++mtd2013.lib to Additional Dependencies for Debug Build.
   • Add gurobi60.lib and gurobi_c++mt2013.lib to Additional Dependencies for Release Build.
4. Build the solution.

Basic Usage

1. Prepare Inputs

At first, write your observation and knowledge base in LISP format.

For example, let's consider following knowledge base and observation for coreference resolution task:

• kb.lisp

      (B (name kb01) (=> (steal-vb e1 x y) (criminal-jj e2 x)))
      (B (name kb02) (=> (criminal-jj e1 x) (arrest-vb e2 y x)))

• obs.lisp

      ; "Tom robbed jewels. Police arrested him."
      (O (name obs01) (^ (steal-vb E1 Tom Jewel) (arrest-vb E2 Police he)))

To know the detail of their format, Refer Input.

2. Compile knowledge base

Before inference, you have to compile your knowledge base to a binary database. This database is needed to make inference efficient.

Here is an example of command:

    $ bin/phil -m compile -c dist=basic -c tab=null -k compiled -P 8 kb.lisp

Since input can be given via STDIN, This command is equal to following one:

    $ cat kb.lisp | bin/phil -m compile -c dist=basic -c tab=null -k compiled -P 8

To know the detail of command options, refer to [Command Line Options](./Command Line Options).

3. Run

Using your observation and pre-compiled knowledge-base, let's run Phillip.

On running, you must give three command options, -c lhs=<NAME>, -c ilp=<NAME> and -c sol=<NAME>. These options specify the movement of Phillip in inference;

• -c lhs: specifies how to generate candidates of the solution hypothesis.
• -c ilp: specifies how to convert candidate hypotheses into ILP problem.
• -c sol: specified which to use for optimization of converted ILP problem.

Here is an example of command:

    $ bin/phil -m infer -k compiled -c lhs=depth -c ilp=weighted -c sol=gurobi -P 8 -T 120 obs.lisp

To know the detail of command options, refer to [Command Line Options](./Command Line Options).

4. Read outputs

Phillip outputs results of abduction as XML-format.