Integrate Hotelling Law Extension into Mesa Examples

examples/hotelling_law/Readme.md

@@ -0,0 +1,67 @@
+# Hotelling's Law Mesa Simulation
+
+## Overview
+
+This project is an agent-based model implemented using the Mesa framework in Python. It simulates market dynamics based on Hotelling's Law, exploring the behavior of stores in a competitive market environment. Stores adjust their prices and locations to maximize revenue, providing insights into the effects of competition and customer behavior on market outcomes.
+
+## Hotelling's Law
+
+Hotelling's Law is an economic theory that predicts competitors in a market will end up in a state of minimum differentiation, often referred to as the "principle of minimum differentiation" or "Hotelling's linear city model". This model explores how businesses choose their location in relation to competitors and how this affects pricing and consumer choice.
+
+## Installation
+
+To run this simulation, you will need Python 3.x and the following Python libraries:
+
+- Mesa
+- Pandas
+- Matplotlib
+- Numpy
+
+You can install all required libraries by running:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Project Structure
+
+```plaintext
+hotelling-law-mesa/
+├── __init__.py
+├── agents.py
+├── model.py
+├── app.py
+├── requirements.txt
+└── tests.py
+```
+
+## Running the Simulation
+
+To start the simulation, navigate to the project directory and execute the following command:
+
+```bash
+python run.py
+
+solara run app.py (mesa 3.0)
+```
+
+# Project Details
+
+### Professor: [Vipin P. Veetil](https://www.vipinveetil.com/)
+### Indian Institute of Management, Kozhikode
+
+### Project by
+
+| Group 8 |                           |               |
+|-|---------------------------|---------------|
+| Name | Email Id                  | Roll No       |
+| Amrita Tripathy | amrita15d@iimk.edu.in     | EPGP-15D-010  |
+| Anirban Mondal | anirban15e@iimk.edu.in    | EPGP-15E-006  |
+| Namita Das | namita15d@iimk.edu.in     | EPGP-15D-046  |
+| Sandeep Shenoy | sandeep15c@iimk.edu.in    | EPGP-15C-076  |
+| Sanjeeb Kumar Dhinda | sanjeeb15d@iimk.edu.in | EPGP-15D-074  |
+| Umashankar Ankuri | umashankar15d@iimk.edu.in | EPGP-15D-096  |
+| Vinayak Nair | vinayak15d@iimk.edu.in    | EPGP-15D-102  |
+| Wayne Joseph Unger | wayne15d@iimk.edu.in    | EPGP-15D-104  |
+
+

examples/hotelling_law/agents.py

@@ -0,0 +1,48 @@
+from mesa import Agent
+
+
+class StoreAgent(Agent):
+    """An agent representing a store with a price and ability to move
+    and adjust prices."""
+
+    def __init__(self, unique_id, model, price=10, can_move=True):
+        # Initializes the store agent with a unique ID,
+        # the model it belongs to,its initial price,
+        # and whether it can move.
+        super().__init__(unique_id, model)
+        self.price = price  # Initial price of the store.
+        self.can_move = can_move  # Indicates if the agent can move.
+
+    def move(self):
+        # Defines how the store agent moves in the environment.
+        if self.can_move:
+            # For a grid / line  environment, find neighboring positions and
+            # randomly move to one.
+            possible_steps = self.model.grid.get_neighborhood(
+                self.pos, moore=True, include_center=False
+            )
+            new_position = self.random.choice(possible_steps)
+            self.model.grid.move_agent(self, new_position)
+
+    def adjust_price(self):
+        # Randomly adjusts the price of the store
+        # by +/- 1 within a defined range.
+        self.price += self.random.choice([-1, 1])
+        self.price = max(
+            5, min(self.price, 15)
+        )  # Ensures the price stays between 5 and 15.
+
+    def step(self):
+        # Defines the actions the store agent takes
+        # in each step of the simulation.
+        if self.model.mode == "default":
+            # In default mode, the agent can move and
+            # adjust prices if allowed.
+            self.move()
+            self.adjust_price()
+        elif self.model.mode == "moving_only":
+            # In moving_only mode, the agent only moves if it can.
+            self.move()
+        elif self.model.mode == "pricing_only":
+            # In pricing_only mode, the agent only adjusts its price.
+            self.adjust_price()

