A website for example models?

[wang-boyu]

Discussed in https://github.com/projectmesa/mesa-examples/discussions/61

^{Originally posted by **wang-boyu** September 21, 2023} I came across with these websites in one of the classes I take this semester: [isee Exchange™](https://exchange.iseesystems.com) and [anylogic cloud](https://cloud.anylogic.com/models). They include models from both the official team as well as the community. Models can be run from within the websites, and there are statistics showing number of runs etc. NetLogo also has its [NetLogo Web](http://www.netlogoweb.org/launch#http://www.netlogoweb.org/assets/modelslib/Sample%20Models/) (but without the statistics). I really like the run statistics as they provide a kind of feedback from users on which models are more popular. This makes me wonder whether we can have something similar for Mesa example models. One advantage we have over Stella/AnyLogic/NetLogo is that we can rely on Google Colab to run models using Jupyter Notebooks. This would also be in line with what we have for Mesa & Mesa-Geo, where there are readthedocs sites for users and GitHub repos for developers. Similarly there could be a website for example model explorers and this GitHub repo containing all source code of the example models.

[EwoutH]

I think pycafe is suggested as one of the options.

• https://github.com/projectmesa/mesa/discussions/2170

[wang-boyu]

I tried to use Solara to build something like https://solara.dev/documentation/examples for Mesa examples. With some kind help from @iisakkirotko in here and Solara's souce code for the page, I was able to get this:

Source code is at my fork: https://github.com/wang-boyu/mesa-examples/tree/mesa-website. The command used is simply solara run mesa_models.website.pages to get it running locally.

My takeaways so far:

1. This needs to be deployed in some (paid?) servers.
2. Documentation may be moved from ReadtheDocs to here if we have such server, much like Solara documentation: https://solara.dev/documentation
3. It would also be nice to have some kind of user management system, so that users can create accounts and we can track popularity of models (number of plays, number of likes, etc), like what's in AnyLogic: https://cloud.anylogic.com/models
4. For each model we can probably add links to open it in Google Colab or pycafe

Overall I think this will be great for showcasing Mesa examples and encouraging coummunity contributions of their models. Thoughts? @projectmesa/maintainers

[EwoutH]

This is really interesting!

1. This needs to be deployed in some (paid?) servers.

Could we deploy with GitHub pages? Or do we need interactive servers on the back-end?

[maartenbreddels]

Would https://py.cafe not work, why would you need a server?

[EwoutH]

@maartenbreddels What's super useful for us of PyCafe is that you have the source code directly side-by-side to the visualisation. That's what NetLogo also does and really powerful to be able to directly interact with it.

How would such a workflow work? Are there any examples, especially on how to setup and deploy? Basically, for us, I image we have one tab for each example in mesa/examples/basic. The model.py and agents.py code should be included in the app, so you can modify the example and then see the effect.

[maartenbreddels]

I'm not exactly sure what you need. But you can imagine embedding pycafe in an iframe. We support special embedding of apps, which is something we use for this mkdocs plugin: https://mkdocs.py.cafe/en/latest/

We also started documenting how we can create these links: https://py.cafe/docs/api#snippet-links

I'm not sure if this helps. If not, let me know in more details what you'd like to build, and we can see how PyCafe can help.

[Corvince]

Yes, py.cafe can be an excellent solution! I just tested it. Here is the Schelling example

I only uploaded the files from examples/basic/schelling, adjusted the requirements.txt file to include mesa and it worked!

So I guess the only thing we would like to have is the ability to automatically think our code with the code on py.cafe. Is there already an api access? So we could just push those files as part of our CI or something like that?

[EwoutH]

I got four of the basic examples working, based on the simulatingrisk/app.py from @rlskoeser.

• Project: https://py.cafe/EwoutH/mesa-solara-basic-examples
• App only: https://py.cafe/app/EwoutH/mesa-solara-basic-examples

So now:

1. We need to link it to our GitHub somehow, that it gets updated with every push to main.
2. Decide what to do with our one Streamlit app conways_game_of_life/st_app.py (convert to Solara or include somehow).

[Corvince]

Ha, I was a few seconds faster, but your solution is already complete 😮

Regarding conway, py.cafe also supports streamlit, but I guess not inside solara? (independent on py.cafe). Any thoughts @maartenbreddels ?

[maartenbreddels]

I wonder if it makes sense to include the 4 apps into 1 into PyCafe, or do split it in 4 PyCafe projects or snippets. The advantage of (separate) projects on PyCafe are that you can add screenshots to it and generate a nice gallery, e.g. https://py.cafe/panel-org/

The downside is that the code lives on PyCafe, and is not linked to GitHub.

Another advantage of having it per project, is that one of your projects could be streamlit based.

Snippet urls, like described on https://py.cafe/docs/api#snippet-links can be programmatically put together, and be generated from a GitHub Action, but they are do not support screenshots/galleries. You can put these links together on a static html file with your own generated gallery, but that is more work.

To explicitly answer the last question: you cannot run streamlit in solara, but indeed it runs on PyCafe

[EwoutH]

@maartenbreddels Thanks!

@Corvince feel free to to continue on my project.

[wang-boyu]

Would https://py.cafe not work, why would you need a server?

Thanks for the response. pycafe would absolutely work, especially something like the gallery metioned above: https://py.cafe/panel-org/.

My concern was that -

1. Each model takes a bit of time to initialize the environment, installing dependencies such as solara, etc. Imagine with dozens or even hundres of examples with their own dependencies, having a server of ready to run models makes it easier for users to quickly go through many examples, before opening pycafe/google colab for one particular example to dig further.
2. Having our own deployment also makes it easier to customize the landing page, e.g., grouping examples by categories, displaying statistics such as number of plays, etc

That said, it's definitely a great idea to have a gallary of mesa models on pycafe, such as what @EwoutH did above. Btw I also tried to use Solara routes, but couldn't get it working for multiple levels, e.g., a path base_url/basic that contains all basic examples (base_url/basic/schelling for Schelling model, and so on), and another base_url/advanced for all advanced models, and base_url/gis for gis models.

[quaquel]

1. Each model takes a bit of time to initialize the environment, installing dependencies such as solara, etc. Imagine with dozens or even hundres of examples with their own dependencies, having a server of ready to run models makes it easier for users to quickly go through many examples, before opening pycafe/google colab for one particular example to dig further.

Given that we have moved a subset of examples back into Mesa itself, would it not be logical to start with those examples (as @EwoutH did)? This would involve 9 curated examples that are always up to date with mesa itself. Depending on how that plays out and what we learn from this, we can always see how we might expand this to mesa-examples (which should become more of a mesa-show-and-tell as discussed as part of the move of some examples back into mesa).

I got four of the basic examples working, based on the simulatingrisk/app.py from @rlskoeser.

Nicely done.

[jackiekazil]

+1 @quaquel - I like this idea -- doing the core ones first.