Create a simple cookiecutter for new mesa projects

closes projectmesa#521
closes projectmesa#520

Update the mesa cli
    - rename `mesa run` to `mesa runserver`
    - add `mesa startproject` to bootstrap a new project

docs/best-practices.rst

@@ -12,9 +12,6 @@ underscores, such as ``thunder_cats``. Within that directory:
 * ``README.md`` describes the model, how to use it, and any other details.
   Github will automatically show this file to anyone visiting the directory.
 
-* ``requirements.txt`` contains any additional Python distributions, beyond
-  Mesa itself, required to run the model.
-
 * ``model.py`` should contain the model class.  If the file gets large, it may
   make sense to move the complex bits into other files, but this is the first
   place readers will look to figure out how the model works.
@@ -23,7 +20,7 @@ underscores, such as ``thunder_cats``. Within that directory:
   class.
 
 * ``run.py`` is a Python script that will run the model when invoked via
-  ``mesa run``.
+  ``mesa runserver``.
 
 After the number of files grows beyond a half-dozen, try to use sub-folders to
 organize them. For example, if the visualization uses image files, put those in
@@ -33,6 +30,8 @@ The `Schelling
 <https://github.com/projectmesa/mesa/tree/master/examples/Schelling>`_ model is
 a good example of a small well-packaged model.
 
+It's easy to create a cookiecutter mesa model by running ``mesa startproject``
+
 Randomization
 -------------
 

docs/index.rst

@@ -40,11 +40,11 @@ Getting started quickly:
 
     $ pip install mesa
 
-To launch an example model, clone the `repository <https://github.com/projectmesa/mesa>`_ folder and invoke ``mesa run`` for one of the ``examples/`` subdirectories:
+To launch an example model, clone the `repository <https://github.com/projectmesa/mesa>`_ folder and invoke ``mesa runserver`` for one of the ``examples/`` subdirectories:
 
 .. code-block:: bash
 
-    schelling $ mesa run examples/wolf_sheep
+    schelling $ mesa runserver examples/wolf_sheep
 
 For more help on using Mesa, check out the following resources:
 

docs/overview.rst

@@ -1,13 +1,13 @@
 Mesa Overview
-=========================================
+=============
 
 Mesa is a modular framework for building, analyzing and visualizing agent-based models.
 
 **Agent-based models** are computer simulations involving multiple entities (the agents) acting and interacting with one another based on their programmed behavior. Agents can be used to represent living cells, animals, individual humans, even entire organizations or abstract entities. Sometimes, we may have an understanding of how the individual components of a system behave, and want to see what system-level behaviors and effects emerge from their interaction. Other times, we may have a good idea of how the system overall behaves, and want to figure out what individual behaviors explain it. Or we may want to see how to get agents to cooperate or compete most effectively. Or we may just want to build a cool toy with colorful little dots moving around.
 
 
 Mesa Modules
--------------------
+------------
 
 Mesa is modular, meaning that its modeling, analysis and visualization components are kept separate but intended to work together. The modules are grouped into three categories:
 
@@ -64,6 +64,7 @@ If you instantiate a model and run it for one step, like so:
 
 You should see agents 0-4, activated in random order. See the `tutorial <tutorials/intro_tutorial.html>`_ or API documentation for more detail on how to add model functionality.
 
+To bootstrap a new model install mesa and run ``mesa startproject``
 
 Analysis modules
 ~~~~~~~~~~~~~~~~

examples/Schelling/README.md

@@ -16,10 +16,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/bank_reserves/Readme.md

@@ -22,10 +22,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## Interactive Model Run
 
-To run the model interactively, use `mesa run` in this directory:
+To run the model interactively, use `mesa runserver` in this directory:
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/), select the model parameters, press Reset, then Start.

examples/boid-flockers/Readme.md

@@ -28,7 +28,7 @@ Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and p
 =======
 * Launch the visualization
 ```
-$ mesa run
+$ mesa runserver
 ```
 * Visit your browser: http://127.0.0.1:8521/
 * In your browser hit *run*

examples/boltzmann_wealth_model_network/README.md

@@ -22,10 +22,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/color_patches/Readme.md

@@ -18,10 +18,10 @@ An agent's state represents its "opinion" and is shown by the color of the cell
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ``` 
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run. 

examples/conways_game_of_life/Readme.md

@@ -9,10 +9,10 @@ The "game" is a zero-player game, meaning that its evolution is determined by it
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ``` 
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press ``run``. 

examples/forest_fire/readme.md

