\ifnum\pdfoutput>0 % pdflatex compilation
\documentclass[a4paper,10pt]{article}
\usepackage[pdftex]{graphicx}
\DeclareGraphicsExtensions{.pdf,.png,.jpg}
\RequirePackage[hyperindex]{hyperref}
\else % htlatex compilation
\documentclass{article}
\usepackage{graphicx}
\DeclareGraphicsExtensions{.png, .gif, .jpg}
\newcommand{\href}[2]{\Link[#1]{}{} #2 \EndLink}
\newcommand{\hypertarget}[2]{\Link[]{}{#1} #2 \EndLink}
\newcommand{\hyperlink}[2]{\Link[]{#1}{} #2 \EndLink}
\newcommand{\url}[1]{\Link[#1]{}{} #1 \EndLink}
\fi



\begin{document}
\title{\texttt{cplint} Manual}


\author{Fabrizio Riguzzi\\
fabrizio.riguzzi@unife.it}

\maketitle


\section{Introduction}


\texttt{cplint} is a suite of programs for reasoning with ICL \cite{DBLP:journals/ai/Poole97}, LPADs \cite{VenVer03-TR,VenVer04-ICLP04-IC} and CP-logic programs \cite{VenDenBru-JELIA06,DBLP:journals/tplp/VennekensDB09}. It contains programs both for inference and learning.

\section{Installation}
\texttt{cplint} is distributed in source code in the source code development tree of Yap. It includes Prolog and C files. Download it by following the instruction in \url{http://www.dcc.fc.up.pt/\string ~vsc/Yap/downloads.html}.

\texttt{cplint} requires \href{http://vlsi.colorado.edu/\string ~fabio/CUDD/}{CUDD}.
You can download CUDD from \url{ftp://vlsi.colorado.edu/pub/cudd-2.5.0.tar.gz}.

Compile CUDD:
\begin{enumerate}
\item decompress cudd-2.4.2.tar.gz
\item \texttt{cd cudd-2.4.2}
\item see the \texttt{README} file for instructions on compilation
\end{enumerate}

Install Yap together with \texttt{cplint}:
when compiling Yap following the instruction of the \texttt{INSTALL} file in the root of the Yap folder, use
\begin{verbatim}
configure --enable-cplint=DIR
\end{verbatim}
where \verb|DIR| is the directory where CUDD is, i.e., the directory ending with \texttt{cudd-2.5.0}.
Under Windows, you have to use Cygwin (CUDD does not compile under MinGW), so\\
\begin{verbatim}
configure --enable-cplint=DIR --enable-cygwin
\end{verbatim}

After having performed \texttt{make install} you can do \texttt{make installcheck} that will execute a suite of tests of the various programs. If no error is reported you have a working installation of \texttt{cplint}.


\section{Syntax}

LPAD and CP-logic programs consist of a set of annotated disjunctive clauses.
Disjunction in the head is represented with a semicolon and atoms in the head are separated from probabilities by a colon. For the rest, the usual syntax of Prolog is used.
For example, the  CP-logic clause
$$h_1:p_1\vee \ldots \vee h_n:p_n\leftarrow b_1,\dots,b_m ,\neg c_1,\ldots,\neg c_l$$
is represented by
\begin{verbatim}
h1:p1 ; ... ; hn:pn :- b1,...,bm,\+ c1,....,\+ cl
\end{verbatim}
 No parentheses are necessary. The \texttt{pi} are numeric expressions. It is up to the user to ensure that the numeric expressions are legal, i.e. that they sum up to less than one.

If the clause has an empty body, it can be represented like this
\begin{verbatim}
h1:p1 ; ... ;hn:pn.
\end{verbatim}
If the clause has a single head with probability 1, the annotation can be omitted and the clause takes the form of a normal prolog clause, i.e. 
\begin{verbatim}
h1:- b1,...,bm,\+ c1,...,\+ cl.
\end{verbatim}
stands for 
\begin{verbatim}
h1:1 :- b1,...,bm,\+ c1,...,\+ cl.
\end{verbatim}

The coin example of  \cite{VenVer04-ICLP04-IC} is represented as (see file \texttt{coin.cpl})
\begin{verbatim}
heads(Coin):1/2 ; tails(Coin):1/2:- 
     toss(Coin),\+biased(Coin).

heads(Coin):0.6 ; tails(Coin):0.4:- 
     toss(Coin),biased(Coin).

fair(Coin):0.9 ; biased(Coin):0.1.

toss(coin).
\end{verbatim}
The first clause states that if we toss a coin that is not biased it has equal probability of landing heads and tails. The second states that if the coin is biased it has a slightly higher probability of landing heads. The third states that the coin is fair with probability 0.9 and biased with probability 0.1 and the last clause states that we toss a coin with certainty.

Moreover, the bodies of rules can contain the built-in predicates:
\begin{verbatim}
is/2, >/2, </2, >=/2 ,=</2,
=:=/2, =\=/2, true/0, false/0,
=/2, ==/2, \=/2 ,\==/2, length/2
\end{verbatim}
The bodies can also contain the following
 library predicates:
\begin{verbatim}
member/2, max_list/2, min_list/2
nth0/3, nth/3
\end{verbatim}
plus the predicate
\begin{verbatim}
average/2
\end{verbatim}
that, given a list of numbers, computes its arithmetic mean.

The syntax of ICL program is the one used by the  \href{http://www.cs.ubc.ca/\string ~poole/aibook/code/ailog/ailog2.html}{AILog 2} system.
\section{Inference}
\texttt{cplint} contains various modules for answering queries.

%It consists of three Prolog modules  for answering queries using goal-oriented procedures plus
% three
%Prolog modules for answering queries using the definition of the semantics of LPADs and CP-logic.

These modules answer queries using using goal-oriented procedures:
\begin{itemize}
\item \texttt{lpadsld.pl}: uses the top-down procedure described in 
in \cite{Rig-AIIA07-IC} and \cite{Rig-RCRA07-IC}. It is based on SLDNF resolution and is an adaptation of the interpreter for ProbLog \cite{DBLP:conf/ijcai/RaedtKT07}.

It was proved correct \cite{Rig-RCRA07-IC} with respect to the semantics of LPADs for range restricted acyclic programs \cite{DBLP:journals/ngc/AptB91} without function symbols.

It is also able to deal with extensions of LPADs and CP-logic: the clause bodies can contain \texttt{setof} and \texttt{bagof}, the probabilities in the head may be depend on variables in the body and it is possible to specify a uniform distribution in the head with reference to a \texttt{setof} or \texttt{bagof} operator. These extended features have been introduced in order to represent CLP(BN) \cite{SanPagQaz03-UAI-IC} programs and PRM models \cite{Getoor+al:JMLR02}:
\texttt{setof} and \texttt{bagof} allow to express dependency of an attribute from an aggregate function of another attribute, as in CLP(BN)  and PRM, while the possibility of specifying a uniform distribution allows the use of the reference uncertainty feature of PRM.
\item \texttt{picl.pl}: performs inference on ICL programs \cite{Rig09-LJIGPL-IJ}
\item \texttt{lpad.pl}: uses  a top-down procedure based on SLG resolution \cite{DBLP:journals/jacm/ChenW96}. As a consequence, it works for any sound LPADs, i.e., any LPAD such that each of its instances has a two valued well founded model. 
\item \texttt{cpl.pl}: uses a top-down procedure based on SLG resolution and moreover checks that the CP-logic program is valid, i.e., that it has at least an execution model.
\item Modules for approximate inference:
\begin{itemize}
\item \texttt{deepit.pl} performs iterative deepening \cite{BraRig10-ILP10-IC}
\item \texttt{deepdyn.pl} performs  dynamic iterative deepening \cite{BraRig10-ILP10-IC}
\item \texttt{bestk.pl} performs  k-Best \cite{BraRig10-ILP10-IC}
\item \texttt{bestfirst.pl} performs  best first \cite{BraRig10-ILP10-IC}
\item \texttt{montecarlo.pl} performs  Monte Carlo \cite{BraRig10-ILP10-IC}
\item \texttt{mcintyre.pl}: implements the algorithm MCINTYRE (Monte Carlo INference wiTh Yap REcord) \cite{Rig11-CILC11-NC}
\end{itemize}
\item \texttt{approx/exact.pl} as \texttt{lpadsld.pl} but uses  SimplecuddLPADs, a modification of the \href{http://dtai.cs.kuleuven.be/problog/download.html}{Simplecudd} instead of the \texttt{cplint} library for building BDDs and computing the probability.
\end{itemize}

These modules answer queries using the definition of the semantics of LPADs and CP-logic:
\begin{itemize}
\item \texttt{semlpadsld.pl}: given an LPAD $P$, it generates all the instances of $P$. The probability of a query $Q$ is computed by identifying all the instances where $Q$ is derivable by SLDNF resolution.
\item \texttt{semlpad.pl}: given an LPAD $P$, it generates all  the instances of $P$. The probability of a query $Q$ is computed by identifying all the instances where $Q$ is derivable by SLG resolution.
\item \texttt{semlcpl.pl}: given an LPAD $P$,  it builds an execution model of $P$, i.e., a probabilistic process that satisfy the principles of universal causation, sufficient causation, independent causation, no deus ex machina events and temporal precedence. It uses the definition of the semantics given in \cite{DBLP:journals/tplp/VennekensDB09}.
\end{itemize}
%For program with function symbols, the semantics of LPADs and CP-logic are not defined. However, the interpreter accepts programs with function symbols and, if it does not go into a loop, it returns an answer. What is the meaning of this answer is subject of current study. 



\subsection{Commands}
%All six modules accept the same commands for reading in files and answering queries.
The LPAD or CP-logic program must be stored in a text file with extension \texttt{.cpl}. Suppose you have stored the example above in file \texttt{coin.cpl}. 
In order to answer queries from this program, you have to run Yap,
load one of the modules (such as for example \texttt{lpad.pl}) by issuing  the command
\begin{verbatim}
use_module(library(lpad)).
\end{verbatim}
at the command prompt.
Then you must parse the source file \texttt{coin.cpl}  with the command
\begin{verbatim}
p(coin).
\end{verbatim}
if \texttt{coin.cpl} is in the current directory, or 
\begin{verbatim}
p('path_to_coin/coin').
\end{verbatim}
if \texttt{coin.cpl} is in a different directory.
At this point you can pose query to the program by using the predicate \texttt{s/2} (for solve) that takes as its first argument a conjunction of goals in the form of a list and returns the computed probability as its second argument. For example, the probability of the conjunction \texttt{head(coin),biased(coin)} can be asked with the query
\begin{verbatim}
s([head(coin),biased(coin)],P).
\end{verbatim}
For computing the probability of a conjunction given another conjunction you can use the predicate \texttt{sc/3} (for solve conditional) that take takes as input the query conjunction as its first argument, the evidence conjunction as its second argument and returns the probability in its third argument.
For example, the probability of  the query \texttt{heads(coin)} given the evidence \texttt{biased(coin)} can be asked with the query
\begin{verbatim}
sc([heads(coin)],[biased(coin)],P).
\end{verbatim}
After having parsed a program, in order to read in a new program you must restart Yap when using 
\texttt{semlpadsld.pl} and \texttt{semlpad.pl}. With the other modules, you can directly parse a new program.

When using \texttt{lpad.pl}, the system can print the message ``Uunsound program'' in the case in which an instance with a three valued well founded model is found.  Moreover, it can print the message ``It requires the choice of a head atom from a non ground head'': in this case, in order to answer the query, all the groundings of the culprit clause must be generated, which may be impossible for programs with function symbols. 

When using \texttt{semcpl.pl}, you can print the execution process by using the command \texttt{print.}
after \texttt{p(file).} Moreover, you can build an execution process given a context by issuing the command \texttt{parse(file)}. and then
\texttt{build(context).} where \texttt{context} is a list of atoms that are true in the context.
\texttt{semcpl.pl}  can print ``Invalid program'' in the case in which no execution process exists. 

When using \texttt{cpl.pl} you can print a partial execution model including all the clauses involved in the query issued with \texttt{print.} \texttt{cpl.pl} can print the messages ``Uunsound program'', ``It requires the choice of a head atom from a non ground head'' and ``Invalid program''.

For \texttt{approx/deepit.pl} and \texttt{approx/deepdyn.pl} the command 
\begin{verbatim}
solve(GoalsList, ProbLow, ProbUp, ResTime, BddTime)
\end{verbatim}
takes as input a list of goals \texttt{GoalsList} and returns a lower bound on the probability \texttt{ProbLow}, an upper bound on the probability \texttt{ProbUp}, the CPU time spent on performing resolution \texttt{ResTime} and the CPU time spent on handling BDDs \texttt{BddTime}.

For \texttt{approx/bestk.pl} the command 
\begin{verbatim}
solve(GoalsList, ProbLow,  ResTime, BddTime)
\end{verbatim}
takes as input a list of goals \texttt{GoalsList} and returns a lower bound on the probability \texttt{ProbLow}, the CPU time spent on performing resolution \texttt{ResTime} and the CPU time spent on handling BDDs \texttt{BddTime}.

For \texttt{approx/bestfirst.pl}  the command 
\begin{verbatim}
solve(GoalsList, ProbLow, ProbUp, Count, ResTime, BddTime)
\end{verbatim}
takes as input a list of goals \texttt{GoalsList} and returns a lower bound on the probability \texttt{ProbLow}, an upper bound on the probability \texttt{ProbUp}, the number of BDDs generated by the algorithm \texttt{Count}, the CPU time spent on performing resolution \texttt{ResTime} and the CPU time spent on handling BDDs \texttt{BddTime}.


For \texttt{approx/montecarlo.pl} 
the command 
\begin{verbatim}
solve(GoalsList, Samples, Time, Low, Prob, Up)
\end{verbatim}
takes as input a list of goals \texttt{GoalsList} and returns the number of samples taken \texttt{Samples}, 
the time required to solve the problem \texttt{Time}, the
lower end of the confidence interval \texttt{Lower}, the estimated probability \texttt{Prob} and the upper end of the confidence interval \texttt{Up}.


For \texttt{mcintyre.pl}:
the command 
\begin{verbatim}
solve(Goals, Samples, CPUTime, WallTime, Lower, Prob, Upper) :-
\end{verbatim}
takes as input a conjunction of goals \texttt{Goals} and returns the number of samples taken \texttt{Samples}, 
the CPU time required to solve the problem \texttt{CPUTime}, the wall time required to solve the problem \texttt{CPUTime}, the
lower end of the confidence interval \texttt{Lower}, the estimated probability \texttt{Prob} and the upper end of the confidence interval \texttt{Up}.

For \texttt{approx/exact.pl}
the command 
\begin{verbatim}
solve(GoalsList, Prob, ResTime, BddTime) 
\end{verbatim}
takes as input a conjunction of goals \texttt{Goals} and returns the probability \texttt{Prob}, the CPU time spent on performing resolution \texttt{ResTime} and the CPU time spent on handling BDDs \texttt{BddTime}.

\subsubsection{Parameters}
The modules make use of a number of parameters in order to control their behavior. They that can be set with the command
\begin{verbatim}
set(parameter,value).
\end{verbatim}
from the Yap prompt after having loaded the module.
The current value can be read with
\begin{verbatim}
setting(parameter,Value).
\end{verbatim}
from the Yap prompt.
The available parameters are:
\begin{itemize}
\item 
	 \verb|epsilon_parsing| (valid for all modules): if (1 - the sum of the probabilities of all the head atoms) is smaller than 
    \verb|epsilon_parsing|
		then \texttt{cplint} adds the null events to the head. Default value 0.00001
\item 	\verb|save_dot| (valid for all goal-oriented modules): if \texttt{true} a graph representing the BDD is saved in the file \texttt{cpl.dot} in the current directory in dot format.
		The variables names are of the form \verb|Xn_m| where \texttt{n} is the number of the multivalued
		variable and \texttt{m} is the number of the binary variable. The correspondence between variables and 
		clauses can be evinced from the message printed on the screen, such as 
\begin{verbatim}
Variables: [(2,[X=2,X1=1]),(2,[X=1,X1=0]),(1,[])]
\end{verbatim}
		where the first element of each couple is the clause number of the input file (starting from 1).
		In the example above variable \texttt{X0} corresponds to clause \texttt{2} with the substitutions \texttt{X=2,X1=1},
		variable \texttt{X1} corresponds to clause \texttt{2} with the substitutions \texttt{X=1,X1=0} and
		variable \texttt{X2} corresponds to clause \texttt{1} with the empty substitution.
		You can view the graph with  \href{http://www.graphviz.org}{\texttt{graphviz}} using the
		command
\begin{verbatim}
dotty cpl.dot &
\end{verbatim}
\item \verb|ground_body|: (valid for \texttt{lpadsld.pl} and all semantic modules) determines how non ground clauses are treated: if \texttt{true}, ground clauses are obtained from a non ground clause by replacing each variable with a constant, if \texttt{false}, ground clauses are obtained by replacing only variables in the head with a constant. In the case where the body contains variables not in the head, setting it to false means that the body represents an existential event.
\item \verb|min_error|: (valid for \texttt{approx/deepit.pl}, \texttt{approx/deepdyn.pl}, \texttt{approx/bestk.pl}, \texttt{approx/bestfirst.pl}, \texttt{approx/montecarlo.pl} and \texttt{mcintyre.pl}) is the threshold under which the difference between upper and lower bounds on probability must fall for the algorithm to stop.
\item \verb|k|: maximum number of explanations  for \texttt{approx/bestk.pl} and \texttt{approx/bestfirst.pl} and number of samples to take at each iteration for \texttt{approx/montecarlo.pl} and \texttt{mcintyre.pl}
\item \verb|prob_bound|: (valid for \texttt{approx/deepit.pl}, \texttt{approx/deepdyn.pl}, \texttt{approx/bestk.pl} and \texttt{approx/bestfirst.pl}) is the initial bound on the probability of explanations when iteratively building explanations
\item \verb|prob_step|: (valid for \texttt{approx/deepit.pl}, \texttt{approx/deepdyn.pl}, \texttt{approx/bestk.pl} and \texttt{approx/bestfirst.pl}) is the increment on the bound on the probability of explanations when iteratively building explanations
\item \verb|timeout|: (valid for \texttt{approx/deepit.pl}, \texttt{approx/deepdyn.pl}, \texttt{approx/bestk.pl}, \texttt{approx/bestfirst.pl} and \texttt{approx/exact.pl}) timeout for builduing BDDs
\end{itemize}

\subsection{Semantic Modules}
The three semantic modules need to produce a grounding of the program in order to compute the semantics.
They require an extra file with extension \texttt{.uni} (for universe) in the same directory where the \texttt{.cpl} file is.

There are two ways to specify how to ground a program. The first consists in providing  the list of constants to which each variable can be instantiated. For example, in our case the current directory will contain a file \texttt{coin.uni} that is a Prolog file containing facts of the form
\begin{verbatim}
universe(var_list,const_list).
\end{verbatim}
where \verb|var_list| is a list of variables names (each must be included in single quotes) and \verb|const_list| is a list of constants. The semantic modules generate the grounding by instantiating in all possible ways the variables of \verb|var_list| with the constants of \verb|const_list|. Note that the variables are identified by name, so a variable with the same name in two different clauses will be instantiated with the same constants.

The other way to specify how to ground a program consists in using mode and type information. For each predicate, the file \texttt{.uni} must contain a fact of the form
\begin{verbatim}
mode(predicate(t1,...,tn)).
\end{verbatim}
that specifies the number and types of each argument of the predicate. Then, the list of constants that
are in the domain of each type \texttt{ti} must be specified with a fact of the form
\begin{verbatim}
type(ti,list_of_constants).
\end{verbatim}
The file \texttt{.uni} can contain both universe and mode declaration, the ones to be used depend on the value of the parameter \texttt{grounding}: with value \texttt{variables}, the universe declarations are used, with value \texttt{modes} the mode declarations are used.

With \texttt{semcpl.pl} only mode declarations can be used.


\subsection{Extensions}
In this section we will present the extensions to the syntax of LPADs and CP-logic programs that \texttt{lpadsld} can handle.

When using \texttt{lpadsld.pl}, the bodies can contain the predicates \texttt{setof/3} and \texttt{bagof/3} with the same meaning as in Prolog. Existential quantifiers are allowed in both, so for example the query
\begin{verbatim}
setof(Z, (term(X,Y))^foo(X,Y,Z), L).
\end{verbatim}
returns all the instantiations of \texttt{Z} such that there exists an instantiation of \texttt{X} and \texttt{Y} for which \texttt{foo(X,Y,Z)} is true.

An example of the use of \texttt{setof} and \texttt{bagof} is in the file \texttt{female.cpl}:
\begin{verbatim}
male(C):M/P ; female(C):F/P:-
    person(C),
    setof(Male,known_male(Male),LM),
    length(LM,M),
    setof(Female,known_female(Female),LF),
    length(LF,F),
    P is F+M.

person(f).

known_female(a).
known_female(b).
known_female(c).
known_male(d).
known_male(e).
\end{verbatim}
The disjunctive rule expresses the probability of a person of unknown sex of being male or female depending on the number of males and females that are known.
This is an example of the use of expressions in the probabilities in the head that depend on variables in the body. The probabilities are well defined because they always sum to 1 (unless \texttt{P} is 0).

Another use of \texttt{setof} and \texttt{bagof} is to have an attribute depend on an aggregate function of another attribute, similarly to what is done in PRM and CLP(BN).

So, in the classical school example (available in \texttt{student.cpl}) you can find the following
clauses:
\begin{verbatim}
student_rank(S,h):0.6 ; student_rank(S,l):0.4:- 
    bagof(G,R^(registr_stu(R,S),registr_gr(R,G)),L),
    average(L,Av),Av>1.5.

student_rank(S,h):0.4 ; student_rank(S,l):0.6:- 
    bagof(G,R^(registr_stu(R,S),registr_gr(R,G)),L),
    average(L,Av),Av =< 1.5.
\end{verbatim}
where \verb|registr_stu(R,S)| expresses that registration \texttt{R} refers to student \texttt{S} and \verb|registr_gr(R,G)| expresses that registration \texttt{R} reports  grade \texttt{G} which is a natural number. The two clauses express a dependency of the rank of the student from the average of her grades.

Another extension can be used with \texttt{lpadsld.pl} in order to be able to represent  reference uncertainty of PRMs. Reference uncertainty means that the link structure of a relational model is not fixed but is uncertain: this is represented by having the instance referenced in a relationship be chosen uniformly from a set. For example, consider a domain modeling scientific papers: you have a single entity, paper, and a relationship, cites, between paper and itself that connects the citing paper to the cited paper. To represent the fact that the cited paper and the citing paper are selected uniformly from certain sets, the following clauses can be used (see file \verb|paper_ref_simple.cpl|):
\begin{verbatim}
uniform(cites_cited(C,P),P,L):-
    bagof(Pap,paper_topic(Pap,theory),L).

uniform(cites_citing(C,P),P,L):-
    bagof(Pap,paper_topic(Pap,ai),L).
\end{verbatim}
The first clauses states that the  paper \texttt{P} cited in a citation \texttt{C} is selected uniformly from the set of all papers with topic theory.
The second clauses expresses that the citing paper is selected uniformly from the papers with
topic ai.

These clauses make use of the predicate
\begin{verbatim}
uniform(Atom,Variable,List)
\end{verbatim}
in the head, where \texttt{Atom} must contain \texttt{Variable}. The meaning is the following: the set of all the atoms obtained by instantiating \texttt{Variable} of \texttt{Atom} with a term taken from \texttt{List} is generated and the head is obtained by having a disjunct for each instantiation with probability $1/N$ where $N$ is the length of \texttt{List}.


A more elaborate example is present in file \verb|paper_ref.cpl|:
\begin{verbatim}
uniform(cites_citing(C,P),P,L):-
    setof(Pap,paper(Pap),L).

cites_cited_group(C,theory):0.9 ; cites_cited_group(C,ai):0.1:-
    cites_citing(C,P),paper_topic(P,theory).

cites_cited_group(C,theory):0.01;cites_cited_group(C,ai):0.99:-
    cites_citing(C,P),paper_topic(P,ai).

uniform(cites_cited(C,P),P,L):-
    cites_cited_group(C,T),bagof(Pap,paper_topic(Pap,T),L).
\end{verbatim}
where the cited paper depends on the topic of the citing paper. In particular, if the topic is theory, the cited paper is selected uniformly  from the papers about theory with probability 0.9 and from the papers about ai with probability 0.1. if the topic is ai, the cited paper is selected uniformly  from the papers about theory with probability 0.01 and from the papers about ai with probability 0.99.

PRMs take into account as well existence uncertainty, where the existence of instances is also probabilistic. For example, in the paper domain, the total number of citations may be unknown and  a citation between any two paper may have a probability of existing. For example, a citation between two paper may be more probable if they are about the same topic:
\begin{verbatim}
cites(X,Y):0.005 :- 
    paper_topic(X,theory),paper_topic(Y,theory).

cites(X,Y):0.001 :- 
    paper_topic(X,theory),paper_topic(Y,ai).

cites(X,Y):0.003 :- 
    paper_topic(X,ai),paper_topic(Y,theory).

cites(X,Y):0.008 :- 
    paper_topic(X,ai),paper_topic(Y,ai).
\end{verbatim}
This is an example where the probabilities in the head do not sum up to one so the null event is automatically added to the head.
The first clause states that, if the topic of a paper \texttt{X} is theory and  of  paper \texttt{Y} is theory, there is a probability of 0.005 that there is a citation from \texttt{X} to \texttt{Y}. The other clauses consider the remaining cases for the topics.


\subsection{Files}
In the directory where Yap keeps the library files (usually \texttt{/usr/local/share/ Yap}) you can find the directory \texttt{cplint} that contains the files:
\begin{itemize}
\item \texttt{testlpadsld\_gbtrue.pl, testlpadsld\_gbfalse.pl, testlpad.pl,
testcpl.pl, testsemlpadsld.pl, testsemlpad.pl testsemcpl.pl}: Prolog programs for testing the modules. They are executed when issuing the command \texttt{make installcheck} during the installation. To execute them afterwords, load the file and issue the command \texttt{t.} 
\item Subdirectory \texttt{examples}:
\begin{itemize}
\item \texttt{alarm.cpl}: representation of the Bayesian network in Figure 2 of
 \cite{VenVer04-ICLP04-IC}.
\item \texttt{coin.cpl}: coin example from   \cite{VenVer04-ICLP04-IC}.
\item \texttt{coin2.cpl}: coin example with two coins.
\item \texttt{dice.cpl}: dice example from \cite{VenVer04-ICLP04-IC}.
\item \verb|twosideddice.cpl, threesideddice.cpl|  game with idealized dice with two or three  sides. Used in the experiments in \cite{Rig-RCRA07-IC}.
\item \texttt{ex.cpl}: first example in \cite{Rig-RCRA07-IC}.
\item \texttt{exapprox.cpl}: example showing the problems of approximate inference (see \cite{Rig-RCRA07-IC}).
\item \texttt{exrange.cpl}: example showing the problems with non range restricted programs (see \cite{Rig-RCRA07-IC}).
\item \texttt{female.cpl}: example showing the dependence of probabilities in the head from variables in the body (from \cite{VenVer04-ICLP04-IC}).
\item \texttt{mendel.cpl, mendels.cpl}: programs describing the Mendelian rules of inheritance, taken from \cite{Blo04-ILP04WIP-IC}.
\item \verb|paper_ref.cpl, paper_ref_simple.cpl|: paper citations examples, showing reference uncertainty, inspired by \cite{Getoor+al:JMLR02}.
\item \verb|paper_ref_not.cpl|: paper citations example showing that negation can be used also for predicates defined by clauses with \texttt{uniform} in the head.
\item \texttt{school.cpl}: example inspired by the example \verb|school_32.yap| from the 
source distribution of Yap in the \texttt{CLPBN} directory.
\item \verb|school_simple.cpl|: simplified version of \texttt{school.cpl}.
\item \verb|student.cpl|: student example from Figure 1.3 of \cite{GetFri01-BC}.
\item \texttt{win.cpl, light.cpl, trigger.cpl, throws.cpl, hiv.cpl,}\\ \texttt{ invalid.cpl}: programs taken from \cite{DBLP:journals/tplp/VennekensDB09}. \texttt{invalid.cpl} is an example of a  program that is invalid but sound.
\end{itemize}
The files \texttt{*.uni} that are present for some of the examples are used  by the semantical modules. Some of the example files contain in an initial comment some queries together with their result.
\item Subdirectory \texttt{doc}: contains this manual in latex, html and pdf.
\end{itemize}

\section{Learning}
\texttt{cplint} contains the following learning algorithms:
\begin{itemize}
\item CEM (\texttt{cplint} EM): an implementation of EM for learning parameters that is based on \texttt{lpadsld.pl} \cite{RigDiM11-ML-IJ}
\item RIB (Relational Information Bottleneck): an algorithm for learning parameters based on the Information Bottleneck \cite{RigDiM11-ML-IJ}
\item EMBLEM (EM over Bdds for probabilistic Logic programs Efficient Mining): an implementation of EM for learning parameters that computes expectations directly on BDDs \cite{BelRig11-IDA,BelRig11-CILC11-NC,BelRig11-TR}
\item SLIPCASE (Structure LearnIng of ProbabilistiC logic progrAmS with Em over bdds): an algorithm for learning the structure of programs by searching directly the theory space \cite{BelRig11-ILP11-IC}
\item SLIPCOVER (Structure LearnIng of Probabilistic logic programs by searChing OVER the clause space): an algorithm for learning the structure of programs by searching the clause space and the theory space separatery \cite{BelRig13-TPLP-IJ}
\item LEMUR (LEarning with a Monte carlo Upgrade of tRee search): an algorithm 
for learning the structure of programs by searching the clase space using 
Monte-Carlo tree search.
\end{itemize}

\subsection{Input}
To execute the learning algorithms, prepare four files in the same folder: 
\begin{itemize}
\item \texttt{<stem>.kb}: contains the example interpretations 
\item \texttt{<stem>.bg}: contains the background knowledge, i.e., knowledge valid for all interpretations
\item \texttt{<stem>.l}: contains language bias information
\item \texttt{<stem>.cpl}: contains the LPAD for you which you want to learn the parameters or the initial LPAD for SLIPCASE and LEMUR. For SLIPCOVER, this file should be absent
\end{itemize}
where \texttt{<stem>} is your dataset name. Examples of these files can be found in the dataset pages.

In \texttt{<stem>.kb} the example interpretations have to be given as a list of Prolog facts initiated by 
\texttt{begin(model(<name>)).} and terminated by \texttt{end(model(<name>)).} as in
\begin{verbatim}
begin(model(b1)).
sameperson(1,2).
movie(f1,1).
movie(f1,2).
workedunder(1,w1).
workedunder(2,w1).
gender(1,female).
gender(2,female).
actor(1).
actor(2).
end(model(b1)).
\end{verbatim}
The interpretations may contain a fact of the form
\begin{verbatim}
prob(0.3).
\end{verbatim}
assigning a probability (0.3 in this case) to the interpretations. If this is omitted, the probability of each interpretation is considered equal to $1/n$ where $n$ is the total number of interpretations. \verb|prob/1| can be used to set different multiplicity for the different interpretations.

In order for RIB to work, the input interpretations must share the Herbrand universe. If this is not the case, you have to translate the interpretations in this was, see for example the \texttt{sp1} files in RIB's folder, that are the results of the conversion of the first fold of the IMDB dataset.

\texttt{<stem>.bg} can contain Prolog clauses that can be used to derive additional conclusions from the atoms in 
the interpretations.

\texttt{<stem>.l} contains the declarations of the input and output predicates, of the unseen predicates and the commands for setting the algorithms' parameters.
Output predicates are declared as
\begin{verbatim}
output(<predicate>/<arity>).
\end{verbatim}
and define the predicates whose atoms in the input interpretations are used as the goals for the prediction of which you want to optimize the parameters. Derivations for these goals are built by the systems.

Input predicates are those for the predictions of which you do not want to optimize the parameters. You can declare closed world input predicates with
\begin{verbatim}
input_cw(<predicate>/<arity>).
\end{verbatim}
For these predicates, the only true atoms are those in the interpretations, the clauses in the input program are not used to derive atoms not present in the interpretations.

Open world input predicates are declared with
\begin{verbatim}
input(<predicate>/<arity>).
\end{verbatim}
In this case, if a subgoal for such a predicate is encountered when deriving the atoms for the output predicates, 
both the facts in the interpretations and the clauses of the input program are used.

For RIB, if there are unseen predicates, i.e., predicates that are present in the input program but not in the interpretations, you have to declare them with
\begin{verbatim}
unseen(<predicate>/<arity>).
\end{verbatim}

For SLIPCASE, SLIPCOVER and LEMUR, you have to specify the language bias by means of mode declarations in the style of 
\href{http://www.doc.ic.ac.uk/\string ~shm/progol.html}{Progol}.
\begin{verbatim}
modeh(<recall>,<predicate>(<arg1>,...).
\end{verbatim}
specifies the atoms that can appear in the head of clauses, while
\begin{verbatim}
modeb(<recall>,<predicate>(<arg1>,...).
\end{verbatim}
specifies the atoms that can appear in the body of clauses.
\texttt{<recall>} can be an integer or \texttt{*} (currently unused).

The arguments are of the form
\begin{verbatim}
+<type>
\end{verbatim}
for specifying an input variable of type \texttt{<type>}, or 
\begin{verbatim}
-<type>
\end{verbatim}
for specifying an output variable of type \texttt{<type>}. or
\begin{verbatim}
<constant>
\end{verbatim}
for specifying a constant.

SLIPCOVER also allows the arguments
\begin{verbatim}
#<type>
\end{verbatim}
for specifying an argument which should be replaced by a constant of type \texttt{<type>} in the bottom clause but should not be used for replacing input variables of the following literals or 
\begin{verbatim}
-#<type>
\end{verbatim}
for specifying an argument which should be replaced by a constant of type \texttt{<type>} in the bottom clause and that should be used for replacing input variables of the following literals. \verb|#| and \verb|-#| differ only in the creation of the bottom clause.

An example of language bias for the UWCSE domain is
\begin{verbatim}
output(advisedby/2).

input(student/1).
input(professor/1).
....

modeh(*,advisedby(+person,+person)). 

modeb(*,professor(+person)).
modeb(*,student(+person)).
modeb(*,sameperson(+person, -person)). 
modeb(*,sameperson(-person, +person)). 
modeb(*,samecourse(+course, -course)). 
modeb(*,samecourse(-course, +course)). 
....
\end{verbatim}
SLIPCOVER and LEMUR lso requires facts for the \verb|determination/2| predicate that indicate which predicates can appear in the body of clauses. 
For example
\begin{verbatim}
determination(professor/1,student/1).
determination(student/1,hasposition/2).
\end{verbatim}
state that \verb|student/1| can appear in the body of clauses for \verb|professor/1| and that \verb|hasposition/2| can appear in 
the body of clauses for \verb|student/1|.

SLIPCOVER also allows mode declarations of the form
\begin{verbatim}
modeh(<r>,[<s1>,...,<sn>],[<a1>,...,<an>],[<P1/Ar1>,...,<Pk/Ark>]). 
\end{verbatim}
These mode declarations are used to generate clauses with more than two head atoms. In them, \verb|<s1>,...,<sn>| are schemas,  \verb|<a1>,...,<an>| are atoms such that \verb|<ai>| is obtained from $\verb|<si>|$ by replacing placemarkers with variables, 
\verb|<Pi/Ari>| are the predicates admitted in the body. \verb|<a1>,...,<an>| are used to indicate which variables should be shared by the atoms in the head.
An example of such a mode declaration is
\begin{verbatim}
modeh(*,
  [advisedby(+person,+person),tempadvisedby(+person,+person)],
  [advisedby(A,B),tempadvisedby(A,B)],
  [professor/1,student/1,hasposition/2,inphase/2,
	  publication/2,taughtby/3,ta/3,courselevel/2,yearsinprogram/2]).
\end{verbatim}



\subsection{Parameters}
In order to set the algorithms' parameters, you have to insert in \texttt{<stem>.l}  commands of the form
\begin{verbatim}
:- set(<parameter>,<value>).
\end{verbatim}
The available parameters are:
\begin{itemize}
\item \verb|depth| (values: integer or \verb|inf|, default value: 3): depth of derivations if  \verb|depth_bound|  is set to \verb|true|
\item \verb|single_var| (values: \verb|{true,false}|, default value: \verb|false|, valid for CEM, EMBLEM, SLIPCASE, SLIPCOVER and LEMUR): if set to \verb|true|, there is a random variable for each clauses, instead of a separate random variable for each grounding of a clause
\item \verb|sample_size| (values: integer, default value: 1000): total number of examples in case in which the models in the \verb|.kb| file contain a \verb|prob(P).| fact. In that case, one model corresponds to \verb|sample_size*P| examples
\item \verb|epsilon_em| (values: real, default value: 0.1, valid for CEM, 
EMBLEM, SLIPCASE, SLIPCOVER and LEMUR): if the difference in the log likelihood in two successive EM iteration is smaller
than \verb|epsilon_em|, then EM stops 
\item \verb|epsilon_em_fraction| (values: real, default value: 0.01, valid for 
CEM, EMBLEM, SLIPCASE, SLIPCOVER and LEMUR): if the difference in the log likelihood in two successive EM iteration is smaller
than \verb|epsilon_em_fraction|*(-current log likelihood), then EM stops
\item \verb|iter| (values: integer, defualt value: 1, valid for EMBLEM, 
SLIPCASE, SLIPCOVER and LEMUR): maximum number of iteration of EM parameter learning. If set to -1, no maximum number of iterations is imposed
\item \verb|iterREF| (values: integer, defualt value: 1, valid for  SLIPCASE,
 SLIPCOVER and LEMUR):
 maximum number of iteration of EM parameter learning for refinements. If set to -1, no maximum number of iterations is imposed.
\item \verb|random_restarts_number| (values: integer, default value: 1, valid for CEM, EMBLEM, SLIPCASE, SLIPCOVER and LEMUR): number of random restarts of EM learning
\item \verb|random_restarts_REFnumber| (values: integer, default value: 1, valid for  SLIPCASE, SLIPCOVER and LEMUR): number of random restarts of EM learning for refinements
\item \verb|setrand| (values: rand(integer,integer,integer)): seed for the random functions, see Yap manual for allowed values
\item \verb|minimal_step| (values: [0,1], default value: 0.005, valid for RIB): minimal increment of $\gamma$
\item \verb|maximal_step| (values: [0,1], default value: 0.1, valid for RIB): maximal increment of $\gamma$
\item \verb|logsize_fraction| (values: [0,1], default value 0.9, valid for RIB): RIB stops when $\mathbf{I}(CH,T;Y)$ is above \verb|logsize_fraction| times its maximum value ($\log |CH,T|$, see \cite{DBLP:journals/jmlr/ElidanF05})
\item \verb|delta| (values: negative integer, default value -10, valid for RIB): value assigned to $\log 0$
\item \verb|epsilon_fraction| (values: integer, default value 100, valid for RIB): in the computation of the step, the value of $\epsilon$ of \cite{DBLP:journals/jmlr/ElidanF05} is obtained as $\log |CH,T|\times$\verb|epsilon_fraction|
\item \verb|max_rules| (values: integer, default value: 6000, valid for RIB and SLIPCASE): maximum number of ground rules. Used to set the size of arrays for storing internal statistics. Can be increased as much as memory allows.
\item \verb|logzero| (values: negative real, default value $\log(0.000001)$, valid for SLIPCASE, SLIPCOVER and LEMUR): value assigned to $\log 0$
\item \verb|examples| (values: \verb|atoms|,\verb|interpretations|, default value \verb|atoms|, valid for SLIPCASE): determines how BDDs are built: if set to \verb|interpretations|, a BDD for the conjunction of all the atoms for the target predicates in each interpretations is built. 
If set to \verb|atoms|, a BDD is built for the conjunction of a group of atoms for the target predicates in each interpretations. The number of atoms in each group is determined by the parameter \verb|group|
\item \verb|group| (values: integer, default value: 1, valid for SLIPCASE): number of target atoms in the groups that are used to build BDDs
\item \verb|nax_iter| (values: integer, default value: 10, valid for SLIPCASE and SLIPCOVER): number of interations of beam search
\item \verb|max_var| (values: integer, default value: 1, valid for SLIPCASE,
SLIPCOVER and LEMUR): maximum number of distinct variables in a clause
\item \verb|verbosity| (values: integer in [1,3], default value: 1): level of verbosity of the algorithms
\item \verb|beamsize|  (values: integer, default value: 20, valid for SLIPCASE and SLIPCOVER): size of the beam 
\item \verb|mcts_beamsize|  (values: integer, default value: 3, valid for LEMUR): size of the MCTS beam

\item \verb|mcts_visits|  (values: integer, default value: +inf, valid for LEMUR): maximum number of visits (Nicola controlla)

\item \verb|megaex_bottom| (values: integer, default value: 1, valid for SLIPCOVER): number of mega-examples on which to build the bottom clauses
\item \verb|initial_clauses_per_megaex| (values: integer, default value: 1, valid for SLIPCOVER): 
 number of bottom clauses to build for each mega-example
\item \verb|d| (values: integer, default value: 10000, valid for SLIPCOVER): 
 number of saturation steps when building the bottom clause
\item \verb|max_iter_structure| (values: integer, default value: 1, valid for SLIPCOVER): 
maximum  number of theory search iterations
\item \verb|background_clauses| (values: integer, default value: 50, valid for SLIPCOVER): 
 maximum numbers of background clauses
\item \verb|maxdepth_var| (values: integer, default value: 2, valid for SLIPCOVER and LEMUR): maximum depth of
variables in clauses (as defined in \cite{DBLP:journals/ai/Cohen95}).
\item \verb|score| (values: \verb|ll|, \verb|aucpr|, default value \verb|ll|, valid for SLIPCOVER): determines the score function for refinement: if set to \verb|ll|, log likelihood is used, if set to \verb|aucpr|, the area under the 
Precision-Recall curve is used. 
\end{itemize}
\subsection{Commands}
To execute CEM, load \texttt{em.pl} with
\begin{verbatim}
?:- use_module(library('cplint/em')).
\end{verbatim}
and call:
\begin{verbatim}
?:- em(stem).
\end{verbatim}
To execute RIB, load \texttt{rib.pl} with
\begin{verbatim}
?:- use_module(library('cplint/rib')).
\end{verbatim}
and call:
\begin{verbatim}
?:- ib_par(stem).
\end{verbatim}
To execute EMBLEM, load \texttt{slipcase.pl} with
\begin{verbatim}
?:- use_module(library('cplint/slipcase')).
\end{verbatim}
and call
\begin{verbatim}
?:- em(stem).
\end{verbatim}
To execute SLIPCASE, load \texttt{slipcase.pl} with
\begin{verbatim}
?:- use_module(library('cplint/slipcase')).
\end{verbatim}
and call
\begin{verbatim}
?:- sl(stem).
\end{verbatim}
To execute SLIPCOVER, load \texttt{slipcover.pl} with
\begin{verbatim}
?:- use_module(library('cplint/slipcover')).
\end{verbatim}
and call
\begin{verbatim}
?:- sl(stem).
\end{verbatim}
To execute LEMUR, load \texttt{lemur.pl} with
\begin{verbatim}
?:- use_module(library('cplint/lemur')).
\end{verbatim}
and call
\begin{verbatim}
?:- "mcts(stem,depth,c,iter,rules,covering)
\end{verbatim}
where \verb|depth| (integer) is the maximum number
of random specialization steps in the default policy, \verb|C| (real) is the value of the MCTS $C$ constant, \verb|iter| (integer) is  the number of UCT rounds, \verb|rules| (integer) is
the maximum number  of clauses to be
learned and \verb|covering| (Boolean) dentoes whether the search is peformed in
the space of clauses (true) or theories (false) (Nicola controlla).

\subsection{Testing}
To test the theories learned, load \texttt{test.pl} with 
\begin{verbatim}
?:- use_module(library('cplint/test')).
\end{verbatim}
and call
\begin{verbatim}
?:- main([<stem_fold1>,...,<stem_foldn>],[<testing_set_fold1>,...,
  <testing_set_foldn>]).
\end{verbatim}
For example, if you want to test the theory in \verb|ai_train.rules| on the set \verb|ai.kb|, you can call
\begin{verbatim}
?:- main([ai_train],[ai]).
\end{verbatim}
The testing program has the following parameter:
\begin{itemize}
\item \verb|neg_ex| (values:  \verb|given|, \verb|cw|, default value: \verb|cw|): if  set to \verb|given|, the negative examples
are taken from \verb|<testing_set_foldi>.kb|, i.e., those example \verb|ex| stored as \verb|neg(ex)|; if set to \verb|cw|, the negative examples are generated according to the closed world assumption, i.e., all atoms for target predicates that are not positive examples. The set of all atoms is obtained by collecting the set of constants for each type of the arguments of the target predicate.
\end{itemize}
The testing program produces the following output in the current folder:
\begin{itemize}
\item \verb|cll.pl|: for each fold, the list of examples orderd by their probability of being true
\item \verb|areas.csv|: the areas under the Precision-Recall curve and the Receiver Operating Characteristic curve
\item \verb|curve_roc.m|: a Matlab file for plotting the Receiver Operating Characteristic curve
\item \verb|curve_pr.m|: a Matlab file for plotting the Precision-Recall curve
\end{itemize}


\subsection{Learning Examples}
The subfolders \verb|em|, \verb|rib|, \verb|slipcase| and \verb|slipcover| of the \verb|packages/cplint| folder in Yap git distribution
contain examples of input and output files for the learning algorithms.

\section{License}
\label{license}



\texttt{cplint}, as Yap, follows the Artistic License 2.0 that you can find in Yap CVS root dir. The copyright is by Fabrizio Riguzzi.
\vspace{3mm}

The modules in the approx subdirectory use SimplecuddLPADs, a modification of the \href{http://dtai.cs.kuleuven.be/problog/download.html}{Simplecudd} library whose copyright is by Katholieke Universiteit Leuven  and that follows the Artistic License 2.0.
\vspace{3mm}

Some modules use the library \href{http://vlsi.colorado.edu/\string ~fabio/}{CUDD} for manipulating BDDs that is included in glu.
For the use of CUDD, the following license must be accepted:

\vspace{3mm}

Copyright (c) 1995-2004, Regents of the University of Colorado

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

\begin{itemize}
\item
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
\item
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
\item
Neither the name of the University of Colorado nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
\end{itemize}
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS \\ AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAU-SED
\\ AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

\texttt{lpad.pl}, \texttt{semlpad.pl} and \texttt{cpl.pl} are based on the SLG system
by Weidong Chen and \href{http://www.cs.sunysb.edu/\string ~warren/}{David Scott Warren},  
Copyright (C) 1993 Southern Methodist University, 1993 SUNY at Stony Brook, see the file COYPRIGHT\_SLG for detailed information on this copyright.

\bibliographystyle{plain}
\bibliography{bib}

\end{document}