How-to Guide#

This guide provides concise instructions and examples to help you start with common tasks in Mesa.

Models with Discrete Time#

For models involving agents of multiple types, including those with a time attribute, you can construct a discrete-time model. This setup allows each agent to perform actions in steps that correspond to the model’s discrete time.


if self.model.schedule.time in self.discrete_time:, new_pos)

Implementing Model-Level Functions with Staged Activation#

In staged activation scenarios, to designate functions that should only operate at the model level (and not at the agent level), prepend the function name with “model.” in the function list definition. This approach is useful for model-wide operations, like adjusting a wage rate based on demand.


stage_list = [Send_Labour_Supply, Send_Labour_Demand, model.Adjust_Wage_Rate]
self.schedule = StagedActivation(self, stage_list, shuffle=True)

Using numpy.random#

To incorporate numpy’s random functions, such as for generating a Poisson distribution, initialize a random number generator in your model’s constructor.


import mesa
import numpy as np

class MyModel(mesa.Model):
    def __init__(self, seed=None):
        self.random = np.random.default_rng(seed)

Usage example:

lambda_value = 5
sample = self.random.poisson(lambda_value)

Multi-process batch_run on Windows#

When using batch_run with number_processes = None on Windows, you might encounter progress display issues or AttributeError: Can't get attribute 'MoneyModel' on <module '__main__' (built-in)>. To resolve this, run your code outside of Jupyter notebooks and use the following pattern, incorporating freeze_support() for multiprocessing support.


from mesa.batchrunner import batch_run
from multiprocessing import freeze_support

params = {"width": 10, "height": 10, "N": range(10, 500, 10)}

if __name__ == '__main__':
    results = batch_run(

If you would still like to run your code in Jupyter, adjust your code as described and consider integrating external libraries like nbmultitask or refer to Stack Overflow for multiprocessing tips.