diff --git a/docs/howto.md b/docs/howto.md deleted file mode 100644 index f7da02e2055..00000000000 --- a/docs/howto.md +++ /dev/null @@ -1,122 +0,0 @@ -# How-to Guide - -This guide provides concise instructions and examples to help you start with common tasks in Mesa. - -## Implementing Different Activation Regimes - - -### Random Activation - -self.agents.shuffle_do("") - -### Random Activation By Type - -```python -for agent_class in self.agent_types: - self.agents_by_type[agent_class].shuffle_do("") -``` -### Only Activating Certain Agent Types - -```python -self.agents_by_type[AgentType].shuffle_do("") -``` - -### Staged Activation - -```python -for stage in ["stage1", "stage2", "stage3"]: - self.agents.do(stage) -``` - -If you want to `shuffle` and/or `shuffle_between_stages` options: -```python - -stages = ["stage1", "stage2", "stage3"] -if shuffle: - self.random.shuffle(stages) -for stage in stages: - if shuffle_between_stages: - self.agents.shuffle_do(stage) - else: - self.agents.do(stage) -``` - -## 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. - -Example: -```python -if self.model.schedule.time in self.discrete_time: - self.model.space.move_agent(self, 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. - -Example: -```python -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. - -Example: -```python -import mesa -import numpy as np - -class MyModel(mesa.Model): - def __init__(self, seed=None): - super().__init__() - self.random = np.random.default_rng(seed) -``` - -Usage example: -```python -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 `. To resolve this, run -your code outside of Jupyter notebooks and use the following pattern, -incorporating `freeze_support()` for multiprocessing support. - -Example: -```python -from mesa.batchrunner import batch_run -from multiprocessing import freeze_support - -params = {"width": 10, "height": 10, "N": range(10, 500, 10)} - -if __name__ == '__main__': - freeze_support() - results = batch_run( - MoneyModel, - parameters=params, - iterations=5, - max_steps=100, - number_processes=None, - data_collection_period=1, - display_progress=True, - ) -``` - -If you would still like to run your code in Jupyter, adjust your code as -described and consider integrating external libraries like -[nbmultitask](https://nbviewer.org/github/micahscopes/nbmultitask/blob/39b6f31b047e8a51a0fcb5c93ae4572684f877ce/examples.ipynb) -or refer to [Stack -Overflow](https://stackoverflow.com/questions/50937362/multiprocessing-on-python-3-jupyter) -for multiprocessing tips. diff --git a/docs/index.md b/docs/index.md index ccd37e99174..3124f488140 100644 --- a/docs/index.md +++ b/docs/index.md @@ -78,7 +78,6 @@ tutorials/visualization_tutorial Examples Migration guide Best Practices -How-to Guide API Documentation Mesa Packages ``` diff --git a/docs/tutorials/intro_tutorial.ipynb b/docs/tutorials/intro_tutorial.ipynb index 10988d6a680..2d3620b750b 100644 --- a/docs/tutorials/intro_tutorial.ipynb +++ b/docs/tutorials/intro_tutorial.ipynb @@ -259,7 +259,7 @@ "\n", "With the basics of the Agent class and Model class created we can no activate the agents to `do` things\n", "\n", - "**Background:** Mesa's `do` function calls agent functions the grow your ABM. A step is the smallest unit of time in the model, and is often referred to as a tick. The `do` function and Python functionality can be configured to activate agents in different orders. This can be important as the order in which agents are activated can impact the results of the model [Comer2014]. At each step of the model, one or more of the agents -- usually all of them -- are activated and take their own step, changing internally and/or interacting with one another or the environment. A overview of different ways to employ the `do` function for different activation regimes can be found in the [\"How To\" Guide](https://mesa.readthedocs.io/latest/howto.html).\n", + "**Background:** Mesa's `do` function calls agent functions the grow your ABM. A step is the smallest unit of time in the model, and is often referred to as a tick. The `do` function and Python functionality can be configured to activate agents in different orders. This can be important as the order in which agents are activated can impact the results of the model [Comer2014]. At each step of the model, one or more of the agents -- usually all of them -- are activated and take their own step, changing internally and/or interacting with one another or the environment.\n", "\n", "**Model-specific information:** For this section we will randomly reorder the Agent activation order using `mesa.Agent.shuffle_do` and have the agents `step` function print the agent unique id they are assigned during the agent creation process. \n", "\n", @@ -1498,9 +1498,7 @@ { "cell_type": "markdown", "metadata": {}, - "source": [ - "**note for Windows OS users:** If you are running this tutorial in Jupyter, make sure that you set `number_processes = 1` (single process). If `number_processes` is greater than 1, it is less straightforward to set up. You can read [Mesa's how-to guide](https://github.com/projectmesa/mesa/blob/main/docs/howto.md), in 'Using multi-process `batch_run` on Windows' section for how to do it." - ] + "source": "**note for Windows OS users:** If you are running this tutorial in Jupyter, make sure that you set `number_processes = 1` (single process). If `number_processes` is greater than 1, it is less straightforward to set up. For details on how to use multiprocessing on windows, see [multiprocessing's programming guidelines](https://docs.python.org/3/library/multiprocessing.html#multiprocessing-programming). " }, { "cell_type": "code", diff --git a/mesa/batchrunner.py b/mesa/batchrunner.py index 2a6d50a3b77..bc35d1cfe65 100644 --- a/mesa/batchrunner.py +++ b/mesa/batchrunner.py @@ -1,4 +1,29 @@ -"""batchrunner for running a factorial experiment design over a model.""" +"""batchrunner for running a factorial experiment design over a model. + +To take advantage of parallel execution of experiments, `batch_run` uses +multiprocessing if ``number_processes`` is larger than 1. It is strongly advised +to only run in parallel using a normal python file (so don't try to do it in a +jupyter notebook). Moreover, best practice when using multiprocessing is to +put the code inside an ``if __name__ == '__main__':`` code black as shown below:: + + from mesa.batchrunner import batch_run + + params = {"width": 10, "height": 10, "N": range(10, 500, 10)} + + if __name__ == '__main__': + results = batch_run( + MoneyModel, + parameters=params, + iterations=5, + max_steps=100, + number_processes=None, + data_collection_period=1, + display_progress=True, + ) + + + +""" import itertools import multiprocessing