-
Notifications
You must be signed in to change notification settings - Fork 869
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Rewrite howto.md using ChatGPT for clarity and conciseness (#2037)
- Loading branch information
Showing
1 changed file
with
45 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,65 +1,83 @@ | ||
# How-to Guide | ||
|
||
Here you can find code that allows you to get to get started on common tasks in Mesa. | ||
This guide provides concise instructions and examples to help you start with common tasks in Mesa. | ||
|
||
## Models with Discrete Time | ||
|
||
If you have `Multiple` type agents and one of them has time attribute you can still build a model that is run by discrete time. In this example, each step of the model, and the agents have a time attribute that is equal to the discrete time to run its own step. | ||
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 in Staged Activation | ||
## Implementing Model-Level Functions with Staged Activation | ||
|
||
In staged activation, if you may want a function to be implemented only on the model level and not at the level of agents. | ||
For such functions, include the prefix "model." before the model function name, when defining the function list. | ||
For example, consider a central employment exchange which adjust the wage rate common to all laborers | ||
in the direction of excess demand. | ||
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) | ||
stage_list = [Send_Labour_Supply, Send_Labour_Demand, model.Adjust_Wage_Rate] | ||
self.schedule = StagedActivation(self, stage_list, shuffle=True) | ||
``` | ||
|
||
## Using `numpy.random` | ||
|
||
Sometimes you need to use `numpy`'s `random` library, for example to get a Poisson distribution. | ||
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 | ||
class MyModel(Model): | ||
def __init__(self, ...): | ||
import mesa | ||
import numpy as np | ||
|
||
class MyModel(mesa.Model): | ||
def __init__(self, seed=None): | ||
super().__init__() | ||
self.random = np.random.default_rng(seed) | ||
``` | ||
|
||
And just use `numpy`'s random as usual, e.g. `self.random.poisson()`. | ||
Usage example: | ||
```python | ||
lambda_value = 5 | ||
sample = self.random.poisson(lambda_value) | ||
``` | ||
|
||
## Using multi-process `batch_run` on Windows | ||
## Multi-process `batch_run` on Windows | ||
|
||
You will have an issue with `batch_run` and `number_processes = None`. Your cell will | ||
show no progress, and in your terminal you will receive *AttributeError: Can't get attribute 'MoneyModel' on | ||
\<module '\_\_main\_\_' (built-in)>*. One way to overcome this is to take your code outside of Jupyter and adjust the above | ||
code as follows. | ||
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. | ||
|
||
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, | ||
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 you will need to adjust the cell as noted above. Then you can | ||
you can add the [nbmultitask library](https://nbviewer.org/github/micahscopes/nbmultitask/blob/39b6f31b047e8a51a0fcb5c93ae4572684f877ce/examples.ipynb) | ||
or look at this [stackoverflow](https://stackoverflow.com/questions/50937362/multiprocessing-on-python-3-jupyter). | ||
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. |