Proposal: Flexible move_agent method that allows multiple movement strategies

[EwoutH]

The Mesa Space module allows a few specific agent movements and interactions within a grid environment. However, the current methods lack a consistent way to apply different movement strategies. This proposal suggests integrating a single, versatile move_agent method, accepting a parameter that can either be a tuple for specific coordinates, a string indicating a movement strategy (like "random" or "empty"), or an object defining a neighborhood.

In the future, it can be extended with movement strategies based on properties (see #1898).

Motivation

I was building a toy model, and

x = self.random.randrange(self.grid.width)
y = self.random.randrange(self.grid.height)
self.grid.place_agent(a, (x, y))

just looked weird and limited.

Proposed changes

1. Unified move method:

   • move_agent(agent: Agent, destination) → None
   • The destination parameter is versatile:
     • It can be a tuple (x, y) for moving the agent to specific coordinates.
     • It can be a string, such as "random" for a random cell, "empty" for a random empty cell.
     • It can be an object or a dictionary defining a neighborhood, allowing custom definitions of neighboring cells. For this we need a formal neighborhood definition, see #1900.

2. Retiring redundant methods:

   • Methods like move_to_empty and place_agent would be redundant and can be removed, as their functionalities are integrated into the new move_agent.

3. Enhanced out-of-bounds and validity checking:

   • Maintain out_of_bounds method, but possibly enhance it to include checks for cell occupancy, ensuring valid movement destinations.

4. Agent removal and position swapping:

   • remove_agent and swap_pos methods remain useful and unchanged.

Example Implementations

• Moving to a Specific Cell:

  space.move_agent(agent, (x, y))
  

• Moving to a Random Cell:

  space.move_agent(agent, "random")
  

• Moving to a Random Empty Cell:

  space.move_agent(agent, "empty")
  

• Moving to a Custom-Defined Neighborhood: (see #1900)

  neighborhood_def = {"type": "Moore", "radius": 2}
  space.move_agent(agent, neighborhood_def)
  

Conclusion

This proposal aims to simplify and unify the movement methods in the Mesa Space module. By consolidating various movement strategies into a single method, we enhance the API's usability and flexibility, allowing users to execute complex movements with minimal and more intuitive code.

Notes

Structural Pattern Matching in Python 3.10 might help a lot with the implementation.