diff --git a/.github/workflows/build_lint.yml b/.github/workflows/build_lint.yml index ab62e75bce5..eeb08460ae9 100644 --- a/.github/workflows/build_lint.yml +++ b/.github/workflows/build_lint.yml @@ -84,4 +84,4 @@ jobs: - name: Test examples run: | cd mesa-examples - pytest -rA -Werror -Wdefault::FutureWarning test_examples.py + pytest -rA -Werror -Wdefault::FutureWarning -Wi::DeprecationWarning test_examples.py diff --git a/docs/apis/api_main.md b/docs/apis/api_main.md index 6a3ef810f52..d6ecf0b8dd4 100644 --- a/docs/apis/api_main.md +++ b/docs/apis/api_main.md @@ -7,6 +7,7 @@ model agent time space +discrete_space datacollection batchrunner visualization diff --git a/docs/apis/discrete_space.md b/docs/apis/discrete_space.md new file mode 100644 index 00000000000..76479dc0464 --- /dev/null +++ b/docs/apis/discrete_space.md @@ -0,0 +1,41 @@ +## Discrete Space + +```{eval-rst} +.. automodule:: mesa.discrete_space.__init__ + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.cell + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.cell_agent + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.cell_collection + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.discrete_space + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.grid + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.network + :members: +``` + +```{eval-rst} +.. automodule:: mesa.discrete_space.voronoi + :members: +``` \ No newline at end of file diff --git a/docs/apis/experimental.md b/docs/apis/experimental.md index 701d6a3e00f..4115feeb502 100644 --- a/docs/apis/experimental.md +++ b/docs/apis/experimental.md @@ -1,47 +1,6 @@ # Experimental This namespace contains experimental features. These are under development, and their API is not necessarily stable. -## Cell Space - -```{eval-rst} -.. automodule:: experimental.cell_space.__init__ - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.cell - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.cell_agent - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.cell_collection - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.discrete_space - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.grid - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.network - :members: -``` - -```{eval-rst} -.. automodule:: experimental.cell_space.voronoi - :members: -``` ## Devs diff --git a/mesa/discrete_space/__init__.py b/mesa/discrete_space/__init__.py new file mode 100644 index 00000000000..add5831f0ee --- /dev/null +++ b/mesa/discrete_space/__init__.py @@ -0,0 +1,50 @@ +"""Cell spaces for active, property-rich spatial modeling in Mesa. + +Cell spaces extend Mesa's spatial modeling capabilities by making the space itself active - +each position (cell) can have properties and behaviors rather than just containing agents. +This enables more sophisticated environmental modeling and agent-environment interactions. + +Key components: +- Cells: Active positions that can have properties and contain agents +- CellAgents: Agents that understand how to interact with cells +- Spaces: Different cell organization patterns (grids, networks, etc.) +- PropertyLayers: Efficient property storage and manipulation + +This is particularly useful for models where the environment plays an active role, +like resource growth, pollution diffusion, or infrastructure networks. The cell +space system is experimental and under active development. +""" + +from mesa.discrete_space.cell import Cell +from mesa.discrete_space.cell_agent import ( + CellAgent, + FixedAgent, + Grid2DMovingAgent, +) +from mesa.discrete_space.cell_collection import CellCollection +from mesa.discrete_space.discrete_space import DiscreteSpace +from mesa.discrete_space.grid import ( + Grid, + HexGrid, + OrthogonalMooreGrid, + OrthogonalVonNeumannGrid, +) +from mesa.discrete_space.network import Network +from mesa.discrete_space.property_layer import PropertyLayer +from mesa.discrete_space.voronoi import VoronoiGrid + +__all__ = [ + "Cell", + "CellAgent", + "CellCollection", + "DiscreteSpace", + "FixedAgent", + "Grid", + "Grid2DMovingAgent", + "HexGrid", + "Network", + "OrthogonalMooreGrid", + "OrthogonalVonNeumannGrid", + "PropertyLayer", + "VoronoiGrid", +] diff --git a/mesa/experimental/cell_space/cell.py b/mesa/discrete_space/cell.py similarity index 97% rename from mesa/experimental/cell_space/cell.py rename to mesa/discrete_space/cell.py index 2dd2c42b85f..685a002d720 100644 --- a/mesa/experimental/cell_space/cell.py +++ b/mesa/discrete_space/cell.py @@ -18,8 +18,8 @@ from random import Random from typing import TYPE_CHECKING -from mesa.experimental.cell_space.cell_agent import CellAgent -from mesa.experimental.cell_space.cell_collection import CellCollection +from mesa.discrete_space.cell_agent import CellAgent +from mesa.discrete_space.cell_collection import CellCollection if TYPE_CHECKING: from mesa.agent import Agent diff --git a/mesa/experimental/cell_space/cell_agent.py b/mesa/discrete_space/cell_agent.py similarity index 98% rename from mesa/experimental/cell_space/cell_agent.py rename to mesa/discrete_space/cell_agent.py index 738196d68ed..b45a0634043 100644 --- a/mesa/experimental/cell_space/cell_agent.py +++ b/mesa/discrete_space/cell_agent.py @@ -18,7 +18,7 @@ from mesa.agent import Agent if TYPE_CHECKING: - from mesa.experimental.cell_space import Cell + from mesa.discrete_space import Cell class HasCellProtocol(Protocol): diff --git a/mesa/experimental/cell_space/cell_collection.py b/mesa/discrete_space/cell_collection.py similarity index 97% rename from mesa/experimental/cell_space/cell_collection.py rename to mesa/discrete_space/cell_collection.py index 6b2f079cdae..9f858e87b2b 100644 --- a/mesa/experimental/cell_space/cell_collection.py +++ b/mesa/discrete_space/cell_collection.py @@ -23,8 +23,8 @@ from typing import TYPE_CHECKING, Generic, TypeVar if TYPE_CHECKING: - from mesa.experimental.cell_space.cell import Cell - from mesa.experimental.cell_space.cell_agent import CellAgent + from mesa.discrete_space.cell import Cell + from mesa.discrete_space.cell_agent import CellAgent T = TypeVar("T", bound="Cell") diff --git a/mesa/experimental/cell_space/discrete_space.py b/mesa/discrete_space/discrete_space.py similarity index 96% rename from mesa/experimental/cell_space/discrete_space.py rename to mesa/discrete_space/discrete_space.py index 5554021f0c2..e7f1a2c51e1 100644 --- a/mesa/experimental/cell_space/discrete_space.py +++ b/mesa/discrete_space/discrete_space.py @@ -21,8 +21,8 @@ from typing import Generic, TypeVar from mesa.agent import AgentSet -from mesa.experimental.cell_space.cell import Cell -from mesa.experimental.cell_space.cell_collection import CellCollection +from mesa.discrete_space.cell import Cell +from mesa.discrete_space.cell_collection import CellCollection T = TypeVar("T", bound=Cell) diff --git a/mesa/experimental/cell_space/grid.py b/mesa/discrete_space/grid.py similarity index 98% rename from mesa/experimental/cell_space/grid.py rename to mesa/discrete_space/grid.py index 6078a038401..5a99033f91f 100644 --- a/mesa/experimental/cell_space/grid.py +++ b/mesa/discrete_space/grid.py @@ -19,8 +19,8 @@ from random import Random from typing import Any, Generic, TypeVar -from mesa.experimental.cell_space import Cell, DiscreteSpace -from mesa.experimental.cell_space.property_layer import ( +from mesa.discrete_space import Cell, DiscreteSpace +from mesa.discrete_space.property_layer import ( HasPropertyLayers, PropertyDescriptor, ) diff --git a/mesa/experimental/cell_space/network.py b/mesa/discrete_space/network.py similarity index 93% rename from mesa/experimental/cell_space/network.py rename to mesa/discrete_space/network.py index 6b616088adb..7f692cd2eaf 100644 --- a/mesa/experimental/cell_space/network.py +++ b/mesa/discrete_space/network.py @@ -15,8 +15,8 @@ from random import Random from typing import Any -from mesa.experimental.cell_space.cell import Cell -from mesa.experimental.cell_space.discrete_space import DiscreteSpace +from mesa.discrete_space.cell import Cell +from mesa.discrete_space.discrete_space import DiscreteSpace class Network(DiscreteSpace[Cell]): diff --git a/mesa/experimental/cell_space/property_layer.py b/mesa/discrete_space/property_layer.py similarity index 99% rename from mesa/experimental/cell_space/property_layer.py rename to mesa/discrete_space/property_layer.py index 8f989326dd2..997b865b5a7 100644 --- a/mesa/experimental/cell_space/property_layer.py +++ b/mesa/discrete_space/property_layer.py @@ -21,7 +21,7 @@ import numpy as np -from mesa.experimental.cell_space import Cell +from mesa.discrete_space import Cell Coordinate = Sequence[int] T = TypeVar("T", bound=Cell) diff --git a/mesa/experimental/cell_space/voronoi.py b/mesa/discrete_space/voronoi.py similarity index 98% rename from mesa/experimental/cell_space/voronoi.py rename to mesa/discrete_space/voronoi.py index 5c48f53af8a..8ff195bac31 100644 --- a/mesa/experimental/cell_space/voronoi.py +++ b/mesa/discrete_space/voronoi.py @@ -18,8 +18,8 @@ import numpy as np -from mesa.experimental.cell_space.cell import Cell -from mesa.experimental.cell_space.discrete_space import DiscreteSpace +from mesa.discrete_space.cell import Cell +from mesa.discrete_space.discrete_space import DiscreteSpace class Delaunay: diff --git a/mesa/examples/advanced/epstein_civil_violence/agents.py b/mesa/examples/advanced/epstein_civil_violence/agents.py index 026ec342e22..05ad919f439 100644 --- a/mesa/examples/advanced/epstein_civil_violence/agents.py +++ b/mesa/examples/advanced/epstein_civil_violence/agents.py @@ -10,7 +10,7 @@ class CitizenState(Enum): ARRESTED = 3 -class EpsteinAgent(mesa.experimental.cell_space.CellAgent): +class EpsteinAgent(mesa.discrete_space.CellAgent): def update_neighbors(self): """ Look around and see who my neighbors are diff --git a/mesa/examples/advanced/epstein_civil_violence/model.py b/mesa/examples/advanced/epstein_civil_violence/model.py index 3e632b65e77..171c0cffc75 100644 --- a/mesa/examples/advanced/epstein_civil_violence/model.py +++ b/mesa/examples/advanced/epstein_civil_violence/model.py @@ -53,7 +53,7 @@ def __init__( self.movement = movement self.max_iters = max_iters - self.grid = mesa.experimental.cell_space.OrthogonalVonNeumannGrid( + self.grid = mesa.discrete_space.OrthogonalVonNeumannGrid( (width, height), capacity=1, torus=True, random=self.random ) diff --git a/mesa/examples/advanced/pd_grid/agents.py b/mesa/examples/advanced/pd_grid/agents.py index eb559361562..f4bab0e6428 100644 --- a/mesa/examples/advanced/pd_grid/agents.py +++ b/mesa/examples/advanced/pd_grid/agents.py @@ -1,4 +1,4 @@ -from mesa.experimental.cell_space import CellAgent +from mesa.discrete_space import CellAgent class PDAgent(CellAgent): diff --git a/mesa/examples/advanced/pd_grid/model.py b/mesa/examples/advanced/pd_grid/model.py index 6350d8c86ba..1970f662f26 100644 --- a/mesa/examples/advanced/pd_grid/model.py +++ b/mesa/examples/advanced/pd_grid/model.py @@ -1,6 +1,6 @@ import mesa +from mesa.discrete_space import OrthogonalMooreGrid from mesa.examples.advanced.pd_grid.agents import PDAgent -from mesa.experimental.cell_space import OrthogonalMooreGrid class PdGrid(mesa.Model): diff --git a/mesa/examples/advanced/sugarscape_g1mt/agents.py b/mesa/examples/advanced/sugarscape_g1mt/agents.py index d3cdb9d8117..ca3ffaf1baf 100644 --- a/mesa/examples/advanced/sugarscape_g1mt/agents.py +++ b/mesa/examples/advanced/sugarscape_g1mt/agents.py @@ -1,6 +1,6 @@ import math -from mesa.experimental.cell_space import CellAgent +from mesa.discrete_space import CellAgent # Helper function diff --git a/mesa/examples/advanced/sugarscape_g1mt/model.py b/mesa/examples/advanced/sugarscape_g1mt/model.py index 8c139eb8ad1..465e7be240a 100644 --- a/mesa/examples/advanced/sugarscape_g1mt/model.py +++ b/mesa/examples/advanced/sugarscape_g1mt/model.py @@ -3,9 +3,9 @@ import numpy as np import mesa +from mesa.discrete_space import OrthogonalVonNeumannGrid +from mesa.discrete_space.property_layer import PropertyLayer from mesa.examples.advanced.sugarscape_g1mt.agents import Trader -from mesa.experimental.cell_space import OrthogonalVonNeumannGrid -from mesa.experimental.cell_space.property_layer import PropertyLayer # Helper Functions diff --git a/mesa/examples/advanced/wolf_sheep/agents.py b/mesa/examples/advanced/wolf_sheep/agents.py index 93f4b4eb77e..b14963442c2 100644 --- a/mesa/examples/advanced/wolf_sheep/agents.py +++ b/mesa/examples/advanced/wolf_sheep/agents.py @@ -1,4 +1,4 @@ -from mesa.experimental.cell_space import CellAgent, FixedAgent +from mesa.discrete_space import CellAgent, FixedAgent class Animal(CellAgent): diff --git a/mesa/examples/advanced/wolf_sheep/model.py b/mesa/examples/advanced/wolf_sheep/model.py index 73b9c26a833..e93a0bffa4a 100644 --- a/mesa/examples/advanced/wolf_sheep/model.py +++ b/mesa/examples/advanced/wolf_sheep/model.py @@ -13,8 +13,8 @@ from mesa import Model from mesa.datacollection import DataCollector +from mesa.discrete_space import OrthogonalVonNeumannGrid from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf -from mesa.experimental.cell_space import OrthogonalVonNeumannGrid from mesa.experimental.devs import ABMSimulator diff --git a/mesa/experimental/__init__.py b/mesa/experimental/__init__.py index 8f0ac91df48..014dc7c7637 100644 --- a/mesa/experimental/__init__.py +++ b/mesa/experimental/__init__.py @@ -15,6 +15,6 @@ - Features graduate from experimental status once their APIs are stabilized """ -from mesa.experimental import cell_space, continuous_space, devs, mesa_signals +from mesa.experimental import continuous_space, devs, mesa_signals -__all__ = ["cell_space", "continuous_space", "devs", "mesa_signals"] +__all__ = ["continuous_space", "devs", "mesa_signals"] diff --git a/mesa/experimental/cell_space/__init__.py b/mesa/experimental/cell_space/__init__.py index 26cbd4978dd..4f2a40da6fe 100644 --- a/mesa/experimental/cell_space/__init__.py +++ b/mesa/experimental/cell_space/__init__.py @@ -15,23 +15,25 @@ space system is experimental and under active development. """ -from mesa.experimental.cell_space.cell import Cell -from mesa.experimental.cell_space.cell_agent import ( +import warnings + +from mesa.discrete_space.cell import Cell +from mesa.discrete_space.cell_agent import ( CellAgent, FixedAgent, Grid2DMovingAgent, ) -from mesa.experimental.cell_space.cell_collection import CellCollection -from mesa.experimental.cell_space.discrete_space import DiscreteSpace -from mesa.experimental.cell_space.grid import ( +from mesa.discrete_space.cell_collection import CellCollection +from mesa.discrete_space.discrete_space import DiscreteSpace +from mesa.discrete_space.grid import ( Grid, HexGrid, OrthogonalMooreGrid, OrthogonalVonNeumannGrid, ) -from mesa.experimental.cell_space.network import Network -from mesa.experimental.cell_space.property_layer import PropertyLayer -from mesa.experimental.cell_space.voronoi import VoronoiGrid +from mesa.discrete_space.network import Network +from mesa.discrete_space.property_layer import PropertyLayer +from mesa.discrete_space.voronoi import VoronoiGrid __all__ = [ "Cell", @@ -48,3 +50,11 @@ "PropertyLayer", "VoronoiGrid", ] + + +warnings.warn( + "you are importing from mesa.experimental.cell_space, " + "all cell spaces have been moved to mesa.discrete_space", + DeprecationWarning, + stacklevel=2, +) diff --git a/mesa/space.py b/mesa/space.py index d503d42e41b..843b9a1c769 100644 --- a/mesa/space.py +++ b/mesa/space.py @@ -6,7 +6,7 @@ All Grid classes (:class:`_Grid`, :class:`SingleGrid`, :class:`MultiGrid`, :class:`HexGrid`, etc.) are now in maintenance-only mode. While these classes remain fully supported, new development occurs in the experimental cell space module - (:mod:`mesa.experimental.cell_space`). + (:mod:`mesa.discrete_space`). The :class:`PropertyLayer` and :class:`ContinuousSpace` classes remain fully supported and actively developed. diff --git a/mesa/visualization/components/altair_components.py b/mesa/visualization/components/altair_components.py index f09167dff76..61ccf0d6648 100644 --- a/mesa/visualization/components/altair_components.py +++ b/mesa/visualization/components/altair_components.py @@ -5,7 +5,7 @@ import altair as alt import solara -from mesa.experimental.cell_space import DiscreteSpace, Grid +from mesa.discrete_space import DiscreteSpace, Grid from mesa.space import ContinuousSpace, _Grid from mesa.visualization.utils import update_counter diff --git a/mesa/visualization/mpl_space_drawing.py b/mesa/visualization/mpl_space_drawing.py index 5c94311c619..f531261016f 100644 --- a/mesa/visualization/mpl_space_drawing.py +++ b/mesa/visualization/mpl_space_drawing.py @@ -24,7 +24,7 @@ from matplotlib.patches import Polygon import mesa -from mesa.experimental.cell_space import ( +from mesa.discrete_space import ( OrthogonalMooreGrid, OrthogonalVonNeumannGrid, VoronoiGrid, @@ -40,8 +40,8 @@ ) OrthogonalGrid = SingleGrid | MultiGrid | OrthogonalMooreGrid | OrthogonalVonNeumannGrid -HexGrid = HexSingleGrid | HexMultiGrid | mesa.experimental.cell_space.HexGrid -Network = NetworkGrid | mesa.experimental.cell_space.Network +HexGrid = HexSingleGrid | HexMultiGrid | mesa.discrete_space.HexGrid +Network = NetworkGrid | mesa.discrete_space.Network def collect_agent_data( @@ -133,7 +133,7 @@ def draw_space( # https://stackoverflow.com/questions/67524641/convert-multiple-isinstance-checks-to-structural-pattern-matching match space: # order matters here given the class structure of old-style grid spaces - case HexSingleGrid() | HexMultiGrid() | mesa.experimental.cell_space.HexGrid(): + case HexSingleGrid() | HexMultiGrid() | mesa.discrete_space.HexGrid(): draw_hex_grid(space, agent_portrayal, ax=ax, **space_drawing_kwargs) case ( mesa.space.SingleGrid() @@ -142,7 +142,7 @@ def draw_space( | mesa.space.MultiGrid() ): draw_orthogonal_grid(space, agent_portrayal, ax=ax, **space_drawing_kwargs) - case mesa.space.NetworkGrid() | mesa.experimental.cell_space.Network(): + case mesa.space.NetworkGrid() | mesa.discrete_space.Network(): draw_network(space, agent_portrayal, ax=ax, **space_drawing_kwargs) case ( mesa.space.ContinuousSpace() @@ -221,7 +221,7 @@ def draw_property_layers( layer = property_layers.get(layer_name, None) if not isinstance( layer, - PropertyLayer | mesa.experimental.cell_space.property_layer.PropertyLayer, + PropertyLayer | mesa.discrete_space.property_layer.PropertyLayer, ): continue diff --git a/tests/test_cell_space.py b/tests/test_discrete_space.py similarity index 99% rename from tests/test_cell_space.py rename to tests/test_discrete_space.py index 7f4dd820b65..42e61d14780 100644 --- a/tests/test_cell_space.py +++ b/tests/test_discrete_space.py @@ -6,7 +6,7 @@ import pytest from mesa import Model -from mesa.experimental.cell_space import ( +from mesa.discrete_space import ( Cell, CellAgent, CellCollection,