Skip to content

v3.0.0

Latest
Compare
Choose a tag to compare
@EwoutH EwoutH released this 09 Nov 08:07
· 7 commits to main since this release
743f830

Highlights

After our most extensive pre-release program ever, we’re proud to release Mesa 3.0 as stable. Mesa 3.0 brings major improvements to agent-based modeling, making it more intuitive and powerful while reducing complexity. This release modernizes core functionalities and introduces new capabilities for both beginners and advanced users.

Streamlined agent management

The centerpiece of Mesa 3.0 is its new agent management system. Agents are now automatically tracked and assigned unique IDs, eliminating common boilerplate code. The new AgentSet functionality provides an elegant and flexible way to work with agents, for example:

# Find agents meeting specific criteria
wealthy_agents = model.agents.select(lambda a: a.wealth > 1000)

# Group and analyze agents
grouped = model.agents.groupby("state")
state_stats = grouped.agg({
     "count": len,
     "avg_age": ("age", np.mean),
     "total_wealth": ("wealth", sum)
 })

# Activate agents in different patterns
model.agents.shuffle_do("step")  # Random activation
model.agents.select(lambda a: a.energy > 0).do("move")  # Conditional activation

The AgentSet provides powerful methods for filtering, grouping, and analyzing agents, making it easier to express complex model logic. Each model automatically maintains an AgentSet containing all agents (model.agents) and separate AgentSets for each agent type (model.agents_by_type). See the full AgentSet docs here.

Modern Visualization with SolaraViz

Mesa 3.0's new experimental visualization system, SolaraViz, provides a modern, interactive interface for model exploration:

from mesa.visualization import SolaraViz, make_space_component, make_plot_component

visualization = SolaraViz(
    model,
    [
        make_space_component(agent_portrayal),
        make_plot_component(["population", "average_wealth"]),
        lambda m: f"Step {m.steps}: {len(m.agents)} agents"  # Custom text component
    ],
    model_params=parameter_controls
)

Key visualization features:

  • Interactive browser-based interface with real-time updates
  • Support for both grid-based and network models
  • Visualization of PropertyLayers and hexagonal grids
  • Custom components using Matplotlib or text
  • Improved performance and responsiveness

Check out the Visualization Tutorial to get started.

Note: SolaraViz is in active development. We might make API breaking changes between Mesa 3.0 and 3.1.

Enhanced data collection

The DataCollector now supports collecting different metrics for different agent types, using agenttype_reporters:

self.datacollector = DataCollector(
    model_reporters={"total_wealth": lambda m: m.agents.agg("wealth", sum)},
    agent_reporters={"age": "age", "wealth": "wealth"},
    agenttype_reporters={
        Predator: {"kills": "kills_count"},
        Prey: {"distance_fled": "total_flight_distance"}
    }
)

Experimental features

Mesa 3.0 introduces several experimental features for advanced modeling:

These experimental features are in active development and might break API between releases.

Breaking changes

See our Mesa 3.0 migration guide for a full overview.

If you want to move existing models from Mesa 2.x to 3.0, there are a few things you have to change.

  1. Models must explicitly initialize the Mesa base class:
class MyModel(mesa.Model):
    def __init__(self, n_agents, seed=None):
        super().__init__(seed=seed)  # Required in Mesa 3.0
  1. Agents are created without manual ID assignment:
# Old
agent = MyAgent(unique_id=1, model=self)
# New
agent = MyAgent(model=self)
  1. Scheduler replacement with AgentSet operations:
# Old (RandomActivation)
self.schedule = RandomActivation(self)
self.schedule.step()

# New
self.agents.shuffle_do("step")

# Old (SimultaneousActivation)
self.schedule = SimultaneousActivation(self)
self.schedule.step()

# New
self.agents.do("step")
self.agents.do("advance")

Furthermore:

  • Steps counter automatically increments
  • mesa.flat namespace removed
  • Python 3.10+ required
  • Reserved model variables (agents, steps, etc.) protected
  • Simplified DataCollector initialization
  • Old visualization system replaced by SolaraViz

Getting Started

Install Mesa 3.0:

pip install --upgrade mesa

If building a new model, we recommend checking out the updated Mesa Overview and Introductory Tutorial.

For updating existing models, we recommend upgrading in steps:

  1. Update to latest Mesa 2.x
  2. Address deprecation warnings
  3. Upgrade to Mesa 3.0
  4. Replace schedulers with AgentSet functionality

A detailed migration guide is available to help moving to Mesa 3.0. For questions or support, join our GitHub Discussions or Matrix Chat.

We would love to hear what you think about Mesa 3.0! Say hello here and leave any feedback on 3.0 here.

What's Changed

