PyBayes is an object-oriented Python library for recursive Bayesian estimation (Bayesian filtering) that is convenient to use. Already implemented are Kalman filter, particle filter and marginalized particle filter, all built atop of a light framework of probability density functions. PyBayes can optionally use Cython for large speed gains (Cython build can be several times faster in some situations).
PyBayes is tested with Python 2.7 and 3.2 (using 2to3). Future plans include more specialised variants of Kalman/particle filters and speed optimisations.
PyBayes is being developed by Matěj Laitl, feel free to send me a mail to matej at laitl dot cz. See ChangeLog.rst file to review a list of most important changes in recent versions.
Automatically generated documentation can be found at http://strohel.github.com/PyBayes-doc/
PyBayes is currently distributed under GNU GPL v2+ license. The authors of PyBayes are however open to other licensing suggestions. (Do you want to use PyBayes in e.g. BSD-licensed project? Ask!)
PyBayes releases can be found in .tar.gz format at github or PyPI. These releases bundle the Tokyo project for convenience. Binary packages for CentOS, Debian, Fedora, RHEL, OpenSUSE and Ubuntu can be downloaded from the OpenSUSE Build Service; these packages are fast Cython builds. (with no requirement to install Cython for building)
Development of PyBayes happens on http://github.com/strohel/PyBayes using git VCS and the most fresh development sources can be obtained using git. It should be noted that PyBayes uses git submodule to bundle Tokyo library, so the proper way to clone PyBayes repository would be:
# cd path/to/projects # git clone git://github.com/strohel/PyBayes.git Cloning into PyBayes... (...) # cd PyBayes # git submodule update --init Submodule 'tokyo' (git://github.com/strohel/Tokyo.git) registered for path 'tokyo' Cloning into tokyo... (...) Submodule path 'tokyo': checked out '896d046b62cf50faf7faa7e58a8705fb2f22f19a'
When updating your repository (using git pull), git should inform you that some submodules have became outdated. In that case you should issue git submodule update.
PyBayes uses standard Python distutils for building and installation. Follow these steps in order to install PyBayes:
download PyBayes, let's assume PyBayes-0.1.tar.gz filename
tar -xvf PyBayes-0.1.tar.gz
change directory into PyBayes source:
build and install (either run as root or install to a user-writeable directory ):
And you're done! However, if you want PyBayes to be considerably faster, please read the following section.
Advanced installation options
PyBayes can use Cython to build itself into binary Python module. Such binary modules are transparent to Python in a way that Python treats then as any other modules (you can import them as usual). Interpreter overhead is avoided and many other optimisation options arise this way.
In order to build optimised PyBayes, you'll additionally need:
- Cython Python to C compiler, version 0.14.1 or newer
- working C compiler (GCC on Unix-like systems, MinGW or Microsoft Visual C on Windows )
- NumPy numerical library for Python, version 1.5 or greater (NumPy is needed also in Python build, but older version suffice in that case)
- On some Debian-based Linux distributions (Ubuntu) you'll need python-dev package that contains Python.h file that is needed by PyBayes
Proceed with following steps:
Install all required dependencies. They should be already available in your package manager if you use a modern Linux Distribution.
Unpack and install PyBayes as described above, you should see following message during build:
Cython and NumPy found, enabling optimised Cython build.
- in order to be 100% sure that optimised build is used, you can add --use-cython=yes option to the ./setup.py call. You can force pure Python mode even when Cython is installed, pass --use-cython=no. By default, PyBayes auto-detects Cython and NumPy presence on system.
- if you plan to profile code that uses optimised PyBayes, you may want to embed profiling information into PyBayes. This can be accomplished by passing --profile=yes to ./setup.py. The default is to omit profiling information in order to avoid performance penalties.
- all standard and custom build parameters can be listed using ./setup.py --help
The best results performance-wise are achieved when also your code that uses or extends PyBayes is compiled by Cython and uses static typing where appropriate. Remember to cimport pybayes[.something] everytime you import pybayes[.something] so that fast Cython calling convention is used.
There is no need to build documentation yourself, an online version is at http://strohel.github.com/PyBayes-doc/
PyBayes uses Sphinx to prepare documentation, version 1.0 or greater is required. The documentation is built separately from the python build process. In order to build it, change directory to doc/ under PyBayes source directory (cd [path_to_pybayes]/doc) and issue make command. This will present you with a list of available documentation formats. To generate html documentation, for example, run make html and then point your browser to [path_to_pybayes]/doc/_build/html/index.html.
PyBayes comes with a comprehensive test and stress-suite that can and should be used to verify that your PyBayes build works as expected.
Since version 0.4, testing is integrated into the setup.py script and can be run without installing PyBayes. In order to run PyBayes test-suite, simply issue ./setup.py test from within the source directory. To run tests during installation procedure, simply install like this: ./setup.py build test install. Failing tests cause installation to fail, but this can be overriden using --non-fatal option of the test command.
If you want to test your already installed PyBayes instance, simply issue python -m pybayes.tests anytime, anywhere. :-)
Stress testing is not yet ported to the setup.py, see the support/run_stresses.py script.