Investigating approaches for reviving mesa-examples

[areyoush]

Purpose

The objective of this discussion is to explore potential approaches and formulate strategies for reviving mesa-examples.

For more context on the project, you can find a detailed description here.

Current Goals

1. Keeping Examples Working - How do we ensure examples don't silently break as Mesa evolves over time?
2. Making Contribution Attractive - What can we do to make contributing examples to Mesa attractive?
3. Improving Discoverability - How do we make finding relevant examples easy?
4. Sustainable Maintenance - What strategies can we adopt for realistic & efficient maintenance of the examples?

More goals can be added as the project gets scoped further.

Your perspectives and ideas on these, and on the discussions that follow are the most welcome!

[areyoush]

3. Improving Discoverability

Categorization Structure of Example Models in mesa-examples

One discoverability issue in mesa-examples I've come across is that models are primarily organized by spatial implementation rather than by domain. While many examples do include domain context or source information in their READMEs and Citations, they're not surfaced in a way that supports browsing or discovery by domain. This makes it difficult for new users to find examples relevant to a specific problem area (e.g., social science, biology, economics), resulting in manual inspection of multiple examples to reach what they're looking for.

I have proposed a possible improvement here.

[areyoush]

PS: I'm also envisioning a deeper overhaul of the categorization/example model directory structure. After studying up on NetLogo, Julia's Model Zoo and scikit-learn's approach to this, I believe there's a lot of room for improvement.

Idea: Intent-based categorization/directory structure for examples

In this setting, examples are organized primarily by intent to improve discoverability and help users efficiently locate examples relevant to their needs. The idea is to preserve the current spatial and technical categories and introduce multiple discovery paths/categorizations such as domain, complexity, etc in the form of first-class indexes via spaces/, domains/ and complexity/ directories that link to examples across the repository, rather than enforcing rigid space- or domain-based folder placement. This keeps the directory easy to navigate while remaining friendly to new contributors.

We can complement this with a sleek metadata.toml file that keeps classification attached to the examples itself, allowing multiple discovery paths without duplication and preventing indexes from drifting out of sync.

Illustration of how a single example can be discovered through different search intents.

domains/
└── ecology.md
    └── forest_fire

spaces/
└── grid.md
    └── forest_fire

complexity/
├── basic.md
│   └── forest_fire
└── advanced.md

In layman terms: The metadata.toml will be used for declaration of what an example is. This allows the same example to be discoverable through multiple paths such as by domain or by spatial/technical/tooling/complexity category. As a result, users can find examples more easily, regardless of how they choose to browse example models in the repository.

This is what one of those markdown files would look like for all three categories:

domains/ecology.md

# Ecology

Examples that model ecological and environmental systems.

- **Forest Fire**  
  `showcase/forest_fire`

spaces/grid.md

# Grid-based Models

Examples that primarily use grid-based spatial representations.

- **Forest Fire**  
  `showcase/forest_fire`

- **Conway’s Game of Life (Fast)**  
  `showcase/conways_game_of_life_fast`

complexity/basic.md

# Basic

Examples that are simple to understand and suitable as starting points.

- **Forest Fire**  
  `showcase/forest_fire`

- **Conway’s Game of Life (Fast)**  
  `showcase/conways_game_of_life_fast`

Directory Visualization Tree

This is not an exact replication of the actual directory structure, as many files have been intentionally excluded for simplicity. It is intended solely to visualize the proposed structure I've described above.

mesa-examples/
├── showcase/
│   ├── deffuant_weisbuch/
│   │
│   ├── forest_fire/
│   │   ├── forest_fire/
│   │   │   ├── __init__.py
│   │   │   ├── agent.py
│   │   │   └── model.py
│   │   ├── app.py
│   │   ├── README.md
│   │   └── metadata.toml
│   │
│   ├── conways_game_of_life_fast/
│   ├── hex_snowflake/
│   └── virus_antibody/
│
├── domains/
│   ├── social_science.md
│   ├── biology.md
│   ├── economics.md
│   ├── ecology.md
│   └── mathematics.md
│
├── spaces/
│   ├── grid.md
│   ├── continuous.md
│   ├── network.md
│   ├── visualization.md
│   └── gis.md
│
├── complexity/
│   ├── basic.md
│   └── advanced.md
│
├── README.md
└── CONTRIBUTING.md

[EwoutH]

I think there are some good ideas in here. Discoverablility is definitely useful. This implementation sounds a bit like we have different catalogs, and an example can be part of one or more catalogs.

@jackiekazil if you have a moment, might be interesting to check this idea

[areyoush]

Yes, exactly. Those catalogs can be maintained as markdown index files with each example carrying a small metadata.toml that tags it by domain, space, complexity, etc.

The existence of multiple catalogs or entry-points can decrease the friction in exploring examples in the repository by letting users approach the examples from the perspective that is most relevant to them.

We could even extend this metadata with a version compatibility tag that's updated via CI, tagging examples with versions they pass against which later feed into compatibility catalogs.

I’d love to discuss whether this is a viable direction, how it might be matured further, and any obvious pitfalls I may be missing, when you both have the time.

Thanks!

[EwoutH]

A minimal prototype of this would be useful I think.

[areyoush]

Makes sense. I'll whip up a prototype in my fork and share here for feedback.

[jackiekazil]

(Please excuse the delay -- I saw this a week ago, but I knew it needed more time to research and respond than I had in that moment.)

@EwoutH, @areyoush I think you have awaking my former library engineer days. If we are doing this right, with respect to metadata, I think we should consider where we want to end up and then pull back to MVP.

I wrote this up, because this felt like more than a passing comment, but a bigger discussion.
mesa/mesa#3272