Add basic tutorial to docs (#7)

* Clean up (and rename) examples code and output files

docs/source/examples/hoburgabbeel_ex6_1.py → docs/source/examples/ex1.py

@@ -1,13 +1,13 @@
-"Fits an example function"
-from numpy import logspace, log, log10, random
+"""Example 6.1 from Hoburg et al."""
+import numpy as np
 from gpfit.fit import MaxAffine, SoftmaxAffine, ImplicitSoftmaxAffine
 
-random.seed(33404)
+np.random.seed(33404)
 
-u = logspace(0, log10(3), 101)
+u = np.logspace(0, np.log10(3), 101)
 w = (u**2 + 3)/(u + 1)**2
-x = log(u)
-y = log(w)
+x = np.log(u)
+y = np.log(w)
 K = 3
 
 fma = MaxAffine(x, y, K, verbosity=1)

docs/source/examples/hoburgabbeel_ex6_3.py → docs/source/examples/ex2.py

@@ -1,14 +1,15 @@
-"Example 6.3 from Hoburg/Abbeel GPfit paper"
+"""Example 6.3 from Hoburg et al."""
 import numpy as np
-from numpy.random import seed, random_sample
 from gpfit.fit import MaxAffine, SoftmaxAffine, ImplicitSoftmaxAffine
 
-seed(33404)
+np.random.seed(33404)
 
-Vdd = random_sample(1000) + 1
-Vth = 0.2*random_sample(1000) + 0.2
+Vdd = np.random.random_sample(1000) + 1
+Vth = 0.2*np.random.random_sample(1000) + 0.2
 P = Vdd**2 + 30*Vdd*np.exp(-(Vth - 0.06*Vdd)/0.039)
+
 u = np.vstack((Vdd, Vth))
+w = P
 x = np.log(u)
 y = np.log(P)
 K = 4

docs/source/index.rst

@@ -17,7 +17,7 @@ Table of Contents
 
        gpfit101
        installation
-       examples
+       tutorial
        reference
        citinggpfit
        acknowledgements

docs/source/tutorial.rst

@@ -0,0 +1,56 @@
+Tutorial
+********
+
+Given log-transformed data `x` and `y`, we can create a fit with `K` terms with
+a single command:
+
+.. code::
+
+   f = ImplicitSoftmaxAffine(x, y, K)
+
+We can then plot it:
+
+.. code::
+
+   f, ax = f.plot() # for 1D fits
+   f, ax = f.plot_slices() # for 2D fits
+   f, ax = f.plot_surface() # for 2D fits
+
+and save it:
+
+.. code::
+
+   f.savetxt(filename="fit.txt") # saves string of fit to text file
+   f.save(filename="fit.pkl") # saves fit object to pickle file
+
+We can even generate a GPkit constraint set:
+
+.. code::
+
+   fcs = f.constraint_set()
+
+
+Examples
+========
+Both examples come from Section 6 of this `paper
+<https://dspace.mit.edu/bitstream/handle/1721.1/105753/11081_2016_9332_ReferencePDF.pdf?sequence=2&isAllowed=y>`_.
+
+Example 1
+---------
+
+Fit convex portion of :math:`w = \frac{u^2 + 3}{(u+1)^2}` on :math:`1 \leq u \leq 3`.
+
+.. literalinclude:: examples/ex1.py
+
+Output:
+
+.. literalinclude:: examples/ex1_output.txt
+
+Example 2
+---------
+
+.. literalinclude:: examples/ex2.py
+
+Output:
+
+.. literalinclude:: examples/ex2_output.txt

gpfit/tests/t_examples.py

@@ -28,14 +28,14 @@ def test_dummy_example(self, example):
               self.assertAlmostEqual(example.sol["cost"], 3.121)
     """
 
-    def test_hoburgabbeel_ex6_1(self, example):
-        """test_hoburgabbeel_ex6_1"""
+    def test_ex1(self, example):
+        """test_ex1"""
         self.assertTrue(example.fma.error["rms"] < 1e-2)
         self.assertTrue(example.fsma.error["rms"] < 1e-4)
         self.assertTrue(example.fisma.error["rms"] < 1e-5)
 
-    def test_hoburgabbeel_ex6_3(self, example):
-        """test_hoburgabbeel_ex6_3"""
+    def test_ex2(self, example):
+        """test_ex2"""
         self.assertTrue(example.fma.error["rms"] < 1e-2)
         self.assertTrue(example.fsma.error["rms"] < 1e-3)
         self.assertTrue(example.fisma.error["rms"] < 1e-3)