**** A Discrete Factor Graph Toolkit for Matlab ****

                    Jerod Weinman
                    jerod@acm.org
                     29 July 2011

The structure of the object-oriented factor graph is as follows. Each
@factorgraph object is composed of several @factor objects, each of
which has some variables as arguments. These variables are represented
numerically as integers, and the adjacency matrix of the factor graph
is thus implicitly (partially) encoded by each factor's arguments.

A @factor is generally a N-dimensional table of values (where N is the
number of arguments), though this implementation may be modified or
specialized via subclassing.

Objects of type @factordiscr represent a general parameterized factor
that require a particular "observation" to complete the factor
table. 

A @factorfeature object is observation required by a @factordiscr to
produce a @factor. The @factorfeature represents a feature vector
associated with a particular set of variables, and the
@factordiscr/mkfactor method can be applied to a @factorfeature object
to produce the corresponding @factor.

The general @factordiscr and @factorfeature objects are associated
with one another via a @factortemplate object, which tracks the
cardinality/dimensionality of the @factor that would be produced by
comining the feature and factor template. In this way, many factors of
the same sort can be generated by multiple @factorfeatures, but a
single @factordiscr and a single @factortemplate, but with multiple
@factorfeature objects.

This behavior (converting @factorfeature objects into @factor objects)
can be abstracted with the factory function mkfactorgraph, which takes
a cell of @factordiscr objects and a cell of @factorfeatures,
producing all the requisite factors and composing them into a
@factorgraph object. This process is sometimes called "unrolling" the
graph (a terminology most apt for chain topologies.")

The @linfactordiscr represents a special, common type of parameterized
linear factor. That is, table entries in the factor are produced by
linear functions of the observation and the parameters.

Inference in a @factorgraph object is supported by several variants of
belief propagation.

All of these aspects (creating @factortemplate objects, creating
@linfactordiscr objects, creating @factorfeature objects, graph
unrolling, and performing inference) are demonstrated for a simple
HMM-like chain in the README.m file.

This code was designed, not to be optimized, but to be correct first,
though we may not have succeeded at even that in places. While I am
likely unable to provide support, bug reports are welcome, as are
small patches for optimizations. Much of the code was written before
the author was aware of cellfun or before bsxfun was introduced to
Matlab, and these are likely points for useful optimizations in
loopybp.