Move mesa.experimental_cell to mesa.discrete_space

.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

docs/apis/api_main.md

@@ -7,6 +7,7 @@ model
 agent
 time
 space
+discrete_space
 datacollection
 batchrunner
 visualization

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:
+```

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
 

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",
+]

mesa/experimental/cell_space/cell.py → 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

mesa/experimental/cell_space/cell_agent.py → 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):

mesa/experimental/cell_space/cell_collection.py → 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")
 

mesa/experimental/cell_space/discrete_space.py → 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)
 

mesa/experimental/cell_space/grid.py → 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,
 )

mesa/experimental/cell_space/network.py → 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]):

mesa/experimental/cell_space/property_layer.py → 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)

mesa/experimental/cell_space/voronoi.py → 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:

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

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
         )
 

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):

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):

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

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

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):

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
 
 

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"]

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,
+)

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.

mesa/visualization/components/altair_components.py

@@ -8,7 +8,7 @@
 with contextlib.suppress(ImportError):
     import altair as alt
 
-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