Skip to main content

Second Order ERror Propagation

Project 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

soerp-0.8.2.zip (25.5 kB view hashes)

Uploaded Source

soerp-0.8.2.tar.gz (21.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page