From 68b8e6ca601ae643bad547ffd0cfc59f8121116a Mon Sep 17 00:00:00 2001 From: rht Date: Sun, 14 May 2023 15:23:01 -0400 Subject: [PATCH] intro_tutorial: Add back fix from #1665 comments --- docs/tutorials/intro_tutorial.ipynb | 45 +++++++++++++++-------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/tutorials/intro_tutorial.ipynb b/docs/tutorials/intro_tutorial.ipynb index 27114ece89c..8f053d17b71 100644 --- a/docs/tutorials/intro_tutorial.ipynb +++ b/docs/tutorials/intro_tutorial.ipynb @@ -66,7 +66,6 @@ "\n", "```bash\n", "pip install matplotlib\n", - "pip install seaborn\n", "```\n" ] }, @@ -131,11 +130,15 @@ "source": [ "import mesa\n", "\n", - "# Visualization tools needed to explore the model.\n", + "# Data visualization tool.\n", "import matplotlib.pyplot as plt\n", + "\n", + "# Has multi-dimensional arrays and matrices. Has a large collection of\n", + "# mathematical functions to operate on these arrays.\n", "import numpy as np\n", - "import pandas as pd\n", - "import seaborn as sns" + "\n", + "# Data manipulation and analysis.\n", + "import pandas as pd" ] }, { @@ -146,11 +149,11 @@ "\n", "First create the agent. As the tutorial progresses, more functionality will be added to the agent.\n", "\n", - "**Background:** Agents are the individual entities that act in the model.IT is a good modeling practice to make certain each Agent can be uniquely identified.\n", + "**Background:** Agents are the individual entities that act in the model. It is a good modeling practice to make certain each Agent can be uniquely identified.\n", "\n", - "**Model Specific Information:** Agents are the individuals that exchange money, in this case the amount of money an individual agent has is represented as wealth. Additionally, agents each have a unique identifier.\n", + "**Model-specific information:** Agents are the individuals that exchange money, in this case the amount of money an individual agent has is represented as wealth. Additionally, agents each have a unique identifier.\n", "\n", - "**Technical Details:** This is done by creating a new class (or object) that extends `mesa.Agent` creating a subclass of the `Agent` class from mesa. The new class is named `MoneyAgent`. The technical details about the agent object can be found in the [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/agent.py).\n", + "**Code implementation:** This is done by creating a new class (or object) that extends `mesa.Agent` creating a subclass of the `Agent` class from mesa. The new class is named `MoneyAgent`. The technical details about the agent object can be found in the [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/agent.py).\n", "\n", "\n", "The `MoneyAgent` class is created with the following code:\n" @@ -188,13 +191,13 @@ "source": [ "### Create Model\n", "\n", - "Next create the model. Again as the tutorial progresses, more functionality will be added to the model.\n", + "Next, create the model. Again, as the tutorial progresses, more functionality will be added to the model.\n", "\n", - "**Background:** The model can be visualized as a grid containing all the agents. The model creates, holds and manages all the agents on the grid. Running the model will work through all the time cycles.\n", + "**Background:** The model can be visualized as a grid containing all the agents. The model creates, holds and manages all the agents on the grid. The model evolves in discrete time steps.\n", "\n", - "**Model Specific Information:** When a model is created the number of agents within the model is specified. The model then creates the agents and places them on the grid. The model also contains a scheduler which controls the order in which agents are activated. The scheduler is also responsible for advancing the model by one step. The model also contains a data collector which collects data from the model. These topics will be covered in more detail later in the tutorial.\n", + "**Model-specific information:** When a model is created the number of agents within the model is specified. The model then creates the agents and places them on the grid. The model also contains a scheduler which controls the order in which agents are activated. The scheduler is also responsible for advancing the model by one step. The model also contains a data collector which collects data from the model. These topics will be covered in more detail later in the tutorial.\n", "\n", - "**Technical Details:** This is done by creating a new class (or object) that extends `mesa.Model` creating a subclass of the `Model` class from mesa. The new class is named `MoneyModel`. The technical details about the agent object can be found in the [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/model.py).\n", + "**Code implementation:** This is done by creating a new class (or object) that extends `mesa.Model` creating a subclass of the `Model` class from mesa. The new class is named `MoneyModel`. The technical details about the agent object can be found in the [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/model.py).\n", "\n", "The `MoneyModel` class is created with the following code:" ] @@ -225,15 +228,15 @@ "metadata": {}, "source": [ "### Adding the Scheduler\n", - "Now the model will me modified to add a scheduler.\n", + "Now the model will be modified to add a scheduler.\n", "\n", "**Background:** The scheduler controls the order in which agents are activated, causing the agent to take their defined action. The scheduler is also responsible for advancing the model by one step. A step is the smallest unit of time in the model, and is often referred to as a tick. The scheduler 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:** A new class is named `RandomActivationByAgent` is created which extends `mesa.time.RandomActivation` creating a subclass of the `RandomActivation` class from mesa. This class activates all the agents once per step, in random order. Every agent is expected to have a ``step`` method. The step method is the action the agent takes when it is activated by the model schedule. We add an agent to the schedule using the `add` method; when we call the schedule's `step` method, the model shuffles the order of the agents, then activates and executes each agent's ```step``` method. The scheduler is then added to the model.\n", + "**Model-specific information:** A new class is named `RandomActivationByAgent` is created which extends `mesa.time.RandomActivation` creating a subclass of the `RandomActivation` class from Mesa. This class activates all the agents once per step, in random order. Every agent is expected to have a ``step`` method. The step method is the action the agent takes when it is activated by the model schedule. We add an agent to the schedule using the `add` method; when we call the schedule's `step` method, the model shuffles the order of the agents, then activates and executes each agent's ```step``` method. The scheduler is then added to the model.\n", "\n", - "**Technical Details:** The technical details about the timer object can be found in the [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/time.py). Mesa offers a few different built-in scheduler classes, with a common interface. That makes it easy to change the activation regime a given model uses, and see whether it changes the model behavior. The details pertaining to the scheduler interface can be located the same [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/time.py).\n", + "**Code implementation:** The technical details about the timer object can be found in the [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/time.py). Mesa offers a few different built-in scheduler classes, with a common interface. That makes it easy to change the activation regime a given model uses, and see whether it changes the model behavior. The details pertaining to the scheduler interface can be located the same [mesa repo](https://github.com/projectmesa/mesa/blob/main/mesa/time.py).\n", "\n", - "With that in mind, the MoneyAgent code is modified below to visually show when a new agent is created. The MoneyModel code is modified by adding the RandomActivation method to the model. with the scheduler added looks like this:" + "With that in mind, the `MoneyAgent` code is modified below to visually show when a new agent is created. The MoneyModel code is modified by adding the RandomActivation method to the model. with the scheduler added looks like this:" ] }, { @@ -254,7 +257,7 @@ " # Pass the parameters to the parent class.\n", " super().__init__(unique_id, model)\n", "\n", - " # Create the agent's variable and set the initial values.\n", + " # Create the agent's attribute and set the initial values.\n", " self.wealth = 1\n", "\n", " def step(self):\n", @@ -268,7 +271,7 @@ "\n", " def __init__(self, N):\n", " self.num_agents = N\n", - " # Scheduler is created and added to the model\n", + " # Create scheduler and assign it to the model\n", " self.schedule = mesa.time.RandomActivation(self)\n", "\n", " # Create agents\n", @@ -289,7 +292,7 @@ "metadata": {}, "source": [ "### Running the Model\n", - "A basic model has now been created. The model can be run by creating a model object and calling the step method. The model will run for one step and print the unique_id of each agent. The model can be run for multiple steps by calling the step method multiple times.\n", + "A basic model has now been created. The model can be run by creating a model object and calling the step method. The model will run for one step and print the unique_id of each agent. You may run the model for multiple steps by calling the step method multiple times.\n", "\n", "Note: If you are using `.py` (script) files instead of `.ipynb` (Jupyter), the common convention is\n", "to have a `run.py` in the same directory as your model code. You then (1) import the ``MoneyModel`` class,\n", @@ -408,13 +411,13 @@ "source": [ "### Agent Step\n", "\n", - "Looping back to the MoneyAgent the actual step process is now going to be created.\n", + "Returning back to the MoneyAgent the actual step process is now going to be created.\n", "\n", "**Background:** This is where the agent's behavior as it relates to each step or tick of the model is defined.\n", "\n", - "**Model Specific Information:** In this case, the agent will check its wealth, and if it has money, give one unit of it away to another random agent.\n", + "**Model-specific information:** In this case, the agent will check its wealth, and if it has money, give one unit of it away to another random agent.\n", "\n", - "**Technical Details:** The agent's step method is called by the scheduler during each step of the model. To allow the agent to choose another agent at random, we use the `model.random` random-number generator. This works just like Python's `random` module, but with a fixed seed set when the model is instantiated, that can be used to replicate a specific model run later." + "**Code implementation:** The agent's step method is called by the scheduler during each step of the model. To allow the agent to choose another agent at random, we use the `model.random` random-number generator. This works just like Python's `random` module, but with a fixed seed set when the model is instantiated, that can be used to replicate a specific model run later." ] }, {