simulatingrisk 1.0.0__py3-none-any.whl

simulatingrisk/hawkdove/model.py

@@ -0,0 +1,391 @@
+from enum import Enum
+from collections import deque
+import math
+import statistics
+
+import mesa
+
+from simulatingrisk.utils import coinflip
+
+Play = Enum("Play", ["HAWK", "DOVE"])
+play_choices = [Play.HAWK, Play.DOVE]
+
+
+# divergent color scheme, ten colors
+# from https://colorbrewer2.org/?type=diverging&scheme=RdYlGn&n=10
+divergent_colors_10 = [
+    "#a50026",
+    "#d73027",
+    "#f46d43",
+    "#fdae61",
+    "#fee08b",
+    "#d9ef8b",
+    "#a6d96a",
+    "#66bd63",
+    "#1a9850",
+    "#006837",
+]
+
+# divergent color scheme, five colors
+# from https://colorbrewer2.org/?type=diverging&scheme=RdYlGn&n=5
+divergent_colors_5 = ["#d7191c", "#fdae61", "#ffffbf", "#a6d96a", "#1a9641"]
+
+
+class HawkDoveAgent(mesa.Agent):
+    """
+    An agent with a risk attitude playing Hawk or Dove
+    """
+
+    def __init__(self, unique_id, model, hawk_odds=None):
+        super().__init__(unique_id, model)
+
+        self.points = 0
+        self.choice = self.initial_choice(hawk_odds)
+        self.last_choice = None
+
+        # risk level must be set by base class, since initial
+        # conditions are specific to single / variable risk games
+        self.set_risk_level()
+
+    def set_risk_level(self):
+        raise NotImplementedError
+
+    def __repr__(self):
+        return (
+            f"<{self.__class__.__name__} id={self.unique_id} "
+            + f"r={self.risk_level} points={self.points}>"
+        )
+
+    def initial_choice(self, hawk_odds=None):
+        # first round : choose what to play randomly or based on initial hawk odds
+        opts = {}
+        if hawk_odds is not None:
+            opts["weight"] = hawk_odds
+        return coinflip(play_choices, **opts)
+
+    @property
+    def choice_label(self):
+        return "hawk" if self.choice == Play.HAWK else "dove"
+
+    def get_neighbors(self, size):
+        """get all neighbors for a supported neighborhood size"""
+        check_neighborhood_size(size)
+        # 4 and 8 neighborhood use default radius 1
+        # 8 and 24 both use moore neighborhood (includes diagonals)
+        opts = {"moore": True}
+        if size == 4:
+            # use von neumann neighborhood instead of moore (no diagonal)
+            opts["moore"] = False
+
+        # for 24 size neighborhood, use radius 2
+        if size == 24:
+            opts["radius"] = 2
+
+        return self.model.grid.get_neighbors(self.pos, include_center=False, **opts)
+
+    @property
+    def play_neighbors(self):
+        """neighbors to play against, based on model play neighborhood size"""
+        return self.get_neighbors(self.model.play_neighborhood)
+
+    @property
+    def observed_neighbors(self):
+        """neighbors to look at when deciding what to play;
+        based on model observed neighborhood size"""
+        return self.get_neighbors(self.model.observed_neighborhood)
+
+    @property
+    def num_dove_neighbors(self):
+        """count how many neighbors played DOVE on the last round
+        (uses `observed_neighborhood` size from model)"""
+        return len([n for n in self.observed_neighbors if n.last_choice == Play.DOVE])
+
+    @property
+    def proportional_num_dove_neighbors(self):
+        """adjust the number of dove neighbors to scale observations
+        to a standard range of risk levels."""
+        # for convenience and simplicity, we scale the neighborhood so
+        # that agent risk levels can always be defined as 0-9 no matter
+        # the neighborhood size. (Can also be thought of as always
+        # scaling to a neighborhood size of 8.).
+        # Agent risk levels are 0-9 but scaling is 1-8, since 0 and 9
+        # always play hawk and dove respectively.
+        ratio = 8 / self.model.observed_neighborhood
+        # always round to an integer
+        return round(ratio * self.num_dove_neighbors)
+
+    def choose(self):
+        "decide what to play this round"
+        # first choice is random since we don't have any information
+        # about neighbors' choices
+        if self.model.schedule.steps == 0:
+            return
+
+        # after the first round, choose based on what neighbors did last time
+
+        # choose based on the number of neighbors who played
+        # dove last round and agent risk level
+
+        # agent with r = 0 should always take the risky choice
+        #   (any risk is acceptable).
+        # agent with r = max should always take the safe option
+        #   (no risk is acceptable)
+        if self.proportional_num_dove_neighbors >= self.risk_level:
+            choice = Play.HAWK
+        else:
+            choice = Play.DOVE
+
+        # based on model configuration, should agent play randomly instead?
+        if self.model.random_play_odds and coinflip(
+            [True, False], weight=self.model.random_play_odds
+        ):
+            # if a random play is selected, flip a coin between hawk and dove
+            choice = coinflip([Play.HAWK, Play.DOVE])
+
+        self.choice = choice
+
+    def play(self):
+        # play against each neighbor and calculate cumulative payoff
+        payoff = 0
+        for n in self.play_neighbors:
+            payoff += self.payoff(n)
+        # update total points based on payoff this round
+        self.points += payoff
+
+        # store this round's choice as previous choice
+        self.last_choice = self.choice
+
+    def payoff(self, other):
+        """
+        If I play HAWK and neighbor plays DOVE: 3
+        If I play DOVE and neighbor plays DOVE: 2
+        If I play DOVE and neighbor plays HAWK: 1
+        If I play HAWK and neighbor plays HAWK: 0
+        """
+        if self.choice == Play.HAWK:
+            if other.choice == Play.DOVE:
+                return 3
+            if other.choice == Play.HAWK:
+                return 0
+        elif self.choice == Play.DOVE:
+            if other.choice == Play.DOVE:
+                return 2
+            if other.choice == Play.HAWK:
+                return 1
+
+    @property
+    def points_rank(self):
+        if self.points:
+            return math.floor(self.points / self.model.max_agent_points * 10)
+        return 0
+
+
+class HawkDoveModel(mesa.Model):
+    """
+    Model for hawk/dove game with risk attitudes.
+
+    :param grid_size: number for square grid size (creates n*n agents)
+    :param play_neighborhood: size of neighborhood each agent plays
+        against; 4, 8, or 24 (default: 8)
+    :param observed_neighborhood: size of neighborhood each agent looks
+        at when choosing what to play; 4, 8, or 24 (default: 8)
+    :param hawk_odds: odds for playing hawk on the first round (default: 0.5)
+    """
+
+    #: whether the simulation is running
+    running = True  # required for batch run
+    #: readable status (running/converged)
+    status = "running"
+
+    #: size of deque/fifo for recent values
+    rolling_window = 30
+    #: minimum size before calculating rolling average
+    min_window = 15
+    #: class to use when initializing agents
+    agent_class = HawkDoveAgent
+    #: supported neighborhood sizes
+    neighborhood_sizes = {4, 8, 24}
+    #: minimum risk level
+    min_risk_level = 0
+    #: maximum risk level allowed
+    max_risk_level = 9
+
+    def __init__(
+        self,
+        grid_size,
+        play_neighborhood=8,
+        observed_neighborhood=8,
+        hawk_odds=0.5,
+        random_play_odds=0.00,
+    ):
+        super().__init__()
+        # check parameters for combinations that aren't allowed together
+        if grid_size < 5:
+            if play_neighborhood > 8:
+                raise ValueError(
+                    "Play neighborhood %d is too large for grid size %d",
+                    play_neighborhood,
+                    grid_size,
+                )
+            if observed_neighborhood > 8:
+                raise ValueError(
+                    "Observed neighborhood %d is too large for grid size %d",
+                    observed_neighborhood,
+                    grid_size,
+                )
+
+        # assume a fully-populated square grid
+        self.num_agents = grid_size * grid_size
+        for nsize in [play_neighborhood, observed_neighborhood]:
+            check_neighborhood_size(nsize)
+
+        self.play_neighborhood = play_neighborhood
+        self.observed_neighborhood = observed_neighborhood
+
+        # distribution of first choice (50/50 by default)
+        self.hawk_odds = hawk_odds
+        # how often should agents make a random play
+        self.random_play_odds = random_play_odds
+
+        # create fifos to track recent behavior to detect convergence
+        self.recent_percent_hawk = deque([], maxlen=self.rolling_window)
+        self.recent_rolling_percent_hawk = deque([], maxlen=self.rolling_window)
+
+        # initialize a single grid (each square inhabited by a single agent);
+        # configure the grid to wrap around so everyone has neighbors
+        self.grid = mesa.space.SingleGrid(grid_size, grid_size, True)
+        self.schedule = mesa.time.StagedActivation(self, ["choose", "play"])
+
+        # initialize all agents
+        agent_opts = self.new_agent_options()
+        for i in range(self.num_agents):
+            # add to scheduler and place randomly in an empty spot
+            agent = self.agent_class(i, self, **agent_opts)
+            self.schedule.add(agent)
+            self.grid.move_to_empty(agent)
+
+        self.datacollector = mesa.DataCollector(**self.get_data_collector_options())
+
+    def get_data_collector_options(self):
+        # method to return options for data collection,
+        # so subclasses can modify
+        return {
+            "model_reporters": {
+                "max_agent_points": "max_agent_points",
+                "percent_hawk": "percent_hawk",
+                "rolling_percent_hawk": "rolling_percent_hawk",
+                "status": "status",
+                # explicitly track total agents, instead of inferring from grid size
+                "total_agents": "num_agents",
+            },
+            "agent_reporters": {
+                "risk_level": "risk_level",
+                "choice": "choice_label",
+                "points": "points",
+            },
+        }
+
+    def new_agent_options(self):
+        # generate and return a dictionary with common options
+        # for initializing all agents
+        return {"hawk_odds": self.hawk_odds}
+
+    def step(self):
+        """
+        A model step. Used for collecting data and advancing the schedule
+        """
+        self.schedule.step()
+        # check if simulation has converged and should stop running
+        if self.converged:
+            self.status = "converged"
+            self.running = False
+
+        # collect data after status is updated, so data collected
+        # for last round will reflect converged status
+        self.datacollector.collect(self)
+
+    @property
+    def max_agent_points(self):
+        # what is the current largest point total of any agent?
+        return max([a.points for a in self.schedule.agents])
+
+    @property
+    def percent_hawk(self):
+        # what percent of agents chose hawk?
+        hawks = [a for a in self.schedule.agents if a.choice == Play.HAWK]
+        phawk = len(hawks) / self.num_agents
+        # add to recent values
+        self.recent_percent_hawk.append(phawk)
+        return phawk
+
+    @property
+    def rolling_percent_hawk(self):
+        # make sure we have enough values to check
+        if len(self.recent_percent_hawk) > self.min_window:
+            rolling_phawk = statistics.mean(self.recent_percent_hawk)
+            # add to recent values
+            self.recent_rolling_percent_hawk.append(rolling_phawk)
+            return rolling_phawk
+
+    @property
+    def converged(self):
+        # check if the simulation is stable and should stop running
+        # calculating based on rolling percent hawk; when this is stable
+        # within our rolling window, return true
+        # - currently checking for single value;
+        #  could allow for a small amount variation if necessary
+
+        # in variable risk with risk adjustment, numbers are not strictly equal
+        # but do get close and fairly stable; round to two digits before comparing
+        rounded_set = set([round(x, 2) for x in self.recent_rolling_percent_hawk])
+        return (
+            len(self.recent_rolling_percent_hawk) > self.min_window
+            and len(rounded_set) == 1
+        )
+
+
+def check_neighborhood_size(size):
+    # neighborhood size check, shared by model and agent
+    if size not in HawkDoveModel.neighborhood_sizes:
+        raise ValueError(
+            f"{size} is not a supported neighborhood size; "
+            + f"must be one of {HawkDoveModel.neighborhood_sizes}"
+        )
+
+
+class HawkDoveSingleRiskAgent(HawkDoveAgent):
+    """
+    An agent with a risk attitude playing Hawk or Dove; must be initialized
+    with a risk level
+    """
+
+    def set_risk_level(self):
+        self.risk_level = self.model.agent_risk_level
+
+
+class HawkDoveSingleRiskModel(HawkDoveModel):
+    """hawk/dove simulation where all agents have the same risk atttitude.
+    Adds a required `agent_risk_level` parameter; supports all
+    parameters in :class:`HawkDoveModel`.
+    """
+
+    #: class to use when initializing agents
+    agent_class = HawkDoveSingleRiskAgent
+
+    risk_attitudes = "single"
+
+    def __init__(self, grid_size, agent_risk_level, *args, **kwargs):
+        if (
+            agent_risk_level > self.max_risk_level
+            or agent_risk_level < self.min_risk_level
+        ):
+            raise ValueError(
+                f"Agent risk level {agent_risk_level} is out of range; must be between "
+                + f"{self.min_risk_level} - {self.max_risk_level}"
+            )
+
+        # store agent risk level
+        self.agent_risk_level = agent_risk_level
+
+        # pass through options and initialize base class
+        super().__init__(grid_size, *args, **kwargs)

