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

[areyoush]

Prototype: Intent-based Organization & Metadata Schema for Mesa Examples

Following the discussion on Discoverability and Metadata Standards for Mesa, I've put together a prototype that builds on exploring intent-based organizational structure in the mesa-examples repository using metadata schema.

Problems this prototype addresses:

• Discovering relevant models - Users often need to manually browse multiple folders and read documentations to reach the example models they intend to find. Organizing example models primarily by spatial implementation reduces discoverability by creating friction for users who are searching for models by domain, temporal structure, complexity to implement, or modeling concept. This is particularly relevant for users who approach the framework and the repository with a specific goal such as finding examples relevant to a research area, understanding a modeling concept, or learning how a certain type of model is implemented in Mesa.

• Lack of consistent metadata - Example currently do not expose structured, machine-readable metadata describing what they demonstrate. While READMEs often explain how the model works or how to run it, important contextual information such as domain, implementation complexity, and keywords is either missing, inconsistently described, or is not machine-readable. Without standardized metadata, this information cannot be reliably used for indexing, filtering, or automated tooling across the repository.

• Scaling Repository Organization - As more community examples are added to the repository, maintaining categorized lists of example models directly in the root README, as is currently done, will not scale well. The file becomes longer and harder to maintain, and contributors/maintainers must update the same document whenever new examples are added.

Overview of the Prototype

This prototype explores an approach to improving how example models in mesa-examples are organized and discovered by leveraging model metadata. Each example model includes a small metadata file that describes key attributes of the model such as its domain, spatial and temporal structure, implementation complexity, and relevant keywords.

Using this metadata, examples can be indexed through dedicated catalog pages that group models by different discovery facets (e.g., domain, space, complexity). These catalogs pages are simple markdown index files that point to examples across the repository. They act as alternative entry-points for exploring the repository, allowing users to browse examples through the perspective most relevant to their intent.

This approach keeps the example models themselves in a single location while enabling multiple ways to discover them without duplicating files or restructuring the repository.

Intent-based discovery structure: Different user intents lead to catalog pages (e.g., by domain, space, or complexity), which then point to the same example model in the repository.

Metadata Schema for Example Models

The following example shows how the proposed metadata schema would appear for the Forest Fire model.

[work]
title = "Forest Fire Model"

abstract = """
A stylized agent-based model of forest dynamics in which trees grow,
ignite, and burn according to stochastic local interaction rules,
exhibiting self-organized criticality.
"""

doi = "10.0000/example.forestfire.mesa"


[work.authorship]
creators = ["Per Bak", "Kim Christensen"]
contributors = ["ABM Community"]


[work.classification]
domain = [
  "ecology",
  "complex systems",
  "statistical physics"
]

keywords = [
  "forest fire",
  "self-organized criticality",
  "cellular automaton",
  "critical phenomena"
]


[work.structure]
space = "grid"
time = "discrete"


[manifestation]
complexity = "basic"
mesa = ">=3.0.0"

---

Prototype Implementation

A working prototype of this organizational structure and metadata schema has been implemented in my fork of the mesa-examples repository.

It includes:

• Example models updated with metadata.toml files
• Catalog pages for domains, spaces, and complexity
• A reorganized root README demonstrating how the catalogs act as discovery entry points

You can explore the prototype here:

https://github.com/areyoush/mesa-examples/tree/prototype/example-metadata

@jackiekazil @EwoutH If you find the time, I would love to hear your thoughts on the structure, metadata fields and the overall approach to the prototype. I would also love to know whether this could form a GSoC proposal under the broader Reviving mesa-examples project, particularly as a component focused on improving discoverability and organization of example models.