Real-time latin-hypercube sampling-based Monte Carlo ERror Propagation
Project description
Overview
mcerp is an on-the-fly calculator for Monte Carlo methods that uses latin-hypercube sampling (see soerp for the Python implementation of the analytical second-order error propagation original Fortran code SOERP by N. D. Cox) to perform non-order specific error propagation (or uncertainty analysis). The mcerp 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.
Due to the nature of random sampling techniques, calculation results will vary from session to session (but be consistent within the session) since new latin-hypercube samples are only generated when variables are newly defined or re-defined. By default, each variable uses 10,000 latin-hypercube samples that are sufficiently random. The number of samples can be changed by assigning an integer value to the mcerp.npts object (typically, values between 1,000 and 1,000,000 are sufficiently large to insure small errors in the resulting statistics). This should only be changed prior to performing calculations since all subsequent calculations assume that each input has the same number of sampled points (this could be changed through resampling, I suppose…).
In order to correctly use mcerp, knowledge of the distributions from the scipy.stats sub-module is required. The result of all calculations generates a mean, variance, and standardized skewness and kurtosis coefficients.
Required Packages
Suggested Packages
Matplotlib : Python plotting library (required for mcerp.plot)
Basic examples
>>> from mcerp import * # N, U, Gamma, Beta, etc. >>> x1 = N(24, 1) # normally distributed >>> x2 = N(37, 4) # normally distributed >>> x3 = Exp(2) # exponentially distributed >>> Z = (x1*x2**2)/(15*(1.5 + x3)) >>> Z uv(1161.14296871, 116093.134064, 0.361152281239, 3.05247793644) >>> Z.describe() # explains what the moments are MCERP Uncertain Value: > Mean................... 1161.14296871 > Variance............... 116093.134064 > Skewness Coefficient... 0.361152281239 > Kurtosis Coefficient... 3.05247793644 >>> x1.stats # the eight moments can be accessed at any time [24.0, 1.0, 0.0, 3.0] >>> x1.plot() # if matplotlib is installed it shows the distribution >>> x1-x1 # correlations are correctly handled 0.0 # Example of volumetric gas flow through orifice meter >>> import mcerp.umath as umath # sin, exp, sqrt, etc. >>> H = N(64, 0.5) >>> M = N(16, 0.1) >>> P = N(361, 2) >>> t = N(165, 0.5) >>> C = 38.4 >>> Q = C*umath.sqrt((520*H*P)/(M*(t + 460))) >>> Q.describe() MCERP Uncertain Value: > Mean................... 1330.9997362 > Variance............... 57.5497899824 > Skewness Coefficient... 0.0229295468388 > Kurtosis Coefficient... 2.99662898689 >>> Q.plot() # shows a kde of the resultant calculations
Using Distributions
Since all of the variables in mcerp are statistical distributions, they are created using the scipy.stats distributions. There are also some convenience constructors that should make defining a distribution easier, though it’s not necessary to use them. See the source code of the UncertainVariable class for info that describes how to construct many of the most common statistical continuous and discrete distributions using the scipy.stats distributions.
Though its not entirely discouraged to use the scipy.stats distributions directly, here are the equivalent constructors that I’ve found to be easier to use (the location, scale, and shape parameters are described in the respective Wikipedia pages):
Continuous Distributions |
|
N(mu, sigma) |
|
U(a, b) |
|
Exp(lamda, [mu]) |
|
Gamma(k, theta) |
|
Beta(alpha, beta, [a, b]) |
|
LogN(mu, sigma) |
|
X2(k) |
|
F(d1, d2) |
|
Tri(a, b, c) |
|
T(v) |
|
Weib(lamda, k) |
|
Discrete Distributions |
|
Bern(p) |
|
B(n, p) |
|
G(p) |
|
H(M, n, N) |
|
Pois(lamda) |
For example, the following constructions are equivalent:
>>> x = uv(ss.norm(loc=10, scale=1)) # scipy.stats distribution >>> x = N(10, 1) # nicer constructor IMHO :)
Main Features
Transparent calculations. No or little modification to existing code required.
Basic NumPy support without modification. (I haven’t done extensive testing, so please let me know if you encounter bugs.)
Advanced mathematical functions supported through the mcerp.umath sub-module. If you think a function is in there, it probably is. If it isn’t, please request it!
Easy continuous distribution constructors. The location, scale, and shape parameters follow the notation in the respective Wikipedia articles.
Installation
Make sure you have the SciPy and NumPy packages installed! This package won’t work without them.
You have several easy, convenient options to install the mcerp package (administrative privileges may be required)
Manually download the package files below, unzip to any directory, and run python setup.py install from the command-line.
Simply copy the unzipped mcerp-XYZ directory to any other location that python can find it and rename it mcerp.
If setuptools is installed, run easy_install --upgrade mcerp from the command-line.
If pip is installed, run pip --upgrade mcerp from the command-line.
Python 3
To use this package with Python 3.x, you will need to run the 2to3 conversion tool at the command-line using the following syntax while in the unzipped mcerp directory:
$ 2to3 -w -f all *.py
This should take care of the main changes required. Then, run python3 setup.py install. If bugs continue to pop up, please email the author.
See also
uncertainties : First-order uncertainty propagation
soerp : Second Order ERror Propagation
Contact
Please send feature requests, bug reports, or feedback to Abraham Lee.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.