Skip to content

Commit

Permalink
docs: Rewrite howto.md using ChatGPT for clarity and conciseness (#2037)
Browse files Browse the repository at this point in the history
  • Loading branch information
rht authored Feb 21, 2024
1 parent 7f10167 commit 913dfb8
Showing 1 changed file with 45 additions and 27 deletions.
72 changes: 45 additions & 27 deletions docs/howto.md
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.

0 comments on commit 913dfb8

Please sign in to comment.