diff --git a/docs/migration_guide.md b/docs/migration_guide.md index 073168df194..c8c06860055 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -29,10 +29,49 @@ The `mesa.flat` namespace is removed. Use the full namespace for your imports. - Ref: [PR #2091](https://github.com/projectmesa/mesa/pull/2091) -### Automatic assignment of `unique_id` to Agents - +### Mandatory Model initialization with `super().__init__()` +In Mesa 3.0, it is now mandatory to call `super().__init__()` when initializing your model class. This ensures that all necessary Mesa model variables are correctly set up and agents are properly added to the model. + +Make sure all your model classes explicitly call `super().__init__()` in their `__init__` method: + +```python +class MyModel(mesa.Model): + def __init__(self, *args, **kwargs): + super().__init__() # This is now required! + # Your model initialization code here +``` + +This change ensures that all Mesa models are properly initialized, which is crucial for: +- Correctly adding agents to the model +- Setting up other essential Mesa model variables +- Maintaining consistency across all models + +If you forget to call `super().__init__()`, you'll now see this error: -- Ref: [PR #2226](https://github.com/projectmesa/mesa/pull/2226) +``` +RuntimeError: The Mesa Model class was not initialized. You must explicitly initialize the Model by calling super().__init__() on initialization. +``` + +- Ref: [PR #2218](https://github.com/projectmesa/mesa/pull/2218), [PR #1928](https://github.com/projectmesa/mesa/pull/1928), Mesa-examples [PR #83](https://github.com/projectmesa/mesa-examples/pull/83) + + +### Automatic assignment of `unique_id` to Agents +In Mesa 3.0, `unique_id` for agents is now automatically assigned, simplifying agent creation and ensuring unique IDs across all agents in a model. + +1. Remove `unique_id` from agent initialization: + ```python + # Old + agent = MyAgent(self.next_id(), self, ...) + + # New + agent = MyAgent(self, ...) + ``` +2. `Model.next_id()` is deprecated and will always return 0. Remove any calls to this method. +3. `unique_id` is now unique relative to a Model instance and starts from 1. +4. If you previously used custom `unique_id` values, you'll need to store that information in a separate attribute. +5. Deprecation warning: Initializing an agent with two arguments (`unique_id` and `model`) will raise a warning. The `unique_id` argument will be ignored. + +- Ref: [PR #2226](https://github.com/projectmesa/mesa/pull/2226), [PR #2260](https://github.com/projectmesa/mesa/pull/2260), Mesa-examples [PR #194](https://github.com/projectmesa/mesa-examples/pull/194), [Issue #2213](https://github.com/projectmesa/mesa/issues/2213) ### AgentSet and `Model.agents`