adding first example

adding try/except for linux test machine

removing png tracking, changing fig loc

.gitignore

@@ -5,6 +5,7 @@
 /.pydevproject
 /cost_models/fuga/pascal_test
 snopt
+*.png
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/source/conf.py

@@ -17,9 +17,6 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 
 
 # -- General configuration ------------------------------------------------
@@ -180,3 +177,5 @@ intersphinx_mapping = {
 'pandas': ('http://pandas-docs.github.io/pandas-docs-travis', None),
 'numpy': ('http://docs.scipy.org/doc/numpy-1.13.0', None)
 }
+
+figure_language_filename = 'examples/{basename}{ext}'

docs/source/dev_guide/quick_guide.rst

-.. _quick_guide:
-
-=======================
-Quick Reference
-=======================
-
-1. Do this first.  
-2. Then do this.  
-3. Lastly, this.

docs/source/examples.rst

-.. _examples:
-
-===========================
-Examples
-===========================
-
-Eventually we would like to have several TOPFARM examples here to demonstrate
-how you can use the code.

docs/source/examples/example_1_constrained_layout_optimization.rst

+.. Example 1
+
+Example 1: Constrained Layout Optimization
+===========================================
+
+This example demonstrates the optimization of a wind turbine layout that is
+subject to boundary constraints.
+
+Specifications
+--------------
+
+- The cost function is a dummy function that penalizes the turbines when they
+  are far away from pre-specified, desired positions.  
+- There is a boundary beyond which the turbines cannot go.  
+- The turbines cannot be closer than 2D.
+
+Results
+-------
+
+The optimization results are visualized in the figure below. The turbines'
+trajectories during the optimizations are shown by the colored lines.
+
+- All turbines that begin outside the boundary immediately jump inside the
+  boundary.  
+- Turbines 1 and 3 rotate around each other as they try to reach their
+  specified final locations but stay at least 2D away from each other.
+- Turbine 2 remains on the boundary but tries to minimize its distance to
+  its specified final location.  
+- Turbine 4 converges to its specified location.
+
+.. figure:: /../../examples/example_1_constrained_layout_optimization.png
+
+Code
+----
+
+.. literalinclude:: /../../examples/example_1_constrained_layout_optimization.py

docs/source/index.rst

@@ -10,13 +10,9 @@ Welcome to TOPFARM, the wind-farm optimizer
     :maxdepth: 2
 
     installation
-    examples
 
+.. toctree::
+    :caption: Examples
+    :maxdepth: 2
 
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    examples/example_1_constrained_layout_optimization

examples/example_1_constrained_layout_optimization.py

+"""Example: optimizing a layout with constraints
+
+This example uses a dummy cost function to optimize a simple wind turbine
+layout that is subject to constraints. The optimization pushes the wind turbine
+locations to specified locations in the farm.
+"""
+import os
+
+from matplotlib.patches import Polygon
+import matplotlib.pyplot as plt
+import numpy as np
+
+from topfarm import TopFarm
+from topfarm.cost_models.dummy import DummyCost
+
+
+# ------------------------ INPUTS ------------------------
+
+# define the conditions for the wind farm
+boundary = [(0, 0), (6, 0), (6, -10), (0, -10)]  # turbine boundaries
+initial = np.array([[6, 0], [6, -8], [1, 1], [-1, -8]])  # initial turbine pos
+desired = np.array([[3, -3], [7, -7], [4, -3], [3, -7]])  # desired turbine pos
+optimal = np.array([[2.5, -3], [6, -7], [4.5, -3], [3, -7]])  # optimal layout
+min_spacing = 2  # min distance between turbines
+
+# ------------------------ OPTIMIZATION ------------------------
+
+# create the wind farm and run the optimization
+tf = TopFarm(initial, DummyCost(desired, ['turbineX', 'turbineY']),
+             min_spacing, boundary=boundary, record_id=None)
+cost, state, recorder = tf.optimize()
+
+# get the positions tried during optimization from the recorder
+rec_x, rec_y = recorder.get('turbineX'), recorder.get('turbineY')
+
+# get the final, optimal positions
+optimized = tf.turbine_positions
+
+# ------------------------ PLOT (if possible) ------------------------
+
+try:
+
+    # initialize the figure and axes
+    fig = plt.figure(1, figsize=(7, 5))
+    plt.clf()
+    ax = plt.axes()
+
+    # plot the boundary and desired locations
+    ax.add_patch(Polygon(boundary, closed=True, fill=False,
+                         label='Boundary'))  # boundary
+    plt.plot(desired[:, 0], desired[:, 1], 'ok', mfc='None', ms=10,
+             label='Desired')  # desired positions
+
+    # plot the history of each turbine
+    for i_turb in range(rec_x.shape[1]):
+        l, = plt.plot(rec_x[0, i_turb], rec_y[0, i_turb],
+                      'x', ms=8, label=f'Turbine {i_turb+1}')  # initial
+        plt.plot(rec_x[:, i_turb], rec_y[:, i_turb],
+                 c=l.get_color())  # tested values
+        plt.plot(rec_x[-1, i_turb], rec_y[-1, i_turb],
+                 'o', ms=8, c=l.get_color())  # final
+
+    # make a few adjustments to the plot
+    ax.autoscale_view()  # autoscale the boundary
+    plt.legend(bbox_to_anchor=(0., 1.02, 1., .102), loc=3,
+               ncol=4, mode='expand', borderaxespad=0.)  # add a legend
+    plt.tight_layout()  # zoom the plot in
+    plt.axis('off')  # remove the axis
+
+    # save the png
+    fig.savefig(os.path.basename(__file__).replace('.py', '.png'))
+
+except RuntimeError:
+    pass

setup.cfg

+# add example_*.py files to those that pytest should test
+[tool:pytest]
+python_files = test_*.py *_test.py testing/*/*.py example_*.py
\ No newline at end of file