Getting Started

This guide will help you install and run your first epidemic simulation in minutes.

---

📋 Prerequisites

Before you begin, make sure you have:

Requirement	Version	Check Command
Python	3.8 or higher	python --version
pip	Latest	pip --version
Git (optional)	Any	git --version

---

💾 Installation

Method 1: Install from PyPI (Recommended)

pip install sir-epidemic

Method 2: Install from Source (for development)

git clone https://github.com/miladrezanezhad/sir_simulator.git
cd sir_simulator
pip install -e .

Method 3: Clone only (without installing)

git clone https://github.com/miladrezanezhad/sir_simulator.git
cd sir_simulator
pip install -r requirements.txt

Verify Installation

python -c "import sir_simulator; print('✅ Success!')"

---

🎮 Your First Simulation

1️⃣ Run SIR Model via CLI

sir-simulator --beta 0.5 --gamma 0.2 --tmax 100

Expected output:

🦠 Running SIR Simulation...
Parameters: beta=0.5, gamma=0.2

✅ Simulation complete!
📊 Output shape: (500, 4)

📈 Last 5 rows:
           time  Susceptible   Infected   Recovered
495   99.198397   105.895275    0.003002  894.101723
496   99.398798   105.895244    0.002915  894.101842
...

💾 Saved to: simulation_output.csv

2️⃣ Run Streamlit Dashboard

streamlit run src/sir_simulator/user_interface/app.py

Then open http://localhost:8501 in your browser.

3️⃣ Run Interactive Menu

python main.py

You'll see:

🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠
   SIR EPIDEMIC SIMULATOR
🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠🦠

   MAIN MENU
   ----------------------------------------

   1. Run SIR Model
   2. Run SEIR Model
   3. Run Network Simulation
   4. Parameter Optimization
   5. ML Prediction
   6. Scenario Comparison
   7. Run All Tests
   0. Exit

4️⃣ Run All Tests

python run_all_tests.py

Expected output:

Ran 35 tests in 3.233s
OK

============================================================
✅ Tests Run: 35
✅ Successes: 35
❌ Failures: 0
⚠️ Errors: 0
============================================================

---

📊 Understanding the Output

CLI Output CSV File

The CLI automatically saves results to simulation_output.csv with columns:

Column	Description
time	Time in days
Susceptible	Number of susceptible individuals
Infected	Number of infected individuals
Recovered	Number of recovered individuals

Key Metrics

Metric	Meaning
R₀	Basic reproduction number (beta/gamma)
Peak Infected	Maximum number of infected individuals
Peak Day	Day when peak infection occurs
Final Size	Total number recovered at the end

---

🧪 Try Different Parameters

High Infection Rate (Outbreak)

sir-simulator --beta 0.8 --gamma 0.1 --tmax 100

Low Infection Rate (Contained)

sir-simulator --beta 0.2 --gamma 0.3 --tmax 100

Quick Recovery

sir-simulator --beta 0.5 --gamma 0.5 --tmax 100

Large Population

sir-simulator --beta 0.5 --gamma 0.2 --S0 10000 --I0 100 --tmax 200

---

🐛 Troubleshooting

Problem: ModuleNotFoundError: No module named 'sir_simulator'

Solution: Install the package in development mode:

pip install -e .

Problem: streamlit: command not found

Solution: Install streamlit:

pip install streamlit

Problem: UnicodeEncodeError on Windows

Solution: Update to the latest version (v1.0.1+):

pip install --upgrade sir-epidemic

Problem: Tests failing

Solution: Install all dependencies:

pip install -r requirements.txt

---

📚 Next Steps

Now that you've run your first simulation, explore:

• SIR Model Tutorial - Deep dive into SIR model
• SEIR Model Tutorial - Learn about exposed compartment
• Network Simulation Tutorial - Simulate social network spread
• ML Prediction Tutorial - Use machine learning for forecasting
• FAQ - Common questions and answers

---

🔗 Related Links

• Main README
• Testing Guide
• Security Guide
• PyPI Package

---

⬆ Back to Home