Tracking issue: Full integration of Example models

[EwoutH]

With the core examples being merged back into Mesa in #2358 and now available in examples we can now start working our checklist:

• [x] Divide models in stable/basic and experimental/advanced models
• [x] Create two folders in Mesa examples: examples/basic and examples/advanced
• [x] Move over those 9 examples from mesa-examples, retaining git history.
• [x] Remove from Mesa-examples (@EwoutH, https://github.com/projectmesa/mesa-examples/pull/225
• [x] Update the examples, to:
  • [x] Use a standard structure: agents.py, model.py and app.py
    • [x] basic examples (@EwoutH, #2365)
    • [x] advanced examples (@EwoutH) (#2408, #2410)
  • [x] Use the latest features and be implemented elegantly
  • [x] Use the latest visualisation
    • [x] basic examples (@EwoutH, #2365)
    • [x] advanced examples (#2408, #2410)
• [x] Include them in Read the Docs (@quaquel, like currently on the EMAworkbench)
• [x] Update all other docs and readmes to point towards the new location
• [ ] Integrate the benchmarks models in them and run benchmarks on them (@EwoutH)
• [x] Update the tests to run continuous testing (https://github.com/projectmesa/mesa-examples/pull/215)
• [ ] Add visualisation testing (https://github.com/projectmesa/mesa-examples/pull/215)
• [ ] We add batch_run testing (#2184, #2185, https://github.com/projectmesa/mesa-examples/pull/144)
• [x] Include examples in coverage #2413
• [x] Enabling ruff and/or ruff-format on (parts of) the examples (in pyproject.toml).
  • [x] basic examples (excluding docstring: https://github.com/projectmesa/mesa/pull/2370)
  • [x] advanced examples #2414
• [ ] Make examples importable (e.g., from mesa.examples import BoltzmannWealthModel) (#2381)
• [x] rework examples landing page on RTD. It should include installation instructions for the examples and should use the examples readme.md.

Feel free to add items, and put your name behind something if you want to pick it up!

[quaquel]

I'll pick up the read the docs stuff as discussed today.

[EwoutH]

@quaquel Awesome! #2365 structures all basic example models to have a flat structure and at least agents.py and model.py, I think that should help.

[EwoutH]

• The moved examples are removed from mesa-examples: https://github.com/projectmesa/mesa-examples/pull/225
• The basic examples have had an extensive update: https://github.com/projectmesa/mesa/pull/2365

I'm going to focus on my thesis for a few days, but happy to review anything!

[Corvince]

Just a heads-up that this broke the docs build for the visualization tutorial, because mesa-examples does no longer provide the BoltzmannWealthModel. The vis tutorial does need a larger update anyways (which I somewhere agreed to do), but still this is a major breaking change that we need to communicate somehow. https://readthedocs.org/projects/mesa/builds/25963527/

Or maybe easier is to provide the same "model export" in core mesa and then just re-export that from mesa-examples. Thats probably the better path now that I think of it. I'll add "make examples importable" to the checklist

[Corvince]

[ ] Discuss enabling ruff and/or ruff-format on (parts of) the examples (in pyproject.toml).

Curious as to why this needs a discussion? I am strongly in favor of enabling it. Whats a reason against it?

[EwoutH]

Just a heads-up that this broke the docs build for the visualization tutorial, because mesa-examples does no longer provide the BoltzmannWealthModel.

I just noticed it also. That's just an question of updating the path to import from mesa/examples/basic, right?

Let's give @tpike3 a chance to finish his tutorial and then go from there.

Curious as to why this needs a discussion? I am strongly in favor of enabling it. Whats a reason against it?

Against: It's a lot of work ;). I made an start in https://github.com/projectmesa/mesa/pull/2370. Docstring we should consider if we want to add and require that everywhere.

[quaquel]

I agree its some work but not as bad as what I did a few weeks back with the docstrings. With @Corvince, I believe that we should just enable it and fix all issues. The examples should exemplify good practices.

[EwoutH]

• Make examples importable (e.g. from mesa.examples import BoltzmannWealthModel)

@Corvince this means we also have to move them from examples to mesa/examples, right? Or can we make them importable in another way?

[Corvince]

Not sure, I checked and experimented briefly. There is an extensive hatch documentation about file selection https://hatch.pypa.io/latest/config/build/#file-selection

From skimming it might be possible from examples, but I don't know if it can automatically be included as "mesa.examples". Someone should figure this out

[EwoutH]

@quaquel if you can find the time, having the examples sorted by Basic and Advanced would be really useful, as well as having the Readme descriptions integrated.

I'm good with making that whole Readme the starting page for https://mesa.readthedocs.io/latest/examples.html, even if it then looks less good on GitHub (or the links only work on Readthedocs, etc.). Renaming headers etc. is also okay.

[quaquel]

The example level readme is already included. I hope to find some time this weekend to do the overview of examples readme.