A Complete Epidemic Modeling Suite with 6 Integrated Features
- Overview
- Features
- Installation
- Quick Start
- Documentation
- Project Structure
- Usage Guide
- Testing
- Security
- Screenshots
- Contributing
- License
The SIR Epidemic Simulator is a comprehensive epidemic modeling toolkit combining classical compartmental models with modern machine learning. It provides researchers, students, and public health professionals with tools to simulate, analyze, and predict epidemic dynamics.
| Capability | Description |
|---|---|
| 📈 SIR Model | Basic Susceptible-Infected-Recovered dynamics |
| 🧬 SEIR Model | Adds Exposed/incubation compartment |
| 🌐 Network Simulation | Fake news spread on social graphs |
| 🎯 Parameter Optimization | Fit models to real-world data |
| 🤖 ML Prediction | Forecast future cases with XGBoost/Random Forest |
| ⚖️ Scenario Comparison | Evaluate quarantine vs vaccination |
- ✅ SIR model with ODE solver
- ✅ SEIR model with exposed compartment
- ✅ Population conservation verification
- ✅ Configurable simulation parameters
- ✅ Scale-free network (Barabási-Albert)
- ✅ Small-world network (Watts-Strogatz)
- ✅ Random network (Erdos-Renyi)
- ✅ SIR spread simulation on social graphs
- ✅ Network statistics calculator
- ✅ Parameter optimization using differential evolution
- ✅ Curve fitting for real-world epidemic data
- ✅ ML prediction with Random Forest & XGBoost
- ✅ Scenario comparison (Baseline, Quarantine, Vaccination, Combined)
- ✅ Streamlit web dashboard
- ✅ Command-line interface (CLI)
- ✅ Interactive menu system
- ✅ CSV export functionality
- ✅ 35+ unit tests
- ✅ 22 security tests (DoS, Memory, Unicode, XSS)
- ✅ GitHub Actions CI/CD
- ✅ Pre-commit hooks for code quality
- Python 3.8 or higher
- pip package manager
pip install sir-epidemicgit clone https://github.com/miladrezanezhad/sir_simulator.git
cd sir_simulator
pip install -e .python -c "import sir_simulator; print('✅ Success!')"streamlit run src/sir_simulator/user_interface/app.pyThen open http://localhost:8501 in your browser.
sir-simulator --beta 0.5 --gamma 0.2 --tmax 100python main.pypython run_all_tests.py
python -m unittest discover tests/securityFor detailed tutorials, API reference, and FAQs, visit our GitHub Wiki:
| Wiki Page | Description |
|---|---|
| 🏠 Home | Wiki home page |
| 🚀 Getting Started | Installation and first steps |
| 📈 SIR Model Tutorial | Complete SIR model guide |
| 🧬 SEIR Model Tutorial | Complete SEIR model guide |
| 🌐 Network Simulation Tutorial | Social network spread guide |
| 🤖 ML Prediction Tutorial | Machine learning forecasting |
| ⚖️ Scenario Comparison Tutorial | Intervention strategies |
| ❓ FAQ | Frequently asked questions |
| 📚 API Reference | Complete function documentation |
| 🤝 Contributing Guide | How to contribute |
| File | Description |
|---|---|
| TESTING.md | Complete testing guide |
| SECURITY_TESTS.md | Security testing documentation |
| SECURITY.md | Security policy |
| CONTRIBUTING.md | Contributing guidelines |
| CODE_OF_CONDUCT.md | Code of conduct |
| CHANGELOG.md | Version history |
sir_simulator/
│
├── src/sir_simulator/ # Source code
│ ├── core_models/ # Core mathematical models
│ │ ├── sir_model.py # Basic SIR implementation
│ │ ├── seir_model.py # SEIR with exposed compartment
│ │ └── network_model.py # Social network spread simulation
│ │
│ ├── advanced_features/ # Advanced capabilities
│ │ ├── parameter_optimization.py # Curve fitting
│ │ ├── ml_prediction.py # ML forecasting
│ │ └── scenario_comparison.py # Intervention analysis
│ │
│ └── user_interface/ # UI applications
│ ├── app.py # Streamlit dashboard
│ └── cli.py # Command-line interface
│
├── tests/ # Test suite (57+ tests)
│ ├── test_seir.py # SEIR model tests
│ ├── test_network.py # Network simulation tests
│ ├── test_optimization.py # Parameter optimization tests
│ ├── test_ml.py # ML prediction tests
│ ├── test_scenarios.py # Scenario comparison tests
│ └── security/ # Security test suite
│ ├── test_dos_attack.py
│ ├── test_memory_exhaustion.py
│ ├── test_unicode_attacks.py
│ └── test_xss_prevention.py
│
├── docs/ # Documentation
│ └── notebook.ipynb # Educational Jupyter notebook
│
├── screenshots/ # Application screenshots (7 images)
│
├── .github/workflows/ # CI/CD pipelines
│ ├── test.yml # Test automation
│ └── security.yml # Security scan pipeline
│
├── README.md # This file
├── TESTING.md # Testing guide
├── SECURITY_TESTS.md # Security testing guide
├── SECURITY.md # Security policy
├── CONTRIBUTING.md # Contributing guide
├── CODE_OF_CONDUCT.md # Code of conduct
├── CHANGELOG.md # Version history
├── LICENSE # MIT License
├── pyproject.toml # Project configuration
├── requirements.txt # Python dependencies
├── requirements_dev.txt # Development dependencies
├── Makefile # Common tasks automation
├── main.py # Interactive menu
└── run_all_tests.py # Master test runner
from sir_simulator.core_models.sir_model import run_sir_simulation
df = run_sir_simulation(
beta=0.5, gamma=0.2,
S0=990, I0=10, R0=0,
t_max=100, steps=500
)from sir_simulator.core_models.seir_model import run_seir_simulation
df = run_seir_simulation(
beta=0.5, sigma=0.2, gamma=0.1,
S0=990, E0=5, I0=5, R0=0,
t_max=100, steps=500
)from sir_simulator.core_models.network_model import SocialNetworkSimulator
sim = SocialNetworkSimulator(num_nodes=200, network_type='scale_free')
df = sim.simulate_spread(transmission_prob=0.4, recovery_prob=0.1)from sir_simulator.advanced_features.parameter_optimization import ParameterOptimizer
optimizer = ParameterOptimizer(model_type='sir')
results = optimizer.fit(observed_data, t, [990, 10, 0])
print(f"β={results['beta']:.3f}, γ={results['gamma']:.3f}, R0={results['R0']:.3f}")from sir_simulator.advanced_features.ml_prediction import EpidemicPredictor
predictor = EpidemicPredictor(model_type='random_forest')
metrics, predictions, _ = predictor.train(historical_data)
future = predictor.predict_future(historical_data, days=30)from sir_simulator.advanced_features.scenario_comparison import ScenarioComparator
comp = ScenarioComparator(beta=0.25, gamma=0.1)
scenarios, metrics = comp.compare_all_scenarios(days=120)
print(metrics)python run_all_tests.py
python -m unittest discover tests/security| Module | Tests | Status |
|---|---|---|
| SEIR Model | 7 | ✅ |
| Network Model | 10 | ✅ |
| Parameter Optimization | 6 | ✅ |
| ML Prediction | 2 (active) + 2 (skip) | ✅ |
| Scenario Comparison | 8 | ✅ |
| Security (DoS, Memory, Unicode, XSS) | 22 | ✅ |
| Total | 57 | ✅ All Passing |
python tests/test_seir.py
python tests/test_network.py
python tests/test_optimization.py
python tests/test_ml.py
python tests/test_scenarios.py
python tests/security/test_dos_attack.pyFor detailed testing documentation, see TESTING.md.
This project includes comprehensive security testing:
| Test Category | Tests | Status |
|---|---|---|
| DoS Attack Prevention | 5 | ✅ |
| Memory Exhaustion Protection | 4 | ✅ |
| Unicode/UTF-8 Attack Mitigation | 6 | ✅ |
| XSS Prevention for Streamlit | 7 | ✅ |
| Total | 22 | ✅ All Passing |
All security tests pass with no vulnerabilities detected.
For security issues, please see SECURITY.md.
| SIR Model | SEIR Model |
|---|---|
| Network Simulation | Parameter Optimization |
|---|---|
| ML Prediction | Scenario Comparison |
|---|---|
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
python run_all_tests.py - Submit a Pull Request
git clone https://github.com/YOUR_USERNAME/sir_simulator.git
cd sir_simulator
pip install -e .
pip install -r requirements_dev.txt
pre-commit installThis project is licensed under the MIT License - see the LICENSE file for details.
- Classical SIR/SEIR models from Kermack-McKendrick theory
- Network science algorithms from NetworkX library
- Machine learning models from scikit-learn and XGBoost
- Streamlit for the interactive dashboard framework
| Channel | Link |
|---|---|
| GitHub Issues | Report bug |
| GitHub Discussions | Ask questions |
| miladvf2014@gmail.com | |
| PyPI | sir-epidemic |
If you find this project useful, please consider starring it on GitHub!
Built with ❤️ for epidemic modeling and public health research