@@ -6,10 +6,10 @@ The [forest fire model](http://en.wikipedia.org/wiki/Forest-fire_model) is a sim
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run. 

examples/hex_snowflake/Readme.md

@@ -7,10 +7,10 @@ In this model, each dead cell will become alive if it has exactly one neighbor.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press ``run``.

examples/pd_grid/readme.md

@@ -19,7 +19,7 @@ The Demographic Prisoner's Dilemma demonstrates how simple rules can lead to the
 
 ##### Web based model simulation
 
-To run the model interactively, run ``mesa run`` in this directory.
+To run the model interactively, run ``mesa runserver`` in this directory.
 
 ##### Jupyter Notebook
 

examples/shape_example/Readme.md

@@ -25,10 +25,10 @@ e.g.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and

examples/sugarscape_cg/Readme.md

@@ -33,10 +33,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/virus_on_network/README.md

@@ -18,10 +18,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

examples/wolf_sheep/Readme.md

@@ -24,10 +24,10 @@ To install the dependencies use pip and the requirements.txt in this directory.
 
 ## How to Run
 
-To run the model interactively, run ``mesa run`` in this directory. e.g.
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
 
 ```
-    $ mesa run
+    $ mesa runserver
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.

mesa/cookiecutter-mesa/cookiecutter.json

@@ -0,0 +1,8 @@
+{
+    "project": "Example Project",
+    "snake": "{{ cookiecutter.project.lower().replace(' ', '_') }}",
+    "camel": "{{ cookiecutter.project.title().replace(' ', '') }}",
+    "agent": "{{ cookiecutter.camel + 'Agent'}}",
+    "model": "{{ cookiecutter.camel + 'Model'}}",
+    "description": "Example short description of the project"
+}

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/README.md

@@ -0,0 +1,4 @@
+{{cookiecutter.project}}
+========================
+
+{{cookiecutter.description}}

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/run.py

@@ -0,0 +1,3 @@
+from {{cookiecutter.snake}}.server import server  # noqa
+
+server.launch()

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/setup.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from setuptools import setup, find_packages
+
+requires = [
+    'mesa'
+]
+
+setup(
+    name='{{cookiecutter.snake}}',
+    version='0.0.1',
+    packages=find_packages(),
+    install_requires=requires
+)

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/{{cookiecutter.snake}}/model.py

@@ -0,0 +1,65 @@
+import random
+
+from mesa import Agent, Model
+from mesa.time import RandomActivation
+from mesa.space import MultiGrid
+from mesa.datacollection import DataCollector
+
+
+class {{cookiecutter.agent}}(Agent):  # noqa
+    """
+    An agent
+    """
+
+    def __init__(self, unique_id, model):
+        """
+        Customize the agent
+        """
+        self.unique_id = unique_id
+        super().__init__(unique_id, model)
+
+    def step(self):
+        """
+        Modify this method to change what an individual agent will do during each step.
+        Can include logic based on neighbors states.
+        """
+        pass
+
+
+class {{cookiecutter.model}}(Model):
+    """
+    The model class holds the model-level attributes, manages the agents, and generally handles
+    the global level of our model.
+
+    There is only one model-level parameter: how many agents the model contains. When a new model
+    is started, we want it to populate itself with the given number of agents.
+
+    The scheduler is a special model component which controls the order in which agents are activated.
+    """
+
+    def __init__(self, num_agents, width, height):
+        super().__init__()
+        self.num_agents = num_agents
+        self.schedule = RandomActivation(self)
+        self.grid = MultiGrid(width=width, height=height, torus=True)
+
+        for i in range(self.num_agents):
+            agent = {{cookiecutter.agent}}(i, self)
+            self.schedule.add(agent)
+
+            x = random.randrange(self.grid.width)
+            y = random.randrange(self.grid.height)
+            self.grid.place_agent(agent, (x, y))
+
+        # example data collector
+        self.datacollector = DataCollector()
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def step(self):
+        """
+        A model step. Used for collecting data and advancing the schedule
+        """
+        self.datacollector.collect(self)
+        self.schedule.step()

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/{{cookiecutter.snake}}/server.py

@@ -0,0 +1,31 @@
+"""
+Configure visualization elements and instantiate a server
+"""
+
+from .model import {{ cookiecutter.model }}, {{ cookiecutter.agent }}  # noqa
+
+from mesa.visualization.ModularVisualization import ModularServer
+from mesa.visualization.modules import CanvasGrid, ChartModule
+
+
+def circle_portrayal_example(agent):
+    if agent is None:
+        return
+
+    portrayal = {"Shape": "circle",
+                 "Filled": "true",
+                 "Layer": 0,
+                 "r": 0.5,
+                 "Color": "Pink"}
+    return portrayal
+
+
+canvas_element = CanvasGrid(circle_portrayal_example, 20, 20, 500, 500)
+chart_element = ChartModule([{"Label": "{{ cookiecutter.camel }}", "Color": "Pink"}])
+
+model_kwargs = {"num_agents": 10,
+                "width": 10,
+                "height": 10}
+
+server = ModularServer({{ cookiecutter.model }}, [canvas_element, chart_element],  # noqa
+                       "{{ cookiecutter.camel }}", model_kwargs)