GSOC'25: Frontend Upgrade

[Sahil-Chhoker]

Here is the crux of my proposal,
We can discuss the ideas and feedback for my proposal in this discussion. It will also act like a journal to document my development.

Phase 1:

1. Add AgentPortrayalStyle and PropertlyLayerStyle:

   • Added by PR Added AgentPortrayalStyle and PropertyLayerStyle #2786
   • Added bug fixes for the portrayal components in PR Bug fixes for portrayal components #2798

2. Add CoordinateMapper:

   • Scrapped the idea for CoordinateMapper.

3. Add SpaceRenderer:

   • Added a PR: Introduction of Space Renderer #2803.

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.

    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 Feat: Added Model sharing through links #2727]Feat: Added Model sharing through links #2727)
2. Refactor Altair inline with Matplotlib:

Action Plan:

• Implement agent extraction logic for Altair backend as well.
• Implement rectangular grids with agent placement logic.
• Implement hex grids with agent placement logic.
• Implement Network grids with agent placement logic.
• Implement continuous space with agent placement logic.
• Implement Voronoi grids with agent placement logic.
• Address any remaining grid implementations or bugs.
• Add the plotting function.

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

[tpike3]

Check out this PR --- #2786

[Sahil-Chhoker]

I am thinking of merging the CoordinateMapper and making a big class SpaceRenderer that contains all the draw logic because putting two classes back to back doesn't seem like a great idea as it can confuse users as to what is going on.
In the draw_agents function in the SpaceRenderer we can just map the coordinates internally without using any other class.

[quaquel]

Conceptually, having an AbstractSpaceRenderer and then subclasses for the different spaces makes good sense to me. It would keep the translation nicely encapsulated. From a performance point of view, it should not matter. You either have a very large class for all kinds of spaces, or a smaller class for the specific space you are rendering.

[Sahil-Chhoker]

A clarification from my side, are we talking about:
AbstractSpaceRenderer
| - OrthogonalGrid(AbstractSpaceRenderer)
| - HexGrid(AbstractSpaceRenderer)
...other spaces
and the user choose class to use according to his used grid.

Because I want to do something entirely different (as proposed in proposal). The structure of SpaceRenderer will remain the same but I want to turn the respective grid drawing logic into its own class so they can store their encodings like size, padding, layout, etc.
I can then access those classes in the SpaceRenderer and draw the respective space. By this approach I think I can prevent repeating myself for the encodings and eliminate the need for CoordinateMapper.

Sorry but I feel like I lost track of where this was going.

[quaquel]

You are in charge, so you are best positioned to design this in an appropriate way. I am just trying to think along.

1. A user should not have to worry about any of this. It should be trivial to map any given space to the correct way of displaying both the space itself (e.g., gridlines) and the agents.
2. Having the grid drawing logic in its own class seems sensible. But I guess that you'll have separate classes for the different spaces?

[Sahil-Chhoker]

You are in charge, so you are best positioned to design this in an appropriate way. I am just trying to think along.

Thanks.

1. A user should not have to worry about any of this. It should be trivial to map any given space to the correct way of displaying both the space itself (e.g., gridlines) and the agents.

Will try my best.

2. Having the grid drawing logic in its own class seems sensible. But I guess that you'll have separate classes for the different spaces?

Yes and since I am making a class anyway I am thinking of both Altair and matplotlib in the same class for each grid (I will have to see how this works out).

[tpike3]

@Sahil-Chhoker to pile on, if you look at what @quaquel did with discrete_space where cell.py is the base class and then built from there, this may be a good example to model/approach to provide some inspiration

[Sahil-Chhoker]

Since now both AgentPortrayalStyle and PropertyLayerStyle are implemented, my updated timeline is looking like this:

Timeline:

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

I've realized that development of SpaceRenderer is going to take more time than I previously thought now that it will also contain the functionality for CoordinateMapper.
Other than that I've just increased a buffer to compensate any miscalculations.

[Sahil-Chhoker]

This is the concrete description of my SpaceRenderer, tell me if there is anything concerning about this.

Space Classes:

class OrthogonalSpaceDrawer:
    def __init__(self, space: OrthogonalGrid, **kwargs):
        self.space = space
        self.s_default = (180 / max(self.space.width, self.space.height)) ** 2
    
    def draw_matplotlib(self, ax):
        ...

    def draw_altair(self):
        ...


