SolaraViz API Design

[Corvince]

I realize I’m a bit late to the discussion on the fundamental API designs for the new SolaraViz frontend, but I hope my input is still valuable.

What sets Solara apart is its ability to create modular and reusable components that can be assembled into a complete frontend. I believe we should leverage this capability much more effectively. Currently, the SolaraViz codebase feels like a catch-all solution, which contributes to a somewhat fragile API. While this is something that can always be refined later, I think it’s worth discussing how we might build a more robust frontend from the ground up.

Let’s start with the foundational layer: a simple visualization component that takes in a model instance and outputs a visualization. This could be something like SpacePlot(model) or BarChart(model). The beauty of these components is that they can stand alone; for instance, in an exploratory notebook, you could simply call BarChart(model) and immediately see the result.

The next layer would be a LayoutLayer that receives a model instance, a list of VisualizationComponents, and a layout specification—like a column-based arrangement.

Moving up, we have the model handler layer. Importantly, this is completely independent of the visualization itself. It receives a model instance and manages its controls: step, run, reset, etc. This layer can also function on its own, allowing you to interactively step through a model, even if you're writing directly to a database without using any other components.

Alongside the model handler is the Model Creator. This module receives the model class along with a combination of static and user-defined parameters, which are visualized by the UserParams widget. The Model Creator is responsible for generating model instances.

At the highest level, we have the "opinionated" glue-code that binds these components and layers together—essentially, the current SolaraViz component. From the structure of the layers below, it’s clear that this should include the model class, model parameters, and a list of visualization modules as the only required parameters. If we compare this to the current API, we see that “measures” correspond to the list of visualization modules (albeit under a different name). However, we also have elements like agent_portrayal and space drawer, which I believe are unnecessary. We could simply pass SpaceDrawer as part of the "measures". Additionally, we have parameters like "name", "seed", and "play_interval", which are essentially modifiers for the underlying components. These should be made keyword arguments (kwargs) to avoid breaking changes when adding new kwargs for different underlying modules, such as layout specifications.

This is my attempt at visualizing this structure:

I think implementing this structure long-term will lead to much more maintainable code. It will also lead to better understanding how to add new vizcomponents and generally solve some of the already open issues with solara. But I think a good first step would be to have a stable API for SolaraViz, on which we can build upon (or even top-down) without breaking changes

Initial diagram

[rht]

I'm swamped today and maybe tomorrow, but will find a time window tomorrow to look into this.

[rht]

Let’s start with the foundational layer: a simple visualization component that takes in a model instance and outputs a visualization. This could be something like SpacePlot(model) or BarChart(model). The beauty of these components is that they can stand alone; for instance, in an exploratory notebook, you could simply call BarChart(model) and immediately see the result.

SGTM. Though, in the context of Jupyter notebook, the bar chart (or any other visualization objects) would be a common API to wrap Matplotlib/Altair, which in themselves are already concise, and the API are well known to the user/StackOverflow/LLM.

Moving up, we have the model handler layer. Importantly, this is completely independent of the visualization itself. It receives a model instance and manages its controls: step, run, reset, etc. This layer can also function on its own, allowing you to interactively step through a model, even if you're writing directly to a database without using any other components.

This is more likely to solve #2176 than the current situation.

We could simply pass SpaceDrawer as part of the "measures".

I agree with this. One consideration of it being separate was that it is automatically drawn without the user having to specify it, because it is what they want most of the time. But instead if agent_portrayal can be merged into SpaceDrawer, then the API is about as concise. From

def agent_portrayal(agent):
    return {"color": "tab:orange" if agent.type == 0 else "tab:blue"}


page = SolaraViz(
    Schelling,
    model_params,
    measures=["happy", make_text(get_happy_agents)],
    agent_portrayal=agent_portrayal,
)

to

space_drawer = SpaceDrawer(...)

page = SolaraViz(
    Schelling,
    model_params,
    measures=[space_drawer, "happy", make_text(get_happy_agents)]
)

I made no assumption about the rest of the API changes, to keep the point localized. Additionally, @wang-boyu had made a point about eliminating agent_portrayal in the context of Mesa-Geo that I couldn't find the discussion thread of (can't exactly remember the cause, is it because of having both custom space drawer and agent portrayal?).

