CovidContagionGridVisual

This example builds upon covid_contagion_grid by adding a Visualizer. It demonstrates how to use MelodieStudio to interactively run the simulation and view real-time animations of the grid and data charts.

Visualizer: Project Structure

The structure is similar to the grid example but adds a visualizer component:

examples/covid_contagion_grid_visual
├── core/
│   ├── agent.py
│   ├── grid.py
│   ├── environment.py
│   ├── model.py
│   ├── scenario.py
│   ├── visualizer.py       # Defines charts and grid styling
│   └── ...
├── data/
│   └── ...
├── run_studio.py           # Launches MelodieStudio
└── run_simulator.py         # Runs headless simulation

Visualizer: Key Changes

1. Visualizer Class: A new class CovidVisualizer inherits from Melodie.Visualizer. It defines:

   • Charts: A line chart tracking the number of Susceptible, Infected, and Recovered agents.

   • Grid View: A visual representation of the grid where agents appear as colored dots (Green=Susceptible, Red=Infected, Gray=Recovered).

2. MelodieStudio: Instead of running a batch simulation immediately, the run_studio.py script starts a local web server (MelodieStudio). You can control the simulation (Start, Pause, Reset) from the browser.

Visualizer: Running the Model

To run the model with the visualizer, execute the main script:

python examples/covid_contagion_grid_visual/run_studio.py

Then, open your browser and navigate to http://localhost:8089. This is the web gateway for MelodieStudio. The backend simulation service will automatically run on 127.0.0.1:8765.

• In the web interface, go to the Simulator page.

• The interactive parameter controls will appear on the left. You can adjust them and click Reset to apply the new values.

• Click Start to begin the simulation.

• The grid animation will be displayed in the center, and the line chart showing health state trends will be on the right.

Visualizer: Customization Guide

Here’s how you can customize the visualizer components:

1. Adding Data Charts (e.g., Line Chart)

• In core/visualizer.py, use self.plot_charts.add_line_chart("unique_chart_name") to create a new chart.

• Chain it with .set_data_source({...}) to bind data series. The values of the dictionary should be functions that return the numerical data for each time step (e.g., self.model.environment.num_susceptible).

• You can add multiple charts (line, pie, bar) as long as each has a unique name.

2. Configuring the Grid View

• Use self.add_grid(...) to link the visualizer to your model’s Grid object.

• The var_style dictionary is key: it maps the integer values returned by var_getter to a specific color and a label for the legend.

• The legend for the grid is automatically generated based on these labels.

3. Adding an Interactive Parameter Panel

• Use self.params_manager.add_param(...) to register interactive parameters. The example adds three FloatParam instances for:

  • initial_infected_percentage

  • infection_prob

  • recovery_prob

• Each parameter requires a getter to read its current value from the Scenario and a setter to write the new value from the web UI back to the Scenario.

• After changing a parameter in the UI, click the Reset button to restart the simulation with the new settings.

4. Adjusting the Layout

• The layout is controlled by .melodie/studio/chart_layout.json. Each key in the JSON object corresponds to a component on the page:

  • "controls": The parameter panel on the left.

  • "visualizer-grid": The grid animation component.

  • "chart-health_state_trend": The line chart (the name must match the one defined in add_line_chart).

• You can adjust the position and size of each component using pixel values for left, top, width, and height. Changes take effect after restarting the server.

5. Styling Charts

• You can provide additional ECharts options in .melodie/studio/chart_options.json.

• The key must match the chart’s name (e.g., "health_state_trend").

• In the example, this is used to enable the legend, add axis titles, and adjust the chart’s internal grid margins for better spacing.

Visualizer: Code

This section shows the key code additions for the visualizer. Core logic files are the same as the covid_contagion_grid example.

Visualizer Definition

This file is the core addition. It maps model data to visual elements. Defined in core/visualizer.py.

from Melodie import Visualizer
from .model import CovidModel
from MelodieInfra.lowcode.params import FloatParam


