Conceptual model of Space

[EwoutH]

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:

1. Do we want an concept of Agents being "present" in some spaces and not in others, or are Agents by definition (due to their position) present in all spaces, and do we just select Agent types etc.
2. Does it still make sense to link properties / property layers to spaces, or can we see them separate from each other? I can imagine a model in which spaces contain Agents and properties are just there to model the environment.
3. With an unified coordinate system, do spaces and properties need to have the same "resolution", or can we mix and match?

Really curious on all the ideas how conceptually spaces should look in Mesa!

[quaquel]

Thanks for this. It's really helpful.

My 2 cents:

1. A model can have more than 1 space. Because I want to be able to do something like this.
2. An agent can only ever be in 1 space. At present, the space defines the coordinate system. This, in turn, determines which agents are close or far. Since we only want a single coordinate system, I don't see an easy way of having an agent in more than one space. Nor do I see a convincing use case so far. When would you need to have multiple alternative definitions of what local means? I can think of social networks next to some other space, but in that case you don't need a network space perse.
3. At present, property layers only work in grids. It might be possible to generalize this to all cell spaces and even continuous spaces, but it won't be trivial. Cell space generalization is easy since you have an integer position, so you can map coordinates in, e.g., a network to a position in a NumPy array. ContinuousSpace is more tricky since you need to translate a float position to potentially a grid space, and there is nog of a continuous space (i.e., how many cells are natural griddin along the x and y axis)?

[EwoutH]

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:

1. Positions could be stored as agent attributes
2. Neighbor relationships could be computed on demand and/or stored in Agents
3. Environmental properties could be stored in separate property layers
4. Movement could be handled by agents updating their own positions

At first glance, this seems appealing:

• Simpler conceptual model - agents own their position and relationships
• More flexible - agents can define custom neighbor relationships
• No consistency issues - one source of truth
• More extensible - no need for different space types

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:

1. Performance Optimizations

• Efficient spatial indexing for neighbor queries
• Quick lookup of agents at a position
• Fast empty position finding
• Optimized property access patterns

2. Consistency Guarantees

• Valid positions and movements
• Symmetric neighbor relationships
• Capacity constraints
• Consistent property access

3. Conceptual Clarity

• Clear rules about spatial relationships
• Standard patterns for movement and neighbors
• Central source of truth for environmental properties

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:

1. Which space responsibilities could be moved to agents without losing the benefits of centralized consistency?
2. Could neighbor relationships be agent-owned while keeping the performance benefits of spatial indexing?
3. How do we balance Agent ownership with Space efficiency?
4. What's the right split between Space coordination and Agent autonomy?

Further more, specifically spaces maintaining neighbour relations:
5. One major potential benefit of multiple spaces is having multiple neighbour relations: A spatial (grid) an network for example. If we make neighbours Agent-owned, would this make this easier?
- Loops partly back to: #1900, the discussion that sparked the cell space!

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.

[quaquel]

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 Cell. Cell spaces are a container for cells and specify how cells are to be wired up.

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

1. I don't see anything in the cell spaces or my wip continuous space that would make sense to move out of space. Both determine what counts as close or far away, and that's about it.
2. No, because being neighbors is a relation between agents, not the state of an agents. The relevant state is the position / cell. Being a neighbor or not is derived from this state and the state of all other agents given a distance norm specified by a space.
3. No idea what you are asking.
4. No idea what you are asking.
5. There is nothing at present to prevent you from having an agent be part of multiple spaces, but you would have to implement your own custom agent class to make it work.

[EwoutH]

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 resources

The 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_spots

You 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.

[quaquel]

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.

[EwoutH]

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:

• Allow multiple neighbour specifications in a single space
• Allow multiple spaces, each with one neighbour specification

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:

• Either uncouple properties from space (and let spaces just measure agent occupancy and neighborship relations)
• Allow multiple spaces

[quaquel]

Allow multiple neighbour specifications in a single space

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.

[EwoutH]

While I agree with most, I might view it a little differently:

an agent can be part of multiple spaces. The issue thus revolves around having agent classes that allow for multiple "locations"

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.

[quaquel]

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 get_agents_in_radius and get_k_nearest_agents), while agents have methods for getting their nearest neighbors (e.g., for ContinuousSpaceAgent get_neighbors_in_radius and get_k_nearest_neighbors).

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 DiscreteSpace and HasCell. I was already planning to add the distinction in the reimplementation of ContinuousSpace after reflecting on the bug reported in #2592.

[wang-boyu]

I've been in discussion with some people (@SongshGeo @AdamZh0u @LunnyRia @peter-kinger and a few others) who are interested in working on projectmesa/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.

[SongshGeo]

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.

[quaquel]

From a conceptual model perspective, obtaining the distance between two agents is a method of space, while getting neighbours is a method of Agent

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 get_agents_in_radius and get_k_nearest_agents, and have an InvalidCoordinateException that is raised if a coordinate is not valid in a given space.

It would be best to have a default parameter indicating which space this method is called in.

Not sure about this, but at least within MESA we might provide standard Agent classes that work well for a given space X (so ContinuousSpaceAgent and CellAgent. If users want to have an agent that is part of multiple spaces, it is up to them how they want to implement this. I think it will be hard to generalize. But with get_agents_in_radius and get_k_nearest_agents on all spaces, this is actually trivial in many cases. It means getting all agents near (radius, or k-nearest) the agent's position and removing itself from the resulting list of agents.

[SongshGeo]

Not sure about this, but at least within MESA we might provide standard Agent classes that work well for a given space X (so ContinuousSpaceAgent and CellAgent. If users want to have an agent that is part of multiple spaces, it is up to them how they want to implement this. I think it will be hard to generalize. But with get_agents_in_radius and get_k_nearest_agents on all spaces, this is actually trivial in many cases. It means getting all agents near (radius, or k-nearest) the agent's position and removing itself from the resulting list of agents.

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.