I don't know how long it takes to modularize the components, but given the time constraint (Mesa 3.0 should be ready by the upcoming academic year), would it be fine to do the beginner user-facing SolaraViz defaults first?

[Corvince]

I don't know how long it takes to modularize the components, but given the time constraint (Mesa 3.0 should be ready by the upcoming academic year), would it be fine to do the beginner user-facing SolaraViz defaults first

Not 100% sure I understand you right, so just for clarification: you suggest we first change the API of SolaraViz and then later revise the underlying components to be fully independent reuseable. I think that makes a lot of sense

Incorporating the input from @EwoutH a minimal API could then look like

def SolaraViz(model: Model, components: Components[], **kwargs)

That is we can pass in an existing model and a list of components and additional kwargs without any predefined order (for things like playback speed).

By the way I also made it work to pass in a model, modify the model "outside" of the viz and have the viz update automatically. But this should be a next step.

Before that it is also important that users can also pass in a model class and parameters. Not yet sure how the API should look like. Maybe just instead of the model instance a dict with class and parameters? Or a ModelCreator, which is basically a glorified UserParams component that emits new models? Input welcome!

[rht]

Not 100% sure I understand you right, so just for clarification: you suggest we first change the API of SolaraViz and then later revise the underlying components to be fully independent reuseable. I think that makes a lot of sense

Exactly.

By the way I also made it work to pass in a model, modify the model "outside" of the viz and have the viz update automatically. But this should be a next step.

How did you notify SolaraViz, given widgetti/solara#192 (comment) ?

Before that it is also important that users can also pass in a model class and parameters. Not yet sure how the API should look like. Maybe just instead of the model instance a dict with class and parameters? Or a ModelCreator, which is basically a glorified UserParams component that emits new models? Input welcome!

What about allowing only a model object? The ModelCreator prepares a model object which params may contain Slider or Checkbox. But users can also just pass a regular model that doesn't have Slider or Checkbox, and it will render in SolaraViz with the start/stop/reset. It's just that the controller UI won't have sliders/checkboxes.

[Corvince]

By the way I also made it work to pass in a model, modify the model "outside" of the viz and have the viz update automatically. But this should be a next step.

How did you notify SolaraViz, given widgetti/solara#192 (comment) ?

Basically I did a variant of this comment #2176 (comment)

The simple version looks something like this

import solara

update_counter = solara.reactive(0)


def force_update():
    update_counter.value += 1


@solara.component
def ShowSteps(model):
    update_counter.get()
    return solara.Text(f"Step: {model.steps}")


@solara.component
def StepButton(model):
    def step():
        model.step()

    return solara.Button("Step", step)


@solara.component
def MyViz(model):
    def connect_to_model():
        # Patch the step function to force updates
        original_step = model.step

        def step():
            original_step()
            force_update()

        model.step = step

        # Add a trigger to model itself
        model.force_update = force_update

    solara.use_effect(connect_to_model, [model])
    return solara.Row(
        [
            ShowSteps(model),
            StepButton(model),
        ]
    )

So the magic evolves around the update_counter, that I declared as a reactive variable outside the viz component. This is forced to be a dependency of the step counter (or Space drawer, or whatever). And secondly I monkeypatched the models step function to force an update.

[wang-boyu]

Additionally, @wang-boyu had made a point about eliminating agent_portrayal in the context of Mesa-Geo that I couldn't find the discussion thread of (can't exactly remember the cause, is it because of having both custom space drawer and agent portrayal?).

Is it this one here: projectmesa/mesa-geo#157 (comment)

[EwoutH]

I realize I’m a bit late to the discussion on the fundamental API designs for the new SolaraViz frontend, but I hope my input is still valuable.

It is, and you're right on time, since we're in 3.0 alpha phase and can break everything :)

The beauty of these components is that they can stand alone

Love it, that's obviously a win.

The Model Creator is responsible for generating model instances.

If you might have the time, could you read though this issue and give your insights on it? I think it's related:

• Access and modify model from Solara visualisation. #2176

For example, in my head it's useful to be able to pass a model instance, so I'm curious what you think about that.

this should include the model class, model parameters, and a list of visualization modules as the only required parameters.

Yes, this is better that the current practice of passing measure strings.