class CovidVisualizer(Visualizer):
    model: CovidModel

    def set_model(self, model: CovidModel):
        """
        Called when the visualizer is bound to a model instance.
        Set grid dimensions here (model is available now).
        """
        super().set_model(model)
        # Ensure grid dimensions are passed to frontend for correct scaling
        self.width = model.grid.width()
        self.height = model.grid.height()

    def setup(self):
        # Add interactive parameters to the left control panel
        self.params_manager.add_param(
            FloatParam(
                name="initial_infected_percentage",
                value_range=(0.0, 1.0),
                step=0.01,
                getter=lambda scenario: scenario.initial_infected_percentage,
                setter=lambda scenario, val: setattr(
                    scenario, "initial_infected_percentage", val
                ),
                label="Initial infected %",
                description="Share of agents initially infected (0-1).",
            )
        )
        self.params_manager.add_param(
            FloatParam(
                name="infection_prob",
                value_range=(0.0, 1.0),
                step=0.01,
                getter=lambda scenario: scenario.infection_prob,
                setter=lambda scenario, val: setattr(
                    scenario, "infection_prob", val
                ),
                label="Infection prob",
                description="Probability an infected agent infects a neighbor each step.",
            )
        )
        self.params_manager.add_param(
            FloatParam(
                name="recovery_prob",
                value_range=(0.0, 1.0),
                step=0.01,
                getter=lambda scenario: scenario.recovery_prob,
                setter=lambda scenario, val: setattr(
                    scenario, "recovery_prob", val
                ),
                label="Recovery prob",
                description="Probability an infected agent recovers each step.",
            )
        )

        # Configure the chart to show population health states over time
        self.plot_charts.add_line_chart("health_state_trend") \
            .set_data_source({
                "Susceptible": lambda: self.model.environment.num_susceptible,
                "Infected": lambda: self.model.environment.num_infected,
                "Recovered": lambda: self.model.environment.num_recovered
            })

        # Configure the grid visualization
        self.add_grid(
            name="covid_grid",
            grid_getter=lambda: self.model.grid,
            var_getter=lambda agent: agent.health_state,
            var_style={
                0: {"label": "Susceptible", "color": "#0000FF"},
                1: {"label": "Infected", "color": "#FF0000"},
                2: {"label": "Recovered", "color": "#808080"}
            },
            update_spots=False
        )

Model Structure

Same as the grid example. Defined in core/model.py.

from typing import TYPE_CHECKING

from Melodie import Model

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

if TYPE_CHECKING:
    from Melodie import AgentList


class CovidModel(Model):
    """
    The Model class assembles all components: agents, environment, grid, and data collector.
    """

    scenario: "CovidScenario"
    agents: "AgentList[CovidAgent]"
    environment: CovidEnvironment
    data_collector: CovidDataCollector
    grid: CovidGrid

    def create(self) -> None:
        """
        Create component instances.
        """
        self.agents = 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) -> None:
        """
        Setup the model components.
        """
        # 1. Initialize agents based on scenario parameter
        self.agents.setup_agents(self.scenario.agent_num)
        
        # 2. Setup grid dimensions and apply properties (like stay_prob)
        self.grid.setup_params(width=self.scenario.grid_x_size, height=self.scenario.grid_y_size)
        
        # 3. Place agents randomly on the grid
        self.grid.setup_agent_locations(self.agents, "random_single")
        
        # 4. Seed initial infections
        self.environment.seed_infection(self.agents)

    def run(self) -> None:
        """
        The main simulation loop.
        """
        for t in self.iterator(self.scenario.period_num):
            self.environment.agents_move(self.agents)
            self.environment.agents_infect(self.agents)
            self.environment.agents_recover(self.agents)
            self.environment.update_population_stats(self.agents)
            self.data_collector.collect(t)
        self.data_collector.save()

Environment Logic

Same as the grid example. Defined in core/environment.py.

import random
from typing import TYPE_CHECKING

from Melodie import Environment

if TYPE_CHECKING:
    from Melodie import AgentList
    from .agent import CovidAgent
    from .scenario import CovidScenario


