Best Practices#

Here are some general principles that have proven helpful for developing models.

Model Layout#

A model should be contained in a folder named with lower-case letters and underscores, such as wolf_sheep. Within that directory:

  • Readme.md describes the model, how to use it, and any other details.

  • model.py should contain the model class.

  • agents.py should contain the agent class(es).

  • app.py should contain the Solara-based visualization code (optional).

You can add more files as needed, for example:

  • run.py could contain the code to run the model.

  • batch_run.py could contain the code to run the model multiple times.

  • analysis.py could contain any analysis code.

Input data can be stored in a data directory, output data in an output, processed results in a results directory, images in an images directory, etc.

All our examples follow this layout.

Randomization#

If your model involves some random choice, you can use the built-in random property that Mesa Model and Agent objects have. This works exactly like the built-in random library.

class AwesomeModel(Model):
  # ...

  def cool_method(self):
    interesting_number = self.random.random()
    print(interesting_number)

class AwesomeAgent(Agent):
  # ...
  def __init__(self, unique_id, model, ...):
    super().__init__(unique_id, model)
    # ...

  def my_method(self):
    random_number = self.random.randint(0, 100)

(The agent’s random property is just a reference to its parent model’s random property).

When a model object is created, its random property is automatically seeded with the current time. The seed determines the sequence of random numbers; if you instantiate a model with the same seed, you will get the same results. To allow you to set the seed, make sure your model has a seed argument in its constructor.

class AwesomeModel(Model):

  def __init__(self, seed=None):
    pass

  def cool_method(self):
    interesting_number = self.random.random()
    print(interesting_number)

>>> model0 = AwesomeModel(seed=0)
>>> model0._seed
0
>>> model0.cool_method()
0.8444218515250481
>>> model1 = AwesomeModel(seed=0)
>>> model1.cool_method()
0.8444218515250481