⚠️ Breaking changes

  • Remove mesa.flat namespace by @rht in #2091
  • breaking: Remove visualization_old (mesa-viz-tornado) by @rht in #2133
  • viz: Combine code for rendering in browser and Jupyter by @rht in #2180
  • breaking: Add dependencies argument to custom space_drawer by @rht in #2209
  • Require Mesa models to be initialized with super().__init__() by @EwoutH in #2218
  • Allow AgentSet.do() to take Callable function by @quaquel in #2219
  • Change warning when setting model.agents to error by @EwoutH in #2225
  • model: Automatically increase steps counter by @EwoutH in #2223
  • move solara_viz back to experimental by @Corvince in #2278
  • track unique_id automatically by @quaquel in #2260
  • update Agent.init to remove deprecation warning by @quaquel in #2328
  • replace model with random in AgentSet init by @quaquel in #2350
  • remove cookiecutter by @quaquel in #2421
  • Viz: Refactor Matplotlib plotting by @quaquel in #2430
  • api reorganization by @quaquel in #2447
  • Deprecate initialize_data_collector by @EwoutH in #2327

🧪 Experimental features

🎉 New features added

🛠 Enhancements made

  • Rename JupyterViz to SolaraViz by @rht in #2187
  • refactor: Rename jupyter_viz namespace to solara_viz by @rht in #2188
  • Visualisation: Allow specifying Agent shapes in agent_portrayal by @rmhopkins4 in #2214
  • Split AgentSet into map and do to seperate return types by @quaquel in #2237
  • Performance enhancements for Model.agents by @quaquel in #2251
  • AgentSet: Allow selecting a fraction of agents in the AgentSet by @EwoutH in #2253
  • Model: Replace get_agents_of_type method with agents_by_type property by @EwoutH in #2267
  • add default SolaraViz by @Corvince in #2280
  • Simplify ModelController by @Corvince in #2282
  • Add default values and missing value handling to agentset.get by @quaquel in #2279
  • SolaraViz Updates by @Corvince in #2299
  • Solara viz: use_task for non-threaded continuous play by @Corvince in #2304
  • Reduce core dependencies, split in optional dependencies by @EwoutH in #2265
  • use GridDraggable instead of Column in SolaraViz by @wang-boyu in #2344
  • update legend, xlabel & format of matplotlib plots by @wang-boyu in #2346
  • init.py: Import mesa.experimental by @EwoutH in #2374
  • Importable examples by @Corvince in #2381
  • update_tutorial environment by @tpike3 in #2411
  • expand ax.scatter kwargs that can be used by @quaquel in #2445

🐛 Bugs fixed

  • datacollector: store separate snapshots of model data per step by @EwoutH in #2129
  • Jupyter_viz: Allow measures to be None by @EwoutH in #2163
  • Jupyter Viz: Don't avoid interactive backend by @EwoutH in #2165
  • fix: Render agent marker radius correctly by @rht in #2181
  • fix: Use model.schedule.steps -> mode._steps for batch_run by @rht in #2183
  • SolaraViz: Reset components when params are changed by @rht in #2240
  • Fix deterministic behavior in move_agent_to_one_of with selection="closest" by @OrenBochman in #2118
  • viz: stop running and disable buttons when model.running is False by @wang-boyu in #2332
  • experimental init: Fix Solara import by making it lazy by @EwoutH in #2357
  • fix: pass model.random to schedulers by @quaquel in #2359
  • fix: register agent after creating unique_id and pos attributes by @wang-boyu in #2368
  • solara: viz tutorial: fix histogram code by @Corvince in #2379
  • Fix for mistaken removal of _draw_grid by @quaquel in #2398
  • fixes weakref bug in shuffe_do by @quaquel in #2399
  • Fix #2452 - handle solara viz model params better by @Corvince in #2454
  • Update MoneyModel.py by @quaquel in #2458
  • Bugfix for Solara deepcopy bug by @quaquel in #2460
  • solaraviz kwargs related bugfix by @quaquel in #2463

🔍 Examples updated

📜 Documentation improvements

🔧 Maintenance

  • CI: Add weekly scheduled run to all CI workflows by @EwoutH in #2130
  • Drop support for Python 3.9, require Python >= 3.10 by @EwoutH in #2132
  • Add script to list unlabeled PR's since latest release by @rht in #2047
  • CI: Let pytest treat warnings as errors for examples by @EwoutH in #2204
  • CI: Add test job for Python 3.13 by @EwoutH in #2173
  • Add pull request templates by @EwoutH in #2217
  • benchmarks: Add BoltzmannWealth model by @EwoutH in #2252
  • CI: Add optional dependency for examples by @EwoutH in #2261
  • Resolve multiprocessing warning, state Python 3.13 support by @rht in #2246
  • make typing behavior of AgentSet.get explicit by @quaquel in #2293
  • model: Move random seed and random to init by @rht in #1940
  • Remove schedulers from benchmark models. by @quaquel in #2308
  • tests: Resolve warnings by removing scheduler and updating arguments by @EwoutH in #2329
  • add super call to Model and remove self.schedule by @quaquel in #2334
  • Code coverage: ignore experimental and visualization by @Corvince in #2361
  • add codecov token, fixes #2363 by @Corvince in #2366
  • add test_time back by @quaquel in #2367
  • Release notes: Add example category by @EwoutH in #2369
  • Add empty pull_request_template.md to enable PR template chooser by @EwoutH in #2409
  • remove deprecated HexGrid class by @quaquel in #2441
  • rename make_plot_measure to make_plot_component and add some kwargs by @quaquel in #2446

New Contributors

Full Changelog: v2.4.0...v3.0.0