Merge branch 'master' into fix-simpleprecession

.codeclimate.yml

@@ -0,0 +1,30 @@
+---
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - python
+  fixme:
+    enabled: true
+  radon:
+    enabled: true
+  pep8:
+    enabled: true
+    checks:
+      # We disable E266 (too many leading #s for block comment)
+      # as this flags on every use of ## for a section header.
+      E266:
+        enabled: false
+  duplication:
+    enabled: true
+    config:
+      languages:
+        - python
+ratings:
+  paths:
+  - "**.py"
+exclude_paths:
+# There's no point in scanning external libraries for code style,
+# as we can't do much with them anyway.
+- "src/qinfer/_lib/*"

.gitignore

@@ -1,3 +1,5 @@
+src/qinfer/version.py
+
 ## Temporary files ##
 *~
 *.tmp
@@ -7,6 +9,9 @@
 Backup/*
 UpgradeLog.htm
 
+## Pycharm Stuff ##
+.idea
+
 ## IPython Checkpoints ##
 .ipynb_checkpoints
 

.travis.yml

@@ -0,0 +1,30 @@
+sudo: false
+language: python
+python:
+  - "2.7"
+  - "3.3"
+  - "3.4"
+  - "3.5"
+
+notifications:
+  email: false
+
+before_install:
+  - wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
+  - chmod +x miniconda.sh
+  - ./miniconda.sh -b -p $HOME/miniconda
+  - export PATH=$HOME/miniconda/bin:$PATH
+  - export PATH=$HOME/miniconda:$PATH
+  - conda update --yes conda
+
+install:
+  - conda install --yes python=$TRAVIS_PYTHON_VERSION numpy scipy matplotlib scikit-learn
+  - pip install -r requirements.txt
+  - python setup.py install
+  - cd src/
+script:
+  - py.test --cov-config .coveragerc --cov=qinfer
+  - pylint --py3k qinfer/
+
+after_success:
+  - coveralls

README.rst

@@ -2,61 +2,42 @@
 Welcome to QInfer
 =================
 
-**QInfer** is a library using Bayesian sequential Monte Carlo for quantum
-parameter estimation.
+.. image:: https://zenodo.org/badge/19664/QInfer/python-qinfer.svg
+   :target: https://zenodo.org/badge/latestdoi/19664/QInfer/python-qinfer
 
-Obtaining QInfer
-================
+.. image:: https://travis-ci.org/QInfer/python-qinfer.svg?branch=master
+    :target: https://travis-ci.org/QInfer/python-qinfer
 
-A stable version of **QInfer** has not yet been released. Until then,
-the latest version may always be obtained by cloning into the GitHub
-repository::
+.. image:: https://coveralls.io/repos/github/QInfer/python-qinfer/badge.svg?branch=master
+    :target: https://coveralls.io/github/QInfer/python-qinfer?branch=master 
 
-    $ git clone git@github.com:csferrie/python-qinfer.git
-    
-Once obtained in this way, **QInfer** may be updated by pulling from GitHub::
+.. image:: https://codeclimate.com/github/QInfer/python-qinfer/badges/gpa.svg
+   :target: https://codeclimate.com/github/QInfer/python-qinfer
+   :alt: Code Climate
 
-    $ git pull
+**QInfer** is a library using Bayesian sequential Monte Carlo for quantum
+parameter estimation. Works with Python 2.7, 3.3, 3.4 and 3.5.
 
 Installing QInfer
 =================
 
-**QInfer** provides a setup script, ``setup.py``, for installing from source.
-On Unix-like systems, **QInfer** can be made available globally by running::
-
-    $ cd /path/to/qinfer/
-    $ sudo python setup.py install
-
-On Windows, run ``cmd.exe``, then run the setup script::
-
-    C:\> cd C:\path\to\qinfer\
-    C:\path\to\qinfer\> python setup.py install
-    
-Note that you may be prompted for permission by User Access Control.
-
-Dependencies
-============
-
-**QInfer** depends on only a very few packages:
+We recommend using **QInfer** with the
+`Anaconda distribution`_. Download and install
+Anaconda for your platform, either Python 2.7 or 3.5. We
+suggest using Python 3.5, but **QInfer**
+works with either. Next, ensure that you have Git installed. On Windows,
+we suggest the `official Git downloads <https://git-scm.com/downloads>`_.
+Once Anaconda and Git are installed, simply run ``pip`` to install **QInfer**::
 
-- Python 2.7 (may work with earlier, but not tested).
-- NumPy and SciPy.
-- [Optional] `SciKit-Learn`_ required for some advanced features.
-- [Optional] `Sphinx`_ required to rebuild documentation.
-
-On Windows, these packages can be provided by `Python(x,y)`_. Linux users may
-obtain the needed dependencies. Under Ubuntu::
-
-    $ sudo apt-get install python2.7 python-numpy python-scipy python-scikits-learn python-sphinx
-    
-On Fedora::
+    $ pip install git+https://github.com/QInfer/python-qinfer.git
 
-    $ sudo yum install python numpy scipy python-sphinx
-    $ sudo easy_install -U scikit-learn
+Alternatively, **QInfer** can be installed manually by downloading from GitHub,
+then running the provided installer::
 
-Alternatively,
-`Enthought Python Distribution`_ has been tested with **QInfer**, and may be
-used on Windows, Mac OS X or Linux.
+    $ git clone git@github.com:QInfer/python-qinfer.git
+    $ cd python-qinfer
+    $ pip install -r requirements.txt
+    $ python setup.py install
 
 More Information
 ================
@@ -77,7 +58,5 @@ On Windows::
 The generated documentation can be viewed by opening
 ``doc/_build/html/index.html``.
 
-.. _Enthought Python Distribution: http://www.enthought.com/products/epd.php
-.. _Python(x,y): http://code.google.com/p/pythonxy/
-.. _SciKit-Learn: http://scikit-learn.org/stable/
+.. _Anaconda distribution: https://www.continuum.io/downloads
 .. _Sphinx: http://sphinx-doc.org/

doc/source/apiref/ipy.rst

@@ -0,0 +1,27 @@
+..
+    This work is licensed under the Creative Commons Attribution-
+    NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this
+    license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a
+    letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View,
+    California, 94041, USA.
+    
+.. _ipy:
+
+.. currentmodule:: qinfer
+
+IPython/Jupyter Support
+=======================
+
+Introduction
+------------
+
+These classes integrate with Jupyter Notebook using
+the `ipywidgets`_ package.
+
+.. _ipywidgets: https://github.com/ipython/ipywidgets/
+
+:class:`IPythonProgressBar` - Progress bar for Jupyter Notebook
+---------------------------------------------------------------
+
+.. autoclass:: IPythonProgressBar
+    :members:

doc/source/apiref/parallel.rst

@@ -0,0 +1,20 @@
+..
+    This work is licensed under the Creative Commons Attribution-
+    NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this
+    license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a
+    letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View,
+    California, 94041, USA.
+    
+.. _parallel:
+
+.. currentmodule:: qinfer.parallel
+
+Parallelized Models
+===================
+
+:class:`~qinfer.DirectViewParallelizedModel`
+--------------------------------------------
+
+.. autoclass:: DirectViewParallelizedModel
+    :members:
+

doc/source/apiref/perf_testing.rst

@@ -37,6 +37,8 @@ Function Reference
 
 .. autofunction:: perf_test
 
+.. autofunction:: perf_test_multiple
+
 .. _perf_testing_struct:
 
 Performance Results Structure

doc/source/conf.py

@@ -152,7 +152,7 @@ def __getattr__(cls, name):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -333,7 +333,8 @@ def __getattr__(cls, name):
 intersphinx_mapping = {
     'http://docs.python.org/': None,
     'numpy': ('http://docs.scipy.org/doc/numpy',None),
-    'IPython': ('http://ipython.org/ipython-doc/stable/', None)
+    'IPython': ('http://ipython.org/ipython-doc/stable/', None),
+    'ipyparallel': ('http://ipyparallel.readthedocs.org/en/latest/', None)
 }
 
 autodoc_member_order = 'bysource'

doc/source/guide/parallel.rst

@@ -21,22 +21,21 @@ across multiple nodes using standard parallelization tools.
 Distributed Computation with IPython
 ------------------------------------
 
-`IPython`_ provides facilities for parallelizing computation across multiple
-cores and/or nodes via the :mod:`IPython.parallel` package. IPython's
-parallelization support separates computation into a *controller* that is
-responsible for one or more *engines*, and a *client* that sends commands to
-these engines via the controller. **QInfer** can use a client to send
-likelihood evaluation calls to engines, via the
-:class:`DirectViewParallelizedModel` class.
-
-This class takes a :class:`~IPython.parallel.client.view.DirectView` onto one
+The `ipyparallel`_ package (previously ``IPython.parallel``) provides
+facilities for parallelizing computation across multiple cores and/or nodes.
+`ipyparallel`_ separates computation into a *controller* that is responsible
+for one or more *engines*, and a *client* that sends commands to these engines
+via the controller. **QInfer** can use a client to send likelihood evaluation
+calls to engines, via the :class:`DirectViewParallelizedModel` class.
+
+This class takes a :class:`~ipyparallel.DirectView` onto one
 or more engines, typically obtained with an expression similar to
-``client[:]``, and splits calls to :meth:`~qinfer.smc.SMCUpdater.likelihood`
-across the engines accessible from the `DirectView`.
+``client[:]``, and splits calls to :meth:`~qinfer.Model.likelihood`
+across the engines accessible from the :class:`~ipyparallel.DirectView`.
 
->>> from IPython.parallel import Client # doctest: +SKIP
->>> from qinfer.test_models import SimplePrecessionModel # doctest: +SKIP
->>> from qinfer.parallel import DirectViewParallelizedModel # doctest: +SKIP
+>>> from ipyparallel import Client # doctest: +SKIP
+>>> from qinfer import SimplePrecessionModel # doctest: +SKIP
+>>> from qinfer import DirectViewParallelizedModel # doctest: +SKIP
 >>> c = Client() # doctest: +SKIP
 >>> serial_model = SimplePrecessionModel() # doctest: +SKIP
 >>> parallel_model = DirectViewParallelizedModel(serial_model, c[:]) # doctest: +SKIP
@@ -54,7 +53,27 @@ per-experiment or per-outcome cost.
     over engines, such that the behavior is unpredictable if any further
     commands are sent to the engines from outside the class.
 
-.. _IPython: http://ipython.org/
+Distributed Performance Testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an alternative to distributing a single likelihood call across multiple
+engines, **QInfer** also supports distributed performance testing. Under this
+model, each engine performs an independent trial of an estimation procedure,
+which is then collected by the client process. Distributed performance testing
+is implemented using the :func:`~qinfer.perf_test_multiple` function, with the
+keyword argument ``apply`` provided. For instance, the `ipyparallel`_ package
+offers a :class:`~ipyparallel.LoadBalancedView` class whose
+:meth:`~ipyparallel.LoadBalancedView.apply` method sends tasks to engines
+according to their respective loads.
+
+>>> lbview = client.load_balanced_view() # doctest: +SKIP
+>>> performance = qi.perf_test_multiple(
+...     100, serial_model, 6000, prior, 200, heuristic_class,
+...     apply=lbview.apply
+... ) # doctest: +SKIP
+
+Examples of both approaches to parallelization are provided as a
+`Jupyter Notebook <http://nbviewer.jupyter.org/github/QInfer/python-qinfer/blob/master/examples/parallelization.ipynb>`_.
 
 GPGPU-based Likelihood Computation with PyOpenCL
 ------------------------------------------------
@@ -71,5 +90,6 @@ Note that for sufficiently fast models, the overhead of copying data between
 the CPU and GPU may overwhelm any speed benefits obtained by this
 parallelization.
 
+.. _ipyparallel: https://ipyparallel.readthedocs.org/en/latest/
 .. _PyOpenCL: http://documen.tician.de/pyopencl/