README

Useful links
============
Project homepage:
http://www.control.lth.se/Staff/JerkerNordh/pyparticleest.html

Source code:
https://github.com/jerkern/pyParticleEst

Documentation:
http://pyparticleest.readthedocs.org


Introduction
============

This is a library to assist with calculations for estimation problems using 
particle based methods, it contains a number of algorithms such as the 
Particle Filter, Auxiliary Particle Filter and support several variants of
Particle Smoothing through the use of Backward Simulation (FFBSi) techniques but
also methods such as the Metropolis-Hastings Backward Proposer (MHBP) and the 
Metropolis-Hastings Improved Particle Smoother (MHIPS).

It also provides a framework for doing parameter estimation in nonlinear
models using Expectation Maximization combined with the particle smoothing
algorithms presented above. (PS-EM).

The use of Rao-Blackwellized models is considered an importan special case
and extensive support for it is provided.

The structure is based on presenting a number of interfaces that a problem
specific class must implement in order to use the algorithms. To assisst the
end user base classes for common model structures, such as 
Mixed Linear/Nonlinear Gaussian (MLNLG) models are provided to keep the 
implementation effort to a minimum.

The idea is to provide an easy prototyping enviroment for testing different
algorithms and model formulations when solving a problem and to act as a 
stepping stone for a later more performance oriented problem specific 
implementation by the end user. (outside the scope of this framework)

Installation
============

Using PyPI
**********
The package is hosted on PyPI, so on many system you can just run:

	pip install pyParticleEst

Manual installation
*******************
Make sure that you have numpy and scipy installed
After downloading the code (see link at top of this document) run:

	python setup.py install

This will build the code and install it to your system using distutils. 


Non-Linux systems
*****************
There is currently no binary distribution, thus you have to have a C-compiler
on your system for distutils to build the C-extension modules. On Unix-like 
systems this normally isn't an issue, but for Windows it may be a bit tricker.
If compilation of the C code fails it will fall back to using pure python code,
this is slower but should work on all platforms but will print a warning when
using the library.

This link provides some advice on how to configure MinGW to compile on Windows.

http://eli.thegreenplace.net/2008/06/28/compiling-python-extensions-with-distutils-and-mingw

If you get an error "Unable to find vcvarsall.bat" you most likely don't have
a correctly configured compilation environment. Perhaps this link will be 
helpful:

http://stackoverflow.com/questions/2817869/error-unable-to-find-vcvarsall-bat