Conceptual model of Space #2585
Replies: 16 comments 45 replies
-
|
Thanks for this. It's really helpful. My 2 cents:
|
Beta Was this translation helpful? Give feedback.
-
|
Then, back to the spaces. Let's do a fun thought experiment and explore what would happen if we tried to design Mesa without spaces, similar to how we discovered we didn't need schedulers (in #1912). With schedulers, we found they were essentially enforcing activation policies that could be more clearly and flexibly expressed directly in model code using AgentSets. However, when we try to decompose spaces, we run into a different kind of challenge. Let's imagine distributing space responsibilities:
At first glance, this seems appealing:
However, spaces solve fundamentally different problems than schedulers did. While schedulers were essentially doing stateless operations on agent lists (which we could replace with AgentSet operations), spaces maintain complex stateful relationships and invariants that are much harder to distribute. In a spaceless design, you encounter a few potential issues:
Without spaces, we'd likely need to recreate many of these features to solve performance and consistency challenges. Each agent would need its own spatial indexing, neighbor computation would be O(n²), and maintaining consistent relationships would be complex. This leads me to believe that spaces are a fundamentally valuable abstraction, but perhaps we could simplify them. The cell space and new continuous space are already going into the right direction, by making the position Agent-owned. Maybe there are more things that make sense to be Agent owned. Some open questions:
Further more, specifically spaces maintaining neighbour relations: Lot's of ideas here, but I think taking a step back and looking critically at the requirements and separation of concerns can be quite beneficial in the long term. |
Beta Was this translation helpful? Give feedback.
-
|
Relationships exist between agents. If one agent moves, this changes the neighbors not just of itself but also (and unbeknownst to them) the neighbors of other agents. As such, there is allways a need for something that can be queried to return neighbors. In cell spaces, this neighborhood relation is kept by the In continuous spaces, you don't have an obvious equivalent of a cell. Positions are infinite, and so it makes no sense to create all positions. Moreover, how positions are related is defined by the distance metric. Implicitly, we are using an Euclidian metric for this. Since we don't have an obvious equivalent for cells, in #2584, I decided to let the space handle the distances (i.e., how positions are related to each other), while the Agent has methods for figuring out who its neighbors are. so, in response to your questions
|
Beta Was this translation helpful? Give feedback.
-
|
That last reply was a bit all over the place, I have been trying to narrow it down a little bit more. I come to the same conclusion of neighbors being a relation between agents. It seems to make sense to have some patterns that formalizes those, like a grid, hex, network or distance. In the real world, this becomes often a bit more messy, especially if you consider things like perceived proximity or social relations. Therefore it makes sense to be able to flexibility alter neighbours. I can imagine model were I keep a "familiar" space, and everytime I visit a location it has a chance of being added to my familiar space. Or the perceived "distance" may become smaller once you frequent there more often. And this way you can have spaces represent many different relationships, including physically spatial ones. In the end a "space" is just something that defines relations between entities. Therefore, I seems obvious to me that an Agent has different spaces in which it can search for features of interest. In one space it might search for a quick path/route to something, in another a resource to utilize, in another which friend to visit. Each space has different entities in it, because you're searching over different things. Friend in radius X, or the closest N ones, is completely different from where to get food. It's also way more efficient to have that in multiple spaces, since you don't need to search over entities you're not needing anyway. So the concept of (n-order) neighbours becomes inherently linked to which space I'm searching in. And thus it seems logical that neighbours are functions of spaces, or functions of agents that take a space as input. The space has to be made explicit. Let me illustrate this with some API examples: First, setting up different spaces for different types of relationships: class CityModel(mesa.Model):
def __init__(self):
super().__init__()
# Different spaces for different types of relationships
self.physical_space = mesa.space.ContinuousSpace(100, 100)
self.social_space = mesa.space.NetworkSpace()
self.familiar_space = mesa.space.AdaptiveSpace(
distance_func=lambda a, b: self._calculate_familiarity(a, b)
)The spaces own the neighbor-finding logic, which agents can query: class Person(mesa.Agent):
def find_friends(self):
# Find friends within social distance 2
friends = self.model.social_space.get_neighbors(self, distance=2)
return friends
def find_nearby_resources(self):
# Find physical resources within 10 units
resources = self.model.physical_space.get_neighbors(
self,
radius=10,
agent_type=Resource
)
return resourcesThe familiar space can adapt over time as agents interact: def record_interaction(self, other_agent):
# Record that these agents have interacted
self.model.familiar_space.add_interaction(self, other_agent)
def find_familiar_locations(self):
# Find places the agent frequently visits
familiar_spots = self.model.familiar_space.get_neighbors(
self,
distance_threshold=0.5 # Familiarity score threshold
)
return familiar_spotsYou can also combine spaces for more complex queries: def find_friends_nearby(self):
# Find friends who are both socially and physically close
social_friends = self.model.social_space.get_neighbors(self, distance=1)
physical_neighbors = self.model.physical_space.get_neighbors(self, radius=5)
return [agent for agent in social_friends if agent in physical_neighbors]Each space defines its own way of calculating distances and neighborhoods: class AdaptiveSpace:
def _calculate_distance(self, agent1, agent2):
interaction_count = self.interaction_history.get((agent1, agent2), 0)
time_known = self.current_step - self.first_meeting.get((agent1, agent2), 0)
return 1.0 / (1.0 + interaction_count * np.log(1 + time_known))
def get_neighbors(self, agent, distance_threshold):
return [
other for other in self.agents
if self._calculate_distance(agent, other) < distance_threshold
]This makes it clear that spaces own the relationship logic, while agents simply query the spaces they're interested in. Each space can implement its own efficient methods for calculating and caching relationships. |
Beta Was this translation helpful? Give feedback.
-
|
Conceptually, I see value in an agent being part of multiple spaces. Practically, I fail to see a convincing use case so far. By the way, there is nothing in MESA that limits you at the moment in implementing agent membership in multiple spaces if needed. The custom agent classes all implicitly assume a single space. However, it would be trivial to implement your own custom subclass allowing an agent to be part of both a cell space and a continuous space. Likewise, the visualization side will break (but this is already true for multiple spaces in a single model). Why don't I see a practical use case? Take the example above, the social network is not a proper discrete space: there are no "cells" that an agent occupies, nor will the agent move from one cell to another. I don't follow what is going on in the adaptive space example. Here, it seems to be about agent familiarity, so there is nothing external to the agents that defines nearness. |
Beta Was this translation helpful? Give feedback.
-
|
A primary use of spaces is expressing neighbour relations, in a performant way. I might have an Agent that wants to have different definitions of what it considers spatial neighbours based on what it's doing or with whom it's interacting. So either we should:
A second use is requesting properties. Currently, those are quite tightly coupled to spaces. And thus, they need to follow the resolution of that space. When you only allow a single space, all your properties should have the same resolution. Which not always might make sense. Therefore, we should:
|
Beta Was this translation helpful? Give feedback.
-
For me, this is a no-go. The entire point of a space is that it defines what is close and far and thus specifies neighborhood relationships. This is why I agree with you that, conceptually, an agent can be part of multiple spaces. The issue thus revolves around having agent classes that allow for multiple "locations", which is trivial to implement already on a case-by-case basis, but very hard to implement generically. That is, in my view, nothing needs to change in MESA itself because it is already possible but requires some coding by the user. On the property side of things, I am not convinced we need to change anything either. Properties are currently tied to discrete spaces only and follow the coordinate system of that space. Why would that need to change even if an agent can be part of multiple spaces? Properties are understood as being properties of that space so why decouple them. |
Beta Was this translation helpful? Give feedback.
-
|
While I agree with most, I might view it a little differently:
In my view an Agent has a single (physical) location, but different spaces can express different neighbour relations and properties. Maybe, it's good enough if an Agent is only present in one space, but can request Agents, properties and neighbours in other spaces. For example, the bird in the ContiniousSpace (air) requesting the largest tree nearby in the Cell space (ground). This way, an agent is present in one space, but can still communicate with Agents in other spaces, based on a shared coordinate system. |
Beta Was this translation helpful? Give feedback.
-
|
Partly based on #2592, I am beginning to realize that there is a difference between getting neighbors of an agent and getting the agents within the vicinity of a given coordinate. It is failing to make this distinction that is behind the bug in #2592. So, this would imply that spaces need to have methods for getting agents given some valid coordinate (e.g., for continous spaces Having methods on spaces for getting agents and having methods on agents for getting neighbors would allow for most of what you want to do, I think. It would be quite easy, to add the relevant methods to |
Beta Was this translation helpful? Give feedback.
-
|
I've been in discussion with some people (@SongshGeo @AdamZh0u @LunnyRia @peter-kinger and a few others) who are interested in working on mesa/mesa-geo#201, and we came up with a proposed design for mesa-geo v1.0 (see figure below). Not sure whether it relates to this discussion, but the new design is very similar to the experimental cell space. Linking to Mesa spaces, we can think of the VectorLayer as the ContinuousSpace, and RasterLayer as the GridSpace. This perhaps resembles the idea of having multiple spaces (i.e., layers in mesa-geo) discussed above. We may even go beyond spaces and have a ModelCollection that allows stepping several models inside a metamodel, in a hierarchical manner. I don't know whether this is what @tpike3 wants for a multi-level mesa. Nonetheless it is beyond the scope of our current discussions and thus not included in the figure.
|
Beta Was this translation helpful? Give feedback.
-
|
Thank you for mentioning everyone involved in the discussion, including myself ;) I'm sorry for seeing this discussion for the first time and for not taking the time to familiarize myself with the related content. I see the potential value of allowing users to belong to multiple spaces. However, there should only be one physical geographic space, so this should not affect our vision of Mesa-Geo. That said, I would like to express some opinions regarding methods like "get_neighbors," where defining neighbours (i.e., distance) is crucial. If we allow potentially different types of spaces, then, for example, neighbours can be different in network-like space compared to geographic-like space. From a conceptual model perspective, obtaining the distance between two agents is a method of space, while getting neighbours is a method of Agent. It would be best to have a default parameter indicating which space this method is called in. |
Beta Was this translation helpful? Give feedback.
-
Exactly! And as long as we ensure all spaces have proper methods for getting agents within the vicinity of a given valid coordinate within that space, agents have tremendous flexibility. We might even standardize this in a protocol for all spaces: let them have
Not sure about this, but at least within MESA we might provide standard Agent classes that work well for a given space X (so |
Beta Was this translation helpful? Give feedback.
-
Fair enough. I agree that it's not necessary to write it in MESA; having more space is a redundant feature for most users. Those who need to write such complex models have their own ways of achieving it. My comment simply stated that if needed, the API should generally be like this. In fact, I don't think it is necessary for MESA. What is needed now is a stable API and more solid testing. |
Beta Was this translation helpful? Give feedback.
-
This gets me thinking, shouldn't cell spaces be an extension of the continuous space, where spaces represent different ways of grouping agents? Each agent has one true continuous position, but can be part of multiple organizational structures - like how a person has one GPS location but exists in many abstract spaces (neighborhoods, social networks, jurisdictions). Think of spaces not just as physical locations, but as different ways of understanding proximity and relationships. An agent could simultaneously:
Here's how this might look in practice: class CityModel(Model):
def __init__(self):
# Base continuous space for true positions
self.physical_space = ContinuousSpace(100, 100)
# Different organizational spaces sharing the coordinate system
self.neighborhoods = CellSpace(100, 100, cell_shape="polygon")
self.terrain = CellSpace(100, 100, cell_shape="hex")
self.markets = AdaptiveSpace(
distance_func=lambda a, b: self._calculate_economic_distance(a, b)
)
class Person(Agent):
def step(self):
# Find physically close agents
nearby = self.model.physical_space.get_neighbors(self.pos, radius=5)
# Find agents in same and neighboring districts
neighborhood = self.model.neighborhoods.get_cell_neighbors(self.pos)
# Find agents in similar terrain
same_terrain = self.model.terrain.get_agents_in_cell(
self.model.terrain.get_cell(self.pos)
)
# Find trading partners within economic distance
trading_partners = self.model.markets.get_neighbors(
self, distance_threshold=0.5
)Each "space" becomes a different way of indexing and querying agents, while sharing the same underlying coordinate system. So when finding neighbors, an agent could get physically nearby agents using continuous distance, find agents in the same or adjacent neighborhoods, identify agents in similar terrain, query their social connections, or find trading partners in their market region. This feels particularly powerful for complex models where agents interact through multiple channels. A city model could have agents moving continuously while simultaneously tracking their neighborhood, socioeconomic group, and social networks - each represented by a different space layered on top of their physical position. This approach would let us keep the precision of continuous positions while adding unlimited organizational structures for different types of relationships and groupings. |
Beta Was this translation helpful? Give feedback.
-
|
To continue this brain dump, discrete spaces could have an underlying network defining relationships between cells. Each cell doesn't just have to use spatial adjacency - we could have explicit connections defining how "close" cells are through different networks. Take a city road network for example - each intersection could be a node, with streets as edges. We could then create cells using Voronoi tessellation, where each cell contains the area closest to its intersection. The network connections (streets) between intersections would define the actual distance relationships between cells, stored in either a NetworkX graph or distance matrix. Here's how this might look: class NetworkedCellSpace(CellSpace):
def __init__(self, width, height, network):
super().__init__(width, height)
self.network = network # NetworkX graph or distance matrix
self.voronoi_cells = self._generate_voronoi_cells()
def get_path_between_cells(self, start_cell, end_cell):
"""Find shortest path between cells using network"""
return nx.shortest_path(
self.network,
start_cell,
end_cell,
weight='distance'
)
class Person(Agent):
def move_to_target(self, target_pos):
# Find which cell contains the target position
target_cell = self.model.road_space.get_cell(target_pos)
current_cell = self.model.road_space.get_cell(self.pos)
# Get path through road network
path = self.model.road_space.get_path_between_cells(
current_cell,
target_cell
)
# Move along path
next_cell = path[1] # Next cell in path
self.model.road_space.move_agent(self, next_cell.center)This would be super useful for:
We could even have multiple networks for different transportation modes (walking, driving, public transit), each defining different distance relationships between the same cells. Agents could then choose routes based on their available transport options. |
Beta Was this translation helpful? Give feedback.
-
|
I want to challenge one of our core assumptions: Do agents actually need a single unified position? The "one true position" idea sounds elegant, but it breaks down when we consider different space types:
These aren't interchangeable or meaningfully convertible. A social network node isn't a coordinate you can map to (x, y). An agent's position in an "economic space" based on wealth similarity has no physical location. Two Distinct ConceptsI think we're conflating:
Architectural Inconsistency in Current MesaLooking at our current implementations, we already have two different architectures: Discrete Spaces (cell_space):
Continuous Spaces (experimental):
This inconsistency suggests we need to think about architectural unification. Options for Unifying SpacesOption A: Space Owns EverythingMake discrete spaces work like continuous spaces - space owns all agent-location mappings: # All spaces own the agent→location relationship
class DiscreteSpace:
def get_cell(self, agent) -> Cell:
return self._agent_to_cell[agent]
def move_agent(self, agent, new_cell):
# Space manages the relationship
...
class ContinuousSpace:
def get_position(self, agent) -> np.ndarray:
return self._agent_positions[self._agent_to_index[agent]]
# Agents query spaces
neighbors = space.get_neighbors(agent, radius=5)Pros: Consistent architecture, space controls optimization, clear separation of concerns Option B: Protocol-BasedDefine what spaces must provide, but don't enforce how: class SpatialSpace(Protocol):
def get_location(self, agent: Agent) -> Any: ...
def move_agent(self, agent: Agent, location: Any) -> None: ...
def get_neighbors(self, agent: Agent, **kwargs) -> list[Agent]: ...
# Each space implements however makes sense internally
class DiscreteSpace: # Can keep current cell-based implementation
def get_location(self, agent):
return self._agent_to_cell[agent]
class ContinuousSpace: # Uses efficient numpy arrays
def get_location(self, agent):
return self._agent_positions[self._agent_to_index[agent]]
# Usage is explicit and clear
physical_neighbors = model.physical_space.get_neighbors(agent, radius=5)
social_contacts = model.social_network.get_neighbors(agent, hops=2)Pros: Maximum flexibility, no required inheritance, easy multiple spaces, explicit queries Option C: Hybrid ApproachSpace owns data, but agents have convenience properties: # Space is source of truth
class DiscreteSpace:
def get_cell(self, agent) -> Cell:
return self._agent_to_cell[agent]
# Agent has convenience property that delegates
class CellAgent(Agent):
@property
def cell(self):
return self._space.get_cell(self)
@cell.setter
def cell(self, new_cell):
self._space.move_agent(self, new_cell)Pros: Keeps convenient API, space still controls data, backward compatible When Spaces AlignThe powerful case is when multiple spaces DO share a coordinate system: class FireModel(Model):
def __init__(self):
# These spaces share coordinates - fire on ground affects air
self.ground = CellSpace(100, 100, coordinate_system="physical")
self.air = ContinuousSpace([[0, 100], [0, 100]], coordinate_system="physical")
class Tree(Agent):
def __init__(self, model, position):
super().__init__(model)
model.ground.add_agent(self, position)
def step(self):
# Query different space types using same coordinate system
my_cell = self.model.ground.get_cell(self)
air_temp = self.model.air.get_property("temperature", my_cell.center)ConsiderationsI'm not sure which way to go at this point. Protocol-based might be the most flexible, it has a few advantages:
This means:
Open questions:
Impact on Agent CompositionThis protocol-based approach also solves the agent composition complexity discussed in https://github.com/projectmesa/mesa/pull/2584/files#r1907499549. If agents don't need space-specific base classes, the composition problem disappears: # No more ContinuousSpaceAgent, CellAgent, etc.
# Just Agent querying whatever spaces it needs
class Boid(Agent):
def __init__(self, model):
super().__init__(model)
model.air_space.add_agent(self, position=[50, 50])
def step(self):
neighbors = self.model.air_space.get_neighbors(self, radius=5)
class HybridAgent(Agent):
def __init__(self, model):
super().__init__(model)
# Register in multiple spaces - no special inheritance needed
model.physical_space.add_agent(self, position=[30, 40])
model.social_network.add_agent(self, node=5)
def step(self):
# Query whichever space is relevant
physical_neighbors = self.model.physical_space.get_neighbors(self, radius=10)
social_contacts = self.model.social_network.get_neighbors(self, hops=2)No capability injection, no multiple inheritance, no magic - just agents querying spaces explicitly. I'm increasingly thinking the explicit space query approach is cleaner and more aligned with our "spaces own the relationship logic" philosophy. Agents don't need special capabilities - they just need to know which space(s) to query. Curious what everybody thinks! |
Beta Was this translation helpful? Give feedback.
-
|
I don't follow your claimed inconsistency. In discrete spaces, we have |
Beta Was this translation helpful? Give feedback.
-
|
I have always argued for an agent-centric API when it comes to spaces, as compared to the space-based api used in Mesa 2. That is, I prefer Moreover, there have been and are still quite a few open issues on adding agent movement functionality. Again, this in my view points to favouring an agent-centric API over a space-centric API. Now, an agent-centric API might still be improved through a protocol-based approach with reference implementations that can serve as examples/templates if a user needs support for multiple different spaces. |
Beta Was this translation helpful? Give feedback.
-
|
Can we do something like this? With multiple spaces, you make the space you want to access explicit: agent.physical.position += velocity
agent.social.node = new_friend
agent.grid.cell = new_cellIf only a single space is defined, we can allow shorthand: agent.position += velocity # OK for single space
agent.position += velocity # ⚠️ Warning if multiple spaces
This reminds me, we probably should work out #2228 to work well. |
Beta Was this translation helpful? Give feedback.
-
|
It would be quite convoluted to make something like that work if it is even possible. At the moment, we rely on inheritance to make class MyAgent(Agent):
position = ContinousSpaceLocation()
node = NetworkLocation()
cell = GridLocation()
...
# and then elsewhere
self.positon += velocity
self.cell = new_cell
# etc.With this, you could even allow for multiple locations in the same type of space by just doing class MyAgent(Agent):
position_a = ContinousSpaceLocation()
position_b = ContinousSpaceLocation() |
Beta Was this translation helpful? Give feedback.
-
|
I think that last proposal makes a lot of sense. It's explicit. It allows one location to be used in multiple spaces, as long as they are of compatible types. It potentially removes inheritance. If we can get all the functionality in some Next step is probably a PoC? Took some turns, but a fruitful discussion already! |
Beta Was this translation helpful? Give feedback.
-
|
I had a quick look at the current code. For discrete spaces, we have at the root of the hierarchy For ContinuousSpace, it's more problematic because we lack the equivalent of In summary, I think the basic idea of composition can be done by:
|
Beta Was this translation helpful? Give feedback.
-
|
I think I compiled an "ultimate" use case which you are doing about everything you can possibly want to do in an spatial-based ABM. We can use it to further develop our conceptual model of space. Note that:
Model overviewA simplified agent-based model where citizens decide whether to migrate between cities based on environmental conditions, transportation networks, and social connections. A region contains multiple cities connected by road and rail networks, where citizens live, work, and travel. Citizens make daily travel decisions (commuting, visiting friends, business trips) using either roads or rails, with road speeds affected by congestion. Over longer timescales, citizens may decide to permanently migrate to different cities based on environmental conditions (temperature, agricultural fertility), economic opportunities, social connections (where their friends live), and ideological compatibility (finding like-minded people). The atmospheric conditions provide environmental context that affects both daily comfort and long-term livability, while the fertility layer influences the economic prosperity of different regions. Spaces1. Air Space (Continuous)
2. City Space (Voronoi Cells)
3. Road Network
4. Rail Network
5. Fertility Layer
6. Social Network
7. Perception Space
Agents: CitizensPosition References
Key Behaviors
Testing RequirementsMultiple coordinate systems:
Different position types:
Cross-space queries:
|
Beta Was this translation helpful? Give feedback.
-
|
I have said this before in this discussion: for each of these "spaces" why would you implement that as a space in MESA? In mesa, a space specifies nearness to other agents and a way of moving around, changing your nearness to other agents unknown to you. Because of this, I would rarely implement transport networks or social networks using a NetworkSpace. Instead, a simple network using your preferred network library would suffice. This point, however, does not imply that enforcing a single space/coordinate system is the way to go. In fact, I am slowly coming around to the idea that designing things in such a way that they leave the user free to do whatever they want might make more sense than prematurely restricting user options. Also, an alternative example where having multiple spaces makes sense to me is an election system model I have been toying with. Here, we have political parties and citizens that coexist in a joint political position space (a 2D continuous space). Citizens also live in districts. Districts can be implemented in any discrete space you prefer (grids and Voronoi are the most straightforward options). Districts and possibly social network dynamics influence opinion dynamics, leading to citizens shifting in the political position space. Moreover, we also have evidence that people may leave districts if their political opinions differ significantly from those of others within their district. In this model, the Political Party agents exist only in the political space. Citizens exist in both the political position space and in the district space. Nearness in the political position space affects voting behavior. Nearness in the district space affects opinion dynamics. |
Beta Was this translation helpful? Give feedback.
-
I do agree, as I also noted:
We’re a library, implementing (foundational) building blocks that are useful for a large share of ABM modelers and are compatible with each other and extendable.
I don’t think we should require every space to follow it, but allow multiple spaces to use a singular, synched position, I think that offers value. It can also be seen of different layers of the same space, whatever works.
Agreed. That’s why it should be optionally synched. I think your example is very useful as well! |
Beta Was this translation helpful? Give feedback.
-
|
In #2875, while adding support for multiple spaces in agents, I mentioned in passing the idea of "derived" spaces. That is, an agent has a location in a primary space, and other spaces can inherit/use this location as well:
Thinking about this a bit more, I realized that something analogous already exists in matplotlib with We might. consider doing something similar in mesa by adding a space = ContinuousSpace([[0, 10], [0,10]], random=model.random)
another_space = Network(graph, share_location=space) |
Beta Was this translation helpful? Give feedback.
-
|
I have to think about this a bit more, but it’s definitely a valid option! |
Beta Was this translation helpful? Give feedback.
-
|
(I'm kicking in some open doors in this post, but better to have them explicit I think) @quaquel I was thinking about your "spaces define neighbours/distance". I think this is a powerful idea we should dive deeper in. So what if spaces are defined as query layers, not containers? An agent being "in" a space just means "include me in neighbor queries for this space." You could an API as clean as this I think: class Model:
def __init__(self):
super().__init__()
# Spaces are just query layers
self.space = ContinuousSpace([[0, 100], [0, 100]])
self.social_network = Network()
self.administrative_grid = VoronoiGrid(centroids)
class Agent:
def __init__(self, model):
super().__init__(model)
# Only an optional physical position
self.position = None
# No forced space membership!
# Agents don't need to know about spaces at all
# Agent presence is managed by the space
class MyAgent(Agent):
def __init__(self, model, physical_pos=None, social_connections=None):
super().__init__(model)
# Optional: register in spaces you care about
if physical_pos is not None:
model.space.add(self, position=physical_pos)
if social_connections is not None:
model.social_network.add(self, connections=social_connections)Agents can now also not be in any space, registration is relatively easy (and explicit!).
We could define a space as a class Space(Protocol):
"""Any space just needs membership and neighbor queries"""
def add(self, agent: Agent, position: ArrayLike) -> None:
"""Add agent at position (sets agent.position)"""
...
def remove(self, agent: Agent) -> None:
"""Remove agent from this space"""
...
def has_agent(self, agent: Agent) -> bool:
"""Check membership"""
...
def get_neighbors(self, agent: Agent, **criteria) -> AgentSet:
"""Get neighbors using agent.position"""
...
@property
def agents(self) -> AgentSet:
"""All agents in this space"""
...Then is the big question: How to make it performant?
My proposal would be to first hash out an API an a slow, but functional minimal version, and then try to make it performant (the latter might be a GSoC project). |
Beta Was this translation helpful? Give feedback.
-
|
If we can just update |
Beta Was this translation helpful? Give feedback.
-
|
A space could also "guide" movement, from example from a cell center to another cell center. This could especially be useful in non-square grids, like hex or Voronoi. class Space(Protocol):
...
def move(self, agent: Agent, target: Any, align: str = "center") -> None:
"""Move agent to target position, respecting this space's structure.
Args:
agent: The agent to move
target: Space-specific target (cell, direction, position, region, etc.)
align: How to align within the target ("center", "random", "closest", etc.)
"""
...
class HexGrid(Grid):
def move(self, agent: Agent, direction: str, align: str = "center") -> None:
"""Move to neighbor cell in given direction"""
current_cell = self.position_to_cell(agent.position)
neighbor_cell = current_cell.connections.get(direction)
if neighbor_cell is None:
raise ValueError(f"No neighbor in direction {direction}")
if align == "center":
agent.position = self.cell_to_position(neighbor_cell.coordinate)
elif align == "random":
# Random point within the hexagon
center = self.cell_to_position(neighbor_cell.coordinate)
offset = self.random.uniform(-self.hex_radius, self.hex_radius, 2)
agent.position = center + offset
elif align == "closest":
# Position closest to current position (always on a edge)
agent.position = self._closest_point(neighbor_cell, agent.position)
class VoronoiGrid(Grid):
def move(self, agent: Agent, target_region: Cell, align: str = "center") -> None:
"""Move to target Voronoi region"""
if align == "center":
agent.position = target_region.centroid
elif align == "random":
agent.position = target_region.random_point_inside()
class ContinuousSpace(Space):
def move(self, agent: Agent, target_position: np.ndarray, align: str = "center") -> None:
"""Move to exact position (align is ignored in continuous space)"""
agent.position = np.array(target_position)
# Usage
class MyAgent(Agent):
def step(self):
# Move to hex neighbor center (default)
self.model.hex_grid.move(self, direction="northeast")
# Move to random point in Voronoi region
target = self.find_best_region()
self.model.voronoi.move(self, target, align="random")
# Move freely in continuous space
self.model.continuous.move(self, [50, 75]) |
Beta Was this translation helpful? Give feedback.
-
|
Probably a single object for the coordinate system would be nice to have, to help with (automatic) conversions and (uniform) bounds: @dataclass(frozen=True)
class CoordinateSystem:
"""Defines a coordinate system for spatial positioning.
Args:
x: X-axis bounds as (min, max)
y: Y-axis bounds as (min, max)
z: Optional z-axis bounds as (min, max) for 3D spaces
"""
x: tuple[float, float]
y: tuple[float, float]
z: tuple[float, float] | None = None
...
# Space integration
class ContinuousSpace:
def __init__(self, coords: CoordinateSystem, *, torus: bool = False):
self.coords = coords
...
# Usage examples
coords = CoordinateSystem(x=(0, 100), y=(0, 100)) # Simple 100x100
coords = CoordinateSystem(x=(-50, 50), y=(-50, 50)) # Centered
coords = CoordinateSystem(x=(-180, 180), y=(-90, 90)) # Geographic
coords = CoordinateSystem(x=(0, 100), y=(0, 100), z=(0, 50)) # 3D
# Model with shared coordinates
class Model:
def __init__(self):
super().__init__()
# Define once
self.world = CoordinateSystem(x=(0, 1000), y=(0, 1000))
# Share across spaces
self.continuous = ContinuousSpace(self.world)
self.grid = Grid(self.world, cell_size=10) |
Beta Was this translation helpful? Give feedback.
-
|
| Concern | Where | Uses position? | Example |
|---|---|---|---|
| Coordinate system | model.world.coords |
Defines it | Bounds, validation, wrapping |
| Continuous queries | model.world or agent |
Yes (reads) | Distance, radius queries |
| Structural queries | model.world.grid |
Yes (indexes) | Cell-based neighbors |
| Spatial topology | model.world.roads |
Yes (nodes) | Graph on positions |
| Non-spatial topology | model.social_network |
No | Pure connections |
Complete API Example
class UrbanModel(Model):
def __init__(self, width=100, height=100):
super().__init__()
# Define the spatial world (shared coordinate system)
self.world = World(
coords=CoordinateSystem(x=(0, width), y=(0, height)),
torus=False
)
# Add spatial layers (all use agent.position in world.coords)
self.world.add_layer("grid", Grid(cell_size=5.0))
self.world.add_layer("districts", VoronoiGrid(centroids=[...]))
self.world.add_layer("roads", Network()) # Spatial network
# Non-spatial structures (don't use position)
self.social_network = Network() # Friendships
self.company_hierarchy = HierarchyTree() # Org chart
# Create agents
for _ in range(100):
Citizen(self)
class Citizen(Agent):
def __init__(self, model):
super().__init__(model)
# ONE position for all spatial layers
self.position = model.world.random_position()
# Register in spatial layers (all read self.position)
model.world.grid.add(self)
model.world.districts.add(self)
model.world.roads.add(self)
# Non-spatial connections (don't use position)
# (added later via social_network.add_edge)
def step(self):
# Continuous query: who's physically nearby? (uses position directly)
visible = self.world.get_neighbors_in_radius(
self,
radius=self.vision_range
)
# Grid query: same cell neighbors (position -> cell -> neighbors)
same_block = self.world.grid.get_neighbors(self, distance=0)
# Voronoi query: same district (position -> region -> neighbors)
district_members = self.world.districts.get_neighbors(self)
# Spatial network: connected by roads (follows edges between positions)
road_accessible = self.world.roads.get_neighbors(self, hops=3)
# Non-spatial network: social connections (ignores position entirely)
friends = self.model.social_network.neighbors(self)
# Move in physical space - all spatial layers see the update
target = self.find_destination()
self.world.move_toward(self, target, speed=1.0)
# Layer-specific property: what's the terrain here?
elevation = self.world.grid.get_property(self, "elevation")What Gets Reused from Current Mesa?
✅ Reuse Heavily:
- PropertyLayer system - already well-designed
- Spatial indexing from
experimental.continuous_space- the NumPy array management and distance calculations - Grid connection patterns - the offset logic for Moore, Von Neumann, Hex
- AgentSet - perfect for returning neighbor queries
⚠️ Adapt:
- Cell concept - becomes derived from position, not a container
- Movement helpers - adapt to work with
agent.position
❌ Replace:
- The "space contains agents" model
- Bidirectional cell ↔ agent relationships
- CellAgent as the primary agent type
Benefits
- Single source of truth:
agent.positionis used by all spatial layers - Clear semantics:
model.world= things sharing a coordinate system - Intuitive separation: Spatial (roads network) vs non-spatial (social network) is explicit
- Discoverable:
model.world.<tab>shows all spatial operations - Flexible: Multiple spatial views of the same geometric reality
- Performant: Each layer can optimize indexing for its structure
- No synchronization needed: All layers read the same
agent.position
Curious if this is a direction worth pursuing.
Beta Was this translation helpful? Give feedback.
-
|
Some pathfinding: |
Beta Was this translation helpful? Give feedback.
-
|
I am not sure about a lot of this.
|
Beta Was this translation helpful? Give feedback.
-
I might have a potential solution for this. There are two cases:
Both are very cheap, you just update one more value to keep everything in sync. Not even caches are needed. What's often expensive, is the whole neighbour part. We don't touch that in the world proposal above, that still 100% belongs to the grid. No changes needed. Operation 1 get's a tiny bit more complex for custom GIS spaces or things like Voronoi. But that's already the case and largely unavoidable. So as I can see it now, performance should be roughly the same in all existing cases. Only for new cases, it might be a bit slower, but that's likely very difficult to avoid. |
Beta Was this translation helpful? Give feedback.
-
|
Based on the pathfinding and discussion the last few days, I think I got a bit closer:
So that leaves you with two ways to update the agent position:
|
Beta Was this translation helpful? Give feedback.
-
|
Proof of concept: |
Beta Was this translation helpful? Give feedback.
-
|
I don't think we should overcomplicate multiple space membership. Basically:
Few example for when this would be useful:
We also shouldn't overcomplicate it. NetLogo only has continuous positions of Agents and cells (patches) for properties. Honestly, good for 90% of use cases. I would personally approach it this way:
Agents in my cell or in a next cell (concepts of neighbours) are just aggerating based on a definition of cell division and proximity according to that. So, in my visions, cells are just standardized ways to structure continuous data into more easy to handle units. A big advantage: an |
Beta Was this translation helpful? Give feedback.
-
|
On how to make this performance:
|
Beta Was this translation helpful? Give feedback.
-
Not sure what you mean by this. In my view, the user should have full control and be able to indicate through the API whether two spaces share a coordinate system or not.
The fact that NetLogo does something is, for me, generally an argument for doing the exact opposite. But, jokes aside, I fundamentally dislike this idea. Many ABMs are in fact cellular automata (e.g., Schelling segregation, Epstein civil violence, Game of Life). In all these models, the discrete nature of the space is not just an aspect of the simulation, but at the core of it. Taking a detour via float coordinates that need to be floored is likely to be wasteful from a performance perspective, for no apparent gain that I can see. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for your perspective. I think we have all the prerequisites for a good conversation Wednesday! |
Beta Was this translation helpful? Give feedback.
-
|
Seems relevant to cross-post this comment here: #3072 (comment)
|
Beta Was this translation helpful? Give feedback.
-
|
@quaquel and I had an extensive in-person discussion. We had the following conclusions:
|
Beta Was this translation helpful? Give feedback.
-
|
Now that we're talking about coordinates, rowcol indices, and the transformations between them, how would you like to name these properties of a Cell in discrete spaces? For Mesa-Geo I had an idea here mesa/mesa-geo#298 mostly to follow Rasterio's convention (see https://rasterio.readthedocs.io/en/stable/topics/transforms.html): |
Beta Was this translation helpful? Give feedback.
-
|
We were discussing the idea of a Locatable protocol. The locatable protocol would apply to Of course, all names are open for suggestions at this point. |
Beta Was this translation helpful? Give feedback.
-
|
@wang-boyu few questions:
|
Beta Was this translation helpful? Give feedback.
-
Probably. For instance:
That said, I'm not 100% certain until the concrete APIs of the new Mesa design are finalized.
Similarly as above, would have a better idea once we have the APIs.
The more Mesa-Geo reuses Mesa components, the easier it probably is to merge into Mesa. Practically I think keeping Mesa-Geo as a separate package still has some benefits. For example it's easier to track PyPI download statistics at pypistats.org that could give me (as an imperfect proxy) a sense of relatively what percentage of Mesa users need GIS functionalities. |
Beta Was this translation helpful? Give feedback.
-
|
Quick update for tracking purposes (maybe mostly for myself): #3268 is now merged, completing the first concrete step we discussed: distinguishing a cell's logical index from its physical position. Every @wang-boyu, this should align well with the Mesa-Geo Next steps from here would be designing the actual stacked-spaces API (the @quaquel you're still committed on being the lead for this? With support from @codebreaker32? Because then let's target 4.0 and break some stuff! |
Beta Was this translation helpful? Give feedback.
-
|
I've been following this discussion with great interest, especially the recent conclusions from discussion. Let me first summarise my understanding: 1. Three-Tier Agent Hierarchy
2. Position as Single Source of Truth
3. Locatable Protocol
4. Translation Functions
5. Property Layers
I have also thoroughly reviewed #2875 and #3043. Are you open to me exploring some initial checklists for Space architecture in #3132 (especially Cell Descriptors ). If yes, do you prefer some draft PRs or detailed ideas here along with some code snippets? |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for your interest in this.
This is not correct. @EwoutH ran some tests exploring this, but it wasn't performant. Moreover, there is no need for it. If all a user needs is a grid, why force them to carry the overhead of a continuous space? So what are we trying to achieve? We want to keep the option of a single space in a model. We want to make it easier to have multiple different spaces in a model without a shared coordinate system. And we want to make it possible to "stack" spaces where agents have a single location but this is valid/used across multiple spaces. Moreover, we want to make it easy for agents to indicate whether they are present in a given space for this "stacked" spaces concept. stacked spaces Once we have a cleaner separation of (x, y) positions and logical coordinates for discrete spaces, the next step is to design an API for the stacked spaces concept. We haven't worked this out yet. In my vision, the relationship between spaces is declared at the space level. One example is to do something analogous to Given a way of declaring the relationship between spaces, the next thing is to automatically make an agent show up in all "stacked" spaces. This is an implementation detail. But, whenever multiple spaces |
Beta Was this translation helpful? Give feedback.
-
|
Thank you for the detailed explanation and correcting me!
Agree.
I propose adding a abstract method to the base class DiscreteSpace:
# ...
def cell_to_pos(self, cell_id: tuple[int, ...] | int) -> np.ndarray | None:
"""
Convert a logical cell index to its physical centroid position.
Args:
cell_id: The logical identifier (coordinate) of the cell.
(e.g., (1, 2) for Grid, node_id for Network)
Returns:
np.ndarray: N-dimensional float array of the physical center.
None: If the space is purely topological (e.g., Network).
"""
raise NotImplementedErrorSome quick questions
|
Beta Was this translation helpful? Give feedback.
-
I recently tried something very much similar to it for mesa-geo in mesa/mesa-geo#299. Essentially as summarized in mesa/mesa-geo#299 (comment), a raster cell (grid cell) has
Mesa-Geo doesn't have Hexagon layers yet, but I think a HexCell could similarly have (as mentioned in mesa/mesa-geo#298 (comment)):
The only main difference between Mesa and Mesa-Geo is then, |
Beta Was this translation helpful? Give feedback.
-
|
@wang-boyu so having this directly in Mesa might simplify Mesa-geo? |
Beta Was this translation helpful? Give feedback.
-
|
Yep possibly, depends on how the APIs are eventually designed and implemented. |
Beta Was this translation helpful? Give feedback.
-
What I Think
|
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Update: Currently aligned direction is summarized here: #2585 (comment)
Before we stabilize the cell space and new continuous space, I would like a discussion how we view spaces, properties and agents, and how they relate or interact to each other.
This is how I currently envision it for Mesa:
Mesa-Space-Conceptual-diagram.pptx
An Agent has a singular position in a single coordinate system. There can be multiple spaces (in which Agents are or are not present (see Q1). Each space can have 0, 1 or multiple properties (see Q2) which have the same "resolution" as the space (see Q3). All properties, spaces and Agents can interact with each other, because they all use a singular coordinate system.
Open questions:
Really curious on all the ideas how conceptually spaces should look in Mesa!
Beta Was this translation helpful? Give feedback.
All reactions