warn if placing already placed agent

While it might be desired in a specific model to have the same agent
be placed in multiple spots simultaneously, the typical use case is
that one agent has one position at every given moment. This commit
adapts the place_agent() method in a way that it emits a warning when
called with an agent which already has a location.

Fixes: #1522

mesa/space.py

@@ -21,6 +21,7 @@
 import contextlib
 import inspect
 import itertools
+import logging
 import math
 import warnings
 from collections.abc import Iterable, Iterator, Sequence
@@ -51,6 +52,7 @@
 MultiGridContent = list[Agent]
 
 F = TypeVar("F", bound=Callable[..., Any])
+logging.basicConfig(format="%(levelname)s:%(message)s", level=logging.WARNING)
 
 
 def accept_tuple_argument(wrapped_function: F) -> F:
@@ -71,6 +73,21 @@ def is_integer(x: Real) -> bool:
     return isinstance(x, _types_integer)
 
 
+def warn_if_agent_has_position_already(placement_func):
+    def wrapper(self, agent, *args, **kwargs):
+        if agent.pos is not None:
+            logging.warn(
+                """You're placing agent %s which already has
+the position %s. In most cases, you'd want to clear the current
+position with remove_agent() before placing the agent again.""",
+                agent.unique_id,
+                agent.pos,
+            )
+        placement_func(self, agent, *args, **kwargs)
+
+    return wrapper
+
+
 class _Grid:
     """Base class for a rectangular grid.
 
@@ -976,6 +993,7 @@ class SingleGrid(_PropertyGrid):
                  the grid for empty spaces.
     """
 
+    @warn_if_agent_has_position_already
     def place_agent(self, agent: Agent, pos: Coordinate) -> None:
         """Place the agent at the specified location, and set its pos variable."""
         if self.is_cell_empty(pos):
@@ -1024,6 +1042,7 @@ def default_val() -> MultiGridContent:
         """Default value for new cell elements."""
         return []
 
+    @warn_if_agent_has_position_already
     def place_agent(self, agent: Agent, pos: Coordinate) -> None:
         """Place the agent at the specified location, and set its pos variable."""
         x, y = pos
@@ -1355,6 +1374,7 @@ def _invalidate_agent_cache(self):
         self._agent_points = None
         self._index_to_agent = {}
 
+    @warn_if_agent_has_position_already
     def place_agent(self, agent: Agent, pos: FloatCoordinate) -> None:
         """Place a new agent in the space.
 
@@ -1515,6 +1535,7 @@ def default_val() -> list:
         """Default value for a new node."""
         return []
 
+    @warn_if_agent_has_position_already
     def place_agent(self, agent: Agent, node_id: int) -> None:
         """Place an agent in a node."""
         self.G.nodes[node_id]["agent"].append(agent)