Sistema computacional para modelar y simular la dinámica poblacional de mosquitos vectores (Aedes aegypti) y su interacción con depredadores naturales (Toxorhynchites spp.). El software integra modelos matemáticos poblacionales con simulaciones basadas en agentes inteligentes, permitiendo evaluar estrategias de control biológico mediante la introducción de especies depredadoras.

1. Motivación Científica
2. Características Principales
3. Arquitectura del Sistema
4. Requisitos del Sistema
5. Instalación
6. Estructura del Proyecto
7. Guía de Uso
8. Especies Modeladas
9. Configuración
10. API y Casos de Uso
11. Pruebas
12. Licencia

Aedes aegypti es el principal vector de enfermedades virales de alto impacto en salud pública, incluyendo:

• Dengue: 390 millones de infecciones anuales estimadas (OMS)
• Zika: Asociado a microcefalia y síndrome de Guillain-Barré
• Chikungunya: Enfermedad articular debilitante
• Fiebre amarilla: Mortalidad del 20-50% en casos severos

El control químico mediante insecticidas enfrenta limitaciones crecientes debido al desarrollo de resistencia en poblaciones de mosquitos. Esto ha impulsado la investigación de alternativas sostenibles como el control biológico.

El género Toxorhynchites comprende mosquitos cuyas larvas son depredadores obligados de otras larvas de mosquitos, mientras que los adultos son exclusivamente nectarívoros (no pican a humanos ni transmiten enfermedades).

Características relevantes:

• Larvas L3-L4 consumen 10-20 presas/día
• Cohabitan en los mismos contenedores que Aedes aegypti
• No desarrollan resistencia a insecticidas (estrategia biológica)
• Liberaciones pueden reducir poblaciones larvarias 40-90%

Este sistema permite modelar computacionalmente la efectividad de introducir Toxorhynchites como agente de control en diferentes escenarios ambientales.

• Simulación poblacional: Modelo basado en matrices de Leslie con integración Prolog
• Simulación depredador-presa: Modelado completo de interacciones Toxorhynchites-Aedes aegypti
• Tasas de supervivencia dinámicas: Motor Prolog ajusta tasas según condiciones ambientales en tiempo real
• Comparación automática: Evaluación de escenarios con y sin depredadores
• Análisis de impacto: Cálculo de reducción poblacional por depredación
• Persistencia: Sistema de checkpoints para guardar/restaurar simulaciones
• Configuración flexible: Parámetros biológicos externalizados en JSON
• Visualización avanzada: Gráficos multi-panel con dinámicas de presa y depredador
• Arquitectura limpia: Separación de responsabilidades en capas independientes

• Interfaz gráfica (GUI): Aplicación de escritorio con tkinter
• Simulación de especies únicas: Configuración completa para Aedes aegypti y Toxorhynchites
• Simulación presa-depredador: Pestaña dedicada con parámetros duales sincronizados
• Validación en tiempo real: Indicadores visuales (✓/⚠/✗) para rangos de parámetros
• Tooltips informativos: Ayuda contextual detallada en todos los parámetros
• Presets ambientales: 6 configuraciones predefinidas (Tropical, Templado, Extremo, Monzón)
• Presets depredador-presa: 9 escenarios de interacción (Balanceado, Control débil/fuerte, Presión, Brote)
• Visualización de resultados: Gráficos integrados de evolución poblacional por estadio
• Comparación visual: Gráficas de impacto de depredación con estadísticas overlay
• Exportación de datos: Funcionalidad CSV y PNG para resultados y gráficas

• Simulación basada en agentes: Arquitectura implementada, pendiente integración GUI
• Simulación híbrida: Comparación poblacional vs. agentes pendiente

El sistema implementa Clean Architecture (Arquitectura Limpia), separando responsabilidades en capas independientes con dependencias unidireccionales.

