Add advanced tutorial (Sugarscape IG) notebook script #189
Conversation
adamamer20
changed the title
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #189 +/- ##
=======================================
Coverage 89.23% 89.23%
=======================================
Files 14 14
Lines 2007 2007
=======================================
Hits 1791 1791
Misses 216 216 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
WalkthroughIntroduces a comprehensive Sugarscape advanced tutorial demonstrating a mesa-frames model with sugar landscape dynamics, multiple agent movement strategies (sequential, Numba-compiled, and Polars-parallel), data collection, and comparative analysis harness across implementations. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Harness as Run Harness
participant S as Sugarscape<br/>(init)
participant AB as AntsBase<br/>(variant)
participant SM as Sugar Map
participant DC as DataCollector
User->>Harness: run_and_compare(steps)
loop For each variant (Sequential, Numba, Parallel)
Harness->>S: __init__(agent_type, seed)
S->>S: _generate_sugar_grid()
S->>S: _generate_agent_frame()
S->>DC: register reporters
loop for step in range(steps)
Harness->>S: step()
S->>AB: move()
alt Sequential/Numba/Parallel
AB->>SM: query sugar positions
AB->>AB: resolve movement & conflicts
end
AB->>AB: eat()
AB->>AB: _remove_starved()
S->>SM: _advance_sugar_field()
S->>DC: collect()
end
Harness->>Harness: aggregate trajectory & runtime
end
Harness->>Harness: generate comparison table<br/>(gini, correlations, agents)
Harness->>User: output results
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/general/tutorials/3_advanced_tutorial.py (2)
129-143: Redundant size check in gini computation.Lines 131-132 check
if sugar.size == 0and returnnan, then line 133 sorts the array intosorted_vals, and lines 135-136 checkif n == 0again. Sincesorted_vals = np.sort(sugar)preserves the size, the second check is redundant.Apply this diff to streamline the check:
sugar = primary_set.df["sugar"].to_numpy().astype(np.float64) if sugar.size == 0: return float("nan") sorted_vals = np.sort(sugar.astype(np.float64)) n = sorted_vals.size - if n == 0: - return float("nan") cumulative = np.cumsum(sorted_vals)
390-407: Duplicate extinction check in step method.The method checks if
self.sets[0]is empty on lines 400-401 and setsself.running = False, then performs the same check again on lines 406-407 after data collection. The second check is defensive but redundant since the agent count cannot increase during data collection.If you prefer to keep the defensive check for clarity, consider adding a comment. Otherwise, consolidate to a single check:
def step(self) -> None: """Advance the model by one step. Notes ----- The per-step ordering is important and this tutorial implements the classic Sugarscape "instant growback": agents move and eat first, and then empty cells are refilled immediately (move -> eat -> regrow -> collect). """ if len(self.sets[0]) == 0: self.running = False return self.sets[0].step() self._advance_sugar_field() self.datacollector.collect() - if len(self.sets[0]) == 0: - self.running = False
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/general/tutorials/3_advanced_tutorial.py(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
**/*.py: Use Python 3.11 or later with 4-space indentation
Include type hints for all public APIs
Use NumPy-style docstrings (validated by Ruff/pydoclint)
UseCamelCasefor class names
Usesnake_casefor function and attribute names
Avoid usingTYPE_CHECKINGguards for type annotations because the project usesbeartypefor runtime type checking, which requires the actual type objects to be available at runtime
Treat underscored attributes as internal/private and not part of the public API
Files:
docs/general/tutorials/3_advanced_tutorial.py
🪛 Ruff (0.14.7)
docs/general/tutorials/3_advanced_tutorial.py
47-47: String contains ambiguous – (EN DASH). Did you mean - (HYPHEN-MINUS)?
(RUF001)
294-296: Avoid specifying long messages outside the exception class
(TRY003)
495-497: Avoid specifying long messages outside the exception class
(TRY003)
1145-1145: Comment contains ambiguous ‑ (NON-BREAKING HYPHEN). Did you mean - (HYPHEN-MINUS)?
(RUF003)
1546-1546: String contains ambiguous – (EN DASH). Did you mean - (HYPHEN-MINUS)?
(RUF001)
1569-1569: Comment contains ambiguous ‑ (NON-BREAKING HYPHEN). Did you mean - (HYPHEN-MINUS)?
(RUF003)
1571-1571: Comment contains ambiguous ‑ (NON-BREAKING HYPHEN). Did you mean - (HYPHEN-MINUS)?
(RUF003)
1645-1645: String contains ambiguous – (EN DASH). Did you mean - (HYPHEN-MINUS)?
(RUF001)
🔇 Additional comments (1)
docs/general/tutorials/3_advanced_tutorial.py (1)
1-1648: Excellent tutorial implementation demonstrating mesa-frames advanced features.This comprehensive tutorial successfully demonstrates:
- Three distinct movement strategies (sequential Python, Numba-compiled, and Polars-parallel)
- Proper separation of concerns between model orchestration and agent behavior
- Extensive documentation with NumPy-style docstrings
- Edge case handling (empty sets, extinction, conflict resolution)
- Comparative analysis framework showing macro-level equivalence across implementations
The code is well-structured, follows project conventions, and provides a strong pedagogical example of mesa-frames capabilities. The minor issues flagged above are optional improvements that don't affect correctness or tutorial value.
| the model converges to the *same* macroscopic inequality pattern regardless of | ||
| whether agents act sequentially or in parallel and that As long as the random draws do | ||
| not push the system into extinction, the long-run Gini coefficient of wealth and | ||
| the wealth–trait correlations line up within sampling error — a classic example |
There was a problem hiding this comment.
Ambiguous Unicode characters in strings and comments.
Static analysis detected non-ASCII dash characters that may cause issues with text editors or search:
- Lines 47, 1546, 1645: EN DASH (–) in strings
- Lines 1145, 1569, 1571: NON-BREAKING HYPHEN (‑) in comments
Consider replacing with standard ASCII HYPHEN-MINUS (-) for consistency.
You can identify and replace these using:
#!/bin/bash
# Find lines with ambiguous Unicode dash characters
rg --line-number '[\u2013\u2011]' docs/general/tutorials/3_advanced_tutorial.pyAlso applies to: 1145-1145, 1546-1546, 1569-1569, 1571-1571, 1645-1645
🧰 Tools
🪛 Ruff (0.14.7)
47-47: String contains ambiguous – (EN DASH). Did you mean - (HYPHEN-MINUS)?
(RUF001)
🤖 Prompt for AI Agents
In docs/general/tutorials/3_advanced_tutorial.py around lines 47, 1145, 1546,
1569, 1571, and 1645, there are ambiguous Unicode dash characters (EN DASH
U+2013 and NON‑BREAKING HYPHEN U+2011) in strings/comments; replace each with
the ASCII hyphen-minus (-) to avoid editor/search issues and ensure consistency;
perform a targeted search for U+2013 and U+2011 in those lines and apply a
simple replace, then run tests or a quick grep to confirm all occurrences were
converted.
Introduce an advanced tutorial notebook script to rebuild the Sugarscape Instant-growback model using mesa-frames
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.