Move essential examples back to main repo and test them in CI

[EwoutH]

All mesa examples were moved to mesa-examples in #1529. While unfortunately that PR doesn't provide or link to motivation for that move, I would propose moving at least some of them - and maybe all of them - back to the main Mesa repo.

This has four distinct advantages:

• The examples will be more visible and easier to install for users.
• The examples will be part of tagged releases, ensuring that examples also follow versioning and are in sync with the Mesa functionality for each release.
• The examples can be (easier) tested in CI, to detect (breaking) changes.

To make that work, when new functionality is included in a PR, we could require the essential examples to be updated as well. This way they will always be up to date and show if any (breaking) changes need to be made.

[wang-boyu]

If I recall correctly, one of the motivations is to have separate repos for devs and users. Devs/maintainers will be mostly working on the source code repo. Users, on the other hand, will be mainly using readthedocs site and the examples repo, without looking into Mesa's source code.

Previously I suggested to have a dedicated website for example models: projectmesa/mesa-examples#61. It would also be interesting to have example models from community contributions: projectmesa/mesa-examples#11 (comment). Separating example models from source code repo would make such efforts easier to maintain, IMHO.

[Corvince]

Yes i think it was one of the original ideas to have some core examples that also get some more love with updating in the main repo. And the examples repo to have more of a model zoo where people can more easily contribute models.

One thing to note is that we should also be able to run the examples as part of our ci even when they are on a different repo. First step would be to have a test in the examples repo, I already submitted a PR for that. Then we just have to clone the repo and run the test.

But I believe it would still be nice to have some examples in the main repo to more easily run them locally as part of the test runner and also to possibly highlight them further.

[EwoutH]

How feasible do you both think something like NetLogo Web but for Mesa would be?

[wang-boyu]

It has become more feasible since the support for Jupyter notebooks - the least we can do is to convert examples into notebooks, have a static webpage with all the notebook, and let users run by themselves on Binder or Colab (example: https://juliaclimate.github.io/Notebooks/ mentioned in projectmesa/mesa-examples#61 (comment))

Another possibility is to deploy all examples on some server, example: https://simrisk.pulcloud.io/riskyfood mentioned in #1906 (comment) and #1800

This is something that I am hoping for, especially if we can have the community to contribute their models (mentioned in projectmesa/mesa-examples#11 (comment)). I also think that it would be nice for some users to only refer to readthedocs site and an example webpage to learn Mesa, without having to visit GitHub at all.

[Corvince]

With you mentioning notebooks - There is also JupyterLite, which allows you to host notebooks statically, but they can directly be run client-side (locally). I think this is super exciting. I already played around with it a bit and want to deploy a test site soon with some of the mesa model notebooks. We then just need to find a way to update them regularly, maybe this can be done through Github Actions.

But the current downside is that solara is not yet supported by Pyodide (which makes JupyterLite possible). But its is on the radar of the solara team and was originally planned for end of last year. If everything falls into place we can then even facilitate a way for users to host their own models statically (which is a lot easier and free on lots of sites, e.g. GitHub Pages)

[EwoutH]

Sounds amazing, I can support on the CI side.

There is an issue we can track: widgetti/solara#449

[EwoutH]

Let's try to get a list of models that we want in the main repo (and why).

I would suggest:

• Boltzmann wealth model. Very easy, very simple, good to start with.
  • RandomActivation, MultiGrid
• Boid flockers. Good demo of agent movements and the continuous space
  • RandomActivation, ContinuousSpace
• Conway's Game Of Life. Classic, shows nice emergent properties. Candidate for PropertyLayer implementation.
  • SimultaneousActivation, SingleGrid
• Wolf-Sheep Predation. Multiple agent types, agent creation and deletion. Candidate for PropertyLayer methods.
  • RandomActivationByTypeFiltered, MultiGrid
• Virus on a Network. Mainly to test the NetworkGrid.
  • RandomActivation, NetworkGrid
• Hexagonal GoL. A (the only) demo of HexGrid.
  • SimultaneousActivation, HexGrid

[rht]

Prior thread: #134. Another reason for having all the examples in 1 repo is that you (both developers and users) know exactly there is 1 repo where all the examples reside, and without having consciously remember which example is in the examples repo, or which example is in the core Mesa repo. Also, there is an issue where most discussion threads, I have pointed to the mesa-examples repo, and to move some of them back would break the links.

[EwoutH]

In popular demand, I will develop a benchmark script, that can both be run locally and in CI that reports back on each GitHub PR. Therefor it needs some model in the repo (to be able to run it locally).

1. Do we want the models purely for the benchmarks, or also as examples?
2. Which models do we want for benchmarking?

[EwoutH]

They are not tracked in git at all, so they remain unchanged.

[quaquel]

I thought so. Thanks for confirming. Then, that is the simple fix.

[EwoutH]

Stuff working locally. I think it can quite reliably detect changes +- 5% in model init and runtimes (depending on system of course).

Next up CI!

[quaquel]

Good stuff! Will be great to test in conjunction with @Corvince's work on an alternative grid implementation. Is the code online up to date?

[EwoutH]

Yes