Deepan048/vector_borne_disease_control

Vector Borne Disease Control Environment 🦟

 

1. Environment Overview and Motivation

The driving force behind this project is deeply personal. A close friend of mine recently got a mosquito bite, contracted a severe case of dengue, and was in critical condition, hospitalized for over a week. That harrowing experience underscored just how quickly and devastatingly vector-borne diseases can impact human lives, and it motivated me to build this environment.

The Vector Borne Disease Control Environment is a graph-based, stochastic, and episodic Reinforcement Learning (RL) environment simulating the spread of vector-borne diseases (like Dengue, Malaria, or Zika) across a city. The city is modeled as a random graph of 25 to 75 zones, with varying populations and dynamic weather conditions. The goal is to train an agent to intelligently allocate limited spray and trap resources to curb the mosquito population and minimize the average infestation rate across the city over a 30-day period.

2. Task Descriptions

The inference script runs three tasks (task1, task2, task3) in a single execution. Each task is an independent 30-day episode on a freshly generated random city graph, with a small fraction of zones seeded with an initial mosquito infestation_rate.

The core objective for every task is to minimize the cumulative average infestation rate across all zones over a 30-day episode (where 1 step = 1 day).

Note: The inference script simply iterates over these 3 tasks sequentially. Each iteration generates a brand-new environment of varying difficulty — a different city graph, population distribution, and initial infestation seeding — so the agent is evaluated across diverse conditions rather than the same fixed scenario.

Dynamics & Difficulty:

• —Weather Drift (Stochasticity): Each zone features dynamically shifting weather conditions (humidity, temperature, and rainfall) that heavily influence mosquito breeding rates.
• —Spatial Spread: Infestations spread to adjacent zones in the graph based on proximity and weather.
• —Resource Scarcity: The agent starts with only 50 Sprays and 20 Traps for the entire month.
• —Sprays provide an immediate, drastic knockdown of the infestation and last for 3 days.
• —Traps act as a preventative measure. They suppress growth and reduce the spread probability along edges. They remain active for 5 days.
• —Difficulty Level: Medium-Hard. Managing sparse resources across a dynamic, stochastic graph with delayed effects requires long-term planning, prioritization of highly populated or highly infested nodes, and geographic containment strategies.

3. Action and Observation Spaces

Action Space

At each step, the agent can take one of the following actions targeting a specific zone:

• —action_type:
• —0 = Spray (Deploy spray resource to aggressively reduce infestation)
• —1 = Trap (Deploy trap resource to suppress growth and spread)
• —2 = Wait (Do nothing, save resources)
• —zone_id: The ID of the target zone (ignored if the action is Wait).

Observation Space

The environment provides a rich state dictionary at each step:

• —`zones`: A dictionary mapping each zone_id to its ZoneState, containing:
• —infestation_rate: Continuous value [0.0, 1.0] (0 = clean, 1 = fully infested).
• —population: Fixed human population in the zone for the episode.
• —temperature, humidity, rained: The current weather conditions influencing mosquito breed rates.
• —has_trap, trap_steps_remaining: Status of traps deployed.
• —is_treated, treatment_steps_remaining: Status of sprays deployed.
• —`adjacency`: The static graph structure for the current city (list of neighboring zones).
• —`remaining_spray`: Count of unused sprays.
• —`remaining_traps`: Count of unused traps.
• —`step`: The current day in the 30-day episode.
• —`cumulative_avg_infestation_rate`: The overall metric tracking the city's health.

4. Algorithms and Mathematical Formulations

The environment uses dynamic stochastic models to simulate weather drift and its impact on mosquito breeding (growth) and disease diffusion (spread). It heavily penalizes sub-optimal strategies through these mathematical mechanisms:

A. Environment and Weather Drift

At each step $t$, the per-zone weather parameters continuously drift using bounded uniform distributions:

• —Humidity ($h \in [0, 1]$): $$h{t+1} = \max(0,\; \min(1,\; ht + \mathcal{U}(-0.05, 0.05)))$$
• —Temperature ($T \in [15, 45]$ °C): $$T{t+1} = \max(15,\; \min(45,\; Tt + \mathcal{U}(-0.5, 0.5)))$$
• —Rainfall Probability ($r \in \{0, 1\}$): $$P(\text{rain}) = 0.10 + h_{t+1} \times 0.25$$

B. Infestation Growth Rate

