Merge branch 'master' of github.com:QInfer/python-qinfer into feature-hyper-heuristic-optimisation

Author: Alan-Robertson

doc/source/apiref/domains.rst

@@ -32,6 +32,16 @@ Class Reference
 .. autoclass:: Domain
     :members:
 
+
+:class:`ProductDomain` - Cartesian product of multiple domains
+--------------------------------------------------------------
+
+Class Reference 
+~~~~~~~~~~~~~~~
+.. autoclass:: ProductDomain
+    :members:
+
+    
 :class:`RealDomain` - (A subset of) Real Numbers
 ------------------------------------------------
 
@@ -58,4 +68,4 @@ This domain is used by :class:`MultinomialModel`.
 Class Reference 
 ~~~~~~~~~~~~~~~
 .. autoclass:: MultinomialDomain
-    :members:
+    :members:

doc/source/guide/citing.rst

@@ -0,0 +1,159 @@
+..
+    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.
+    
+.. _citing_guide:
+    
+.. currentmodule:: qinfer
+
+Citing QInfer and Related Projects
+==================================
+
+Citing Released Versions
+------------------------
+
+If you use **QInfer** in your publication or presentation, we would appreciate it
+if you cited our work. We recommend citing **QInfer** by using the BibTeX
+entry::
+
+    @misc{qinfer-1_0,
+      author       = {Christopher Granade and
+                      Christopher Ferrie and
+                      Steven Casagrande and
+                      Ian Hincks and
+                      Michal Kononenko and
+                      Thomas Alexander and
+                      Yuval Sanders},
+      title        = {{QInfer}: Library for Statistical Inference in Quantum Information},
+      month        = september,
+      year         = 2016,
+      doi          = {10.5281/zenodo.157007},
+      url          = {http://dx.doi.org/10.5281/zenodo.157007}
+    }
+
+
+Pre-Release Versions
+--------------------
+
+If you wish to cite **QInfer** functionality that has not yet appeared in a
+released version, it may be helpful
+to cite a given SHA hash as listed on
+`GitHub <https://github.com/QInfer/python-qinfer/commits/master>`_ (the
+hashes of each commit are listed on the right hand side of the page).
+A recommended BibTeX entry for citing a particular commit is::
+
+    @misc{qinfer-prerelease,
+      author       = {Christopher Granade and
+                      Christopher Ferrie and
+                      Steven Casagrande and
+                      Ian Hincks and
+                      Michal Kononenko and
+                      Thomas Alexander and
+                      Yuval Sanders},
+      title        = {{QInfer}: Library for Statistical Inference in Quantum Information},
+      month        = may,
+      year         = 2016,
+      url =    "https://github.com/QInfer/python-qinfer/commit/bc3736c",
+      note =   {Version \texttt{bc3736c}.}
+    }
+
+In this example, ``bc3736c`` should be replaced by the
+particular commit being cited, and the date should be replaced by the date
+of that commit.
+
+Automatic Citation Collection
+-----------------------------
+
+QInfer also supports the use of the `duecredit`_ project to automatically
+collect citations for a bibliography. This support is still experimental,
+and may not yet generate complete bibliographies, so please manually check
+the resulting bibliography. In any case, to get started, install `duecredit`_::
+
+    $ pip install duecredit
+
+If your project then uses a script to generate and/or analyze data, then you
+can use `duecredit`_ to collect citations for Python modules and functions
+called by your script. For example, if your project can be run as
+`python script.py`, use the following command to collect a bibliography::
+
+    $ python -m duecredit script.py
+
+Alternatively, it may be more reliable to use environment variables to turn
+on `duecredit`_ collection, since this approach also works with 
+Jupyter Notebook::
+
+    $ export DUECREDIT_ENABLE=yes # Bash
+    PS> $Env:DUECREDIT_ENABLE = "yes" # PowerShell
+    
+Or, from within an Jupyter Notebook, environment variables can be set before
+import using::
+
+    import os
+    os.environ['DUECREDIT_ENABLE'] = 'yes'
+    import qinfer as qi
+
+Whenever it is detected that this variable is true, any uses of **Qinfer** in a 
+given folder (even multiple distinct runs) will maintain 
+a file in the same folder called ``.duecredit.p`` that contains 
+a representation of your bibliography. This file is updated whenever **Qinfer**
+uses a module, class, or method that is appropriately tagged with a citation.
+
+If you wish to see the citation compilaton of a *single* python session, 
+you can dump the current state with::
+
+    qi.due.dump()
+
+On the other hand, to print it out the entire ``.duecredit.p`` collection 
+in BibTeX form, use the summary functionality of `duecredit`_::
+
+    $ duecredit summary --format=bibtex
+
+Note that this summary will also include projects such as NumPy and SciKit-Learn
+that are supported by `duecredit`_, as well as any other projects which natively
+host citation metadata through `duecredit`_.  For example::
+
+    $ export DUECREDIT_ENABLE=yes
+    $ ipython
+    In [1]: import qinfer as qi
+    In [2]: exit
+
+    DueCredit Report:
+    - Scientific tools library / numpy (v 1.11.1) [1]
+    - Bayesian inference for quantum information / qinfer (v 1.0) [2]
+    - Machine Learning library / sklearn (v 0.17.1) [3]
+        - Affinity propagation clustering algorithm / sklearn.cluster.affinity_propagation_ (v 0.17.1) [4]
+
+    3 packages cited
+    1 module cited
+    0 functions cited
+
+    References
+    ----------
+
+    [1] Van Der Walt, S., Colbert, S.C. & Varoquaux, G., 2011. The NumPy array: a structure for efficient numerical computation. Computing in Science & Engineering, 13(2), pp.22–30.
+    [2] Granade, C. et al., 2016. QInfer: Statistical Inference Software for Quantum Applications. arXiv:1610.00336 [physics, physics:quant-ph, stat].
+    [3] Pedregosa, F. et al., 2011. Scikit-learn: Machine learning in Python. The Journal of Machine Learning Research, 12, pp.2825–2830.
+    [4] Frey, B.J. & Dueck, D., 2007. Clustering by Passing Messages Between Data Points. Science, 315(5814), pp.972–976.
+
+The bibliography entries defined by QInfer are organized according to different
+*tags*, making it easier to filter through the results of `duecredit`_. In particular,
+QInfer uses the following citation tags, as defined in the `duecredit documentation
+<https://github.com/duecredit/duecredit/blob/master/README.md>`_:
+
+- ``implementation``: The tagged function is an implementation of the cited work.
+- ``experiment``: Concerns experimental demonstrations of an algorithm or procedure. This tag
+  is similar to, but distinct from, the ``use`` tag defined by `duecredit`_.
+
+These tags can be controlled using the ``DUECREDIT_REPORT_ALL`` and ``DUECREDIT_REPORT_TAGS``
+environment variables. By default, all tags by ``implementation`` are hidden, such that
+summaries of the collected bibliography describe which software implementations are used
+in the course of a project.
+
+For more details on how to use `duecredit`_, please see their `documentation on
+GitHub <https://github.com/duecredit/duecredit/blob/master/README.md>`_.
+
+
+.. _duecredit: https://github.com/duecredit/duecredit/

doc/source/guide/index.rst

@@ -24,4 +24,5 @@ User's Guide
     perf_testing
     parallel
     interop
+    citing
 

doc/source/intro.rst

@@ -63,32 +63,7 @@ entry::
       url          = {http://dx.doi.org/10.5281/zenodo.157007}
     }
 
-If you wish to cite **QInfer** functionality that has not yet appeared in a
-released version, it may be helpful
-to cite a given SHA hash as listed on
-`GitHub <https://github.com/QInfer/python-qinfer/commits/master>`_ (the
-hashes of each commit are listed on the right hand side of the page).
-A recommended BibTeX entry for citing a particular commit is::
-
-    @misc{qinfer-1_0b4,
-      author       = {Christopher Granade and
-                      Christopher Ferrie and
-                      Steven Casagrande and
-                      Ian Hincks and
-                      Michal Kononenko and
-                      Thomas Alexander and
-                      Yuval Sanders},
-      title        = {{QInfer}: Library for Statistical Inference in Quantum Information},
-      month        = may,
-      year         = 2016,
-      url =    "https://github.com/QInfer/python-qinfer/commit/bc3736c",
-      note =   {Version \texttt{bc3736c}.}
-    }
-
-    
-In this example, ``bc3736c`` should be replaced by the
-particular commit being cited, and the date should be replaced by the date
-of that commit.
+For more details, please see :ref:`citing_guide`.
 
 Getting Started
 ===============

src/qinfer/__init__.py

@@ -26,6 +26,28 @@
 from __future__ import absolute_import
 from qinfer.version import version as __version__
 
+## CITATION METADATA ##########################################################
+
+from ._due import due, Doi, BibTeX
+
+due.cite(
+    BibTeX("""
+        @article{qinfer,
+            title = {{QInfer}: {Statistical} Inference Software for Quantum Applications},
+            eprinttype = {arxiv},
+            eprint = {1610.00336},
+            journal = {arXiv:1610.00336 [physics, physics:quant-ph, stat]},
+            author = {Granade, Christopher and Ferrie, Christopher and Hincks, Ian and Casagrande, Steven and Alexander, Thomas and Gross, Jonathan and Kononenko, Michal and Sanders, Yuval},
+            month = oct,
+            year = {2016}
+        }
+    """),
+    description="Bayesian inference for quantum information",
+    tags=["implementation"],
+    cite_module=True,
+    path="qinfer"
+)
+
 ## IMPORTS ####################################################################
 # These imports control what is made available by importing qinfer itself.
 

src/qinfer/_due.py

@@ -0,0 +1,74 @@
+# emacs: at the end of the file
+# ex: set sts=4 ts=4 sw=4 et:
+# pylint: skip-file
+# ## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### #
+"""
+
+Stub file for a guaranteed safe import of duecredit constructs:  if duecredit
+is not available.
+
+To use it, place it into your project codebase to be imported, e.g. copy as
+
+    cp stub.py /path/tomodule/module/due.py
+
+Note that it might be better to avoid naming it duecredit.py to avoid shadowing
+installed duecredit.
+
+Then use in your code as
+
+    from .due import due, Doi, BibTeX
+
+See  https://github.com/duecredit/duecredit/blob/master/README.md for examples.
+
+Origin:     Originally a part of the duecredit
+Copyright:  2015-2016  DueCredit developers
+License:    BSD-2
+"""
+
+__version__ = '0.0.5'
+
+
+class InactiveDueCreditCollector(object):
+    """Just a stub at the Collector which would not do anything"""
+    def _donothing(self, *args, **kwargs):
+        """Perform no good and no bad"""
+        pass
+
+    def dcite(self, *args, **kwargs):
+        """If I could cite I would"""
+        def nondecorating_decorator(func):
+            return func
+        return nondecorating_decorator
+
+    cite = load = add = _donothing
+
+    def __repr__(self):
+        return self.__class__.__name__ + '()'
+
+
+def _donothing_func(*args, **kwargs):
+    """Perform no good and no bad"""
+    pass
+
+
+try:
+    from duecredit import due, BibTeX, Doi, Url
+    if 'due' in locals() and not hasattr(due, 'cite'):
+        raise RuntimeError(
+            "Imported due lacks .cite. DueCredit is now disabled")
+except Exception as e:
+    if type(e).__name__ != 'ImportError':
+        import logging
+        logging.getLogger("duecredit").error(
+            "Failed to import duecredit due to %s" % str(e))
+    # Initiate due stub
+    due = InactiveDueCreditCollector()
+    BibTeX = Doi = Url = _donothing_func
+
+# Emacs mode definitions
+# Local Variables:
+# mode: python
+# py-indent-offset: 4
+# tab-width: 4
+# indent-tabs-mode: nil
+# End:

src/qinfer/ale.py

@@ -49,6 +49,7 @@
 from qinfer.derived_models import DerivedModel
 from qinfer.abstract_model import Model, Simulatable, FiniteOutcomeModel
 from qinfer._exceptions import ApproximationWarning
+from qinfer._due import due, Doi
 
 ## CLASSES ####################################################################
 
@@ -73,6 +74,11 @@ class ALEApproximateModel(DerivedModel):
         cause the algorithm to require more samples.
     """
 
+    @due.dcite(
+        Doi("10.1103/PhysRevLett.112.130402"),
+        description="Adaptive likelihood estimation",
+        tags=["implementation"]
+    )
     def __init__(self, simulator,
         error_tol=1e-2, min_samp=10, samp_step=10,
         est_hedge=0.509, adapt_hedge=0.509