Proposal: Flexible move_agent method that allows multiple movement strategies about mesa

[EwoutH]

I was thinking about how this would integrate with the _PropertyGrid introduced in #1898. That currently offers separate functions for the selection of target cells, and then moving to the target cells.

def select_cells_by_properties():
def move_agent_to_cell_by_properties():
def select_extreme_value_cells():
def move_agent_to_extreme_value_cell():

If move_agent would also take a list or mask of target cells, that could allow removing the two movement methods from #1898, and make the API more consistent. All movement goes through move_agents, and any amount of custom methods can be written to select some target cells.

Currently, #1898 also include two mask functions which limit the number of candidate cells to cells empty or in a neighborhood.

def get_empty_mask():
def get_neighborhood_mask():

We might also want to integrate that into the move_agent method. It could take a mask or a list of masks.

A utility method to combine a list of masks into a single mask could also be provided.

[EwoutH]

Maybe we can combine things:

def move_agent(agent, pos=None, empty=False, neighborhood=None, mask=None, selection="random"):

• pos: A single position or list of possible positions
• empty: False allows all cells, True only empty ones
• neighborhood: Optional neighborhood (#1900)
• mask: a mask or list of masks of allowed input cells
• selection: Can be "random" or "closest". Maybe something else in the future (in the _PropertyGrid it could be highest or lowest maybe).

[EwoutH]

@jackiekazil @tpike3 Same story as with #1905, I would like to discuss and potentially implement this before moving on the PropertyLayer (#1898), since this is a more generalized solution for a problem that I specifically solve in that PR. So if we can implement this, it would make especially the _PropertyGrid in #1898 a lot simpler.

So my specific questions are:

1. Do you agree we should expand the built-in move_agent() movement method to allow moving to an empty, random or neighbouring cell?
2. What do you think of the current proposed API? Do you like the initial one better or the last one?

[EwoutH]

I went for a relatively simple implementation: The move_agent method now can take a list of positions and choose either one randomly or the closest:

• #1920

Selecting neighborhoods and empty cells can be done with other functions, and support for masks will be added in #1898.