Update migration_guide.md

[quaquel]

This is a minor expansion to using super in Model. I explicate how to handle the seed keyword argument, and briefly state something about how to handle arguments and keyword arguments via super.

[EwoutH]

Is the *args, **kwargs here essential for the Model class?

[quaquel]

not for the class itself but for proper use of super. See my remark above the code on this.

[EwoutH]

I found the super().__init__(*args, seed=seed, **kwargs) so ugly I started to find some creative ways around it.

One problem, why we have to call super().__init__() at all, is that we advise users to override the Model __init__ method, and then fix that by calling super().__init__().

Maybe that doesn't have to be that way. What is if we recommend users to put their setup code into a differently named method, so the Model.__init__ does get overridden?

In our model, we now call a new setup (or initialize) function in the init by default:

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

We request users to override setup instead of __init__. Their model then looks something like this:

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")

Which I find to look extremely clean.

As an additional advantage, we can now more easily modify the order of Model arguments, rename ones or add new ones without breaking user models, because we can handle all that (and throw warnings if necessary, etc.

We never have to be afraid an user doesn't call the super().__init__() incorrectly, because we simply don't allow overriding it anymore.

This is the most breaking change of changes, but I think it allows for so much flexibility in the future that it might be worth it.

[quaquel]

I am not against shifting to having a model setup method, but that probably deserves its own discussion rather than discuss it here in this PR. This PR really is about making sure seed is handled correctly in the migration guide.

[quaquel]

@EwoutH in line with our conversation, I simplified the migration guide and not bother with the *args and *kwargs and just explicitly only pass seed to super. This is what 95% of users needs. The *args, **kwargs stuff is only relevant when having a class hierarchy that includes other super classes next to Model. Users that do this should be well equipped to understand how to make that work themselves.

[EwoutH]

Thanks for cleaning it up!