Proposal: Formal neighborhood definition for grids about mesa

[EwoutH]

Now really full solution of this, but some thoughts:

• In it's simplest form, a neighborhood definition can just be a dictionary:

neighborhood_def = {include_center: False, radius: 1, moore: True}

• It could also be a simple object.

class NeighborhoodDefinition:
    def __init__(self, include_center=False, radius=1, moore=True):
        self.include_center = include_center
        self.radius = radius
        self.moore = moore

• A dataclass could make this more elegant
• However, we have to consider different grid types (like hex and network) that take different keywords
• Each grid could have a get_neighborhood_definition() method that gives a definition that can be used in all methods of that grid type (whether it's a dict, object or something else).

[Corvince]

An advantage of using a simple dictionary would be to directly use the definition via unpacking. So Imho we could do

grid.get_neighbirhood(pos, **neighborhood_def)

Whenever we need the values in a traditional function.
Or do you suggest changing the API to get_neighborhood(pos, neighborhood_def)?

[Corvince]

But this issue has let me to think about how we define theesa space API and if we should switch to a more "chainable" API?

So for example instead of doing grid.get_neighbors(pos, moore, radius, center)

We do something like this

grid[pos] # get the current position (a Position)
    .neighborhood(moore, radius, center) # get the neighborhood (a PositionList)
    .agents # get the agents (an AgentList)

So we would have all those intermediate classes with their own attributes and methods.

In this case it might seem a bit verbose, but I think especially combined with properties we can have a much cleaner and more powerful way of extracting the things we want. I mean to say that we can have simpler functions as building blocks for complex logic and not having highly specialized functions like move_agent_to_extreme_value_cell.

What do you think?

[EwoutH]

Thanks for the insights!

I like both ideas of the dictionary unpacking and the chainable API (feels a bit like Pandas). I don't know yet which I prefer.

It might be useful to discuss this at the dev meeting.