Adding readmes

Expanding examples and Schelling readme files.

README.rst

@@ -46,6 +46,8 @@ You can also use `pip` to install the github version:
 
     $ pip install git+https://github.com/projectmesa/mesa
 
+
+
 For more help on using Mesa, check out the following resources:
 
 * `Intro to Mesa Tutorial`_

examples/Readme.md

@@ -2,20 +2,31 @@
 
 This directory contains example models meant to test and demonstrate Mesa's features, and provide demonstrations for how to build and analyze agent-based models. For more information on each model, see its own Readme and documentation.
 
-### Schelling.py
-Simple implementation of the classic Schelling segregation model. 
+### ConwaysGameOfLife
 
-### WolfSheep
-Implementation of a simple ecological model of predation and reproduction.
-
-### ForestFire
-Simple cellular automata of a fire spreading through a forest of cells on a grid.
+Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life), a cellular automata where simple rules can give rise to complex patterns.
 
 ### EpsteinCivilViolence
 Joshua Epstein's [model](http://www.uvm.edu/~pdodds/files/papers/others/2002/epstein2002a.pdf) of how a decentralized uprising can be suppressed or reach a critical mass of support.
 
 ### Flockers
-Boids-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.
+[Boids](https://en.wikipedia.org/wiki/Boids)-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.
+
+### ForestFire
+Simple cellular automata of a fire spreading through a forest of cells on a grid, based on the NetLogo [Fire model](http://ccl.northwestern.edu/netlogo/models/Fire).
 
 ### PD_Grid
-Grid-based demographic prisoner's dilemma model, demonstrating how simple mimicing can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
+Grid-based demographic prisoner's dilemma model, demonstrating how simple mimicing can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
+
+### Schelling
+Mesa implementation of the classic [Schelling segregation model](http://nifty.stanford.edu/2014/mccown-schelling-model-segregation/). 
+
+### Tutorial-Boltzmann_Wealth_Model
+Completed code to go along with the [tutorial]() on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
+
+### WolfSheep
+Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation model](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation).
+
+
+
+

examples/Schelling/README.md

@@ -1,28 +1,39 @@
 # Schelling Segregation Model
 =========================================
-A simple implementation of a Schelling segregation model.
 
-To run this model in the browser:
-    `$ python run.py`
+## Summary
 
-To review the analysis in jupyter notebook:
-    `$ jupyter notebook`
+The Schelling segregation model is a classic agent-based model, demonstrating how even a mild preference for similar neighbors can lead to a much higher degree of segregation than we would intuitively expect. The model consists of agents on a square grid, where each grid cell can contain at most one agent. Agents come in two colors: red and blue. They are happy if a certain number of their eight possible neighbors are of the same color, and unhappy otherwise. Unhappy agents will pick a random empty cell to move to each step, until they are happy. The model keeps running until there are no unhappy agents.
 
+By default, the number of similar neighbors the agents need to be happy is set to 3. That means the agents would be perfectly happy with a majority of their neighbors being of a different color (e.g. a Blue agent would be happy with five Red neighbors and three Blue ones). Despite this, the model consistently leads to a high degree of segregation, with most agents ending up with no neighbors of a different color.
 
+## How to Run
 
+To run the model interactively, run ``run.py`` in this directory. e.g.
 
-TODO -- update text
+```
+    $ python run.py
+``` 
 
-This version demonstrates the ASCII renderer.
-To use, run this code from the command line, e.g.
-    `$ ipython -i Schelling.py`
+Then open your browser to [http://127.0.0.1:8888/](http://127.0.0.1:8888/) and press Reset, then Run.
 
-viz is the visualization wrapper around
-To print the current state of the model:
-    `viz.render()`
+To view and run some example model analyses, launch the IPython Notebook and open ``analysis.ipynb``. 
 
-To advance the model by one step and print the new state:
-    `viz.step()`
+## Files
 
-To advance the model by e.g. 10 steps and print the new state:
-    `viz.step_forward(10)`
+* ``run.py``: Launches a model visualization server.
+* ``model/world.py``: Contains the overall model class.
+* ``model/agents.py``: Contains the class that defines the model agents.
+* ``model/server.py``: Defines classes for visualizing the model, both as text and using the Mesa modular server.
+* ``analysis.ipybn``: Notebook demonstrating how to run experiments and parameter sweeps on the model.
+* ``requirements.txt``: Defines additional external requirements for running the model; in this case, it's just matplotlib, for the interactive analysis in the IPython Notebook.
+
+## Further Reading
+
+Schelling's original paper describing the model:
+
+[Schelling, Thomas C. Dynamic Models of Segregation. Journal of Mathematical Sociology. 1971, Vol. 1, pp 143-186.](https://www.stat.berkeley.edu/~aldous/157/Papers/Schelling_Seg_Models.pdf)
+
+An interactive, browser-based explanation and implementation:
+
+[Parable of the Polygons](http://ncase.me/polygons/), by Vi Hart and Nicky Case.