Add advanced example models

Author: EwoutH

examples/advanced/epstein_civil_violence/Epstein Civil Violence.ipynb

@@ -0,0 +1,33 @@
+# Epstein Civil Violence Model
+
+## Summary
+
+This model is based on Joshua Epstein's simulation of how civil unrest grows and is suppressed. Citizen agents wander the grid randomly, and are endowed with individual risk aversion and hardship levels; there is also a universal regime legitimacy value. There are also Cop agents, who work on behalf of the regime. Cops arrest Citizens who are actively rebelling; Citizens decide whether to rebel based on their hardship and the regime legitimacy, and their perceived probability of arrest.
+
+The model generates mass uprising as self-reinforcing processes: if enough agents are rebelling, the probability of any individual agent being arrested is reduced, making more agents more likely to join the uprising. However, the more rebelling Citizens the Cops arrest, the less likely additional agents become to join.
+
+## How to Run
+
+To run the model interactively, run ``EpsteinCivilViolenceServer.py`` in this directory. e.g.
+
+```
+    $ python EpsteinCivilViolenceServer.py
+```
+
+Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.
+
+## Files
+
+* ``EpsteinCivilViolence.py``: Core model and agent code.
+* ``EpsteinCivilViolenceServer.py``: Sets up the interactive visualization.
+* ``Epstein Civil Violence.ipynb``: Jupyter notebook conducting some preliminary analysis of the model.
+
+## Further Reading
+
+This model is based adapted from:
+
+[Epstein, J. “Modeling civil violence: An agent-based computational approach”, Proceedings of the National Academy of Sciences, Vol. 99, Suppl. 3, May 14, 2002](http://www.pnas.org/content/99/suppl.3/7243.short)
+
+A similar model is also included with NetLogo:
+
+Wilensky, U. (2004). NetLogo Rebellion model. http://ccl.northwestern.edu/netlogo/models/Rebellion. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.

examples/advanced/epstein_civil_violence/Readme.md

@@ -0,0 +1,158 @@
+import math
+
+import mesa
+
+
+class EpsteinAgent(mesa.experimental.cell_space.CellAgent):
+    def update_neighbors(self):
+        """
+        Look around and see who my neighbors are
+        """
+        self.neighborhood = self.cell.get_neighborhood(radius=self.vision)
+
+        self.neighbors = self.neighborhood.agents
+        self.empty_neighbors = [c for c in self.neighborhood if c.is_empty]
+
+
+class Citizen(EpsteinAgent):
+    """
+    A member of the general population, may or may not be in active rebellion.
+    Summary of rule: If grievance - risk > threshold, rebel.
+
+    Attributes:
+        hardship: Agent's 'perceived hardship (i.e., physical or economic
+            privation).' Exogenous, drawn from U(0,1).
+        regime_legitimacy: Agent's perception of regime legitimacy, equal
+            across agents.  Exogenous.
+        risk_aversion: Exogenous, drawn from U(0,1).
+        threshold: if (grievance - (risk_aversion * arrest_probability)) >
+            threshold, go/remain Active
+        vision: number of cells in each direction (N, S, E and W) that agent
+            can inspect
+        condition: Can be "Quiescent" or "Active;" deterministic function of
+            greivance, perceived risk, and
+        grievance: deterministic function of hardship and regime_legitimacy;
+            how aggrieved is agent at the regime?
+        arrest_probability: agent's assessment of arrest probability, given
+            rebellion
+    """
+
+    def __init__(
+        self,
+        model,
+        hardship,
+        regime_legitimacy,
+        risk_aversion,
+        threshold,
+        vision,
+    ):
+        """
+        Create a new Citizen.
+        Args:
+            model: the model to which the agent belongs
+            hardship: Agent's 'perceived hardship (i.e., physical or economic
+                privation).' Exogenous, drawn from U(0,1).
+            regime_legitimacy: Agent's perception of regime legitimacy, equal
+                across agents.  Exogenous.
+            risk_aversion: Exogenous, drawn from U(0,1).
+            threshold: if (grievance - (risk_aversion * arrest_probability)) >
+                threshold, go/remain Active
+            vision: number of cells in each direction (N, S, E and W) that
+                agent can inspect. Exogenous.
+            model: model instance
+        """
+        super().__init__(model)
+        self.hardship = hardship
+        self.regime_legitimacy = regime_legitimacy
+        self.risk_aversion = risk_aversion
+        self.threshold = threshold
+        self.condition = "Quiescent"
+        self.vision = vision
+        self.jail_sentence = 0
+        self.grievance = self.hardship * (1 - self.regime_legitimacy)
+        self.arrest_probability = None
+
+    def step(self):
+        """
+        Decide whether to activate, then move if applicable.
+        """
+        if self.jail_sentence:
+            self.jail_sentence -= 1
+            return  # no other changes or movements if agent is in jail.
+        self.update_neighbors()
+        self.update_estimated_arrest_probability()
+        net_risk = self.risk_aversion * self.arrest_probability
+        if self.grievance - net_risk > self.threshold:
+            self.condition = "Active"
+        else:
+            self.condition = "Quiescent"
+
+        if self.model.movement and self.empty_neighbors:
+            new_cell = self.random.choice(self.empty_neighbors)
+            self.move_to(new_cell)
+
+    def update_estimated_arrest_probability(self):
+        """
+        Based on the ratio of cops to actives in my neighborhood, estimate the
+        p(Arrest | I go active).
+        """
+        cops_in_vision = len([c for c in self.neighbors if isinstance(c, Cop)])
+        actives_in_vision = 1.0  # citizen counts herself
+        for c in self.neighbors:
+            if (
+                isinstance(c, Citizen)
+                and c.condition == "Active"
+                and c.jail_sentence == 0
+            ):
+                actives_in_vision += 1
+        self.arrest_probability = 1 - math.exp(
+            -1 * self.model.arrest_prob_constant * (cops_in_vision / actives_in_vision)
+        )
+
+
+class Cop(EpsteinAgent):
+    """
+    A cop for life.  No defection.
+    Summary of rule: Inspect local vision and arrest a random active agent.
+
+    Attributes:
+        unique_id: unique int
+        x, y: Grid coordinates
+        vision: number of cells in each direction (N, S, E and W) that cop is
+            able to inspect
+    """
+
+    def __init__(self, model, vision):
+        """
+        Create a new Cop.
+        Args:
+            x, y: Grid coordinates
+            vision: number of cells in each direction (N, S, E and W) that
+                agent can inspect. Exogenous.
+            model: model instance
+        """
+        super().__init__(model)
+        self.vision = vision
+
+    def step(self):
+        """
+        Inspect local vision and arrest a random active agent. Move if
+        applicable.
+        """
+        self.update_neighbors()
+        active_neighbors = []
+        for agent in self.neighbors:
+            if (
+                isinstance(agent, Citizen)
+                and agent.condition == "Active"
+                and agent.jail_sentence == 0
+            ):
+                active_neighbors.append(agent)
+        if active_neighbors:
+            arrestee = self.random.choice(active_neighbors)
+            sentence = self.random.randint(0, self.model.max_jail_term)
+            arrestee.jail_sentence = sentence
+            arrestee.condition = "Quiescent"
+        if self.model.movement and self.empty_neighbors:
+            new_pos = self.random.choice(self.empty_neighbors)
+            self.move_to(new_pos)

examples/advanced/epstein_civil_violence/epstein_civil_violence/__init__.py

@@ -0,0 +1,146 @@
+import mesa
+
+from .agent import Citizen, Cop
+
+
+class EpsteinCivilViolence(mesa.Model):
+    """
+    Model 1 from "Modeling civil violence: An agent-based computational
+    approach," by Joshua Epstein.
+    http://www.pnas.org/content/99/suppl_3/7243.full
+    Attributes:
+        height: grid height
+        width: grid width
+        citizen_density: approximate % of cells occupied by citizens.
+        cop_density: approximate % of cells occupied by cops.
+        citizen_vision: number of cells in each direction (N, S, E and W) that
+            citizen can inspect
+        cop_vision: number of cells in each direction (N, S, E and W) that cop
+            can inspect
+        legitimacy:  (L) citizens' perception of regime legitimacy, equal
+            across all citizens
+        max_jail_term: (J_max)
+        active_threshold: if (grievance - (risk_aversion * arrest_probability))
+            > threshold, citizen rebels
+        arrest_prob_constant: set to ensure agents make plausible arrest
+            probability estimates
+        movement: binary, whether agents try to move at step end
+        max_iters: model may not have a natural stopping point, so we set a
+            max.
+    """
+
+    def __init__(
+        self,
+        width=40,
+        height=40,
+        citizen_density=0.7,
+        cop_density=0.074,
+        citizen_vision=7,
+        cop_vision=7,
+        legitimacy=0.8,
+        max_jail_term=1000,
+        active_threshold=0.1,
+        arrest_prob_constant=2.3,
+        movement=True,
+        max_iters=1000,
+    ):
+        super().__init__()
+        self.width = width
+        self.height = height
+        self.citizen_density = citizen_density
+        self.cop_density = cop_density
+        self.citizen_vision = citizen_vision
+        self.cop_vision = cop_vision
+        self.legitimacy = legitimacy
+        self.max_jail_term = max_jail_term
+        self.active_threshold = active_threshold
+        self.arrest_prob_constant = arrest_prob_constant
+        self.movement = movement
+        self.max_iters = max_iters
+        self.iteration = 0
+
+        self.grid = mesa.experimental.cell_space.OrthogonalMooreGrid(
+            (width, height), capacity=1, torus=True
+        )
+
+        model_reporters = {
+            "Quiescent": lambda m: self.count_type_citizens(m, "Quiescent"),
+            "Active": lambda m: self.count_type_citizens(m, "Active"),
+            "Jailed": self.count_jailed,
+            "Cops": self.count_cops,
+        }
+        agent_reporters = {
+            "x": lambda a: a.cell.coordinate[0],
+            "y": lambda a: a.cell.coordinate[1],
+            "breed": lambda a: type(a).__name__,
+            "jail_sentence": lambda a: getattr(a, "jail_sentence", None),
+            "condition": lambda a: getattr(a, "condition", None),
+            "arrest_probability": lambda a: getattr(a, "arrest_probability", None),
+        }
+        self.datacollector = mesa.DataCollector(
+            model_reporters=model_reporters, agent_reporters=agent_reporters
+        )
+        if self.cop_density + self.citizen_density > 1:
+            raise ValueError("Cop density + citizen density must be less than 1")
+
+        for cell in self.grid.all_cells:
+            if self.random.random() < self.cop_density:
+                cop = Cop(self, vision=self.cop_vision)
+                cop.move_to(cell)
+
+            elif self.random.random() < (self.cop_density + self.citizen_density):
+                citizen = Citizen(
+                    self,
+                    hardship=self.random.random(),
+                    regime_legitimacy=self.legitimacy,
+                    risk_aversion=self.random.random(),
+                    threshold=self.active_threshold,
+                    vision=self.citizen_vision,
+                )
+                citizen.move_to(cell)
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def step(self):
+        """
+        Advance the model by one step and collect data.
+        """
+        self.agents.shuffle_do("step")
+        # collect data
+        self.datacollector.collect(self)
+        self.iteration += 1
+        if self.iteration > self.max_iters:
+            self.running = False
+
+    @staticmethod
+    def count_type_citizens(model, condition, exclude_jailed=True):
+        """
+        Helper method to count agents by Quiescent/Active.
+        """
+        citizens = model.agents_by_type[Citizen]
+
+        if exclude_jailed:
+            return len(
+                [
+                    c
+                    for c in citizens
+                    if (c.condition == condition) and (c.jail_sentence == 0)
+                ]
+            )
+        else:
+            return len([c for c in citizens if c.condition == condition])
+
+    @staticmethod
+    def count_jailed(model):
+        """
+        Helper method to count jailed agents.
+        """
+        return len([a for a in model.agents_by_type[Citizen] if a.jail_sentence > 0])
+
+    @staticmethod
+    def count_cops(model):
+        """
+        Helper method to count jailed agents.
+        """
+        return len(model.agents_by_type[Cop])

examples/advanced/epstein_civil_violence/epstein_civil_violence/agent.py

@@ -0,0 +1,33 @@
+from .agent import Citizen, Cop
+
+COP_COLOR = "#000000"
+AGENT_QUIET_COLOR = "#0066CC"
+AGENT_REBEL_COLOR = "#CC0000"
+JAIL_COLOR = "#757575"
+
+
+def citizen_cop_portrayal(agent):
+    if agent is None:
+        return
+
+    portrayal = {
+        "Shape": "circle",
+        "x": agent.pos[0],
+        "y": agent.pos[1],
+        "Filled": "true",
+    }
+
+    if isinstance(agent, Citizen):
+        color = (
+            AGENT_QUIET_COLOR if agent.condition == "Quiescent" else AGENT_REBEL_COLOR
+        )
+        color = JAIL_COLOR if agent.jail_sentence else color
+        portrayal["Color"] = color
+        portrayal["r"] = 0.8
+        portrayal["Layer"] = 0
+
+    elif isinstance(agent, Cop):
+        portrayal["Color"] = COP_COLOR
+        portrayal["r"] = 0.5
+        portrayal["Layer"] = 1
+    return portrayal