┌─────────────────────────────────────────────────────────────┐
│                    CAPA DE PRESENTACIÓN                     │
│         GUI (Tkinter) - Vistas, Controladores, Widgets      │
│   Validación | Tooltips | Presets | Visualización Gráfica  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    CAPA DE APLICACIÓN                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Casos de  │  │  Servicios  │  │        DTOs         │  │
│  │     Uso     │  │             │  │ (Data Transfer Obj) │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      CAPA DE DOMINIO                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Modelos   │  │  Entidades  │  │      Agentes        │  │
│  │ Matemáticos │  │  de Negocio │  │    Inteligentes     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  CAPA DE INFRAESTRUCTURA                    │
│  ┌─────────────────────┐  ┌─────────────────────────────┐   │
│  │ Gestión de Config   │  │     Puente Python-Prolog    │   │
│  │      (JSON)         │  │         (PySwip)            │   │
│  └─────────────────────┘  └─────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    BASE DE CONOCIMIENTO                     │
│                        (Prolog)                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Ontología  │  │   Hechos    │  │       Reglas        │  │
│  │  Taxonómica │  │  Biológicos │  │    de Inferencia    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Núcleo del sistema con la lógica de negocio biológica:

• Modelos: Matrices de Leslie, procesos estocásticos, dinámica ambiental
• Entidades: Especies, mosquitos individuales, poblaciones, hábitats
• Agentes: Agentes racionales con decisiones basadas en Prolog

Orquestación de operaciones y transformación de datos:

• Casos de Uso: Operaciones completas (ejecutar simulación, comparar escenarios)
• Servicios: Coordinación entre dominio e infraestructura
• DTOs: Estructuras de transferencia entre capas

Comunicación con recursos externos:

• ConfigManager: Carga y validación de configuraciones JSON
• PrologBridge: Interfaz Python-SWI-Prolog vía PySwip

Interfaces de usuario implementadas y en desarrollo:

• GUI: Aplicación de escritorio con Tkinter (implementada)
• Vistas: SimulationView, ResultsView, HomeView
• Widgets: Tooltips, validación en tiempo real, presets de escenarios
• CLI: Interfaz de línea de comandos (pendiente)
• API REST: Endpoints para integración (pendiente)

• RAM: 4 GB mínimo (8 GB para simulaciones grandes)
• CPU: Procesador multi-núcleo para simulaciones paralelas
• Almacenamiento: 500 MB para instalación + espacio para checkpoints

git clone https://github.com/usuario/Mosquitoes-Simulation.git
cd Mosquitoes-Simulation

Windows:

# Descargar instalador desde https://www.swi-prolog.org/download/stable
# Agregar al PATH: C:\Program Files\swipl\bin

Linux (Ubuntu/Debian):

sudo apt-add-repository ppa:swi-prolog/stable
sudo apt-get update
sudo apt-get install swi-prolog

macOS:

brew install swi-prolog

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

pip install -r requirements.txt

cd src
python -c "from infrastructure import PrologBridge; print('Prolog OK')"
python -c "from domain.models import PopulationModel; print('Modelos OK')"
python -m unittest discover tests -v

Mosquitoes-Simulation/
├── config/                      # Configuraciones JSON
│   ├── default_config.json      # Configuración general
│   ├── species/                 # Parámetros por especie
│   │   ├── aedes_aegypti.json
│   │   └── toxorhynchites.json
│   └── environment/             # Condiciones ambientales
│       └── default_environment.json
│
├── src/                         # Código fuente
│   ├── domain/                  # Capa de Dominio
│   │   ├── models/              # Modelos matemáticos
│   │   ├── entities/            # Entidades de negocio
│   │   └── agents/              # Agentes inteligentes
│   │
│   ├── application/             # Capa de Aplicación
│   │   ├── services/            # Servicios de negocio
│   │   ├── use_cases/           # Casos de uso
│   │   ├── dtos.py              # Data Transfer Objects
│   │   └── visualization.py     # Funciones de graficación
│   │
│   ├── infrastructure/          # Capa de Infraestructura
│   │   ├── config.py            # Gestión de configuración
│   │   └── prolog_bridge.py     # Puente Python-Prolog
│   │
│   ├── presentation/            # Capa de Presentación
│   │   ├── views/               # Vistas de la aplicación
│   │   ├── controllers/         # Controladores MVC
│   │   ├── components/          # Componentes reutilizables
│   │   ├── widgets/             # Widgets personalizados (tooltips)
│   │   ├── data/                # Datos estáticos (presets, rangos)
│   │   ├── styles/              # Temas y estilos visuales
│   │   └── main.py              # Punto de entrada GUI
│   │
│   ├── prolog/                  # Base de Conocimiento Prolog
│   │   ├── knowledge_base/      # Ontología y hechos
│   │   └── inference/           # Reglas de inferencia
│   │
│   └── tests/                   # Pruebas unitarias
│
├── checkpoints/                 # Checkpoints de simulaciones
├── docs/                        # Documentación adicional
├── requirements.txt             # Dependencias Python
└── README.md                    # Este archivo