The daily mosquito infestation growth added to a zone is heavily modulated by temperature and humidity. Ideal temperatures (near 30°C) and high humidity cause rapid spikes.

• —Temperature Factor: $f_{temp} = \max\left(0,\; 1 - \frac{|T - 30|}{15}\right)$
• —Base Growth Rate ($\alpha = 0.08$): $$Rate{growth} = \alpha \times (1 + f{temp} + 0.5 \times h + 0.4 \times r)$$

Treatment Effects on Growth:

• —If a Spray is active in the zone, $Rate_{growth}$ drops immediately to $0.0$.
• —If a Trap is present, the effective $Rate_{growth}$ is reduced to $40\%$ of normal.

C. Disease Spread Probability

Infestation diffuses along the edges of the city's graph depending on the source zone's current infestation and weather:

• —Base Spread Probability ($\beta = 0.10$): $$P{spread} = \beta \times \text{Infestation}{src} \times (1 + 0.3 \times h{src} + 0.25 \times r{src})$$

Suppression Mechanisms (Cap $90\%$):

• —Traps: Each trap at either the source or destination knot reduces $P_{spread}$ to $50\%$. (i.e., traps at both ends stack to reduce spread to $25\%$).
• —Sprays: Active sprays at the destination zone drastically resist incoming infestations, dropping $P_{spread}$ to just $15\%$.

5. Setup and Usage Instructions

This environment is built on top of OpenEnv and uses Docker for easy reproducibility.

Prerequisites

• —Python 3.10+
• —Docker

Installation

1. 1.Clone the repository and navigate to the project directory:

   git clone <your-repo-url>
   cd vector_borne_disease_control-main

1. 1.Install the necessary dependencies:

   pip install -e .

1. 1.Build the Docker image for the environment server:

   docker build -t vector_borne_disease_control-env:latest .

Running the Environment

You can interact with the environment perfectly using the OpenEnv docker launcher:

from vector_borne_disease_control import VectorBorneDiseaseControlEnv
from vector_borne_disease_control.models import VectorBorneDiseaseControlAction, ActionType

try:
    # 1. Initialize from the built Docker image
    env = VectorBorneDiseaseControlEnv.from_docker_image("vector_borne_disease_control-env:latest")

    # 2. Reset to start a new 30-day episode
    result = env.reset()
    observation = result.observation
    
    print(f"Starting City Zones: {len(observation.zones)}")
    print(f"Initial Tools: {observation.remaining_spray} Sprays, {observation.remaining_traps} Traps")

    # 3. Take a step (e.g., Spray Zone 0)
    action = VectorBorneDiseaseControlAction(
        action_type=ActionType.SPRAY, 
        zone_id=0
    )
    result = env.step(action)
    print(f"Reward: {result.reward}")

finally:
    # Always clean up the Docker container when done!
    env.close()

Let's build intelligent systems to solve real-world crises. Every small step towards better disease control matters.

Advanced Usage

Connecting to an Existing Server

If you already have a Vector Borne Disease Control environment server running, you can connect directly:

from vector_borne_disease_control import VectorBorneDiseaseControlEnv

env = VectorBorneDiseaseControlEnv(base_url="<ENV_HTTP_URL_HERE>")
result = env.reset()
result = env.step(VectorBorneDiseaseControlAction(action_type=ActionType.WAIT, zone_id=None))

Note: When connecting to an existing server, env.close() will NOT stop the server.

Development & Testing

Direct Environment Testing

Test the environment logic directly without starting the HTTP server:

# From the server directory
python3 server/vector_borne_disease_control_environment.py

This verifies that:

• —Environment resets correctly
• —Step executes actions properly
• —State tracking works
• —Rewards are calculated correctly

Running Locally

Run the server locally for development:

uvicorn server.app:app --reload

Project Structure

vector_borne_disease_control/
├── .dockerignore         # Docker build exclusions
├── Dockerfile             # Container image definition
├── __init__.py            # Module exports
├── README.md              # This file
├── openenv.yaml           # OpenEnv manifest
├── pyproject.toml         # Project metadata and dependencies
├── uv.lock                # Locked dependencies (generated)
├── client.py              # VectorBorneDiseaseControlEnv client
├── models.py              # Action and Observation models
└── server/
    ├── __init__.py        # Server module exports
    ├── vector_borne_disease_control_environment.py  # Core environment logic
    └── app.py             # FastAPI application (HTTP + WebSocket endpoints)