simulatingrisk/hawkdove/run.py

@@ -0,0 +1,31 @@
+import mesa
+
+from simulatingrisk.hawkdove.model import HawkDoveModel
+from simulatingrisk.hawkdove.server import (
+    agent_portrayal,
+    grid_size,
+    model_params,
+    # risk_bins,
+)
+from simulatingrisk.charts.histogram import HistogramModule
+
+
+risk_histogram = HistogramModule(list(range(9)), 175, 500, "risk levels", "risk_level")
+points_histogram = HistogramModule(
+    list(range(10)), 45, 200, "cumulative payoff percentile", "points_rank"
+)
+
+grid = mesa.visualization.CanvasGrid(agent_portrayal, grid_size, grid_size, 500, 500)
+
+
+server = mesa.visualization.ModularServer(
+    HawkDoveModel,
+    # [grid, histogram, world_chart, risk_chart],
+    [grid, risk_histogram, points_histogram],
+    "Hawk/Dove risk attitude Simulation",
+    model_params=model_params,
+)
+server.port = 8521  # The default
+server.launch()
+
+server.launch()

simulatingrisk/hawkdove/server.py

@@ -0,0 +1,189 @@
+"""
+Configure visualization elements and instantiate a server
+"""
+
+import altair as alt
+import solara
+import pandas as pd
+
+from simulatingrisk.hawkdove.model import (
+    Play,
+    divergent_colors_10,
+    HawkDoveModel,
+)
+
+
+def agent_portrayal(agent):
+    # initial display
+    portrayal = {
+        # styles for mesa runserver
+        "Shape": "circle",
+        # "Color": "gray",
+        # "Filled": "true",
+        "Layer": 0,
+        "r": 0.2,
+        "risk_level": agent.risk_level,
+        "choice": str(agent.choice),
+        # styles for solara / jupyterviz
+        "size": 25,
+        # "color": "tab:gray",
+    }
+    # specific to multiple risk attitude variant
+    if hasattr(agent, "risk_level_changed"):
+        portrayal["risk_level_changed"] = agent.risk_level_changed
+
+    # color based on risk level; risk levels are always 0-9
+    colors = divergent_colors_10
+
+    portrayal["Color"] = colors[agent.risk_level]
+    # copy to lowercase color for solara
+    portrayal["color"] = portrayal["Color"]
+
+    # filled for hawks, hollow for doves
+    # (shapes would be better...)
+    portrayal["Filled"] = agent.choice == Play.HAWK
+    portrayal["choice"] = "hawk" if agent.choice == Play.HAWK else "dove"
+
+    # size based on points within current distribution after first round
+    if agent.points > 0:
+        # # set radius based on relative points, but don't go smaller than 1 radius
+        # # or too large to fit in the grid
+        portrayal["r"] = (agent.points_rank / 15) + 0.2
+        # # size for solara / jupyterviz
+        portrayal["size"] = (agent.points_rank / 15) * 50
+
+    return portrayal
+
+
+grid_size = 10
+
+model_params = {
+    "grid_size": grid_size,
+}
+
+neighborhood_sizes = sorted(list(HawkDoveModel.neighborhood_sizes))
+
+# parameters common to both hawk/dove variants
+common_jupyterviz_params = {
+    "grid_size": {
+        "type": "SliderInt",
+        "value": grid_size,
+        "label": "Grid Size",
+        "min": 10,
+        "max": 100,
+        "step": 1,
+    },
+    "play_neighborhood": {
+        "type": "Select",
+        "value": 8,
+        "values": neighborhood_sizes,
+        "label": "Play neighborhood size",
+    },
+    "observed_neighborhood": {
+        "type": "Select",
+        "value": 8,
+        "values": neighborhood_sizes,
+        "label": "Observed neighborhood (determines choice of play)",
+    },
+    "hawk_odds": {
+        "type": "SliderFloat",
+        "value": 0.5,
+        "label": "Hawk Odds (first choice)",
+        "min": 0.0,
+        "max": 1.0,
+        "step": 0.1,
+    },
+    "random_play_odds": {
+        "type": "SliderFloat",
+        "value": 0.01,
+        "label": "Random play odds",
+        "min": 0.0,
+        "max": 1.0,
+        "step": 0.01,
+    },
+}
+
+# in single-risk variant, risk level is set for all agents at init time
+jupyterviz_params = common_jupyterviz_params.copy()
+jupyterviz_params["agent_risk_level"] = {
+    "type": "SliderInt",
+    "label": "Agent risk attitude",
+    "min": 0,
+    "max": 8,
+    "step": 1,
+    "value": 2,
+}
+
+
+def draw_hawkdove_agent_space(model, agent_portrayal):
+    # custom agent space chart, modeled on default
+    # make_space method in mesa jupyterviz code,
+    # but using altair so we can contrl shapes as well as color and size
+    all_agent_data = []
+    for i in range(model.grid.width):
+        for j in range(model.grid.height):
+            agent_data = {}
+            content = model.grid._grid[i][j]
+            if not content:
+                continue
+            if not hasattr(content, "__iter__"):
+                # Is a single grid
+                content = [content]
+            for agent in content:
+                # use all data from agent portrayal, and add x,y coordinates
+                agent_data = agent_portrayal(agent)
+                agent_data["x"] = i
+                agent_data["y"] = j
+            all_agent_data.append(agent_data)
+
+    df = pd.DataFrame(all_agent_data)
+    # print(all_agent_data)
+
+    # use grid x,y coordinates to plot, but supress axis labels
+
+    # currently passing in actual colors, not a variable to use for color
+    # use domain/range to use color for display
+    hawkdove_domain = ("hawk", "dove")
+    shape_range = ("triangle-up", "circle")
+
+    # when risk attitude is variable,
+    # use divergent color scheme to indicate risk level
+    if model.risk_attitudes == "variable":
+        colors = list(set(a["color"] for a in all_agent_data))
+        chart_color = alt.Color("color").legend(None).scale(domain=colors, range=colors)
+    elif model.risk_attitudes == "single":
+        chart_color = (
+            alt.Color("choice")
+            # .legend(None)
+            .scale(domain=hawkdove_domain, range=["orange", "blue"])
+        )
+
+    # optionally display information from multi-risk attitude variant
+    if "risk_level_changed" in df.columns:
+        outer_color = alt.Color(
+            "risk_level_changed", title="adjusted risk attitude"
+        ).scale(
+            domain=[False, True],
+            range=["transparent", "black"],
+        )
+    else:
+        outer_color = chart_color
+
+    agent_chart = (
+        alt.Chart(df)
+        .mark_point()  # filled=True)
+        .encode(
+            x=alt.X("x", axis=None),  # no x-axis label
+            y=alt.Y("y", axis=None),  # no y-axis label
+            size=alt.Size("size", title="points rank"),  # relabel size for legend
+            # when fill and color differ, color acts as an outline
+            fill=chart_color,
+            color=outer_color,
+            shape=alt.Shape(  # use shape to indicate choice
+                "choice", scale=alt.Scale(domain=hawkdove_domain, range=shape_range)
+            ),
+        )
+        .configure_view(strokeOpacity=0)  # hide grid/chart lines
+    )
+
+    return solara.FigureAltair(agent_chart)