class HexSpaceDrawer:
    def __init__(self, space: HexGrid, **kwargs):
        self.space = space
        self.s_default = (180 / max(self.space.width, self.space.height)) ** 2
        self.size = 1.0
        self.x_spacing = np.sqrt(3) * self.size
        self.y_spacing = 1.5 * self.size

        self.x_max = self.space.width * self.x_spacing + (self.space.height % 2) * (self.x_spacing / 2)
        self.y_max = self.space.height * self.y_spacing

        self.x_padding = self.size * np.sqrt(3) / 2  # Distance from center to rightmost point of hexagon
        self.y_padding = self.size

        self.hexagons = self._get_hexmesh(self.space.width, self.space.height)

    @lru_cache(maxsize=1024, typed=True)
    def _get_hexmesh(
        self, width: int, height: int, size: float = 1.0
    ) -> list[tuple[float, float]]:
        ...

    def draw_matplotlib(self, ax):
        ...

    def draw_altair(self):
        ...

...

SpaceRenderer:

class SpaceRenderer:    
    def __init__(self, model, backend: str = "matplotlib", ax: Axes | None = None):
        self._space = model.space
        self.backend = backend
        self.space_drawer = self._get_space_drawer()

        # Initialize mesh storage
        self.space_mesh = None
        self.agent_mesh = None
        self.propertylayer_mesh = None

        # Handle axis management
        if self.backend == "matplotlib":
            if ax is None:
                fig, ax = plt.subplots()
                self.fig = fig
            self.ax = ax
        elif self.backend == "altair":
            self.ax = None

    def _get_space_drawer(self):
        if isinstance(self._space, OrthogonalGrid):
            return OrthogonalSpaceDrawer(self._space)
        elif isinstance(self._space, HexGrid):
            return HexSpaceDrawer(self._space)
        return None

    def _map_coordinates(self, arguments):
        """Map agent coordinates to appropriate space coordinates."""
        mapped_arguments = arguments.copy()
        
        if isinstance(self._space, OrthogonalGrid):
            mapped_arguments["loc"] = arguments["loc"].astype(float)
        elif isinstance(self._space, HexGrid):
            loc = arguments["loc"].astype(float)
            if loc.size > 0:
                # Calculate hexagon centers using the space drawer
                loc[:, 0] = (loc[:, 0] * self.space_drawer.x_spacing + 
                           ((loc[:, 1] - 1) % 2) * (self.space_drawer.x_spacing / 2))
                loc[:, 1] = loc[:, 1] * self.space_drawer.y_spacing
            mapped_arguments["loc"] = loc
        
        return mapped_arguments

    # Structure drawing methods
    def draw_structure(self, ax: Axes | None = None):
        """Draw the space structure (grid lines, etc.)."""
        if self.backend == "matplotlib":
            if ax is None:
                ax = self.ax
            self.space_mesh = self.space_drawer.draw_matplotlib(ax)
            return self.space_mesh
        elif self.backend == "altair":
            self.space_mesh = self.space_drawer.draw_altair()
            return self.space_mesh

    # Agent drawing methods
    def _draw_agents_matplotlib(self, ax: Axes | None, arguments, **kwargs):
        ...

    def _draw_agents_altair(self, arguments, **kwargs):
        ...

    def draw_agents(self, agent_portrayal, ax: Axes | None = None, **kwargs):
        arguments = collect_agent_data(
            self._space, agent_portrayal, default_size=self.space_drawer.s_default
        )
        arguments = self._map_coordinates(arguments)
        
        if self.backend == "matplotlib":
            self.agent_mesh = self._draw_agents_matplotlib(ax, arguments, **kwargs)
            return self.agent_mesh
        elif self.backend == "altair":
            self.agent_mesh = self._draw_agents_altair(arguments, **kwargs)
            return self.agent_mesh

    # Property layer drawing methods
    def _draw_propertylayer_matplotlib(self, space, propertylayer_portrayal, ax):
        ...

    def _draw_propertylayer_altair(self, space, propertylayer_portrayal):
        ...

    def draw_propertylayer(self, space, propertylayer_portrayal, ax: Axes | None = None):
        if self.backend == "matplotlib":
            if ax is None:
                ax = self.ax
            self.propertylayer_mesh = self._draw_propertylayer_matplotlib(
                space, propertylayer_portrayal, ax
            )
            return self.propertylayer_mesh
        elif self.backend == "altair":
            self.propertylayer_mesh = self._draw_propertylayer_altair(
                space, propertylayer_portrayal
            )
            return self.propertylayer_mesh

    # Main rendering method
    def render(self, agent_portrayal, propertylayer_portrayal=None, ax: Axes | None = None, **kwargs):
        """Render the complete space with structure, agents, and property layers."""
        if self.backend == "matplotlib":
            self.draw_structure(ax)
            self.draw_agents(agent_portrayal, ax, **kwargs)
            if propertylayer_portrayal is not None:
                self.draw_propertylayer(self._space, propertylayer_portrayal, ax)
        elif self.backend == "altair":
            pass

