BFS Programming Tutorial

from collections import deque

def bfs_shortest_path(graph, start, goal):
    """
    Find shortest path using BFS (Breadth-First Search)
    
    Args:
        graph: dict of city connections {city: [neighbors]}
        start: starting city name (string)
        goal: destination city name (string)
        
    Returns:
        list: path from start to goal (shortest in terms of hops)
        None: if no path exists
        
    Time Complexity: O(V + E) where V=vertices, E=edges
    Space Complexity: O(V) for queue and visited set
    """
    # Step 1: Initialize data structures
    queue = deque([start])        # FIFO queue for BFS
    visited = set([start])        # Track visited cities
    parent = {start: None}        # Track parent for path reconstruction
    
    print(f"🚀 Starting BFS from {start} to {goal}")
    print(f"📋 Initial queue: {list(queue)}")
    
    # Step 2: BFS main loop
    while queue:
        # Dequeue: Remove first city from queue (FIFO)
        current = queue.popleft()
        print(f"\n🔍 Processing: {current}")
        print(f"📋 Queue after dequeue: {list(queue)}")
        
        # Step 3: Check if goal reached
        if current == goal:
            print(f"🎯 Goal {goal} found!")
            # Reconstruct path by following parent pointers
            path = []
            temp = current
            while temp is not None:
                path.append(temp)
                temp = parent[temp]
            return path[::-1]  # Reverse to get start→goal order
        
        # Step 4: Explore all neighbors of current city
        neighbors = graph.get(current, [])
        print(f"👀 Exploring neighbors of {current}: {neighbors}")
        
        for neighbor in neighbors:
            if neighbor not in visited:
                # Mark as visited to avoid cycles
                visited.add(neighbor)
                # Set parent for path reconstruction
                parent[neighbor] = current
                # Enqueue: Add to back of queue
                queue.append(neighbor)
                print(f"  ➕ Added {neighbor} to queue (via {current})")
        
        print(f"📋 Queue after exploring {current}: {list(queue)}")
        print(f"✅ Visited cities: {visited}")
    
    print(f"❌ No path found from {start} to {goal}")
    return None  # No path exists

def print_bfs_analysis(graph, start, goal):
    """Run BFS with detailed analysis"""
    print("="*60)
    print("🧠 BFS ALGORITHM ANALYSIS")
    print("="*60)
    
    path = bfs_shortest_path(graph, start, goal)
    
    if path:
        print(f"\n🏆 SUCCESS! Path found: {' → '.join(path)}")
        print(f"📏 Path length: {len(path) - 1} hops")
        print(f"🏙️  Cities in path: {len(path)}")
    else:
        print(f"\n💔 No path exists from {start} to {goal}")

# Our Saudi cities network (same as visual demo)
cities_graph = {
    'Riyadh': ['Qassim', 'Jeddah'],      # Capital city: 2 connections
    'Qassim': ['Riyadh', 'Medina'],      # Central region: 2 connections  
    'Medina': ['Qassim', 'Jeddah'],      # Holy city: 2 connections
    'Jeddah': ['Riyadh', 'Medina', 'Makkah'],  # Port city: 3 connections
    'Makkah': ['Jeddah']                 # Holy city: 1 connection
}

# Example usage
if __name__ == "__main__":
    print_bfs_analysis(cities_graph, 'Riyadh', 'Makkah')
    
    # Try different start/goal combinations
    print("\n" + "="*40)
    print("🔄 TESTING OTHER ROUTES")
    print("="*40)
    
    test_cases = [
        ('Riyadh', 'Medina'),
        ('Qassim', 'Makkah'),  
        ('Medina', 'Riyadh')
    ]
    
    for start, goal in test_cases:
        path = bfs_shortest_path(cities_graph, start, goal)
        result = f"{' → '.join(path)}" if path else "No path"
        print(f"📍 {start} to {goal}: {result}")