Learn More about Felix

Users' Manual Technical Report

Installation Guide

Felix has the same installation procedure as Tuffy, with one tiny exception: the configuration file is named felix.conf instead of tuffy.conf. If you want to use Greenplum instead of PostgreSQL, you should install Greenplum in a way similar to PostgreSQL so that it can be accessed via JDBC. (You need to install the PostgreSQL plug-ins intagg and intarray in Greenplum. This link shows a way to do that.)

Usage Guide

Felix has the same command options and input/output format as Tuffy, but again, with some tiny exceptions: 1) Felix has an additional command option called -explain which, when enabled, will make Felix show you the logical plan without actually executing it; 2) Felix has some additional options that setup Hadoop and Greenplum. The details can be found in the user manual.

An Example

After unpacking Felix, you can find an example MLN in the directory sample. The content of the program file (prog.mln) is as follows:

*seqTime(seqid, date)
*word(seqid, wordid, word)
*feature(wordid, feature)
*weight(label, feature, double_)
*tcrt(word, word)

dwinner(word, date)
dloser(word, date)
label(seqid, wordid, label!)
tcoref(wordid, wordid)
*tcoref_map(wordid, wordid)

dwinner(text1, date) := label(seq, word, "WIN"), tcoref_map(word, word1), 
word(seq1, word1, text1), seqTime(seq, date).

dloser(text1, date) := label(seq, word, "LOS"), tcoref_map(word, word1), 
word(seq1, word1, text1), seqTime(seq, date).

tcoref(t1, t1).
tcoref(t1, t2) => tcoref(t2, t1).
tcoref(t1, t2), tcoref(t2, t3) => tcoref(t1, t3).

20 word(seqid1, wordid1, word1), word(seqid2, wordid2, word2), tcrt(word1, w), tcrt(word2, w) 
=> tcoref(wordid1, wordid2)

wgt: word(seq, id, word), feature(id, feature), weight(label, feature, wgt) 
=> label(seq, id, label)

5 label(seq, word, "WIN"), tcoref_map(word, word1), word(seq1, word1, text1), seqTime(seq, date) 
=> dwinner(text1, date)

5 label(seq, word, "LOS"), tcoref_map(word, word1), word(seq1, word1, text1), seqTime(seq, date) 
=> dloser(text1, date)

5 dwinner(t1, date) => !dloser(t1, date)

Run the following command:

java -jar felix.jar -i sample/prog.mln -e sample/evidence.db -queryFile sample/query.db -r out.txt -explain

... and you will immediately see the following execution plan printed on the console:

Execution Plan:

Concurrently:
{COREF} Operator of {tcoref(wordid1, wordid2)} with {4} Relevant Clauses Communicate
{tcoref(wordid1, wordid2)}

Concurrently:
{LR} Operator of {label(seqid1, wordid2, label3)} with {3} Relevant Clauses Part
itioned by: {label(seqid1, wordid2, label3)=(round((seqid1 * 1.0)) % 2) = 0} Communicate
{label(seqid1, wordid2, label3)}
{LR} Operator of {label(seqid1, wordid2, label3)} with {3} Relevant Clauses Part
itioned by: {label(seqid1, wordid2, label3)=(round((seqid1 * 1.0)) % 2) = 1} Communicate
{label(seqid1, wordid2, label3)}

Concurrently:
{TUFFY} Operator of {dloser(word1, date2),dwinner(word1, date2)} with {3} Releva
nt Clauses Communicate {label(seqid1, wordid2, label3), tcoref(wordid1, wordid2)}

To interpret, Felix will run this MLN as three operators; it will solve the relation tcoref as correlation clustering, label as logistic regression and dloser/dwinner together as a generic MLN using Tuffy. The Communicate clause in the execution plan means that the corresponding relations are shared with other operators. You can also read from this execution plan that Felix will run two instances of Logistic Regression concurrently when computing label, with each of them working on a different portion of the data. In this example, the data is partitioned by hashing the first argument (seqid) of label.

Note that Felix won't actually execute the operations listed above. To actually run this plan, simply remove the -explain command option.

Usually, -explain is much cheaper than actually running inference because Felix only goes through the evidence file once in explain mode and does not materialize anything else. Once you find the execution plan acceptable, you can remove -explain and run again. (Unfortunately, the current version of Felix does not provide a way for you to tune the execution plan. If you find the execution plan generated by Felix to be unreasonable, you can try to slightly change your program; or if you think it is a bug or something need to be improved, please feel free to contact us.)

Felix in Depth

Browse the java doc online.

Check out the unit tests coverage report.

Read the technical report.

Download the user manual.

Skim a poster on Felix.

Or, stare at the following picture: