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 many Mesa objects have, including Model, Agent, and AgentSet. 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)

Agent.random is just a convenient shorthand in the Agent class to self.model.random. If you create your own AgentSet instances, you have to pass random explicitly. Typically, you can simply do, in a Model instance, my_agentset = AgentSet([], random=self.random). This ensures that my_agentset uses the same random number generator as the rest of the model.

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 __init__.

class AwesomeModel(Model):

  def __init__(self, seed=None):
    super().__init__(seed=seed)
    ...

  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