Refactoring mesa.space

[adamamer20]

Roadmap

• Abstract SpaceDF #39
• Abstract DiscreteSpaceDF #40
• Abstract GridDF #41
• Concrete GridPandas #34
• Concrete GridPolars #35
• Concrete ContinousSpaceDF #36
• Concrete MultiSpaceDF #37
• Concrete GeoGridDF #38
• feat: Adding Concrete NetworkDF #47

Class Structure and Design

SpaceDF

• Base class for all spaces
• Defines a common interface for all spaces
• Stores agent positions in the _agents attribute in a DataFrame/GeoDataFrame. This approach avoids many missing values in the AgentSetDF and reduces confusion when multiple spaces of the same type are present (e.g., an agent in both a grid and in a social network)
• TODO: Implement a pos property for AgentContainer that performs an instant join with the space _agents DataFrame

MultiSpaceDF

• Stores the collection of spaces in a model, similar to AgentsDF

DiscreteSpaceDF

• Defines an interface for GridDF and NetworkDF
• Supports setting cell properties at both class level (setting an attribute of the class) and cell level (using the set_cells method)
• In addition to _agents stores cell properties in the _cells attribute in a DataFrame. The _cells DataFrame explicitly stores only cells that have agents or have specific properties different from the class level

ContinousSpaceDF

• Stores agents in a GeoDataFrame (only geopandas in the future)
• Bridges mesa and mesa-geo
• All agents are geoagents and shapely objects
• Can be used as a continuous space in mesa without setting CRS, or as a geospace in mesa-geo by setting CRS

GridDF

• Implemented in both GridPolars and GridPandas versions
• Supports multiple dimensions
• The '_empty_grid' attribute stores the remaining capacity of the grid.

GeoGridDF

• Position in the class hierarchy still to be determined
• Is it possible to create a unique class or attempt to merge with GridDF? Probably not possible to merge as GridDF supports multiple dimensions, while shapely objects are limited to 2 dimensions.

[rht]

Can't wait for this feature. This is the only blocker to me implementing mesa-frames version of Sugarscape constant growback. It boils down to implementing the move within the space: https://github.com/projectmesa/mesa-examples/blob/668eb974ffdaaf2d20ca9a5fd7ba828f1b043426/examples/sugarscape_cg/sugarscape_cg/agents.py#L40-L61. Only eat and die part of the step can be DF-vectorized as of now.

[adamamer20]

Can't wait for this feature. This is the only blocker to me implementing mesa-frames version of Sugarscape constant growback. It boils down to implementing the move within the space: https://github.com/projectmesa/mesa-examples/blob/668eb974ffdaaf2d20ca9a5fd7ba828f1b043426/examples/sugarscape_cg/sugarscape_cg/agents.py#L40-L61. Only eat and die part of the step can be DF-vectorized as of now.

Let me ensure I understood correctly the issue. The available spaces are the neighborhood spaces which are not occupied. The problem is that in the traditional Sugarscape model, since the step is sequential for agents, there is a race condition. If parallelized, we could have two agents that select the same space at the same time.
What if we were to run an iteration across all agents, select randomly one of the agents which have a duplicate neighborhood, and then run the choice algorithm again on the agents with duplicates that are not selected? This approach is not as efficient as parallelizing everything at once, but it shouldn't require many iterations to resolve conflicts.

[rht]

Yeah, that (update the position in parallel, then do tie-breaking) is the method used in the FLAME 2 implementation of Sugarscape instantaneous growback (i.e. simpler version of constant growback, where the sugar grows to max value in the next step right after being consumed; constant growback has a growing rate), in figure 6. Here is their code.

[adamamer20]

I see, that's very interesting that it's so recent! Do you think tie-breaking should be left to the user or handled by the library? Depending on the model, it can be either very simple or very complex to handle tie-breaking, similar to the challenge of vectorizing user-defined functions. Perhaps it would be better to include a section in the documentation on how to deal with race conditions?

[rht]

I think the basic version move_to_empty and move_to_empty_neighborhood should be handled by the library. They can be a starting point for users who want to implement more complex move logic. The former is used by the Schelling model. But the Boltzmann wealth model and Wolf sheep simply use moving to anywhere within the neighborhood.

[adamamer20]

@rht Do you think it would be better to convert DataFrames to GeoDataFrames with the respective geo-library if space is added to the model or simply adding a position/geometry column?
I think the first way would be much more powerful for the end-user but geopolars is currently 0.1.0-alpha4 and breaking changes are expected. Nevertheless, I would still go for the geolibraries.

[rht]

Which one is faster to implement? I have no strong opinion on either, as long as there could be a common API -- unlikely? Because Mesa-Geo and Mesa's current space.py have different API. If designing a common API is too much at this stage, my only requirement is that it shouldn't be too much boilerplate code for user who starts learning by doing Schelling or Boltzmann wealth model.

Note that in core Mesa, we are moving away from the old space.py implementation to a new cell-based implementation, https://github.com/projectmesa/mesa/tree/main/mesa/experimental/cell_space, that is conceptually simpler (see e.g. the get neighborhood method, https://github.com/projectmesa/mesa/blob/2cee49efeac07ea44342b918b2db6fb170649793/mesa/experimental/cell_space/cell.py#L132) but also sufficiently performant (the PR itself).

But the structure in core Mesa that is closer to Mesa-Geo is the new experimental PropertyLayer (the PR for more context and examples).