La aplicación cuenta con una interfaz gráfica completa que permite configurar y ejecutar simulaciones sin código:

cd src/presentation
python main.py

1. Simulación de Especie Única

   • Configuración para Aedes aegypti o Toxorhynchites individualmente
   • 10 escenarios predefinidos en 5 categorías (Base, Estrés, Control, Óptimas, Brote)
   • Poblaciones iniciales por estadio (huevos, larvas L1-L4, pupas, adultos)
   • Condiciones ambientales unificadas
   • Visualización de evolución temporal completa

2. Simulación Presa-Depredador

   • Pestaña dedicada "🦁 Presa-Depredador"
   • Parámetros ambientales compartidos entre especies
   • Configuración dual: poblaciones de presa (4 estadios) y depredador (3 estadios)
   • 6 presets ambientales: Tropical Óptimo, Tropical Seco, Templado, Calor Extremo, Invierno, Monzón
   • 9 presets de interacción: Balanceado, Control Débil, Control Fuerte, Presión sobre Presa, Introducción Tardía, Seco, Óptimo, Largo Plazo, Brote
   • Comparación automática con y sin depredadores
   • Uso obligatorio de Prolog para inferencia dinámica

3. Validación en Tiempo Real

   • Indicadores visuales: ✓ (válido), ⚠ (fuera de rango), ✗ (error)
   • Actualización instantánea al modificar valores
   • Tooltips con mensajes de error específicos

4. Ayuda Contextual

   • Tooltips informativos en todos los parámetros
   • Información sobre rangos válidos y valores típicos
   • Guías de referencia para configuraciones

5. Visualización de Resultados

   • Especie única: Gráficos de evolución poblacional por estadio con estadísticas
   • Presa-Depredador: Visualización dual con dos modos:
     • Dinámicas Completas: Grid 2×2 con poblaciones totales, composición por estadio (presa y depredador), y estadísticas overlay
     • Comparación con/sin Depredadores: Gráficas lado a lado mostrando impacto de depredación con porcentaje de reducción
   • Estadísticas detalladas: poblaciones inicial/final, picos, promedios, desviación estándar
   • Botones para alternar entre vistas de gráficas

6. Exportación de Datos

   • CSV: Exportación de trayectorias completas (día, poblaciones por estadio, condiciones ambientales)
   • PNG: Guardado de todas las gráficas disponibles (dinámicas y comparaciones)
   • Selección de carpeta de destino mediante diálogo

from application.services.simulation_service import SimulationService
from application.dtos import SimulationConfig

# Crear servicio de simulación
service = SimulationService()

# Configurar simulación de Aedes aegypti
config = SimulationConfig(
    species_id='aedes_aegypti',
    duration_days=90,
    initial_eggs=100,
    initial_larvae=50,
    initial_pupae=20,
    initial_adults=30,
    temperature=28.0,      # °C
    humidity=75.0,         # %
    water_availability=0.8 # Disponibilidad de sitios de oviposición
)

# Ejecutar simulación
result = service.run_population_simulation(config)

# Analizar resultados
print(f"Población final: {result.total_population[-1]:.0f}")
print(f"Pico poblacional: {result.statistics['peak_population']:.0f}")
print(f"Día del pico: {result.statistics['peak_day']}")

from application.services.population_service import PopulationService
from application.dtos import PredatorPreyConfig

# Servicio de simulación
service = PopulationService()

# Configurar simulación presa-depredador
config = PredatorPreyConfig(
    species_id='aedes_aegypti',           # Presa
    predator_species_id='toxorhynchites', # Depredador
    duration_days=90,
    
    # Poblaciones iniciales de presa
    initial_eggs=1000,
    initial_larvae=500,
    initial_pupae=100,
    initial_adults=100,
    
    # Poblaciones iniciales de depredador (estadios larvales únicamente)
    predator_initial_larvae=20,
    predator_initial_pupae=5,
    predator_initial_adults=10,
    
    # Ambiente compartido
    temperature=28.0,
    humidity=75.0,
    water_availability=0.8
)

# Ejecutar simulación con depredadores
result = service.simulate_predator_prey(config, use_prolog=True)

