GSOC'25: Frontend Development

[ghost]

Hi I am @Sahil-Chhoker, I am having some problems with my main account therefore opening this discussion with an alternate account. @tpike3, we can discuss the ideas and feedback for my proposal in this discussion. It will also act like a journal to document my development.

Here is the crux of my proposal:

Phase 1:

1. Add AgentPortrayalStyle and PropertlyLayerStyle:
2. Add CoordinateMapper:

class CoordinateMapper: 
    def __init__(self, space): 
        self.space = space
    def collect_agent_data(self, agent_portrayal, color, size, marker, zorder):
        # moved this function inside this class 
    def map_coordinates(self, agent_data): 
        # use pattern matching to call appropriate method to convert the coordinates 
    def _map_hex_coordinates(self, agent_data): 
        # convert to hex coordinates after defining hex parameters (i.e., size, x_spacing, y_spacing) 
    def _map_network_coordinates(self, agent_data): 
        # convert node IDs to spatial positions after calculating network layout
    def ...:
        # other relevant method

• This CoordinateMapper acts as a layer between SpaceMatplotlib and draw_space. The signatures of draw_space will be updated to include the mapper class.

3. Add SpaceRenderer:

class SpaceRenderer: 
    def __init__(self, model, backend: str = “matplotlib”, **kwargs): 
        self._space = model.grid
        self.mapper = CoordinateMapper(self._space) self.grid_mesh = None
        self.agent_mesh = None self.propertylayer_mesh = []

    # All the rendering methods 
    def draw_structure(self, **kwargs): 
        # grid drawing
    def draw_properties(self, portrayal=None, layer_name=None, **kwargs): 
        # property layer drawing
    def draw_agents(self, portrayal=None, **kwargs): 
        # agent drawing
    def draw_custom_components(self, components: list, **kwargs): 
        # new components made for viz. can be put into this list to be rendered.
    @property
    def space(self):
         return self.grid_mesh
    @space.setter
    def space(self, new_grid_mesh):
        self._space = new_grid_mesh
    def render(self, agent_portrayal=None, property_portrayal=None, post_process=None, **kwargs): 
        # combined method to render all grid, agents and property_layer at once.

• Usage Examples:

# separate rendering of space, agents and property_layers. 
renderer = SpaceRenderer(model) 
renderer.draw_structure() 
renderer.draw_agents(agent_portrayal)
renderer.draw_properties(propertylayer_portrayal) 

# direct manipulation 
ax = renderer.space 
ax.set_title("My Custom Visualization")
ax.set_xlim(0, 100) 

renderer.space = ax # Set modified space back 

# group rendering 
renderer.render(agent_portrayal, propertylayer_portrayal, post_process, draw_grid=True) 
page = SolaraViz(model, renderer, [components, ...], model_params) # passing renderer in SolaraViz.

• API diagram:
  

---

Phase 2:

1. Model Sharing Through Links: Extend the work in PR Feat: Added Model sharing through links #2727
2. Refactor Altair inline with Matplotlib: Action Plan:
   • Implement agent extraction logic or repurpose collect_agent_data to be cleanly used in the Altair backend as well.
   • Implement rectangular grids with agent placement logic.
   • Implement hex grids with agent placement logic.
   • Implement property layer visualization for HexGrids.
   • Implement continuous space with agent placement logic.
   • Implement Voronoi grids with agent placement logic.
   • Implement network grids with agent placement logic.
   • Address any remaining grid implementations or bugs.
   • Add the plotting function.

---

Timeline:

1. Week 1 & 2: Develop AgentPortrayalStyle and PropertyLayerStyle
2. Week 3 & 4: Develop CoordinateMapper
3. Week 5, 6 & 7: Develop SpaceRenderer
4. Week 8: Buffer
5. Week 9: Complete model sharing through links feature.
6. Week 10, 11 & 12: Implement Altair backend inline with matplotlib.

[ghost]

