mcerp 0.9.5
Realtime latinhypercubesamplingbased Monte Carlo Error Propagation
Latest Version: 0.11
Overview
mcerp is an onthefly calculator for Monte Carlo methods that uses latinhypercube sampling (see soerp for the Python implementation of the analytical secondorder error propagation original Fortran code ‘SOERP’ by N. D. Cox) to perform nonorder 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 latinhypercube samples are only generated when variables are newly defined or redefined. By default, each variable uses 10,000 latinhypercube 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 ensure 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 submodule is required. The result of all calculations generates a mean, variance, and standardized skewness and kurtosis coefficients.
What’s New In This Release
 New correlation features (see examples below):
 correlate: Impose a set of correlation coefficients on variables (if needed, this should be used before performing any calculations).
 plotcorr: Show a scatterplot matrix of variables
Suggested Packages
 Matplotlib : Python plotting library (required for mcerp.plot)
Basic examples
Let’s start with the main import:
>>> from mcerp import * # N, U, Gamma, Beta, etc.
Now, we can construct many kinds of statistical distributions (both continuous and discrete). Here’s a basic example that involves a threepart assembly:
>>> x1 = N(24, 1) # normally distributed >>> x2 = N(37, 4) # normally distributed >>> x3 = Exp(2) # exponentially distributed
The first four moments can be accessed at any time:
>>> x1.mean 24.000015983319528 >>> x1.var 1.0001064993938098 >>> x1.skew 0.00053245280109193898 >>> x1.kurt 3.0017697746273813 >>> x1.stats # this returns all four as a list
Now we’ll compute the actual stackup using normal mathematics and see what happens:
>>> Z = (x1*x2**2)/(15*(1.5 + x3))
We can see how the statistics of each of these distributions propagated through the calculations in two basic ways:
Telling python to print the object:
>>> Z # Explicit "print" command not necessary at the commandline uv(1161.35518507, 116688.945979, 0.353867228823, 3.00238273799)
Using the describe class method (provides a more detailed explanation):
>>> Z.describe() MCERP Uncertain Value: > Mean................... 1161.35518507 > Variance............... 116688.945979 > Skewness Coefficient... 0.353867228823 > Kurtosis Coefficient... 3.00238273799
Viewing the distribution
We can also plot the distributions using the plot class method:
>>> x1.plot() # No inputs shows the distribution's PDF >>> x1.show() # explicit 'show()' required to display to screen
and for the outputs:
>>> Z.plot() # shows the Kernel Density Estimate (KDE) of the data >>> Z.show()
>>> Z.plot(hist=True) # shows a histogram instead of a KDE >>> Z.show()
or both:
>>> Z.plot() >>> Z.plot(hist=True) >>> Z.show()
Correlations
Even correlations are correctly handled:
>>> x1  x1 0.0 >>> Z*Z  Z**2 0.0
If it desired to force a set of variables to have certain correlations, which is not uncommon in reallife situations, this can be done with the correlate function (NOTE: this should be done BEFORE any calculations have taken place in order to work properly). For example, say we desire to impose a 0.75 correlation between x1 and x2 from the above example:
# The correlation coefficients before adjusting >>> print correlation_matrix([x1, x2, x3]) [[ 1. 0.00558381 0.01268168] [ 0.00558381 1. 0.00250815] [ 0.01268168 0.00250815 1. ]]
And here is what the actual data looks like in a matrix plot form:
Now we’ll apply the desired correlations (note that all diagonal elements should be 1.0):
# The desired correlation coefficient matrix >>> c = np.array([[ 1.0, 0.75, 0.0], ... [0.75, 1.0, 0.0], ... [ 0.0, 0.0, 1.0]]) # Apply the correlations into the samples (works inplace) >>> correlate([x1, x2, x3], c) # Show the new correlation coefficients >>> print correlation_matrix([x1, x2, x3]) [[ 1.00000000e+00 7.50010477e01 1.87057576e03] [ 7.50010477e01 1.00000000e+00 8.53061774e04] [ 1.87057576e03 8.53061774e04 1.00000000e+00]]
The correlation matrix is roughly what we expected within a few percent. This is what the newly correlated samples looks like:
Now that the inputs’ relations have been modified, let’s check how the output of our stackup has changed:
# Z should now be a little different >>> Z = (x1*x2**2)/(15*(1.5 + x3)) >>> Z.describe MCERP Uncertain Value: > Mean................... 1153.710442 > Variance............... 97123.3417748 > Skewness Coefficient... 0.211835225063 > Kurtosis Coefficient... 2.87618465139
We can also see what adding that correlation did: reduced the mean, reduced the variance, increased the skewness, increased the kurtosis.
If any exceptions appear during this operation, it is likely because the correlation matrix is either not symmetric, not positivedefinite, or both.
Advanced Example
Here’s a slightly more advanced engineering example, showing how the random effects of input parameters propagates through the calculation of the volumetric gas flow through an 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
Interestingly enough, even though the calculations involve multiplication, division, and a squareroot, the result appears to be very close to a Normal (Gaussian) distribution (Q ~ N(1331, 7.6) where 7.6 = sqrt(58.2)).
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.
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)  Normal distribution 
U(a, b)  Uniform distribution 
Exp(lamda, [mu])  Exponential distribution 
Gamma(k, theta)  Gamma distribution 
Beta(alpha, beta, [a, b])  Beta distribution 
LogN(mu, sigma)  Lognormal distribution 
X2(k)  Chisquared distribution 
F(d1, d2)  Fdistribution 
Tri(a, b, c)  Triangular distribution 
T(v)  Tdistribution 
Weib(lamda, k)  Weibull distribution 
Discrete Distributions  
Bern(p)  Bernoulli distribution 
B(n, p)  Binomial distribution 
G(p)  Geometric distribution 
H(M, n, N)  Hypergeometric distribution 
Pois(lamda)  Poisson distribution 
For example, the following constructions are equivalent:
# explicitly calling out the scipy.stats distribution >>> import scipy.stats as ss >>> x = uv(ss.norm(loc=10, scale=1)) # using a builtin constructor >>> x = N(10, 1)
From my experience, the first option can be tedious and difficult to work with, but you make the choice. That’s why there are options!
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 submodule. If you think a function is in there, it probably is. If it isn’t, please request it!
 Easy statistical distribution constructors. The location, scale, and shape parameters follow the notation in the respective Wikipedia articles.
 Correlation enforcement and variable sample visualization capabilities.
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)
Simply copy the unzipped mcerpXYZ directory to any other location that python can find it and rename it mcerp.
From the commandline, do one of the following:
Manually download the package files below, unzip to any directory, and run:
$ [sudo] python setup.py install
If setuptools is installed, run:
$ [sudo] easy_install upgrade mcerp
If pip is installed, run:
$ [sudo] pip install upgrade mcerp
Python 3
To use this package with Python 3.x, you will need to run the 2to3 conversion tool at the commandline using the following syntax while in the unzipped mcerp directory:
$ 2to3 w .
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 : Firstorder error propagation
 soerp : Secondorder error propagation
