# 🪟 Dynamic Traffic Signal Optimization - Windows Setup Guide

## Complete Step-by-Step Installation and Setup Guide for Windows

This guide provides detailed instructions for setting up the Dynamic Traffic Signal Optimization project on Windows systems.

---

## 📋 **Table of Contents**

1. [Prerequisites](#prerequisites)
2. [System Requirements](#system-requirements)
3. [Step 1: Install Python](#step-1-install-python)
4. [Step 2: Install Git](#step-2-install-git)
5. [Step 3: Install SUMO Traffic Simulator](#step-3-install-sumo-traffic-simulator)
6. [Step 4: Clone and Setup Project](#step-4-clone-and-setup-project)
7. [Step 5: Create Virtual Environment](#step-5-create-virtual-environment)
8. [Step 6: Install Dependencies](#step-6-install-dependencies)
9. [Step 7: Configure Environment Variables](#step-7-configure-environment-variables)
10. [Step 8: Verify Installation](#step-8-verify-installation)
11. [Step 9: Run the Project](#step-9-run-the-project)
12. [Troubleshooting](#troubleshooting)
13. [GPU Setup (Optional)](#gpu-setup-optional)

---

## 🔧 **Prerequisites**

- Windows 10 or Windows 11 (64-bit)
- Administrator access to install software
- At least 8GB RAM (16GB recommended)
- 10GB free disk space
- Internet connection for downloads

---

## 💻 **System Requirements**

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| OS | Windows 10 64-bit | Windows 11 64-bit |
| RAM | 8GB | 16GB+ |
| Storage | 10GB free | 20GB+ free |
| GPU | Not required | NVIDIA GPU (for acceleration) |
| Python | 3.8+ | 3.10+ |

---

## 🐍 **Step 1: Install Python**

### Method 1: Download from Python.org (Recommended)

1. **Download Python**:
   - Go to [https://www.python.org/downloads/](https://www.python.org/downloads/)
   - Click "Download Python 3.11.x" (latest stable version)
   - Download the Windows installer (.exe file)

2. **Install Python**:
   - Run the downloaded installer as Administrator
   - ⚠️ **IMPORTANT**: Check "Add Python to PATH" at the bottom
   - Click "Install Now"
   - Wait for installation to complete
   - Click "Close"

3. **Verify Installation**:
   ```cmd
   # Open Command Prompt (cmd) and run:
   python --version
   pip --version
   ```

### Method 2: Microsoft Store (Alternative)

1. Open Microsoft Store
2. Search for "Python 3.11"
3. Install the official Python version

---

## 🔧 **Step 2: Install Git**

1. **Download Git**:
   - Go to [https://git-scm.com/download/win](https://git-scm.com/download/win)
   - Download the 64-bit Git for Windows Setup

2. **Install Git**:
   - Run the installer as Administrator
   - Use default settings (click "Next" through all options)
   - Complete the installation

3. **Verify Installation**:
   ```cmd
   git --version
   ```

---

## 🚦 **Step 3: Install SUMO Traffic Simulator**

### Download and Install SUMO

1. **Download SUMO**:
   - Go to [https://eclipse.org/sumo/](https://eclipse.org/sumo/)
   - Click on "Download" in the top menu
   - Download the Windows installer (sumo-win64-x.x.x.msi)

2. **Install SUMO**:
   - Run the downloaded MSI file as Administrator
   - Follow the installation wizard
   - Choose installation directory (default: `C:\Program Files (x86)\Eclipse\Sumo`)
   - Complete the installation

3. **Add SUMO to PATH**:
   - Right-click "This PC" → Properties
   - Click "Advanced system settings"
   - Click "Environment Variables"
   - Under "System Variables", find and select "Path"
   - Click "Edit" → "New"
   - Add: `C:\Program Files (x86)\Eclipse\Sumo\bin`
   - Click "OK" to close all dialogs

4. **Set SUMO_HOME Environment Variable**:
   - In Environment Variables window (still open)
   - Under "System Variables", click "New"
   - Variable name: `SUMO_HOME`
   - Variable value: `C:\Program Files (x86)\Eclipse\Sumo`
   - Click "OK"

5. **Verify SUMO Installation**:
   ```cmd
   # Close and reopen Command Prompt, then run:
   sumo --version
   ```

---

## 📁 **Step 4: Clone and Setup Project**

1. **Create Project Directory**:
   ```cmd
   # Open Command Prompt and navigate to desired location
   cd C:\
   mkdir Projects
   cd Projects
   ```

2. **Clone Repository**:
   ```cmd
   git clone https://git.kronos-nexus.com/giteaAdmin/DTSO-Mtech_2025
   cd DTSO-Mtech_2025
   ```

3. **Create Directory Structure**:
   ```cmd
   # Create all necessary directories
   mkdir src\environment src\agents src\training src\evaluation src\utils
   mkdir config sumo_configs models\checkpoints
   mkdir data\raw data\processed logs\tensorboard
   mkdir results\plots results\analysis scripts notebooks tests
   ```

---

## 🐍 **Step 5: Create Virtual Environment**

1. **Create Virtual Environment**:
   ```cmd
   # In the project directory
   python -m venv venv
   ```

2. **Activate Virtual Environment**:
   ```cmd
   # Activate the environment (Windows Command Prompt)
   venv\Scripts\activate

   # For PowerShell users:
   venv\Scripts\Activate.ps1
   ```

3. **Verify Activation**:
   - You should see `(venv)` at the beginning of your command prompt

---

## 📦 **Step 6: Install Dependencies**

1. **Create requirements.txt**:
   ```cmd
   # Create file with necessary dependencies
   echo torch>=1.9.0 > requirements.txt
   echo torchvision>=0.10.0 >> requirements.txt
   echo numpy>=1.21.0 >> requirements.txt
   echo pandas>=1.3.0 >> requirements.txt
   echo matplotlib>=3.4.0 >> requirements.txt
   echo seaborn>=0.11.0 >> requirements.txt
   echo opencv-python>=4.5.0 >> requirements.txt
   echo gym>=0.18.0 >> requirements.txt
   echo traci>=1.10.0 >> requirements.txt
   echo sumolib>=1.10.0 >> requirements.txt
   echo scikit-learn>=0.24.0 >> requirements.txt
   echo tensorboard>=2.6.0 >> requirements.txt
   echo tqdm>=4.62.0 >> requirements.txt
   echo PyYAML>=5.4.0 >> requirements.txt
   echo imageio>=2.9.0 >> requirements.txt
   echo pillow>=8.3.0 >> requirements.txt
   ```

2. **Install Dependencies**:
   ```cmd
   # Make sure virtual environment is activated
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

3. **Wait for Installation**:
   - This may take 10-15 minutes depending on your internet speed
   - PyTorch is a large package (~800MB)

---

## 🔧 **Step 7: Configure Environment Variables**

1. **Verify Environment Variables**:
   ```cmd
   echo %SUMO_HOME%
   echo %PATH%
   ```

2. **Test SUMO from Python**:
   ```cmd
   python -c "import traci; print('TraCI imported successfully')"
   python -c "import sumolib; print('SUMO library imported successfully')"
   ```

---

## ✅ **Step 8: Verify Installation**

1. **Create and Run Setup Script**:
   ```cmd
   # Create setup verification script
   python scripts/setup_project.py
   ```

2. **Test Basic Functionality**:
   ```cmd
   # Test Python packages
   python -c "import torch; print('PyTorch version:', torch.__version__)"
   python -c "import numpy; print('NumPy version:', numpy.__version__)"
   python -c "import pandas; print('Pandas version:', pandas.__version__)"
   ```

3. **Test SUMO Integration**:
   ```cmd
   # Test SUMO command line
   sumo --help
   
   # Test SUMO with GUI (optional)
   sumo-gui
   ```

---

## 🚀 **Step 9: Run the Project**

### 9.1 Basic Training

```cmd
# Make sure you're in the project directory with activated virtual environment
cd C:\Projects\DTSO-Mtech_2025
venv\Scripts\activate

# Run basic training
python main.py --mode train
```

### 9.2 Test Trained Model

```cmd
# Test with pre-trained model
python main.py --mode test --model models/final_model.pth --episodes 5
```

### 9.3 Monitor Training Progress

```cmd
# In a separate command prompt, start TensorBoard
venv\Scripts\activate
tensorboard --logdir logs/tensorboard

# Open browser and go to: http://localhost:6006
```

---

## 🔧 **Troubleshooting**

### Common Issues and Solutions

#### 1. **Python not found**
```cmd
# Error: 'python' is not recognized
# Solution: Add Python to PATH or use:
py --version
```

#### 2. **SUMO not found**
```cmd
# Error: 'sumo' is not recognized
# Solution: Check PATH and SUMO_HOME environment variables
set PATH=%PATH%;C:\Program Files (x86)\Eclipse\Sumo\bin
set SUMO_HOME=C:\Program Files (x86)\Eclipse\Sumo
```

#### 3. **Permission Issues**
```cmd
# Run Command Prompt as Administrator
# Right-click Command Prompt → "Run as administrator"
```

#### 4. **Virtual Environment Issues**
```cmd
# If activation fails, try:
python -m venv --clear venv
venv\Scripts\activate
```

#### 5. **Package Installation Errors**
```cmd
# If pip install fails, try:
pip install --upgrade pip setuptools wheel
pip install --no-cache-dir -r requirements.txt
```

#### 6. **SUMO GUI Issues**
```cmd
# If SUMO GUI doesn't work, check if you have:
# - Visual C++ Redistributable installed
# - Updated graphics drivers
```

#### 7. **Memory Issues**
```cmd
# If training crashes due to memory:
# Edit config/config.yaml and reduce:
# - batch_size: 32 (instead of 64)
# - memory_size: 50000 (instead of 100000)
```

### Windows-Specific Commands

```cmd
# Check system information
systeminfo

# Check available disk space
dir C:\

# Check running processes
tasklist | findstr python

# Kill Python processes if needed
taskkill /f /im python.exe
```

---

## 🎮 **GPU Setup (Optional)**

### NVIDIA GPU Setup

1. **Check GPU Compatibility**:
   ```cmd
   # Check if you have NVIDIA GPU
   nvidia-smi
   ```

2. **Install CUDA Toolkit**:
   - Download from [NVIDIA CUDA Toolkit](https://developer.nvidia.com/cuda-downloads)
   - Install CUDA 11.8 or 12.x
   - Restart computer after installation

3. **Verify GPU Support**:
   ```cmd
   python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
   python -c "import torch; print('GPU count:', torch.cuda.device_count())"
   ```

4. **Run with GPU**:
   ```cmd
   python main.py --mode train --gpu
   ```

---

## 📊 **Performance Monitoring**

### System Monitoring During Training

1. **Task Manager**:
   - Press `Ctrl + Shift + Esc`
   - Monitor CPU, RAM, and GPU usage

2. **Command Line Monitoring**:
   ```cmd
   # Monitor GPU usage (if NVIDIA)
   nvidia-smi -l 5

   # Monitor system resources
   wmic cpu get loadpercentage /value
   ```

---

## 🔄 **Project Management**

### Regular Maintenance

```cmd
# Update packages
pip list --outdated
pip install --upgrade package_name

# Clean cache
pip cache purge

# Backup important files
xcopy models\ backup\models\ /E /I
xcopy results\ backup\results\ /E /I
```

### Development Workflow

```cmd
# Daily development routine
cd C:\Projects\DTSO-Mtech_2025
venv\Scripts\activate
git pull origin main
python main.py --mode train
```

---

## 📝 **Notes for Windows Users**

1. **File Paths**: Use backslashes (`\`) or forward slashes (`/`) in paths
2. **Command Prompt vs PowerShell**: Both work, but commands may differ slightly
3. **Antivirus**: Add project folder to antivirus exclusions for better performance
4. **Windows Defender**: May slow down file operations; consider temporary exclusion
5. **Updates**: Keep Windows, Python, and SUMO updated for best performance

---

## 📞 **Support and Resources**

### Getting Help

- **Project Issues**: Check GitHub Issues or create new issue
- **SUMO Help**: [SUMO Documentation](https://sumo.dlr.de/docs/)
- **Python Help**: [Python.org Documentation](https://docs.python.org/)
- **PyTorch Help**: [PyTorch Documentation](https://pytorch.org/docs/)

### Useful Links

- [SUMO Windows Installation](https://sumo.dlr.de/docs/Installing/Windows_Build.html)
- [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html)
- [Git for Windows](https://gitforwindows.org/)
- [Visual Studio Code](https://code.visualstudio.com/) (Recommended IDE)

---

## ✅ **Final Checklist**

Before starting development, ensure:

- [ ] Python 3.8+ installed and in PATH
- [ ] Git installed and configured
- [ ] SUMO installed with GUI working
- [ ] Environment variables set (SUMO_HOME, PATH)
- [ ] Virtual environment created and activated
- [ ] All dependencies installed successfully
- [ ] Basic functionality tests passing
- [ ] Project structure created
- [ ] Configuration files in place

---

**🎉 Congratulations! Your Windows development environment is ready!**

You can now proceed with training your traffic signal optimization model. Start with:

```cmd
python main.py --mode train --episodes 100
```

For any issues, refer to the troubleshooting section or check the main README.md file.