Cleanup and restructure basic example models

[EwoutH]

This PR updates the basic example models to:

• All have their Agent code in an agents.py file.
• Use a flat structure.
• Use the newest SolaraViz API
• Have the old visualization code removed.

This PR is structured in 9 commits, here are the specific updates per model/commit:

1. Boid Flockers:
   • Updated visualization with sliders for colored boids (1648fe0)
   • Removed old visualization code (904030b)
   • Restructured into separate agents.py and model.py files (421ee78)
2. Boltzmann Wealth Model:
   • Restructured into agents.py and model.py (98e9604)
   • Made compute_gini a Model function (98e9604)
3. Conway's Game of Life:
   • Renamed cell.py to agents.py (18a1e1d)
   • Flattened directory structure (18a1e1d)
   • Removed unnecessary visualization code (18a1e1d)
4. Schelling Segregation Model:
   • Split SchellingAgent into separate agents.py file (985f979)
   • Removed run_ascii.py (no longer supported) (985f979)
   • Cleaned up files (985f979)
   • Updated analysis.ipynb to use new batch_run instead of BatchRunner (6b48e61)
5. Virus on Network:
   • Fixed sliders in SolaraViz app.py to use new API (86aeb52)
   • Moved VirusAgent to separate agents.py file (10a2ef5)
   • Flattened directory structure (10a2ef5)
   • Removed old visualization code (10a2ef5)

Boid Flockers and Virus on Network also got improved visualisation, which now looks like:

[quaquel]

This looks largely fine to me. However, can you run ruff on the examples? The docstring is not allways up to date. In places its missing (e.g., boidflockers app.py) or arguments are in the signature but not the docstring. It can be done as part of this PR or in a follow up PR, but it would be good to ensure that also the documentation is exemplary.

[EwoutH]

However, can you run ruff on the examples?

I installed the packages with pip install . -e, and then all the imports magically work.

The other approach is to add mesa explicitly to your Python path:

import sys
import os

# Add the 'mesa/mesa' directory to the Python path
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../mesa")))

it would be good to ensure that also the documentation is exemplary.
Totally agree, that will be a follow up PR.

I have to figure out what’s the best general approach here, either the pip, path or something else. Then I will document that for all examples. Thoughts on this are welcome!

[EwoutH]

@Corvince I now mostly use matplotlib for space drawings. Would you generally recommend that, or are there any/all cases in which Altair might be a better fit?

[EwoutH]

Another this: I used agents.py instead of the alternative possible naming agent.py, because there might be multiple Agents in that file. Do you agree with this naming?

[Corvince]

@Corvince I now mostly use matplotlib for space drawings. Would you generally recommend that, or are there any/all cases in which Altair might be a better fit?

For now I think this is fine, because we are not there yet, but long term I think altair will be the better choice, as it opens up so much more possibilities. Altair is aware of its data, so it allows things like clicking or hovering on specific agents to trigger some actions, like implemented in mesa-interactive. Thinking about it, its not hard to bring that functionality to mesa, I see if I can submit a PR for it soon. It also allows tooltips with additional information.

Currently the biggest downside is the performance. But Altair ultimatively translates into vega and vega allows dynamically updating the data. So there are some hackish ways to achieve this and maybe this can at some time be done without hacks. And maybe there are more obvious things to increase the performance, I havent looked closely yet.

[Corvince]

However, can you run ruff on the examples?

I installed the packages with pip install . -e, and then all the imports magically work.

I dont think I understand how these 2 things relate to each other. I also don't understand why ruff does not run for the examples automatically? Shouldn't this be part of our CI?

Oh and in general: Great work @EwoutH ! I like the improved visualizations. Haven't looked closely at the code yet.

[EwoutH]

Thanks for the context on Altair! I will actively support and facilitate any work on that.

---

I dont think I understand how these 2 things relate to each other.

Maybe I understood the questions wrong. You can just run the models through either the visualisation (solara run app.py) or (in a new file) create a model instance and run if for a number of steps. Maybe we should also standardize it, but that's our of scope for this PR.

pip install . -e (or the Python path thing) is purely so all the imports work.

I also don't understand why ruff does not run for the examples automatically

It didn't in mesa-examples, and I didn't want everything to break in the original PR. I disabled it purposely here in pyproject.toml. We can discuss if/where we want ruff to run on the examples (there are also arguments against it) and then enable it there. I added it to the tracking list.

[Corvince]

Maybe I understood the questions wrong.

Ah, yes I think you did. @quaquel asked if you could run ruff on the examples, not how you could run the examples.

But I agree that it should be done in a separate PR, otherwise its too hard to distinguish the ruff changes from normal changes.

[EwoutH]

Lol totally missed the word “ruff” in that sentence.

Merging, so we can continue with other stuff from our list.