simulatingrisk/hawkdovemulti/README.md

@@ -0,0 +1,92 @@
+# Hawk-Dove with multiple risk attitudes
+
+This is a variation of the [Hawk/Dove game with risk attitudes](../hawkdove/).
+This version adds multiple risk attitudes, with options for updating
+risk attitudes periodically based on comparing success of neighboring agents.
+
+The basic mechanics of the game are the same. This model adds options
+for agent risk adjustment (none, adopt, average) and period of risk
+adjustment (by default, every ten rounds). The payoff used to compare
+agents when adjusting risk attitudes can either be recent (since the
+last adjustment round) or total points for the whole game. The
+adjustment neighborhood, or which neighboring agents are considered
+when adjusting risk attitudes, can be configured to 4, 8, or 24.
+
+Initial risk attitudes are set by the model. Risk distribution can
+be configured to use a normal distribution, uniform (random), bimodal,
+skewed left, or skewed right.
+
+Like the base hawk/dove risk attitude game, there is also a
+configuration to add some chance of agents playing hawk/dove randomly
+instead of choosing based on the rules of the game.
+
+## Convergence
+
+The model is configured to stop automatically when it has stabilized.
+
+Model and agent data collection reports on whether agents updated their
+risk level in the last adjustment round, and model data collection
+includes a status of "running" or "converged".
+
+### With Adjustment
+
+When adjustment is enabled (adopt / average), convergence is checked
+after the simulation has run for a minimum of 50 rounds.  The simulation
+is considered stable when individual agents are no longer adjusting risk attitudes,
+or when the number of agents in each risk attitude are relatively stable
+(e.g., agents are swapping risk attitudes but the overall total for each
+category is stable).
+
+Convergence is reached when an adjustment round occurs and _either_:
+
+-  _zero_ agents adjust their risk attitude
+- the total changes of agents per risk attitudes is less than 7% of the population size
+
+### Without Adjustment
+
+If adjustment is not enabled, convergence logic falls back to the
+implementation of the hawk/dove single-risk attitude simulation. In this case,
+convergence is based on a stable rolling % average of agents playing hawk.
+
+
+## Batch running
+
+This module includes a custom batch run script to run the simulation and
+collect data across a large combination of parameters and generate data
+files with collected model and agent data.
+
+To run the script locally from the root project directory:
+```sh
+simulatingrisk/hawkdovemulti/batch_run.py
+```
+Use `-h` or `--help` to see options.
+
+If this project has been installed with pip or similar, the script is
+available as `simrisk-hawkdovemulti-batchrun`.
+
+To run the batch run script on an HPC cluster:
+
+- Create a conda environment and install dependencies and this project.
+  (Major mesa dependencies available with conda are installed first as
+  conda packages)
+
+```sh
+module load anaconda3/2023.9
+conda create --name simrisk pandas networkx matplotlib numpy tqdm click
+conda activate simrisk
+pip install git+https://github.com/Princeton-CDH/simulating-risk.git@hawkdove-batchrun
+```
+For convenience, an example [slurm batch script](simrisk_batch.slurm) is
+included for running the batch run script (some portions are
+specific to Princeton's Research Computing HPC environment.)
+
+- Customize the slurm batch script as desired, copy it to the cluster, and submit
+the job: `sbatch simrisk_batch.slurm`
+
+By default, the batch run script will use all available processors, and will
+create model and agent data files under a `data/hawkdovemulti/` directory
+relative to the working directory where the script is called.
+
+
+
+