examples/hotelling_law/app.py

@@ -0,0 +1,138 @@
+import numpy as np
+import solara
+from matplotlib.figure import Figure
+from mesa.experimental import JupyterViz
+
+from .model import HotellingModel
+
+
+# This function defines how agents are visually
+# represented in the simulation.
+def agent_portrayal(agent):
+    size = 50  # Default size
+    color = "grey"  # Default color for agents
+
+    # Check if the agent has a 'price' attribute.
+    # This is to ensure compatibility
+    # with different types of agents.
+    if hasattr(agent, "price"):
+        # Adjust color based on the price attribute of the StoreAgent
+        if agent.price > 12:
+            color = "#FF0000"  # Higher prices in red
+        elif agent.price > 8:
+            color = "#FFA500"  # Moderate prices in orange
+        else:
+            color = "#00FF00"  # Lower prices in green
+    # Construct and return the portrayal dictionary
+    portrayal = {
+        "size": size,
+        "color": color,
+    }
+    return portrayal  # Return the portrayal dictionary to be used by
+    # the visualization engine.
+
+
+def space_drawer(model, agent_portrayal):
+    # Create a new figure
+    fig = Figure(figsize=(8, 5), dpi=100)
+    ax = fig.subplots()
+
+    # Define grid lines
+    ticks = np.arange(0, model.grid.width + 1, 1)
+    ax.set_xticks(ticks, minor=False)
+    ax.set_yticks(ticks, minor=False)
+    ax.grid(which="both", color="gray", linestyle="-", linewidth=0.5)
+    ax.tick_params(which="both", size=0)  # Hide grid ticks
+
+    # Set axis limits and aspect
+    ax.set_xlim(0, model.grid.width)
+    ax.set_ylim(0, model.grid.height)
+    ax.set_aspect("equal")
+
+    # Hide major tick labels
+    ax.set_xticklabels([])
+    ax.set_yticklabels([])
+
+    # Plotting agents using portrayal
+    for agent in model.schedule.agents:
+        portrayal = agent_portrayal(agent)
+        x, y = agent.pos
+        # Adjust plot call for object-oriented API
+        ax.scatter(
+            x + 0.5,
+            y + 0.5,
+            c=portrayal.get("color", "black"),
+            s=portrayal.get("size", 100),
+            linewidths=0.5,
+            edgecolors="black",
+            alpha=0.6,
+        )
+
+    # Invert y-axis to match grid origin (bottom-left)
+    ax.invert_yaxis()
+
+    # Adjust layout properly for embedded plots
+    fig.tight_layout()
+
+    return solara.FigureMatplotlib(fig)
+
+
+model_params = {
+    "N": {
+        "type": "SliderInt",
+        "value": 20,
+        "label": "Number of stores:",
+        "min": 10,
+        "max": 100,
+        "step": 1,
+    },
+    "mode": {
+        "type": "Select",
+        "value": "default",
+        "label": "Mode:",
+        "values": ["default", "pricing_only", "moving_only"],
+    },
+    "environment_type": {
+        "type": "Select",
+        "value": "grid",
+        "label": "Environment Type:",
+        "values": ["grid", "line"],
+    },
+    "mobility_rate": {
+        "type": "SliderInt",
+        "value": 100,
+        "label": "Mobility Rate (%):",
+        "min": 10,
+        "max": 100,
+        "step": 5,
+    },
+    "width": {
+        "type": "SliderInt",
+        "value": 20,  # Adjusted from 10 to 20 for wider grid
+        "label": "Grid Width:",
+        "min": 10,
+        "max": 50,
+        "step": 5,
+    },
+    "height": {
+        "type": "SliderInt",
+        "value": 20,  # Adjusted from 10 to 20 for taller grid
+        "label": "Grid Height:",
+        "min": 10,
+        "max": 50,
+        "step": 5,
+    },
+}
+
+# Instantiate the JupyterViz component with your model
+page = JupyterViz(
+    model_class=HotellingModel,
+    model_params=model_params,
+    measures=["Average Price", "Total Revenue", "Price Variance"],
+    name="Hotelling's Law Model",
+    agent_portrayal=agent_portrayal,
+    space_drawer=space_drawer,
+)
+
+# Display the visualization in the Jupyter Notebook
+page  # noqa