EpiNexus: Spatio-Temporal Outbreak Intelligence Engine

EpiNexus is a high-fidelity epidemiological decision-support platform designed for localized outbreak control. By combining physics-informed viral modeling with advanced spatial indexing, EpiNexus allows public health officials to visualize transmission networks and optimize testing resources in real-time.

---

💎 Real-World Impact & Value

Traditional contact tracing is manual, slow, and reactive. EpiNexus transforms this into a proactive intelligence operation:

• Resource Optimization: Instead of mass testing, use the Value of Information (VoI) metric to identify the 5% of agents whose test results will collapse 50% of system uncertainty.
• Environmental Precision: Model risk not just by "who met whom," but by the air exchange rate (ACH) and viral decay of the specific rooms they shared.
• Scalable Crisis Response: Capable of processing thousands of movement trajectories in seconds to provide immediate actionable insights during the first 72 hours of an outbreak.

---

🚀 Performance & Scalability (Epi-Score: 91.3/100)

We benchmarked the system under high-load scenarios to ensure it can meet the demands of a metropolitan health department.

Metric	Performance	Description
Throughput	4,597 agent-sims/sec	Number of individual agent exposure cycles processed per second.
Inference Latency	174ms	Time to complete one full Monte Carlo simulation for 800+ agents.
Certainty Gain	74.9%	Reduction in risk uncertainty (CI narrowing) after 50 MC iterations.
System Capacity	~45,000 Agents	Theoretical maximum agents handled within a 10s response window.
Overall Score	91.3 / 100	Composite score of speed, scalability, and convergence efficiency.

📈 Scalability Projection

The engine utilizes a cKDTree spatial index, resulting in $O(N \log N)$ complexity. While current tests use 801 agents, the system is projected to handle 10,000 agents with a latency of ~3.0s per iteration, making it suitable for university campuses, industrial complexes, or small cities.

---

🏗 Core Technology

• Ghost Virus Engine: A physics-informed exposure kernel that calculates transmission probability based on distance, time, and room ventilation (ACH).
• Monte Carlo Ensemble: Runs hundreds of stochastic simulations to generate 95% Confidence Intervals for every agent.
• Active Learning: Uses Shannon Entropy and hospitalization risk to prioritize testing for agents with the highest "Value of Information."
• Vectorized Inference: Core loops are implemented in NumPy for high-performance CPU utilization.

---

📁 Repository Structure

• backend/: Python (FastAPI) engine for spatial exposure and Monte Carlo simulation.
• frontend/: TypeScript (React/TanStack) dashboard for real-time visualization.
• docs/: Comprehensive documentation on mathematics, data schemas, and vision.

🛠 Setup & Execution

EpiNexus uses two distinct environments. Ensure you are in the correct directory before running commands.

🐍 Backend (Simulation Engine)

The backend requires a specific Python environment with NumPy and SciPy.

1. cd backend
2. Activate Environment:
   • Windows: ..\.venv\Scripts\activate
   • Mac/Linux: source ../.venv/bin/activate
3. Generate Data (First time only): python generator.py
4. Run Server: python run.py

⚛️ Frontend (Dashboard)

The frontend is a Vite-powered React application.

1. cd frontend
2. npm install
3. npm run dev

---

⚡ Quick Start (Windows)

Use the included launcher scripts in the root directory to start both servers automatically:

• Double-click start.bat or run ./start.ps1 in PowerShell.

---

Built during a 72-hour research sprint to redefine localized outbreak response.