updates

Author: quaquel

docs/examples.md

@@ -3,12 +3,12 @@
 
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 
-<examples/boid_flockers>
-<examples/virus_on_network>
-<examples/conways_game_of_life>
-<examples/schelling>
-<examples/boltzmann_wealth_model>
+./examples/boid_flockers <examples/boid_flockers>
+./examples/virus_on_network <examples/virus_on_network>
+./examples/conways_game_of_life <examples/conways_game_of_life>
+./examples/schelling <examples/schelling>
+./examples/boltzmann_wealth_model <examples/boltzmann_wealth_model>
 
 ```

docs/examples/boid_flockers.md

@@ -0,0 +1,266 @@
+
+## Description
+# Boids Flockers
+
+## Summary
+
+An implementation of Craig Reynolds's Boids flocker model. Agents (simulated birds) try to fly towards the average position of their neighbors and in the same direction as them, while maintaining a minimum distance. This produces flocking behavior.
+
+This model tests Mesa's continuous space feature, and uses numpy arrays to represent vectors. It also demonstrates how to create custom visualization components.
+
+## Installation
+
+To install the dependencies use pip and the requirements.txt in this directory. e.g.
+
+```
+    $ pip install -r requirements.txt
+```
+
+## How to Run
+
+* To launch the visualization interactively, run ``mesa runserver`` in this directory. e.g.
+
+```
+$ mesa runserver
+```
+
+or
+
+Directly run the file ``run.py`` in the terminal. e.g.
+
+```
+    $ python run.py
+```
+
+* Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.
+
+## Files
+
+* [model.py](model.py): Core model file; contains the Boid Model and Boid Agent class.
+* [app.py](app.py): Visualization code.
+
+## Further Reading
+
+The following link can be visited for more information on the boid flockers model:
+https://cs.stanford.edu/people/eroberts/courses/soco/projects/2008-09/modeling-natural-systems/boids.html
+
+
+## Agents
+
+```python
+import numpy as np
+
+from mesa import Agent
+
+
+class Boid(Agent):
+    """A Boid-style flocker agent.
+
+    The agent follows three behaviors to flock:
+        - Cohesion: steering towards neighboring agents.
+        - Separation: avoiding getting too close to any other agent.
+        - Alignment: try to fly in the same direction as the neighbors.
+
+    Boids have a vision that defines the radius in which they look for their
+    neighbors to flock with. Their speed (a scalar) and direction (a vector)
+    define their movement. Separation is their desired minimum distance from
+    any other Boid.
+    """
+
+    def __init__(
+        self,
+        model,
+        speed,
+        direction,
+        vision,
+        separation,
+        cohere=0.03,
+        separate=0.015,
+        match=0.05,
+    ):
+        """Create a new Boid flocker agent.
+
+        Args:
+            speed: Distance to move per step.
+            direction: numpy vector for the Boid's direction of movement.
+            vision: Radius to look around for nearby Boids.
+            separation: Minimum distance to maintain from other Boids.
+            cohere: the relative importance of matching neighbors' positions
+            separate: the relative importance of avoiding close neighbors
+            match: the relative importance of matching neighbors' headings
+        """
+        super().__init__(model)
+        self.speed = speed
+        self.direction = direction
+        self.vision = vision
+        self.separation = separation
+        self.cohere_factor = cohere
+        self.separate_factor = separate
+        self.match_factor = match
+        self.neighbors = None
+
+    def step(self):
+        """Get the Boid's neighbors, compute the new vector, and move accordingly."""
+        self.neighbors = self.model.space.get_neighbors(self.pos, self.vision, False)
+        n = 0
+        match_vector, separation_vector, cohere = np.zeros((3, 2))
+        for neighbor in self.neighbors:
+            n += 1
+            heading = self.model.space.get_heading(self.pos, neighbor.pos)
+            cohere += heading
+            if self.model.space.get_distance(self.pos, neighbor.pos) < self.separation:
+                separation_vector -= heading
+            match_vector += neighbor.direction
+        n = max(n, 1)
+        cohere = cohere * self.cohere_factor
+        separation_vector = separation_vector * self.separate_factor
+        match_vector = match_vector * self.match_factor
+        self.direction += (cohere + separation_vector + match_vector) / n
+        self.direction /= np.linalg.norm(self.direction)
+        new_pos = self.pos + self.direction * self.speed
+        self.model.space.move_agent(self, new_pos)
+
+```
+
+
+## Model
+
+```python
+"""Flockers.
+=============================================================
+A Mesa implementation of Craig Reynolds's Boids flocker model.
+Uses numpy arrays to represent vectors.
+"""
+
+import numpy as np
+
+import mesa
+
+from .agents import Boid
+
+
+class BoidFlockers(mesa.Model):
+    """Flocker model class. Handles agent creation, placement and scheduling."""
+
+    def __init__(
+        self,
+        seed=None,
+        population=100,
+        width=100,
+        height=100,
+        vision=10,
+        speed=1,
+        separation=1,
+        cohere=0.03,
+        separate=0.015,
+        match=0.05,
+    ):
+        """Create a new Flockers model.
+
+        Args:
+            population: Number of Boids
+            width, height: Size of the space.
+            speed: How fast should the Boids move.
+            vision: How far around should each Boid look for its neighbors
+            separation: What's the minimum distance each Boid will attempt to
+                    keep from any other
+            cohere, separate, match: factors for the relative importance of
+                    the three drives.
+        """
+        super().__init__(seed=seed)
+        self.population = population
+        self.vision = vision
+        self.speed = speed
+        self.separation = separation
+
+        self.space = mesa.space.ContinuousSpace(width, height, True)
+        self.factors = {"cohere": cohere, "separate": separate, "match": match}
+        self.make_agents()
+
+    def make_agents(self):
+        """Create self.population agents, with random positions and starting headings."""
+        for _ in range(self.population):
+            x = self.random.random() * self.space.x_max
+            y = self.random.random() * self.space.y_max
+            pos = np.array((x, y))
+            direction = np.random.random(2) * 2 - 1
+            boid = Boid(
+                model=self,
+                speed=self.speed,
+                direction=direction,
+                vision=self.vision,
+                separation=self.separation,
+                **self.factors,
+            )
+            self.space.place_agent(boid, pos)
+
+    def step(self):
+        self.agents.shuffle_do("step")
+
+```
+
+
+## App
+
+```python
+from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
+
+from .model import BoidFlockers
+
+
+def boid_draw(agent):
+    if not agent.neighbors:  # Only for the first Frame
+        neighbors = len(agent.model.space.get_neighbors(agent.pos, agent.vision, False))
+    else:
+        neighbors = len(agent.neighbors)
+
+    if neighbors <= 1:
+        return {"color": "red", "size": 20}
+    elif neighbors >= 2:
+        return {"color": "green", "size": 20}
+
+
+model_params = {
+    "population": Slider(
+        label="Number of boids",
+        value=100,
+        min=10,
+        max=200,
+        step=10,
+    ),
+    "width": 100,
+    "height": 100,
+    "speed": Slider(
+        label="Speed of Boids",
+        value=5,
+        min=1,
+        max=20,
+        step=1,
+    ),
+    "vision": Slider(
+        label="Vision of Bird (radius)",
+        value=10,
+        min=1,
+        max=50,
+        step=1,
+    ),
+    "separation": Slider(
+        label="Minimum Separation",
+        value=2,
+        min=1,
+        max=20,
+        step=1,
+    ),
+}
+
+model = BoidFlockers()
+
+page = SolaraViz(
+    model,
+    [make_space_matplotlib(agent_portrayal=boid_draw)],
+    model_params=model_params,
+    name="Boid Flocking Model",
+)
+page  # noqa
+
+```