Now regarding the design of AgentPortraylStyle, should I extend current agent_portrayal dictionary or the new design that contains loc in AgentPortraylStyle instead (PR #2728)?

[EwoutH]

Personally I think we have had enough problems with the dict that it warrants replacement.

If #2728 is not moving forward feel free to continue it yourself or open your own version.

[quaquel]

I would switch to a dedicated class that allows the user to specify the visual encoding for x, y, color, shape, and size. So yes, loc should be included in this. Also, don't worry about backward compatibility at first. For me, AgentPortrayalStyle is user-facing, so in the backend, we might do things differently for performance reasons.

[ghost]

So the design will look like:

def agent_portrayal(agent):
    return AgentPortrayalStyle(color="blue", marker="o", size=50, zorder=1, loc=agent.pos)
                                                                          # ^^^~~~is this assumption right?   

I want to know the benefits of adding loc in agent_portrayal, also @quaquel to what extent PR #2728 is right?

[quaquel]

The reason for adding loc is that AgentPortrayalStyle would then encapsulate the entire visual encoding of an agent. It would also open up more flexibility to the user, where loc would default to agent.position, but it could be something else. In fact, I am inclined to seperate x and y explicitly. So

AgentPortrayalStyle(color="blue", marker="o", size=50, zorder=1, x=agent.pos[0], y=agent.pos[1])

I have left various comments in #2728, so you can build on those. However, there is no right or wrong because I don't fully know what is needed or what makes sense.

[ghost]

How should the PropertyLayerStyle look and be used?
My idea:

@dataclass
class PropertyLayerStyle:
    color: str | None
    colormap: str | None
    alpha: int = 1
    colorbar: bool = True
    vmin: float | None
    vmax: float | None

and usage:

def propertylayer_portrayal(layer):
    if layer.name == "sugar":
        return PropertyLayerStyle(color="blue", alpha=0.8, colorbar=True, vmin=0, vmax=10)
    else:
        return PropertyLayerStyle(color="red", alpha=0.5, colorbar=True, vmin=0, vmax=10)

Is this approach correct? How it can be improved (if it can)?

[quaquel]

1. It would be great if agents and layers have the same style of API. This will make it easier to use
2. However, for layers, I would like to be able to also masks parts of it. This is currently not easy to do.
3. A broader point: I like the idea of the SpaceRenderer, however, it should be easy to pass your own custom render function for agents, layers, structures, or custom components. So the renderer might be better implemented as a function with keyword arguments for each of the subfunctions. A challenge with this idea is to figure out the signature of these subfunctions such that is easy to pass your own if desired.

[ghost]

Regarding masking I would love to discuss some more, are we talking about some part of property layers in which we want to apply some function or we are talking about some part of property layer that we want to show and hide the remaining?

If we are talking about showing only a part of property layer by value, it can be possible with setting appropriate vmin and vmax, or are we talking about masking by position, like corners or center, etc...

Or are we talking about something else entirely?

[ghost]

3. A broader point: I like the idea of the SpaceRenderer, however, it should be easy to pass your own custom render function for agents, layers, structures, or custom components. So the renderer might be better implemented as a function with keyword arguments for each of the subfunctions. A challenge with this idea is to figure out the signature of these subfunctions such that is easy to pass your own if desired.

I also like the idea of able to pass custom render functions to visualize agents, layers, structures differently, but I am not convinced that renderer should be a function, it will end up being a bulky function and kind of different direction from separating the drawing of agents, grids and layers.
I think we should just extend the class to handle the custom drawing functions.

[ghost]

@quaquel, @EwoutH, @tpike3 and @jackiekazil, I should have asked this first—please list all the critiques of the proposal, including what was good, what wasn't, and how it can be improved.

[tpike3]

@02-Sahil --

• Conceptually, your proposal was clear and laid out a comprehensive plan for improving the visualization. However, please appreciate if we had an exact answer for Mesa visualization, we would have already implemented it. This process will be a lot of discussion where we will have to identify the tradeoffs and make choices.

• The key concepts to me are (but anyone else feel free to jump in and propose something more articulate):

• User perspective

  • Intuitive functions that have a similar look and feel across the visualization module (this echoes @quaquel points earlier of agents and layers have similar API style) -- Principle of least surprise
  • Allow for user flexibility, we cannot predict every possible visual people may want for mesa so how to let them inject their own (one example is we talked x and y, but what about z for 3-D visuals.

• Backend efficiencies

  • How do we then make the backend as efficient as possible to optimize performance.
  • How can we make the backend extensible for future Mesa and Mesa-Geo upgrades.

If I am summarizing correctly ---

right now the immediate goal is switch from the current dictionary set up to two classes

• PropertyLayerStyle
• AgentLayerStyle

both of which feed into SpaceRenderer

Again let me emphasize this is a discussion, there is no clear answer at this point and open communication is critical. I am more often than not wrong in my assumptions and thoughts so feel free to correct them or ask for clairification.