Bayes Blocks library
version 1.1.1, 2007-01-03


SYSTEM REQUIREMENTS --------------------------------------------------

  Python toolbox

The Python version of the library should in principle work under any
platform Python supports that has a standards compliant C++ compiler.
Specific software requirements are as follows:

- Python 2.3 or later (earlier versions may work, but are unsupported)
- NumPy or Numerical Python

Optional software:

- MATLAB 6.5 or later (for saving and loading .mat files)
- Graphviz 1.9 or later (for BBVis visualisation package)
- fig2dev from TransFig (for BBVis visualisation package)
- Python Megawidgets 1.1 or later (for BBVis visualisation package)
- SWIG 1.3.17 or later (for recompiling from scratch)

Most of these are included in modern Linux distributions.  Pre-built
Windows binaries are provided at the web page of the library, but they
do not include support for Matlab integration.

The files compiled by SWIG are included in the distribution so SWIG is
not needed to compile the distributed version of the library, but only
if some modifications are made.


  Standalone C++ library

The underlying library is primarily designed for and should work under
any reasonably modern Un*x operating system.  We have used various
versions of Linux, Mac OS X, IRIX 6.5, HP Tru64 Unix and Solaris.
Others should work but may require some fiddling with compiler
options.  Some platform specific hints for compilation are given
below.

For using only the C++ library, only additional software required are
a standards compliant C++ compiler and GNU make.


COMPILATION ----------------------------------------------------------

  Python toolbox

To compile the Python version, use
  python setup.py build
  python setup.py install
or other standard Python setup.py magic.  The setup script tries to
detect a Matlab installation to compile the library with Matlab
support (i.e. ability to save the results in .mat files).  In order to
change the name of Matlab executable from the default 'matlab', please
edit the file setup.cfg.


  Standalone C++ library

The package contains a configure script to detect compiler and
other settings so the plain C++ library can be compiled by the
standard
  ./configure
  make 
method.  The configure script can take options to specify
whether Matlab is used.  Run it with option '--help' for more
information.


PLATFORM SPECIFIC INSTRUCTIONS ---------------------------------------

  Windows

A Python version of the library should compile using setup.py with
Microsoft Visual Studio C++.  As the library has been developed mainly
under Linux it should compile with GCC derivatives (MinGW, DJGPP), but
compiling Python extensions with those is in general a nontrivial
task.  Provided setup.py disables Matlab hooks under Windows, but it
may be possible to restore them by finding suitable compiler flags
for include and library paths.


  Mac OS X

Compilation of the Python library with Matlab binding yields some
errors at the end, but they can be safely ignored.  To use the Python
library with Matlab bindings, you must set the value of the
environment variable DYLD_LIBRARY_PATH to <Matlab root>/bin/mac,
e.g. DYLD_LIBRARY_PATH=/Applications/MATLAB704/bin/mac.


  IRIX 6.5

Compilation of the C++ module for Python may be tricky.  In case of
problems, try upgrading to the latest Python release and apply the
following patch to Python:
http://sourceforge.net/tracker/?func=detail&aid=1222585&group_id=5470&atid=305470


  Tru64 Unix

Compilation of the C++ module for Python may be tricky.  In case of
problems, try upgrading to the latest Python release and apply the
following patch to Python:
http://sourceforge.net/tracker/?func=detail&aid=1222585&group_id=5470&atid=305470

HP compiler seems to require additional flags to use standards
compliant libraries.  This can be addressed by setting environment
variable CXX to value 'cxx -D__USE_STD_IOSTREAM' before running
'python setup.py build'.


USAGE ----------------------------------------------------------------

Please see the examples.py available together with the full package.

For realistic examples of using the library, there are extra packages
with code used in the experiments of our papers available at the web
page
  http://www.cis.hut.fi/projects/bayes/

Some documentation for the package is included in subdirectory 'doc'
of the main archive.


REFERENCE ------------------------------------------------------------

If you use the software in your work, please cite:
  M. Harva, T. Raiko, A. Honkela, H. Valpola, and J. Karhunen.
  Bayes Blocks: An Implementation of the Variational Bayesian
  Building Blocks Framework. In Proceedings of the 21st Conference
  on Uncertainty in Artificial Intelligence, Edinburgh, UK,
  pp. 259-266, 2005.


LEGALESE -------------------------------------------------------------

Copyright (C) 2001-2006 by Markus Harva, Antti Honkela, Alexander
Ilin, Tapani Raiko, Harri Valpola and Tomas stman.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.


CONTACT INFORMATION --------------------------------------------------

The WWW home page of this library is:

  http://www.cis.hut.fi/projects/bayes/

The authors can be reached by paper mail:

  Bayes group
  Laboratory of Computer and Information Science
  P.O. Box 5400
  FI-02015 TKK
  Finland

or by email:

  bayeslib@cis.hut.fi