[Sahil-Chhoker]

Another vague idea expanding Jan's comments:

SpaceRenderer

class SpaceRenderer(ABC):
    _renderer_registry = {}

    def __new__(cls, n_space, *args, **kwargs):
        space = n_space
        target_cls = cls._renderer_registry.get(space)

        instance = object.__new__(target_cls)
        return instance

    @classmethod
    def register(cls, space_type_name):
        def decorator(subclass):
            cls._renderer_registry[space_type_name] = subclass
            return subclass
        return decorator

    def __init__(self, model, space_encodings=None, **kwargs):
        self.model = model
        self.space = model.space
        self.ax = None

        self.space_encodings = space_encodings or {}

    def setup_figure(self, ax=None, fig_kwargs=None):
        if ax is None:
            fig, self.ax = plt.subplots(**fig_kwargs)
        else:
            self.ax = ax

        return self.ax

    @abstractmethod
    def map_coordinates(self, arguments=None, **kwargs):
        """
        MUST BE OVERRIDDEN BY SUBCLASSES.
        Translates model space coordinates to drawing canvas coordinates and size.
        """
        pass

    @abstractmethod
    def draw_structure(self, **kwargs):
        """
        MUST BE OVERRIDDEN BY SUBCLASSES.
        Draws the static structure of the space (grid lines, cell backgrounds, etc.).
        """
        pass

    def draw_agents(self, agent_portrayal=None, **kwargs):
        ...

    def draw_property_layers(self, property_layer_portrayal=None, **kwargs):
        ...

    def render(self, agent_portrayal=None, property_layer_portrayal=None,
               post_process=None, draw_grid=True,
               fig_kwargs=None, **kwargs):
        ...
        

Space Subclasses

@SpaceRenderer.register("hexagonal")
class HexGridRenderer(SpaceRenderer):
    def __init__(self, space, space_encodings=None, **kwargs):
        super().__init__(space, space_encodings=space_encodings, **kwargs)

    def map_coordinates(self, arguments,**kwargs):
        # map coordinates in the respective space class
        ...

    def draw_structure(self, **kwargs): # Uses self.space_encodings
        ...

...

[quaquel]

