Merge remote-tracking branch 'upstream/main'

quaquel · quaquel · commit e3df717e7097 · 2025-12-30T10:40:15.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -177,6 +177,42 @@ All roles are expected to:
 
 Mesa grows through good ideas and contributions. We're all volunteers working together to make Mesa better. Don't hesitate to reach out to any maintainer to discuss your interests and potential growth within the project!
 
+## Mesa examples structure and policy
+Mesa maintains a curated set of core examples within the main repository, complemented by a separate [mesa-examples](https://github.com/mesa/mesa-examples) repository for community contributions. This two-tier structure balances maintainability with community creativity.
+
+### Core examples (in `mesa/examples`)
+Core examples in the main Mesa repository are classic, well-known agent-based models that demonstrate Mesa's capabilities and serve as learning resources. They are organized into two categories:
+
+- **Basic Examples** use only stable Mesa features and are ideal starting points for beginners.
+- **Advanced Examples** are more complex models that may use experimental features to demonstrate advanced concepts.
+
+Core examples are:
+- Tested in CI, including batch runs and visualizations
+- Maintained to high code quality standards
+- Updated to work with each Mesa release
+- Documented and included in ReadTheDocs
+- Some are used in performance benchmarking
+
+### Community examples (in mesa-examples)
+The [mesa-examples](https://github.com/mesa/mesa-examples) repository serves as a gallery for user-contributed models and creative applications of Mesa. We welcome diverse contributions here with more relaxed maintenance requirements. Examples in this repository should include:
+- A clear README explaining the model
+- Requirements or environment files for reproducibility
+- Working code compatible with at least one Mesa major version
+
+We accept contributions liberally to this repository to showcase the breadth of Mesa applications, even if we cannot actively maintain all examples long-term.
+
+### Contributing examples
+When contributing a new example, consider:
+- **For core examples**: Propose additions through a GitHub discussion first. Core examples should be:
+  - widely-recognized canonical models
+  - demonstrate specific Mesa features effectively (that are not already sufficiently demonstrated by other models)
+- **For community examples**: Open a PR directly to mesa-examples with your model, README, and environment file.
+- **Improving existing examples**: PRs to update or enhance any example are always welcome in either repository.
+
+This structure allows us to maintain a stable, high-quality set of learning resources while encouraging community creativity and diverse applications of Mesa.
+
+Historical context and further motivation can be found in discussion [#2330](https://github.com/mesa/mesa/discussions/2330) and PR [#2349](https://github.com/mesa/mesa/pull/2349).
+
 ## Maintainers' notes
 Some notes useful for Mesa maintainers.
 
diff --git a/docs/tutorials/1_adding_space.ipynb b/docs/tutorials/1_adding_space.ipynb
@@ -347,7 +347,7 @@
    "source": [
     "## Next Steps\n",
     "\n",
-    "Check out the [collecting data tutorial](https://mesa.readthedocs.io/latest/tutorials/2_collecting_data_tutorial.html) on how to collect data form your model."
+    "Check out the [collecting data tutorial](https://mesa.readthedocs.io/latest/tutorials/2_collecting_data.html) on how to collect data form your model."
    ]
   },
   {
diff --git a/mesa/discrete_space/grid.py b/mesa/discrete_space/grid.py
@@ -141,7 +141,7 @@ def _validate_parameters(self):
             raise ValueError("Capacity must be a number or None.")
 
     def select_random_empty_cell(self) -> T:  # noqa
-        # FIXME:: currently just a simple boolean to control behavior
+        # Use a heuristic: try random sampling first for performance (O(1))
         # FIXME:: basically if grid is close to 99% full, creating empty list can be faster
         # FIXME:: note however that the old results don't apply because in this implementation
         # FIXME:: because empties list needs to be rebuild each time
@@ -151,12 +151,14 @@ def select_random_empty_cell(self) -> T:  # noqa
         # https://github.com/mesa/mesa/pull/1565. The cutoff value provided
         # is the break-even comparison with the time taken in the else branching point.
         if self._try_random:
-            while True:
+            # Limit attempts to avoid infinite loops on full grids
+            for _ in range(50):
                 cell = self.all_cells.select_random_cell()
                 if cell.is_empty:
                     return cell
-        else:
-            return super().select_random_empty_cell()
+
+        # Fallback to the robust parent method (O(N)) if random sampling fails
+        return super().select_random_empty_cell()
 
     def _connect_single_cell_nd(self, cell: T, offsets: list[tuple[int, ...]]) -> None:
         coord = cell.coordinate
diff --git a/tests/discrete_space/test_discrete_space.py b/tests/discrete_space/test_discrete_space.py
@@ -1092,3 +1092,21 @@ def test_select_random_agent_empty_safe():
         empty_collection.select_random_agent()
     assert empty_collection.select_random_agent(default=None) is None
     assert empty_collection.select_random_agent(default="Empty") == "Empty"
+
+
+def test_infinite_loop_on_full_grid():
+    """Test that select_random_empty_cell does not hang on a full grid."""
+    # 1. Create a small 2x2 model
+    model = Model()
+    grid = OrthogonalMooreGrid((2, 2), random=model.random)
+
+    # 2. Fill the grid completely
+    for cell in grid.all_cells:
+        agent = CellAgent(model)
+        agent.cell = cell
+
+    # 3. Verify grid is full
+    assert len(grid.empties) == 0
+
+    with pytest.raises(IndexError):
+        grid.select_random_empty_cell()
diff --git a/tests/examples/test_examples_viz.py b/tests/examples/test_examples_viz.py
@@ -72,12 +72,12 @@ def run_model_test(
         # Display and capture the updated visualizations
         display(space_viz)
         page_session.wait_for_selector("img")
-        changed_space = page_session.locator("img").screenshot()
+        changed_space = page_session.locator("img").first.screenshot()
 
         if measure_config:
             display(graph_viz)
             page_session.wait_for_selector("img")
-            changed_graph = page_session.locator("img").screenshot()
+            changed_graph = page_session.locator("img").last.screenshot()
 
         # Convert screenshots to base64 for comparison
         initial_space_encoding = base64.b64encode(initial_space).decode()

Original file line number	Diff line number	Diff line change
`@@ -347,7 +347,7 @@`
`347`	`347`	`"source": [`
`348`	`348`	`"## Next Steps\n",`
`349`	`349`	`"\n",`
`350`		`- "Check out the [collecting data tutorial](https://mesa.readthedocs.io/latest/tutorials/2_collecting_data_tutorial.html) on how to collect data form your model."`
	`350`	`+ "Check out the [collecting data tutorial](https://mesa.readthedocs.io/latest/tutorials/2_collecting_data.html) on how to collect data form your model."`
`351`	`351`	`]`
`352`	`352`	`},`
`353`	`353`	`{`