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.
License: MIT License
Requires Python: >=3.8
Keywords: network-simulator, ieee-802-11, wifi, csma-ca, time-leaping, discrete-event-simulation, hidden-terminal, congestion-control, scientific-research

# 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:

```bash
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.