print(f"Presa - Población inicial: {result.statistics['prey_initial']:.0f}")
print(f"Presa - Población final: {result.statistics['prey_final']:.0f}")
print(f"Presa - Reducción por depredación: {result.statistics['predation_reduction_percent']:.1f}%")
print(f"Depredador - Población final: {result.statistics['predator_final']:.0f}")

# Comparar con y sin depredadores
comparison = service.compare_predation_effect(config, use_prolog=True)

with_pred = comparison['with_predators']
without_pred = comparison['without_predators']

print(f"\nCon depredadores: {with_pred.statistics['prey_final']:.0f} presas")
print(f"Sin depredadores: {without_pred.statistics['prey_final']:.0f} presas")
print(f"Efectividad del control: {comparison['reduction_percentage']:.1f}%")

# Simulación con Toxorhynchites como control biológico
result = service.run_agent_simulation(
    config=config,
    num_predators=10,
    predator_species_id='toxorhynchites'
)

print(f"Vectores supervivientes: {result.num_vectors_final}")
print(f"Tasa de supervivencia: {result.get_survival_rate_vectors():.2%}")
print(f"Presas consumidas: {result.total_prey_consumed}")

# Ejecutar ambos modelos en paralelo
hybrid_result = service.run_hybrid_simulation(
    config=config,
    num_predators=10,
    predator_species_id='toxorhynchites'
)

# Comparar resultados
summary = hybrid_result.get_comparison_summary()
print(f"Pico (Poblacional: {summary['population_peak']:.0f}")
print(f"Pico (Agentes): {summary['agent_peak']:.0f}")
print(f"Diferencia: {summary[Comparativa]:.0f}")

from application.use_cases.compare_scenarios import (
    CompareScenarios,
    CompareScenariosRequest,
    ScenarioConfig
)

# Definir escenarios con diferentes temperaturas
scenarios = {
    "temp_25C": ScenarioConfig(
        species_id='aedes_aegypti',
        duration_days=60,
        initial_adults=50,
        temperature=25.0,
        humidity=75.0,
        water_availability=0.8
    ),
    "temp_30C": ScenarioConfig(
        species_id='aedes_aegypti',
        duration_days=60,
        initial_adults=50,
        temperature=30.0,
        humidity=75.0,
        water_availability=0.8
    ),
    "temp_35C": ScenarioConfig(
        species_id='aedes_aegypti',
        duration_days=60,
        initial_adults=50,
        temperature=35.0,
        humidity=75.0,
        water_availability=0.8
    )
}

# Comparar escenarios
use_case = CompareScenarios(service)
request = CompareScenariosRequest(
    scenarios=scenarios,
    simulation_type='population',
    comparison_metric='peak_population'
)
response = use_case.execute(request)

# Resultados
print(f"Mejor escenario para crecimiento: {response.best_scenario}")
print(f"Ranking: {response.ranking}")

from application.use_cases.manage_checkpoints import (
    SaveCheckpoint, LoadCheckpoint,
    SaveCheckpointRequest, LoadCheckpointRequest
)

# Guardar checkpoint
save_use_case = SaveCheckpoint(service)
save_request = SaveCheckpointRequest(
    result=result,
    config=config,
    simulation_type='population',
    checkpoint_name='aedes_90dias.json'
)
save_response = save_use_case.execute(save_request)
print(f"Guardado en: {save_response.checkpoint_path}")

# Cargar checkpoint
load_use_case = LoadCheckpoint(service)
load_request = LoadCheckpointRequest(
    checkpoint_path=save_response.checkpoint_path
)
load_response = load_use_case.execute(load_request)
loaded_result = load_response.result

from application.visualization import (
    plot_population_evolution,
    plot_scenario_comparison,
    plot_predator_prey_interaction,
    plot_predation_impact_comparison
)

# Gráfico de evolución poblacional (especie única)
fig = plot_population_evolution(
    result=result,
    save_path='results/population_evolution.png'
)

# Gráfico de comparación de escenarios
fig = plot_scenario_comparison(
    comparison_result=response.result,
    metric='peak_population',
    save_path='results/scenario_comparison.png'
)

# Gráfico de interacción presa-depredador (2×2 grid)
fig = plot_predator_prey_interaction(
    result=predator_prey_result,
    show=True,
    save_path='results/predator_prey_dynamics.png'
)

