PyWINS 0.1.0

A high-fidelity, AI-ready IEEE 802.11 simulator powered by O(log N) Time-Leaping mechanism for complex MAC layer dynamics.

PyWINS

PyWINS (Python Wireless Network Simulator) is a lightweight, discrete-event-driven simulator designed for analyzing the performance of the IEEE 802.11 MAC layer dynamics.

Unlike traditional time-stepping simulators, PyWINS implements a Time-Leaping mechanism based on a Min-Heap data structure. This allows the system clock to skip idle intervals instantaneously, ensuring high execution efficiency even in large-scale network topologies.

🚀 Key Features

• Time-Leaping Kernel: Powered by a Min-Heap priority queue, the simulator efficiently manages events without the overhead of fixed time-step polling.
• Full CSMA/CA Logic: Implements the complete IEEE 802.11 DCF protocol stack, including Carrier Sensing, Binary Exponential Backoff (BEB), DIFS/SIFS timing, and ACK timeouts.
• Custom Topology Support: Uses an Adjacency Matrix (via listen lists) to define node connectivity. This allows for the precise simulation of complex interference scenarios such as Hidden Terminals and Exposed Terminals.
• Pure Python: Built entirely in Python with minimal dependencies, making it easy to read, modify, and integrate with AI/ML frameworks.

🛠️ Installation

You can install PyWINS via pip:

pip install PyWINS

💻 Quick Start

1. Basic Simulation

Simulate a standard fully-connected network (Single BSS) with 5 nodes.

Python

from pywins import Simulator

# Initialize simulator with 5 nodes
# Default: All nodes can hear each other (Fully Connected)
sim = Simulator(STATIONS=5, total_time=1e6)

# Configure MAC parameters (e.g., 802.11a standard)
sim.update(RATE=54, MAX_RETRY=7, CW_MIN=16)

# Run simulation
drop_rate, ratio, throughput = sim.run()

print(f"Simulation Results:")
print(f"Throughput: {throughput:.2f} Mbps")
print(f"Drop Rate: {drop_rate:.2%}")

2. Hidden Terminal Scenario

Simulate a specific topology where two nodes are "hidden" from each other, causing collisions at the Access Point (AP).

Python

from pywins import Simulator

# Define Topology using Adjacency List (Listen Matrix)
# Node 0 (AP): Can hear Node 1 and Node 2
# Node 1 (STA): Can only hear Node 0 (Blind to Node 2)
# Node 2 (STA): Can only hear Node 0 (Blind to Node 1)
hidden_topology = [[1, 2], [0], [0]]

# Initialize simulator with custom topology
sim = Simulator(STATIONS=3, listen=hidden_topology)

# Reduce retry limit to simulate high-contention pressure
sim.update(RATE=54, MAX_RETRY=4)

# Run simulation
drop_rate, ratio, throughput = sim.run()

print(f"Hidden Terminal Scenario:")
print(f"Throughput: {throughput:.2f} Mbps")
print(f"Drop Rate: {drop_rate:.2%}")

🏗️ Architecture

PyWINS follows a modular Three-Layer Architecture:

1. Core Scheduling Layer: Manages the global event queue and system clock advancement.
2. Network Entity Layer: Handles Node Finite State Machines (FSM) and protocol decision-making.
3. Physical Environment Layer: Manages logical connectivity and interference relationships.

📄 License

This project is licensed under the MIT License.