Metadata-Version: 1.1
Name: soerp
Version: 0.8.2
Summary: Second Order ERror Propagation
Home-page: http://pypi.python.org/pypi/soerp
Author: Abraham Lee
Author-email: tisimst@gmail.com
License: BSD License
Description: Overview
        =========
        
        ``soerp`` is the Python implementation of the original Fortran code `SOERP` by N. D. Cox to apply a second-order analysis to `error propagation`_ (or uncertainty analysis). The ``soerp`` package allows you to **easily** and **transparently** track the effects of uncertainty through mathematical calculations. Advanced mathematical functions, similar to those in the standard `math`_ module can also be evaluated directly.
        
        In order to correctly use ``soerp``, knowledge of the **first eight statistical moments** is required. These are the *mean*, *variance*, and then the *standardized third through eighth moments*. These can be input manually in the form of an array, but they can also be **conveniently generated** using distributions from the ``scipy.stats`` sub-module. See the examples below for usage examples of both input methods. The result of all calculations generates a *mean*, *variance*, and *standardized skewness and kurtosis* coefficients.
        
        
        Required Packages
        =================
        
        - `ad`_ : For automatic differentiation (install this first).
        
        Suggested Packages
        ==================
        
        - `SciPy`_ : Scientific Python
        
        Basic examples
        ==============
        ::
        
            >>> from soerp import uv   # the constructor for uncertain variables
        
            >>> x1 = uv([24, 1, 0, 3, 0, 15, 0, 105])  # normally distributed
            >>> x2 = uv([37, 16, 0, 3, 0, 15, 0, 105])  # normally distributed
            >>> x3 = uv([0.5, 0.25, 2, 9, 44, 265, 1854, 14833])  # exponentially distributed
        
            >>> Z = (x1*x2**2)/(15*(1.5 + x3))
            >>> Z  # output compactly shows the mean, variance, and standardized skewness and kurtosis
            uv(1176.45, 99699.682291666657, 0.70801305294370709, 6.1370133446354318)
        
            >>> Z.describe  # use for more detailed output
            SOERP Uncertain Value:
             > Mean...................  1176.45
             > Variance...............  99699.6822917
             > Skewness Coefficient...  0.708013052944
             > Kurtosis Coefficient...  6.13701334464
                
            >>> import scipy.stats as ss   # using empirically defined distribution objects
            >>> x1 = uv(rv=ss.norm(loc=24, scale=1))  # normally distributed
            >>> x2 = uv(rv=ss.norm(loc=37, scale=4))  # normally distributed
            >>> x3 = uv(rv=ss.expon(scale=0.5))  # exponentially distributed
            
            >>> x1.moments()  # the eight moments can be accessed at any time
            [24.0, 1.0, 0.0, 3.0000000000000053, 0.0, 15.000000000000004, 0.0, 105.0]
            
            >>> x1-x1  # correlations are correctly handled
            0.0
            
            # convenient access to derivatives
            >>> Z.d(x1)  # first derivative wrt x1 (returns all if no input, 0 if derivative doesn't exist)
            45.63333333333333
        
            >>> Z.d2(x2)  # second derivative wrt x2
            1.6
        
            >>> Z.d2c(x1, x3)  # second cross-derivative wrt x1 and x3 (order doesn't matter)
            -22.816666666666666
            
            >>> Z.gradient([x1, x2, x3])  # convenience function, useful for optimization
            [45.63333333333333, 59.199999999999996, -547.6]
        
            >>> Z.hessian([x1, x2, x3])   # another convenience function
            [[0.0, 2.466666666666667, -22.816666666666666], [2.466666666666667, 1.6, -29.6], [-22.816666666666666, -29.6, 547.6]]
        
            >>> Z.error_components(pprint=True)  # show how each variable is contributing errors
            COMPOSITE VARIABLE ERROR COMPONENTS
            uv(37.0, 16.0, 0.0, 3.0) = 58202.9155556 or 58.378236%
            uv(24.0, 1.0, 0.0, 3.0) = 2196.15170139 or 2.202767%
            uv(0.5, 0.25, 2.0, 9.0) = -35665.8249653 or 35.773258%
        
            # a more advanced example (volumetric gas flow through orifice meter)
            >>> from soerp.umath import *  # sin, exp, sqrt, etc.
            >>> H = uv(rv=ss.norm(loc=64, scale=0.5))
            >>> M = uv(rv=ss.norm(loc=16, scale=0.1))
            >>> P = uv(rv=ss.norm(loc=361, scale=2))
            >>> t = uv(rv=ss.norm(loc=165, scale=0.5))
            >>> C = 38.4
            >>> Q = C*umath.sqrt((520*H*P)/(M*(t + 460)))
            
            >>> Q.describe
            SOERP Uncertain Value:
             > Mean...................  1330.99973939
             > Variance...............  58.210762839
             > Skewness Coefficient...  0.0109422068056
             > Kurtosis Coefficient...  3.0003269571
            
        Main Features
        =============
        
        1. **Transparent calculations** with derivatives automatically calculated. **No or little modification** to existing code required.
        2. Basic `NumPy` support without modification. Vectorized calculations built-in to the ``ad`` package.
        3. Nearly all standard `math`_ module functions supported through the ``soerp.umath`` sub-module. If you think a function is in there, it probably is.
        4. Nearly all derivatives calculated analytically using ``ad`` functionality.
        
        Installation
        ============
        
        **Make sure you install the** `ad`_ **package first!**
        
        You have several easy, convenient options to install the ``soerp`` package 
        (administrative privileges may be required)
        
        1. Download the package files below, unzip to any directory, and run ``python setup.py install`` from the command-line
        2. Simply copy the unzipped ``soerp-XYZ`` directory to any other location that python can find it and rename it ``soerp``
        3. If ``setuptools`` is installed, run ``easy_install --upgrade soerp`` from the command-line
        4. If ``pip`` is installed, run ``pip --upgrade soerp`` from the command-line
        
        Contact
        =======
        
        Please send **feature requests, bug reports, or feedback** to 
        `Abraham Lee`_.
        
        Credits
        =======
        
        A lot of the credit goes to `Eric O. LEBIGOT`_ who first developed `uncertainties`_, a very nice first-order package for error propagation, from which many inspiring ideas (like correlating variables, etc.) are re-used or slightly evolved. If you **don't** need second order functionality, I recommend using his package.
        
        References
        ==========
        
        - N.D. Cox, 1979, Tolerance Analysis by Computer, Journal of Quality Technology, Vol. 11, No. 2, pp. 80-87
        
        
        
        .. _error propagation: http://en.wikipedia.org/wiki/Propagation_of_uncertainty
        .. _math: http://docs.python.org/library/math.html
        .. _ad: http://pypi.python.org/pypi/ad
        .. _SciPy: http://scipy.org
        .. _uncertainties: http://pypi.python.org/pypi/uncertainties
        .. _Abraham Lee: mailto: tisimst@gmail.com
        .. _Eric O. LEBIGOT: http://www.linkedin.com/pub/eric-lebigot/22/293/277
        .. _PEP8: http://www.python.org/dev/peps/pep-0008
        
Keywords: uncertainty analysis,uncertainties,error propagation,second order,derivative,statistics,method of moments,distribution
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires: ad
