CovidGridContagion

To show how the Melodie.Grid module can be used, we provide this CovidGridContagion model, which is based the CovidContagion model. So, if you haven’t, we will strongly suggest to read the Tutorial section first.

The differences are:

• Agents walk on a 2D grid randomly.

• The grid is constructed with spots. Each spot has an attribute stay_prob, which decides if the agent standing on this spot will move probabilistically.

• The infected agents can pass the virus to the other uninfected agents in the neighborhood.

Project Structure

The project structure is as below. Compared with the structure of the CovidContagion model, one grid.py file is added in the source folder, and one Parameter_GridStayProb.xlsx file is added in the data/input folder.

CovidGridContagion
├── data
│   ├── input
│   │   ├── SimulatorScenarios.xlsx
│   │   ├── ID_HealthState.xlsx
│   │   ├── ID_AgeGroup.xlsx
│   │   ├── Parameter_GridStayProb.xlsx
│   │   └── Parameter_AgeGroup_TransitionProb.xlsx
│   └── output
│       ├── CovidGridContagion.sqlite
│       ├── PopulationInfection_S0R0.png
│       └── PopulationInfection_S1R0.png
├── source
│   ├── agent.py
│   ├── environment.py
│   ├── grid.py
│   ├── data_collector.py
│   ├── data_info.py
│   ├── data_loader.py
│   ├── scenario.py
│   ├── model.py
│   └── analyzer.py
├── config.py
├── run_simulator.py
├── run_analyzer.py
└── readme.md

Grid and Spot

To include such differences about grid, Melodie provides two classes Grid and Spot, based on which the CovidGrid and CovidSpot classes are defined.

grid.py

from Melodie import Spot, Grid
from source import data_info


class CovidSpot(Spot):

    def setup(self):
        self.stay_prob = 0.0


class CovidGrid(Grid):

    def setup(self):
        self.set_spot_property(
            "stay_prob", self.scenario.get_matrix(data_info.grid_stay_prob)
        )

As shown, the two classes are defined in brief, i.e., most functions and attributes are inherited from Melodie. The only reason to define this CovidGrid class for the model, is to include the stay_prob attribute of each CovidSpot. Or, one can also use the Grid and Spot classes of Melodie directly.

Matrix Data

The stay_prob values of the spots are saved in a matrix, which is the same size with the grid. Like other dataframes, the matrix is first registered in the data_info.py and loaded by the data_loader, then can be accessed by the scenario object by using get_matrix function (Line 15). The registry of the matrix is as follows.

data_info.py

import sqlalchemy

from Melodie import MatrixInfo


grid_stay_prob = MatrixInfo(
    mat_name="grid_stay_prob",
    data_type=sqlalchemy.Float(),
    file_name="Parameter_GridStayProb.xlsx",
)

Model

With the classes and data, the next step is to include the grid object as a new component of the model. As shown in Line 24, Melodie.Model provides a create_grid function, taking the two class variables as input - CovidGrid and CovidSpot.

model.py

from typing import TYPE_CHECKING

from Melodie import Model

from source import data_info
from source.agent import CovidAgent
from source.data_collector import CovidDataCollector
from source.environment import CovidEnvironment
from source.grid import CovidGrid
from source.grid import CovidSpot
from source.scenario import CovidScenario

if TYPE_CHECKING:
    from Melodie import AgentList


class CovidModel(Model):
    scenario: "CovidScenario"

    def create(self):
        self.agents: "AgentList[CovidAgent]" = self.create_agent_list(CovidAgent)
        self.environment = self.create_environment(CovidEnvironment)
        self.data_collector = self.create_data_collector(CovidDataCollector)
        self.grid = self.create_grid(CovidGrid, CovidSpot)

    def setup(self):
        self.agents.setup_agents(
            agents_num=self.scenario.agent_num,
            params_df=self.scenario.get_dataframe(data_info.agent_params),
        )
        self.grid.setup_params(
            width=self.scenario.grid_x_size,
            height=self.scenario.grid_y_size
        )
        self.grid.setup_agent_locations(self.agents)

In the setup function, the grid needs to be initialized with size parameters from scenario. Then, the agents need to be located on the grid, which requires that they are already initialized with the attributes x and y.

GridAgent

The agents that can walk on the grid are defined by inheriting the GridAgent class of Melodie. They have three additional attributes: category, x, and y. Additionally, they also have access to the grid (Line 26) and some grid-related functions, e.g., rand_move_agent in Line 32.

agent.py

import random
from typing import TYPE_CHECKING

from Melodie import GridAgent

if TYPE_CHECKING:
    from source.scenario import CovidScenario
    from Melodie import AgentList
    from source.grid import CovidSpot
    from source.grid import CovidGrid


class CovidAgent(GridAgent):
    scenario: "CovidScenario"
    grid: "CovidGrid[CovidSpot]"
    spot: "CovidSpot"

    def set_category(self):
        self.category = 0

    def setup(self):
        self.x: int = 0
        self.y: int = 0
        self.health_state: int = 0
        self.age_group: int = 0

    def move(self):
        spot: "CovidSpot" = self.grid.get_spot(self.x, self.y)
        stay_prob = spot.stay_prob
        if random.uniform(0, 1) > stay_prob:
            move_radius = 1
            self.rand_move_agent(move_radius, move_radius)

    def infection(self, agents: "AgentList[CovidAgent]"):
        neighbors = self.grid.get_neighbors(self)
        for neighbor_category, neighbor_id in neighbors:
            neighbor_agent: "CovidAgent" = agents.get_agent(neighbor_id)
            if neighbor_agent.health_state == 1:
                if random.uniform(0, 1) < self.scenario.infection_prob:
                    self.health_state = 1
                    break

One thing that might be confused: Why is there the category attribute?

The category attribute is to make sure that, when there are multiple groups of agents walking on the grid, the grid can distinguish them and work well. So, the function set_category much be implemented in a class that inherits the GridAgent class. For example, as shown in Line 35-36, when iterating through the neighbors returned by grid.get_neighbors, each neighbor is indexed with both category and the id of the agent.

For more details of the Grid and Spot modules, please refer to the API Reference section.