symfer Package

The symfer package is split into several sub-modules listed here. However, everything in the sub-modules is imported into the namespace of the top-level module, so you can simply import everything at once:

import symfer as s
model = s.loadhugin('extended-student.net')

factor sub-module

An instance of class Factor (or a subclass) is a data structure that represents an expression in factor algebra.

Manipulation of these expressions is symfer’s core functionality. Afterwards, a factor expression can be exported as a YAML file using function dumpyaml(expr1,filename); likewise, symfer can also load factor expressions from YAML files using expr2 = loadyaml(filename). Roundtripping should result in the same factor algebra expression (expr1==expr2 and sharing is preserved).

The representation of a Factor is kept as close as possible to the YAML data structure; for example, the mapping

!sumprod {arg: [A,B], fac: []}

corresponds to the factor

SumProd(arg=[‘A’,’B’], fac=[])

which is an object with attributes ‘arg’ and ‘fac’. The only difference is (currently) that each factor has auxiliary attributes ‘domlist’ and ‘domtypes’ providing information about its domain variables.

To provide maximum flexibility in the data structure layout, a factor expression is not limited to Factor instances but can be mixed with dict. For example:

SumProd(arg=[], fac=[ {‘label’: ‘aap’, ‘fac’: [Multinom([],[])]} ])

and

fac: - !multinom {dom: [], par: []} - !sumprod {arg: [], fac: []}

are valid factor expressions in Python and YAML format, respectively. If such a dict contains another factor expression, it should be in a singleton list behind the key ‘fac’. Then, in constructing the Python object from YAML, the domlist/domtypes information of that factor is copied to the dict. Otherwise, the dict gets domlist [] and domtypes {}. (When domlist/domtypes are already provided in the dict, these are used, however they are currently stripped in dumpyaml so this doesn’t roundtrip.)

In order to give both Factor and dict factors a compatible interface, the attributes of a factor can also be accessed as dict items:

mysumprod[‘arg’]

Factor expressions are meant to be IMMUTABLE; especially since they are meant to be freely shared, mutation is a very bad idea and can break things at unexpected places. It should only happen in a factor’s own __init__ method.

getfac(tree)

Return the subtrees of a factor tree, ie tree[‘fac’].

setfac(tree, reschildren)

Return a copy of this factor tree with tree[‘fac’] set to reschildren.

getdetfac(tree)

Get det and fac children. If neither are present, raise an error.

reconstruct(tree)

Reconstruct a factor tree using the class constructors (which YAML does not use).

All keys/value combinations in the factor’s dict are passed to the constructor as keyword arguments.

remove_doms(tree)

Remove auxiliary attritutes ‘domlist’, ‘domtypes’, ‘codlist’, ‘codtypes’ from factor tree.

mergedoms(fac)

Merge the domlist/domtype of a list of factors. Detect domtype conflicts.

inference sub-module

ve_order(facs, order)

Variable elimination with a given elimination order.

facs: list of factors, or dict with factor values order: list of variables Returns a factor expression equal to the product of facs, with the variables summed out.

ve_minweight(facs, query)

Variable elimination with minweight heuristic.

facs: list of factors, or dict with factor values query: list of variables to keep Returns a factor expression equal to the product of facs, with all variables summed out except those in query.

junctiontree(tree)

Junction tree propagation based on a nested SumProd expression.

Returns a dict {‘fac’: L}. Here, L is a list of factor expressions, one for each leaf in the original expression. Subexpressions of these are shared such that the evaluation cost is only about twice that of the original expression.

marginals(multifac)

Single-variable marginals, based on a multi-factor expression (like the one returned from the function junctiontree(tree).

indextree(det, tree)

Insert evidence into a factor expression, just above each Multinom factor that contains an evidence variable.

det: dict of type {‘varname’: ‘observed val’}

cost(tree)

Count additions, multiplications and lookups.

io sub-module

symfer I/O functions for Hugin (.net), YAML and C files

loadhugin(filename='tmp.net', uselabels=False)

Load a Hugin (.net) file into a dict of type {‘varname’:Multinom(...)}.

By default, uses the node identifiers as variable names; with uselabels=True, uses the node labels.

loadyaml(filename='tmp.yaml')

Load a YAML file; if it is a Factor, reconstruct it using Factor (sub)class constructors.

dumpyaml(tree, filename='tmp.yaml')

Dump a data structure as a YAML file; if it is a factor tree, remove the ‘domlist’ and ‘domtypes’ auxiliary attributes.

dumpc(tree, filename='tmp.c')

evalc(tree, compiler='unix')

Evaluate a factor by generating C, compiling and executing. It uses the gcc compiler provided by distutils.ccompiler.new_compiler. Use compiler=’msvc’ for Microsoft Visual Studio, if you have it.

evaluator sub-module

Python-based numeric evaluator for symfer.

Uses NumPy (http://numpy.scipy.org) to do the array manipulations, and a layer above it (FArray) that associates variable names to array dimensions.

evaluate(tree)

Numerically evaluate a Factor expression.

cgenerator sub-module

cgen(tree)

cgenstats(tree)

Count number of multiplications, additions and lookups in plan.

countrefs(tree)

Count number of references (post-order).

transform sub-module

detect_noisy_or(mn, tolerance=0.0001)

draw sub-module

drawplan(plan, filename='out.svg')

Draw a SumProd/Index/Multinom factor expression using graphviz.