elements like agent_portrayal and space drawer, which I believe are unnecessary
"name", "seed", and "play_interval" ... These should be made keyword arguments (kwargs)

Agreed, I never liked the agent_portrayal dict, and agreed!

---

This sounds way more modular and scalable than what we currently have (and it's hard to get it right on the first iteration, so that's understandable).

You're the absolute expert of us on front-end development and I trust your choice on UI/UX design, I like these ideas, so from my part, go ahead and built it.

If you're serious about this I'm going to fix that our examples are tested in CI Monday, so we can see which examples need to be updated and keep them in sync.

[Corvince]

The Model Creator is responsible for generating model instances.

If you might have the time, could you read though this issue and give your insights on it? I think it's related:

• Access and modify model from Solara visualisation. #2176

For example, in my head it's useful to be able to pass a model instance, so I'm curious what you think about that.

Yes I think you are on track with this one. This part was also the one I was the most unsure about. I think its better and even simpler to pass either a Model or a ModelCreator to SolaraViz. In terms of data flow that is either a model or something that resolves to a model. I'll update the diagram

[Corvince]

Thanks for your input! I was playing around yesterday evening and one of the comments from maarten in #2176 could be extremly helpful, so thanks for bringing this back on my attention.

Regarding the current state: I hope my initial post didn't sound too dismissive, as you said its hard to get right on first try and actually most of my proposed building blocks are already there, but just scattered around and not always clearly seperated. I think I'll have to conceptually rebuild from the ground up in a POC fashion, but once that works I can probably reuse most of the existing logic.

[EwoutH]

I hope my initial post didn't sound too dismissive

It didn’t, but I found it important to mention to everyone who helped build the current implementation. We’re standing on shoulders of giants :)

Don’t be afraid to completely start from scratch!

[Corvince]

Just to keep this updated. I didn't have the time to put up a PR, but I keep refining the API in my head and I think I'm pretty close to a good solution.

First step would be a minimal PR to introduce the new API and have a more focused discussion there. Hope to get this done this week

[EwoutH]

Great to hear, looking forward to it!

Would be especially nice if we can get the high-level structure / API in Mesa 3.0.

Let me know if I can help with any of it.

[Corvince]

Actually started working on this today! Tonight I shall be able to open a first draft PR. Was knocking my head on the wall the last 1-2 hours, but now everything looks very promising again. But it turns out rewriting some parts from scratch is actually easier than modifying the existing structure - I had hoped to do this more incremental. But lets discuss once the PR is out.

[wang-boyu]

The LayoutLayer and VizComponent look much similar to Figure and Axes from matplotlib. I'm wondering how compatible the new API will be with matplotlib, so that perhaps users could leverage their knowledge in matplotlib to create customized plots as they want.

Looking forward!

[Corvince]

This is definitively something we should document properly in a "how-to" style, but yes, with solara you can just write a normal matploblib figure and display it with solara.FigureMatplotlib(fig). Now the user just hast to implement its visualisation as a function that accepts "model" as its sole argument. and can pass that to SolaraViz. This is how the space drawers and measure plots are already implemented (and this is independent of the SolaraViz API change)

[wang-boyu]

Hi @Corvince, I'm wondering if there's any easier ways to customize the default column layout of the components? For instance if we'd like to have two measure plots side-by-side on the same row. Thanks!

[Corvince]

For that use case we should probably provide some wrapper around solara.row or solara.column. so roughly something like

def Row(components):
  def wrapper(model):
    with solara.row():
      for c in components:
         c(model)
  return wrapper
   

/Edit I never can remember if it should be row or column

[wang-boyu]

How about something similar to what we had for measures in the experimental SolaraViz?

If we have a list of components: components=[comp1, comp2, comp3] then it gets rendered in a column (current behavior):

+++++++++
+ comp1 +
+++++++++
+ comp2 +
+++++++++
+ comp3 +
+++++++++

If there's an inner list, it gets rendered in a row. For instance for components=[comp1, [comp2, comp3]] we have

+++++++++++++++++
+     comp1     +
+++++++++++++++++
+ comp2 + comp3 +
+++++++++++++++++

This is still not very customizable (e.g., what if we want comp1 to be 2/3 of the full width?) but is a step forward.