Documentation

The inference engines provided by this package are

• fojt.LiftedDynamicJTEngine (Lifted Dynamic Junction Tree Algorithm, default)
• jt.JTEngine (Standard Junction Tree Algorithm)
• fojt.LiftedJTEngine (Lifted Junction Tree Algorithm)
• fove.LiftedVarElim (First Order Variable Elimination)

To specify the engine use the -e parameter (see below).

Parameters

As the LDJT package provides only exact inference algorithms, sampling options are unavailable in this distribution. The following parameters are available

Parameter	Description
-e <s>, --engine <s>	Use inference engine <s>. (Default is fojt.LiftedDynamicJTEngine)
-t, --temporal	Dynamic inference (required to parse dynamic models). This parameter is mandatory with the fojt.LiftedDynamicJTEngine or if parameters -x or -u are specified.
--max_timestep <n>	If model is dynamic, generate up to <n> timesteps. This parameter is mandatory if fojt.LiftedJTEngine is used with parameter -x or -u.
-x, --extend	Extend the model for given timesteps. The model is unrolled by the specified number of timesteps before the junction tree is created. Used with fojt.LiftedJTEngine. Parameter --max_timesteps is required.
-u, --unrollfojt	Extend the first-order junction tree for given timesteps. The junction tree is unrolled after creation. Used with fojt.LiftedJTEngine. Parameter --max_timesteps is required.
--package <s>	Parser looks for classes in package <s>.
-d, --[no]debug	Print model, evidence, and queries.
-o <s>, --output <s>	Output stats to file <s>.
-P<key>=<value>	Set inference configuration properties.
-a <n>, --architecture <n>	Use message passing architecture <n>.
-v, --verbose	Verbose (print a lot of information).

Building Models

FOJT is an extension to BLOG. Input models for the FOJT engine are written in the BLOG language and its extensions from v0.3. As in basic BLOG, models consist of 

• type definitions and their extensions
• fixed variables
• random variables
• evidence.
• factors and parfactors

The LDJT engine relies on exact inference, so sampling options from the basic BLOG language are not allowed in the models. This section is only a short overview of how to specify BLOG models. For more details, please refer to the resources linked above.

Type definitions

Type definitions have the form

type X;
guaranteed X x[<n>];

Here, we introduce the type X, where the second line is optional and guarantees at least <n> instances of the X type, named x1, x2, ... xn.

Random variables

As in BLOG, a random variable Y is defined by

random <type> Y(<S>);

where <type> can be one of the BLOG built-in types 

• Boolean
• Integer
• Real
• Character
• String

or one of the user-defined types. The parameter <S> denotes the set of random variables the new random variable depends on. Let's assume, we want to model a Boolean random variable that indicates wheter a Person attends a Workshop:

random Boolean Attends(Person, Workshop);

 

Dynamic random variables

To make a random variable dynamic, two instances of the same variable are used. The naming convention is <var>1 and <var>2. 

random Boolean Attends1(Person, Workshop);
random Boolean Attends2(Person, Workshop);

This is due to technical reasons. The variable with suffix 1 stands for the random variable in timestep t whereas the variable with suffix 2 stands for the random variable in timestep t+1.

As in BLOG, fixed variables are also allowed. Fixed variables are introduced with the keyword fixed:

fixed real pi = 3.141592653;

Factors and Parfactors

Factors and parfactors are specified as described in the BLOG manual for v0.3. A factor is defined as a Matrix 

factor MultiArrayPotential[<M>](<S>);

Where <M> = [t1, ... tm] is the row vector specifying the factor and <S> is the set of randvars shared by the factor. To model the fact that R is true with probability 0.1 we would write

random Boolean R;
factor MultiArrayPotential[[0.1, 0.9]](R);

Parfactors are specified in a  similar way

parfactor <type> R. MultiArrayPotential[<M>](<S(R)>);

where the type definition specifies the domain of the logvar used in the parfactor. As in BLOG, multiple logvars of different types are allowed.

The parfactors are specified in the form [p0, p1, ... , pn] where pi denotes the factor potential if all parameters set to true with the last i parameters set to false. 

If a parfactor is a factor of a dynamic random variable, it must be specified for Var1 and Var2 seperately (see the Reference Example) whereas the potentials of the two parfactors must be be identical.

Dynamic evidence

To introduce evidence about timestep t, the following syntax is used

obs <Var><K>(<x>, @<t>) = <value>;

where 

• <Var> is the name of the random variable 
• with <K> being 1 in timestep t=1, or K=2 else (provided that the corresponding random variables are declared), see 'Dynamic random variables'
• <x> is the observed ground entity
• <t> denotes the timestep of the observation
• <value> the observed value

Examples:

Observing person p1 attending workshop w1 in timestep 1:

obs Attends1(p1, w1, @1) = true;

Observing person p2 not attending workshop w1 in timestep 3. Note that the randvar with suffix 2 has to be used for timesteps ≥2:

obs Attends2(p2, w1, @3) = false;

 

Dynamic Queries

For dynamic queries the following syntax is used.

query <VarK>(<x>, @<t1>, @<t2>);

where

• <VarK> is the query variable with K=1 for timestep t=1 or K=2 else (assuming the variable has been declared properly)
• <x> is the queried entity
• <t1> is the timestep of the query
• <t2> is the queried timestep 

So, if we want the probability at timestep t1=4 that person p82 attends Workshop w2 in timestep t2=10 we would write

query Attends(p82, w2, @4, @10);

To query a random variable in timestep 1, the random variable with suffix 1 has to be used, whereas for in all other timesteps t≥2 the variable with suffix 2 has to be queried.

Output

Even if the parameter -t is specified, an error message reading

"No function named <function name> is applicable to arguments of types [<type>, Timestep, Timestep]"

might be displayed upon introduction of evidence. This error message is due to technical limitations of the underlying BLOG parser and can be ignored.