Contact
Please send feature requests, bug reports, or feedback to Abraham Lee.
File  Type  Py Version  Uploaded on  Size  

mcerp0.9.5.tar.gz (md5)  Source  20131018  21KB  
 Author: Abraham Lee
 Documentation: mcerp package documentation
 Home Page: https://github.com/tisimst/mcerp
 Keywords: monte carlo,latin hypercube,sampling calculator,error propagation,uncertainty,error,realtime
 License: BSD License

Categories
 Development Status :: 5  Production/Stable
 Environment :: Console
 Environment :: MacOS X
 Environment :: Win32 (MS Windows)
 Environment :: X11 Applications
 Intended Audience :: Customer Service
 Intended Audience :: Developers
 Intended Audience :: Education
 Intended Audience :: Financial and Insurance Industry
 Intended Audience :: Healthcare Industry
 Intended Audience :: Manufacturing
 Intended Audience :: Other Audience
 Intended Audience :: Science/Research
 License :: OSI Approved :: BSD License
 Natural Language :: English
 Operating System :: MacOS
 Operating System :: Microsoft
 Operating System :: Microsoft :: Windows
 Operating System :: OS Independent
 Operating System :: POSIX
 Operating System :: Unix
 Programming Language :: Python
 Programming Language :: Python :: 2.6
 Programming Language :: Python :: 2.7
 Programming Language :: Python :: 3
 Programming Language :: Python :: 3.0
 Programming Language :: Python :: 3.1
 Programming Language :: Python :: 3.2
 Programming Language :: Python :: 3.3
 Topic :: Education
 Topic :: Scientific/Engineering
 Topic :: Scientific/Engineering :: Chemistry
 Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
 Topic :: Scientific/Engineering :: Information Analysis
 Topic :: Scientific/Engineering :: Mathematics
 Topic :: Scientific/Engineering :: Physics
 Topic :: Software Development
 Topic :: Software Development :: Libraries
 Topic :: Software Development :: Libraries :: Python Modules
 Topic :: Utilities
 Package Index Owner: tisimst.myopenid.com
 DOAP record: mcerp0.9.5.xml