added simple univariate splitting example to docs

Author: keithalegrand

docs/examples.rst

@@ -3,6 +3,27 @@ Examples
 
 This section provides examples of using PyEst for various applications.
 
+Splitting the Univariate Standard Normal Distribuion
+---------------------------------------------------------------------
+The PyEst library makes it easy to split a univariate standard normal distribution
+in an optimal way, which is fundamental to the formation of so-called
+"splitting libraries."
+
+Each splitting solution is determined by the number of mixands :math:`L` and the
+regularization parameter :math:`\lambda`, which controls how large the resulting
+mixand variances are.
+
+The first time PyEst generates an optimal split solution for an
+:math:`(L,\lambda)` pair that hasn't been used before, it will solve an
+optimization problem and cache the resulting solution to disk. All future calls
+with this parameter pair will simply reference the cached result and thus be much
+faster.
+
+.. literalinclude:: ../examples/example_simple_gaussian_split.py
+   :language: python
+
+.. image:: image/univariate_split.png
+
 Splitting and Plotting PyEst Gaussian Mixtures
 ---------------------------------------------------------------------
 

docs/image/univariate_split.png

@@ -0,0 +1,23 @@
+import pyest.gm as gm
+import matplotlib.pyplot as plt
+import numpy as np
+
+# find the optimal standard normal split solutions for different mixture
+# sizes and regularization parameter values
+L = 5
+lam = 1e-3
+p = gm.split_1d_standard_gaussian(L, lam)
+
+# we can now plot each of the mixands by using the iterable feature of GaussianMixture
+x = np.linspace(-4, 4, 100)
+fig, ax = plt.subplots()
+for wi, mi, Pi in p:
+    ax.plot(x, wi*gm.eval_mvnpdf(x[:, np.newaxis], mi, Pi), linestyle='--')
+
+# plot the GM approximation
+ax.plot(x, p(x[:, np.newaxis]), linestyle='-')
+ax.set_xlabel('x')
+ax.set_ylabel('p(x)')
+plt.show()
+# # save figure at high resolution with no extra whitespace
+# fig.savefig('univariate_split.png', dpi=400, bbox_inches='tight')