Either design can work. I think the first one makes more sense (although it's also more detailed) because of the clean separation of concerns. One issue will be the backend site of things. Given how different altair and matplotlib are in their underlying desing philosophy, this might have implications for the SpaceRenderer.

[Sahil-Chhoker]

Should I expand on the 2nd and see how it compares with the first because there is zero consideration of altair in the 2nd or start the work on first?

[quaquel]

I am fine with you continuing on the first option.

[Sahil-Chhoker]

Now that the SpaceRenderer PR is merged, my next focus is refactoring the altair's plotting function and experiment with the custom plots a bit. But I am not sure if I want to put the plotting functionality in SpaceRenderer or keep it separate for both matplotlib and altair.
What's your view on this @tpike3, @quaquel and @EwoutH?

[tpike3]

Through this GSOC, I am learning that visualization, really seems to epitomize the inherent trade-offs in the Mesa architecture.

Following the principle of least surprise, would be putting them in renderer so we have consistency. This way forward we create the render object , pick your backend and then each render.draw_agents, render.plot gives you the consistency for each of the items,

However, from a visual point of view would cause slower drawing particularly because Solara can multithread (correct?), which allows each plot (agents, graphs etc) to be produced at the same time instead of sequentially.

If it will render faster and cleaner, I think the current approach is better.

My only thought is at @Sahil-Chhoker, is there some art we can inject in this to make it more user friendly. With render make that generally all inclusive so it by default draws the agents, with the ability for customization? Make the plots feel intuitively different, I think loading them through components will do this implicitly, but there may be some additional enhancements, could help. Not sure the best answer, but there may be some creative solutions.

What I am understanding this will look like is---

# Renderer encapsulates model behavior
render = SpaceRenderer(model, backend="matplotlib")
render.draw_agents(agent_portrayal) # Without specification can agents will rendered by default in renderer??
render.draw_properties(propertylayer_portrayal)

# Components captures datacollector/plot behavior
plot1 = make_plot_component(...)
plot2 = make_plot_component(...)

page = SolaraViz(
    model,
    render,
    components=[plot1, plot2],
    model_params=model_params,
    name="Model of Renowned Fanciness",
)
page  # noqa

Let me know if I am tracking and if this makes sense

[Sahil-Chhoker]

I think the current approach is better.

Ok I will extend the altair to follow the current approach.

My only thought is at @Sahil-Chhoker, is there some art we can inject in this to make it more user friendly. With render make that generally all inclusive so it by default draws the agents, with the ability for customization? Make the plots feel intuitively different, I think loading them through components will do this implicitly, but there may be some additional enhancements, could help. Not sure the best answer, but there may be some creative solutions.

Not sure I get your question, if we are talking about skipping the agent_portrayal inside the draw_agents(), I can make this work, but for the default encodings I really recommend this:

from mesa.visualization.components import AgentPortrayalStyle
def agent_portrayal(agent):
    return AgentPortrayalStyle()

And if we are talking about skipping the individual functions to setup a visualization, currently you can just do:

renderer = SpaceRenderer(model, backend="matplotlib")
# this draws everything if specified, passing agent_portrayal is a signal to draw the agents.
renderer.render(agent_portrayal, propertylayer_portrayal, post_process, space_kwargs={...}, agent_kwagrs={...})

But if this feels long, I can make changes to the render function to do something like:

renderer = SpaceRenderer(model, backend="matplotlib").render(agent_portrayal, ...)

page = SolaraViz(
    model,
    renderer,
    ...
)

Let me know if I should add these both functionalities, and point out if I understood anything wrong.

[tpike3]

@Sahil-Chhoker That functionality is great, and we need to ensure we capture the different syntax in examples for users. I do not think we need to make the described changes to the render function. but @EwoutH thoughts?

I was thinking more an easy default so if someone just does

renderer = SpaceRenderer(model)

page = SolaraViz(
   model,
   renderer,
   ...
)

It will plot a simple visual of the model, with minimal embellishments, similar to the current version that will plot model (appreciating we are switching to a matplotlib default instead of altair... which is fine).

The idea is users can get something as fast as possible with minimal code, but then with the ability to customize each part--- agent portrayal, property layer portrayal, and then different plots.

Does this make more sense?

[Sahil-Chhoker]

I get the point now, but that kind of limits the functionality of the renderer. If we are drawing the agents always it will prevent the user to make visualizations only containing structures or property layers.
Especially property layers along with their visualization can help in some really advanced models like this one

[tpike3]

Should have posted this days ago for knowledge of the group--- in discussions @Sahil-Chhoker and I agreed to keep as is as we constantly balance the trade-off of ease and customization, which continue to dominate the visualization discussion.

[Sahil-Chhoker]

Since we have crossed the halfway point, here is how the timeline is looking:

Timeline:

1. Week 1-6: Implemented SpaceRenderer
2. Week 7: Implemented plotting function for Altair.

---

4. Week 8 & 9: Update the examples and documentation to show the capabilities of new API.
5. Week 10 & 11: Develop multiple pages in the same app feature.
6. Week 12: Buffer

PyCafe doesn't support multithreading in solara therefore it is not possible to run the latest version of mesa there, therefore the idea of sharing models through links is scrapped.

[tpike3]

Thanks @Sahil-Chhoker #2810 merged, nice work!