Importable examples

examples/basic/__init__.py

@@ -0,0 +1,13 @@
+from .boid_flockers.model import BoidFlockers
+from .boltzmann_wealth_model.model import BoltzmannWealthModel
+from .conways_game_of_life.model import ConwaysGameOfLife
+from .schelling.model import Schelling
+from .virus_on_network.model import VirusOnNetwork
+
+__all__ = [
+    "BoidFlockers",
+    "BoltzmannWealthModel",
+    "ConwaysGameOfLife",
+    "Schelling",
+    "VirusOnNetwork",
+]

examples/basic/boid_flockers/app.py

@@ -1,7 +1,7 @@
-from model import BoidFlockers
-
 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

examples/basic/boid_flockers/model.py

@@ -5,10 +5,11 @@
 """
 
 import numpy as np
-from agents import Boid
 
 import mesa
 
+from .agents import Boid
+
 
 class BoidFlockers(mesa.Model):
     """Flocker model class. Handles agent creation, placement and scheduling."""

examples/basic/boltzmann_wealth_model/app.py

@@ -1,11 +1,11 @@
-from model import BoltzmannWealthModel
-
 from mesa.visualization import (
     SolaraViz,
     make_plot_measure,
     make_space_matplotlib,
 )
 
+from .model import BoltzmannWealthModel
+
 
 def agent_portrayal(agent):
     size = 10

examples/basic/boltzmann_wealth_model/model.py

@@ -1,7 +1,7 @@
-from agents import MoneyAgent
-
 import mesa
 
+from .agents import MoneyAgent
+
 
 class BoltzmannWealthModel(mesa.Model):
     """A simple model of an economy where agents exchange currency at random.

examples/basic/conways_game_of_life/model.py

@@ -1,8 +1,8 @@
-from agents import Cell
-
 from mesa import Model
 from mesa.space import SingleGrid
 
+from .agents import Cell
+
 
 class ConwaysGameOfLife(Model):
     """Represents the 2-dimensional array of cells in Conway's Game of Life."""

examples/basic/conways_game_of_life/server.py

@@ -1,8 +1,8 @@
-from model import ConwaysGameOfLife
-from portrayal import portrayCell
-
 import mesa
 
+from .model import ConwaysGameOfLife
+from .portrayal import portrayCell
+
 # Make a world that is 50x50, on a 250x250 display.
 canvas_element = mesa.visualization.CanvasGrid(portrayCell, 50, 50, 250, 250)
 

examples/basic/schelling/app.py

@@ -1,5 +1,4 @@
 import solara
-from model import Schelling
 
 from mesa.visualization import (
     Slider,
@@ -8,6 +7,8 @@
     make_space_matplotlib,
 )
 
+from .model import Schelling
+
 
 def get_happy_agents(model):
     """Display a text count of how many happy agents there are."""

examples/basic/schelling/model.py

@@ -1,8 +1,8 @@
-from agents import SchellingAgent
-
 import mesa
 from mesa import Model
 
+from .agents import SchellingAgent
+
 
 class Schelling(Model):
     """Model class for the Schelling segregation model."""

examples/basic/virus_on_network/app.py

@@ -3,10 +3,11 @@
 import solara
 from matplotlib.figure import Figure
 from matplotlib.ticker import MaxNLocator
-from model import State, VirusOnNetwork, number_infected
 
 from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
 
+from .model import State, VirusOnNetwork, number_infected
+
 
 def agent_portrayal(graph):
     def get_agent(node):

examples/basic/virus_on_network/model.py

@@ -1,11 +1,12 @@
 import math
 
 import networkx as nx
-from agents import State, VirusAgent
 
 import mesa
 from mesa import Model
 
+from .agents import State, VirusAgent
+
 
 def number_state(model, state):
     return sum(1 for a in model.grid.get_all_cell_contents() if a.state is state)

mesa/__init__.py

@@ -5,6 +5,7 @@
 
 import datetime
 
+import mesa.examples as examples
 import mesa.experimental as experimental
 import mesa.space as space
 import mesa.time as time
@@ -21,6 +22,7 @@
     "DataCollector",
     "batch_run",
     "experimental",
+    "examples",
 ]
 
 __title__ = "mesa"

mesa/examples.py

@@ -0,0 +1,3 @@
+"""This module is a collection of example models built using the Mesa framework."""
+
+__path__ = ["examples"]

pyproject.toml

@@ -87,7 +87,7 @@ repository = "https://github.com/projectmesa/mesa"
 mesa = "mesa.main:cli"
 
 [tool.hatch.build.targets.wheel]
-packages = ["mesa"]
+packages = ["mesa", "examples"]
 
 [tool.hatch.version]
 path = "mesa/__init__.py"

tests/test_examples.py

@@ -6,6 +6,23 @@
 import unittest
 
 
+def test_examples_imports():
+    """Test examples imports."""
+    from mesa.examples.basic import (
+        BoidFlockers,
+        BoltzmannWealthModel,
+        ConwaysGameOfLife,
+        Schelling,
+        VirusOnNetwork,
+    )
+
+    BoltzmannWealthModel()
+    Schelling()
+    BoidFlockers()
+    ConwaysGameOfLife()
+    VirusOnNetwork()
+
+
 def classcase(name):  # noqa: D103
     return "".join(x.capitalize() for x in name.replace("-", "_").split("_"))