class CovidEnvironment(Environment):
    """
    The environment class orchestrates the simulation steps and manages macro-level logic.
    """

    scenario: "CovidScenario"

    def setup(self) -> None:
        """
        Initialize macro-level counters for statistics.
        """
        self.num_susceptible: int = 0
        self.num_infected: int = 0
        self.num_recovered: int = 0

    def agents_move(self, agents: "AgentList[CovidAgent]") -> None:
        """
        1. Agents move.
        """
        for agent in agents:
            agent.move()

    def agents_infect(self, agents: "AgentList[CovidAgent]") -> None:
        """
        2. Infected agents spread the virus.
        """
        for agent in agents:
            agent.infect_neighbors(agents)

    def agents_recover(self, agents: "AgentList[CovidAgent]") -> None:
        """
        3. Infected agents try to recover.
        """
        for agent in agents:
            agent.recover()

    def seed_infection(self, agents: "AgentList[CovidAgent]") -> None:
        """
        Infect a percentage of agents at the start of the simulation.
        """
        for agent in agents:
            if random.random() < self.scenario.initial_infected_percentage:
                agent.health_state = 1

    def update_population_stats(self, agents: "AgentList[CovidAgent]") -> None:
        """
        Count the number of agents in each health state.
        """
        self.num_susceptible = 0
        self.num_infected = 0
        self.num_recovered = 0
        for agent in agents:
            if agent.health_state == 0:
                self.num_susceptible += 1
            elif agent.health_state == 1:
                self.num_infected += 1
            elif agent.health_state == 2:
                self.num_recovered += 1

Agent Behavior

Same as the grid example. Defined in core/agent.py.

import random
from typing import TYPE_CHECKING

from Melodie import GridAgent

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


class CovidAgent(GridAgent):
    """
    An agent capable of moving on a grid and spreading infection to neighbors.
    Inherits from GridAgent to gain spatial attributes (x, y) and methods.
    """

    scenario: "CovidScenario"
    grid: "CovidGrid"
    spot: "CovidSpot"

    def set_category(self) -> None:
        """
        Set the category of the agent. 
        Melodie uses this to manage different groups of agents.
        """
        self.category = 0

    def setup(self) -> None:
        """
        Initialize agent attributes.
        """
        self.x: int = 0
        self.y: int = 0
        # Health state: 0 = Susceptible, 1 = Infected, 2 = Recovered
        self.health_state: int = 0

    def move(self) -> None:
        """
        Move the agent based on the property of the current spot.
        The agent has a probability (1 - stay_prob) to move to a random neighboring cell.
        """
        current_spot = self.grid.get_spot(self.x, self.y)
        if random.random() > current_spot.stay_prob:
            # Move randomly within a radius of 1 cell (Moore neighborhood)
            self.rand_move_agent(x_range=1, y_range=1)

    def infect_neighbors(self, agents: "AgentList[CovidAgent]") -> None:
        """
        If infected, try to infect susceptible neighbors.
        """
        if self.health_state != 1:
            return

        # Get neighbors within a radius of 1
        neighbors = self.grid.get_neighbors(self, radius=1)
        
        for neighbor_id in neighbors:
            # In Melodie, get_neighbors returns a list of agent IDs (or objects depending on config).
            # Here we assume it returns IDs or we access the agent list directly.
            # Actually, standard Grid.get_neighbors returns list of (agent_category, agent_id).
            category, agent_id = neighbor_id
            neighbor: "CovidAgent" = agents.get_agent(agent_id)
            
            if neighbor.health_state == 0:
                if random.random() < self.scenario.infection_prob:
                    neighbor.health_state = 1

    def recover(self) -> None:
        """
        If infected, there is a chance to recover.
        """
        if self.health_state == 1 and random.random() < self.scenario.recovery_prob:
            self.health_state = 2

Grid Definition

Same as the grid example. Defined in core/grid.py.

from Melodie import Grid, Spot
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .scenario import CovidScenario


class CovidSpot(Spot):
    """
    Represents a single cell on the grid.
    Can hold properties that affect agent behavior, like 'stay_prob'.
    """

    def setup(self) -> None:
        self.stay_prob: float = 0.0


class CovidGrid(Grid):
    """
    Manages the 2D space, spots, and agent positions.
    """
    
    scenario: "CovidScenario"

    def setup(self) -> None:
        """
        Configure the grid.
        Here we apply the 'stay_prob' matrix loaded in the scenario to the spots.
        """
        # set_spot_property loads a 2D numpy array or list of lists into the grid spots
        self.set_spot_property("stay_prob", self.scenario.stay_prob_matrix)