# Gráfico de comparación con/sin depredadores
fig = plot_predation_impact_comparison(
    with_predators=comparison['with_predators'],
    without_predators=comparison['without_predators'],
    show=True,
    save_path='results/predation_impact.png'
)

config/default_config.json:

{
  "simulation": {
    "default_days": 365,
    "time_step": 1,
    "random_seed": null,
    "stochastic_mode": true
  },
  "initial_populations": {
    "aedes_aegypti": {
      "egg": 200,
      "larva_l1": 150,
      "larva_l2": 120,
      "larva_l3": 100,
      "larva_l4": 80,
      "pupa": 50,
      "adult_female": 100,
      "adult_male": 100
    }
  },
  "species_configs": [
    "species/aedes_aegypti.json",
    "species/toxorhynchites.json"
  ],
  "environment_config": "environment/default_environment.json"
}

config/species/aedes_aegypti.json:

{
  "species_id": "aedes_aegypti",
  "display_name": "Aedes aegypti",
  "life_stages": {
    "egg": {
      "duration_days": {"min": 2, "max": 7},
      "survival_to_next": 0.80
    },
    "larva_l1": {
      "duration_days": {"min": 1, "max": 2},
      "survival_to_next": 0.85
    }
    // ... más estadios
  },
  "reproduction": {
    "eggs_per_batch": {"min": 80, "max": 150},
    "oviposition_events": 3,
    "min_age_reproduction_days": 3
  },
  "environmental_sensitivity": {
    "optimal_temperature": {"min": 25, "max": 28},
    "lethal_temperature": {"min": 10, "max": 40},
    "optimal_humidity": 80
  }
}

cd src
python -m unittest discover tests -v

# Pruebas de casos de uso
python -m unittest tests.test_use_cases_core -v

# Pruebas de servicios
python -m unittest tests.test_application_simulation_service -v

# Pruebas de checkpoints
python -m unittest tests.test_use_cases_checkpoints -v

La capa de presentación cuenta con una interfaz gráfica completa implementada en Tkinter:

• GUI (Graphical User Interface): Aplicación de escritorio funcional
• Vista principal con navegación por pestañas
• Vista de configuración de simulación con validación
• Vista de resultados con gráficos integrados
• Sistema de tooltips contextual
• Presets de escenarios predefinidos
• Tema visual profesional y consistente

La GUI implementa el patrón Modelo-Vista-Controlador (MVC):

• Vistas (views/): Componentes visuales (SimulationView, ResultsView, HomeView)
• Controladores (controllers/): Lógica de interacción (SimulationController)
• Componentes (components/): Elementos reutilizables (Sidebar, StatusBar)
• Widgets (widgets/): Controles personalizados (ToolTip)
• Datos (data/): Configuraciones estáticas (scenario_presets, parameter_ranges)
• Estilos (styles/): Temas visuales (theme.py con paleta de colores profesional)

El sistema Prolog está totalmente integrado para ajustar dinámicamente las tasas de supervivencia:

• Consulta activa: Cada paso de simulación consulta effective_survival/6
• Factores ambientales: Temperatura, humedad, disponibilidad de agua
• Fallback robusto: Si Prolog falla, usa tasas estáticas del JSON
• Validación: Tasas fuera de [0,1] son rechazadas automáticamente
• Impacto medido: Tests muestran diferencias de +14,000% en población con tasas dinámicas

Las bases para depredación están implementadas pero inactivas:

• Reglas Prolog: predation_risk/5, predation_rate/4 definidas
• Método en modelo: _apply_predation_effects() preparado
• Falta: Activar llamada en step() y crear GUI para configuración

Cada capa del sistema cuenta con documentación detallada:

• Capa de Dominio - Modelos, entidades y agentes
• Capa de Aplicación - Servicios, casos de uso y DTOs
• Capa de Infraestructura - Configuración y Prolog bridge
• Sistema Prolog - Base de conocimiento

Este proyecto está licenciado bajo la Licencia MIT.

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Las contribuciones son bienvenidas. Por favor:

1. Fork del repositorio
2. Crear rama para feature (git checkout -b feature/nueva-funcionalidad)
3. Commit de cambios (git commit -m 'Agregar nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abrir Pull Request

Para preguntas, sugerencias o reportes de bugs, por favor abrir un Issue en el repositorio.