Stop overriding Model.__init__() in user models, use a setup method instead

[EwoutH]

Context and Motivation

In the current Mesa framework, users are advised to override the Model.__init__ method to set up their custom models. However, this approach has led to some challenges:

1. Users must remember to call super().__init__() in their custom __init__ method.
2. The need to pass *args and **kwargs through super().__init__() can lead to confusing and "ugly" code.
3. Modifying the Model.__init__ signature in future versions of Mesa could potentially break user-defined models.

To address these issues and provide a cleaner, more flexible approach to model initialization, we propose introducing a new setup method.

Proposed Changes

1. Introduce a new setup method in the Model class:

class Model:
    def __init__(self, seed: Optional[float] = None, **kwargs: Any) -> None:
        self.running = True
        self.steps: int = 0
        self._seed = seed if seed is not None else random.random()
        self.random = random.Random(self._seed)
        self._setup_agent_registration()
        
        # Remove 'seed' from kwargs before passing to setup
        kwargs.pop('seed', None)
        # Call user-defined setup
        self.setup(**kwargs)

    def setup(self, **kwargs: Any) -> None:
        """
        User-defined setup method.
        Subclasses should override this method instead of __init__.
        """
        pass

2. Advise users to override setup instead of __init__ in their custom models:

class MyModel(Model):
    def setup(self, param1: int, param2: str):
        self.param1 = param1
        self.param2 = param2
        # Additional setup logic...

    def step(self):
        # Model step logic...
        pass

# Usage
model = MyModel(seed=42, param1=10, param2="example")

Benefits

1. Cleaner Code: Users no longer need to worry about calling super().__init__() or handling *args and **kwargs.
2. Flexibility: We can modify Model.__init__ in the future without breaking user models.
3. Consistency: All user-defined setup logic is consistently placed in the setup method.
4. Error Prevention: Eliminates the risk of users incorrectly calling or forgetting to call super().__init__().

Potential Drawbacks

1. Breaking Change: This would be a significant change in how users define their models, requiring updates to existing code.
2. Learning Curve: Users familiar with the current approach would need to learn and adapt to the new pattern.

[quaquel]

A couple of thoughts

1. your code example for Model is not correct. This should still call super as is done now to insure that mulitple inheritance works correctly.
2. I don't agree with most of your benefits as currently listed. For example, cleaner code is largely a matter of taste. I don't object to seeing super calls in user code and I don't consider them ugly. In fact, it enforces explicitness regarding which arguments are used where. I also don't see the flexibility argument. We can already make any changes we want to Model.__init__. The only issue is that the current structure forces the user to call super before creating any agents because otherwise the agent registration is not initialized. Consistency can also be debated because this super code is also used for Agents. Error prevention is true, but will trigger an immediate error because all kinds of stuff that e.g. agents need is not there.
3. I agree that the correct use of super can be challenging for novel users, but this only really kicks in once you are trying to use multiple inheritance. Multiple inheritance is not something that a typical novice user will do, and even experiences users largely and correctly shy away from it. There is a good reason why Java does not allow for this in the first place. Likewise, to understand the *args *kwargs stuff is a bit tricky for novice users. However, in my experience, most students can get their head around this in 5 to 10 minutes.
4. I can see other arguments for using a setup approach. At the moment running multiple experiments is done by intializing the model from scratch. However, if the model initialization requires reading all kinds of databases this can be very timely. Moreover, for multiprocessing, the model must either be pickleable after instantiation or can only be instantiated in each subprocess (I don't know what the batchrunner currently does). So, in my view, it would be great to have a setup and reset method on model. Running experiments would then become setup, run for n steps / stopping condition, reset model, repeat.
5. If we were to go down this route, I would have explicit setup_args and setup_kwargs rather than try and guess which arguments from model.__init__ should go to self.setup. Again, there might be arguments or keyword arguments that are required by any of the other super classes that a user want to use for their custom model. So, when in doubt, refuse the temptation to guess.

In short, I don't agree with the arguments given here, but I am not in principle against exploring this further

[EwoutH]

Thanks for your extensive reply. One quick point and one idea before we continue this discussion in person:

1. You're right. This should work, right?

class Model:
    def __init__(self, seed: Optional[float] = None, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self.running = True

3. ... most students can get their head around this in 5 to 10 minutes.

While you're not wrong, I think Mesa contains about a hundred things that takes about 5 to 10 minutes to wrap your head around. If we can eliminate one for (almost) everyone, I think that counts for something.

4. I can see other arguments for using a setup approach.

We could keep using __init__ for essential initializations and setup for experiment-specific configurations. This way you indeed have to __init__ only once, and then can reset and setup after that.

[EwoutH]

Also take the point of the Agent: In an UserAgent the change from

super().__init__(unique_id, model)

to

super().__init__(model)

was a huge breaking change, for which we already have multiple questions filed, and we haven't even released yet.

If we can privatize the __init__ of Agent, and let users just overwrite an empty setup, we can make these kinds of changes way easier in the future. With things as seed, random, agentset stuff, grids/spaces I can see this making stuff way easier in the future.

[quaquel]

1. yes that code is correct.
2. I think part of the issue is that I tried to be complete in Update migration_guide.md #2347. In most cases it is much simpler. You would rarely require the user to deal with *args and **kwargs themselves. 99% of use cases involve something like the following because there is no further class hierarchy to worry about.

class MyModel(Model)
    def __init__(self, n_agents, width, height, seed=None):
        super().__init__(seed=seed)

4. yes that is what I can envision as a desirable approach.

Regarding the agent change, I am not sure what explains the questions. Part of it is generic lack of familiarty with OO in python. This is a critique I also have at the python teaching at e.g., our faculty. Part of it is also confusion between the examples and the installed code.

[Corvince]

Thanks for bringing this up! I think this goes quite well into another idea I have had for quite some time in the back of my head. My idea was to go done a decorator path, similar to a dataclass. So you would define your models something like this

import mesa

@mesa.Model
class MyModel:
    pass

But building a prototype around this I still got some headaches merging the __init__ definitions of mesa.Model and MyModel. Switching to setup would solve this cleanly, which is again similar to what dataclasses do with __post_init__. The added benefit of using a decorator is that mesa.Model setup and MyModel setup can be nicely configured seperately without conflating the inits on the user side. So something like

@mesa.Model(
    seed=123,
    space=Orthogonal2DGrid() # automatically add space attribute
    ....)
class MyModel:
    def setup(foo, bar):
        pass

model1 = MyModel(1foo, 2bar, seed=456) # <- We can program the decorator to automatically pass args to setup and have some kwargs passed to __init__

In the last line you can see that this approach could also work with args and not just kwargs or setup_kwargs.

The idea of a decorator approach came back recently to me especially for agents, where for example providing a space would automatically add the appropriate movement methods and things like that.

[quaquel]

This is an interesting idea and offers further argument for exploring moving away from __init__