.. image:: https://travis-ci.org/SunPower/UncertaintyWrapper.svg?branch=master :target: https://travis-ci.org/SunPower/UncertaintyWrapper
    UncertaintyWrapper
    ==================

    Use ``@unc_wrapper`` decorator to wrap any Python callable to append the
    covariance and Jacobian matrices to the return values. See documentation and
    tests for usage and examples.

    Installation
    ------------

    Use ``pip install UncertaintyWrapper`` to install from
    `PyPI <https://pypi.python.org/pypi/UncertaintyWrapper>`_ or download a source
    distribution, extract and use ``python setup.py install``.

    Requirements
    ------------

    * `NumPy <http://www.numpy.org/>`_

    Optional Requirements
    ~~~~~~~~~~~~~~~~~~~~~

    * `Nose <https://nose.readthedocs.org/en/latest/index.html>`_ for testing.
    * `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ to build documentation.
    * `NREL SOLPOS <http://rredc.nrel.gov/solar/codesandalgorithms/solpos/>`_ for testing
    * `AlgoPy <https://pythonhosted.org/algopy/>`_ for testing

    Usage
    -----

    Example::

        from uncertainty_wrapper import unc_wraper
        import numpy as np

        @unc_wrapper
        def f(x):
            return np.exp(x)

        x, cov = np.array([[1.0]]), np.array([[0.1]])
        f(x, __covariance__=cov)

    Returns::

        (array([[ 2.71828183]]),      # exp(1.0)
         array([[[ 0.73890561]]]),    # (delta-f)^2 = (df/dx)^2 * (delta-x)^2
         array([[[ 2.71828183]]]))    # df/dx = exp(x)


    History
    -------
    Releases are named after
    `geological eons, periods and epochs <https://en.wikipedia.org/wiki/Geologic_time_scale>`_.

    `v0.4.1 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.4.1>`_ `Paleozoic Era <https://en.wikipedia.org/wiki/Paleozoic>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    * Jagged arrays of covariance keys work now.
    * simplify

    `v0.4 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.4>`_ `Phanerozoic Era <https://en.wikipedia.org/wiki/Phanerozoic>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    * Fixes #5, ``ValueError`` if covariance keys have multiple observations
    * fix covariance cross terms not scaled correctly

    `v0.3.3 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.3.3>`_ `Neoproterozoic Era <https://en.wikipedia.org/wiki/Neoproterozoic>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    * Fixes #4, ``ValueError`` if just one observation

    `v0.3.2 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.3.2>`_ `Mesoproterozoic Era <https://en.wikipedia.org/wiki/Mesoproterozoic>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    * Fixes #2, don't need to tile scalar x for multiple observations
    * Fixes #3, use sparse matrices for dot product instead of dense
    * uses pvlib example instead of proprietary solar_utils


    `v0.3.1 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.3.1>`_ `Paleoproterozoic Era <https://en.wikipedia.org/wiki/Paleoproterozoic>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    * Fixes #1 works with Pint's @ureg.wraps()
    * Use indices for positional arguments. Don't use inspect.argspec since not
      guaranteed to be the same for wrapped or decorated functions
    * Test Jacobian estimate for IV with `AlgoPy <https://pythonhosted.org/algopy/>`_
    * Show Jacobian errors plot in getting started docs.


    `v0.3 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.3>`_ `Proterozoic Eon <https://en.wikipedia.org/wiki/Proterozoic>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    * new ``unc_wrapper_args()`` allows selection of independent variables that the
      partial derivatives are with respect to and also grouping those arguments
      together so that in the original function they can stay unpacked.
    * return values are grouped correctly so that they can remain unpacked in
      original function. These allow Uncertainty Wrapper to be used with
      `Pint's wrapper <http://pint.readthedocs.org/en/latest/wrapping.html>`_
    * covariance now specified as dimensionaless fraction of square of arguments
    * more complex tests: IV curve and solar position (requires
      `NREL's solpos <http://rredc.nrel.gov/solar/codesandalgorithms/solpos/>`_)


    `v0.2.1 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.2>`_ `Eoarchean Era <https://en.wikipedia.org/wiki/Eoarchean>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    * update documentation


    `v0.2 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.2>`_ `Archean Eon <https://en.wikipedia.org/wiki/Archean>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    * Fix nargs and nf order mixup in Jacobian
    * add more complex test
    * fix tile cov by nobs
    * move partial derivative to subfunction
    * try threading, but same speed, and would only work with NumPy anyway


    `v0.1 <https://github.com/SunPower/UncertaintyWrapper/releases/tag/v0.1>`_ `Hadean Eon <https://en.wikipedia.org/wiki/Hadean>`_
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    * adds covariance to output
    * allows __covariance__ to be passed as input
    * uses estimate Jacobian based on central finite difference method