This is a tracking issue. It's mean for short, concise status updates to keep track of progress, not for extensive discussions. Discussions take place here.

The major discussion on Mesa 4.0 have crystalized and found enough alignment to start development. This is an opportunity for breaking changes to address core architectural limitations and make some clean sheet designs.

Based on discussions in:

• Mesa 4 goals #2972

Maintainers and collaborators, feel free to update directly.

Committed

Goals with commitment from the maintenance team.

1. Unified event scheduling and time progression

• Single model.time as universal time source Add model.time as universal source of truth for simulation time #2903
• EventGenerator class for recurring event patterns Add EventGenerator class for recurring event patterns #3201
• Unify event list between Model and Simulator Unify event list between Model and Simulator #3204
• Refactor step scheduling to use EventGenerator internally Refactor step scheduling to use EventGenerator internally #3260
• Add public run_for(), run_until(), schedule_event(), schedule_recurring() to Model Add public event scheduling and time advancement methods #3266
• Migrate examples and tutorials from model.step() to model.run_for() Migrate tutorials and examples to model.run_for() #3270
• Update wolf-sheep example to use new event scheduling API Update wolf-sheep example to use new event scheduling API #3278
• Stabilize event scheduling system from experimental to mesa.time Stabilize event scheduling system from experimental to mesa.time #3276
• Deprecate Simulator, ABMSimulator, and DEVSimulator classes Deprecate Simulator classes, add migration guide entry #3277
• Add deprecation warnings to model.step() and run_model()
• Rewrite agent activation, event scheduling and time progression tutorials Add agent activation, event scheduling and time progression tutorials #3280
• Remove model.steps remove model.steps #3328
• Enforce monotonic time in event scheduling Enforce monotonic time invariant in event scheduling #3343
• Add pause() and resume() to EventGenerator add pause and resume to EventGenerator #3431
• Add next_scheduled_time property to EventGenerator add next_scheduled_time property to EventGenerator #3423
• Add compact() to EventList for cancelled event cleanup Add compaction method to Eventlist to reduce performance degradation under heavy cancellation #3359
• Remove remaining deprecated APIs (e.g., Simulator classes)

Open discussions:

1. Either exposing _default_schedule as a public property (allowing users to modify/disable the default step pattern) or moving away from a default scheduled method completely: Does Mesa need a "heartbeat"?
2. Conditional running and stopping API.

Related:

• Proposal: Unified Time and Event Scheduling API #2921, Conceptual model of Space #2585, Support for agent movement in continuous spaces #2967

Coordinating lead: @EwoutH

2. Space Architecture

• Define Locatable protocol (requires agent.position and cell.position)
• Agent hierarchy: base Agent → CellAgent (1 discrete space) → ContinuousAgent (1 continuous + 0...n discrete)
• Distinguish cell coordinates from logical indices in discrete spaces
• Each discrete space implements position_to_cell() translation
• Replace PropertyLayer with raw NumPy arrays on grid Remove PropertyLayer and HasPropertyLayers mixin  #3340
• Convert DiscreteSpace to abstract base class Convert DiscreteSpace to an Abstract Base Class #3387
• Remove mesa.space Remove mesa.space #3337
• Properties linked to cell indices (not coordinates)
• Support multiple aligned spaces sharing coordinate system
• Observable position pattern: agent.position setter notifies discrete spaces
• Space membership determines: capacity, neighbor queries, visibility

Related:

• Conceptual model of Space #2585, Support for agent movement in continuous spaces #2967, World prototype #3034, Support multiple spaces (using observable positions) #3043, Make cell.empty read only #3072

Coordinating lead: @quaquel

3. Data Collection

• Make the model reactive so that DataSet and Collector can (potentially) do this Making Model reactive #3212
• Add DataSet and DataRegistry Add data registry #3156
• Add a reactive collector for datasets Add DataRecorder for reactive Data Storage and DatasetConfig for Configuration #3145
• Add DataSet.record() method Add DataSet.record() #3295
• Add deprecation warnings to DataCollector
• Remove DataCollector in Mesa 4.0
• Rewrite data collection tutorials

Related:

• The future of data collection #1944, Multi-Agent data collection #348

Coordinating lead: @quaquel

4. Clean Experimentation

• Remove batch_run Remove batch_run.py #3325
• Remove seed parameter from Model.__init__() Remove seed kwarg #3318
• Add Scenario class for run specifications Add explicit support for Scenarios #3103
• Design clean API: set parameters → run model → extract data
• ...

Related:

• Next-gen batch runner #2321, A system for managing Model/Agent default values and ranges #2268

Collaborative effort.

Uncommitted

More discussion, commitment from contributors and/or support from maintainers team might be needed. Potential for GSoC!

4. Stable Visualization

• Evaluate long-term viability of Solara dependency
• Implement reactive UI design (decouple render speed from model speed)
• Support replay/rewind capabilities
• Focus on stability over new features
• Related: mesa-interactive direction

5. Advanced Agent Behavior

• Add experimental Action system with timed, interruptible actions Add Actions: event-driven timed agent behavior (v2) #3461
• Composable behavioral building blocks
• Support for goals, tasks, interruptions
• Continuous state evolution
• Related: Behavioral Framework #2538, Tasks #2526, Continuous States #2529

6. ML/RL/AI Integration

• Clean integration points for ML/RL/LLM approaches
• Support simulation-based inference
• Differentiable models where possible
• Related: Mesa RL #2070, ActionSpace: Defining the influence Agents can have #2858

7. Module System

• Extensible, shareable component architecture
• Domain-specific libraries (epidemiology, economics, etc.)
• Clear compatibility and maintenance expectations
• Related: variable name heading0/1 in ArrowHead shape is not intuitive. #295.

Overlapping/other

8. Performance

• Extensive profiling of Mesa overhead
• Explore Cython for continuous spaces
• Evaluate Rust for discrete grids (experimental mesa-rust repo)
• Optimize CellCollection.agents and Space.select_random_empty_cell

9. API Design

• Custom Mesa exception hierarchy (MesaError base class) POC: Exception Hierarchy for Mesa 4.0 #3197
• Keyword-only arguments for core Model/Agent methods
• Metadata in exceptions (Mesa version, agent context, etc.)
• Related: Refactor: Replace generic Exception with RuntimeError in Cell.add_agent #2950, Feat: Introduce dedicated exception hierarchy in mesa/errors.py  #2992