Update docstring of SimEvent

[quaquel]

In response to this feedback on the beta, this PR adds a notes to SimEvent to explicitly point out that using lambda's in SimEvent won't work.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +2.9% [+1.4%, +4.5%]	🔵 -0.6% [-0.8%, -0.5%]
BoltzmannWealth	large	🔵 -1.0% [-1.3%, -0.8%]	🔵 -0.9% [-1.3%, -0.6%]
Schelling	small	🔵 -0.3% [-0.7%, +0.0%]	🔵 -0.6% [-0.7%, -0.5%]
Schelling	large	🔵 +0.1% [-0.8%, +1.0%]	🔵 -2.0% [-3.9%, -0.3%]
WolfSheep	small	🔵 -1.9% [-2.1%, -1.7%]	🔵 -1.8% [-2.0%, -1.5%]
WolfSheep	large	🔵 -2.8% [-4.4%, -1.7%]	🟢 -6.0% [-8.3%, -3.8%]
BoidFlockers	small	🟢 -3.9% [-4.3%, -3.5%]	🔵 -1.0% [-1.7%, -0.3%]
BoidFlockers	large	🔵 -3.2% [-3.8%, -2.5%]	🔵 -0.5% [-0.9%, -0.1%]

[EwoutH]

Thanks! @jtcooper10, would this solve your point raised?

[Corvince]

Just out of curiosity, why does it use a weak reference at all?

[jtcooper10]

Thanks! @jtcooper10, would this solve your point raised?

I think so! The note being here will help to save from any future head-scratching about lambdas.

[quaquel]

Just out of curiosity, why does it use a weak reference at all?

Imagine an event is scheduled to invoke some_agent.method, but this agent is, for some other reason, removed from the simulation. If we don't use a weakref, the agent cannot be garbage collected. There is a SimEvent.cancel method that could be used if some_agent.method was scheduled by some_agent itself. Basically, you could track all events some_agent has scheduled and cancel all of those. However, some_agent.method can also be scheduled by other objects. How are they to be informed of the fact that some_agent is being removed from the simulation and that therefore the events has to be canceled? All these problems are avoided by using a weakref in SimEvent.

[Corvince]

Ah, yes of course! Thanks for detailing it out, made it very clear