Abstract space and grid implementation

[adamamer20]

Still a work in progress, not everything described below has been implemented yet.
For now, only the GridDF class is completely implemented into GridPolars and GridPandas. The implementation of GeoGridDF, Network, and ContinousSpaceDF will be addressed in their own separate PRs.

Still missing

• Implement tests for GridPandas and GridPolars (maybe using hypothesis/deal?)
• Implement MultiSpaceDF
• Make sure grid remains updated every time agents are added or removed (maybe lazy collection?)

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.

Implementation Details for GridDF

Pandas Implementation

• Uses np.full at the start to generate the empty grid, filling with int values corresponding to the specified capacity
• Grid is kept updated when users add agents or change cell capacities

Polars Implementation

• Uses pl.arange with lazy evaluation
• Two implementations:
  1. Fully lazy: Only possible if all cells have the same capacity
  2. Eager: Used when cells can have different capacities
• TODO: Benchmark to assess performance difference between lazy and eager implementations

Common Methods

• get_neighbors: Implemented on top of get_neighborhood instead of get_distance
  • Rationale: Should be faster for dense spaces, while get_distance might be faster for sparse spaces
  • TODO: Consider implementing conditional use based on space density
• move_to_empty: Implementation delayed due to challenges in avoiding generation of entire grid coordinates
  • Current implementation generates coordinates for the entire grid
  • TODO: Explore optimizations to reduce computational overhead

Open Questions and Future Improvements

1. Implement the pos property for AgentContainer
2. Optimize the move_to_empty method
3. Consider implementing an indexer class for cells, neighborhood, and neighbors (similar to pandas .loc)
   • This would allow operations like .neighbors[pos] or .neighbors[agents]
   • Challenge: Resolving ambiguity when both pos and agents can be sequences of integers
4. Evaluate the use of generics for GridDF (e.g., GridDF[Pandas] or GridDF[Polars]) to simplify imports and usage
   • This is particularly relevant given the discussion on generics in Towards a unique AgentSet class #12
   • Rationale: Few users are likely to subclass GridPandas or GridPolars directly

[rht]

It's overkill to have all the features listed implemented in a single PR. Can we make it slightly smaller by implementing just enough for Boltzmann wealth model and Sugarscape CG? No continuous space and geo are necessary yet.

[adamamer20]

You're right. Let me split up in different PRs. The rest of non-implemented features will become open issues.

1. Abstract SpaceDF
2. GridDF
3. GridPandas
4. GridPolars