Getting Started

Installation

VLCSim can be installed via PyPI or from source.

From Source

For development or the latest features:

$ git clone https://gitlab.com/DaniloBorquez/simvlc.git
$ cd simvlc
$ poetry install  # or pip install -e .

Basic Usage with Default Algorithm

The simplest way to use VLCSim is with the built-in default allocation algorithm. No custom allocation code required!

from vlcsim import Simulator, VLed, RF

# Create simulator (10x10x3m room)
sim = Simulator(10.0, 10.0, 3.0, 20, 0.8)

# Add VLed access point
vled = VLed(5.0, 5.0, 3.0, 2, 2, 20, 60)
vled.sliceTime = 0.2
vled.slicesInFrame = 10
vled.B = 5e4
sim.scenario.addVLed(vled)

# Add RF fallback
rf = RF(5.0, 5.0, 0.85)
rf.sliceTime = 0.2
rf.slicesInFrame = 10
rf.B = 5e4
sim.scenario.addRF(rf)

# Configure traffic parameters
sim.lambdaS = 1      # Arrival rate (Poisson)
sim.mu = 30          # Service rate (Exponential)
sim.goalConnections = 100

# Run simulation (default algorithm used automatically!)
sim.init()
sim.run()

# View results
print(f"Blocking Probability: {sim.get_Blocking_Probability()}")
print(f"Waiting Probability: {sim.get_Waiting_Probability()}")

Understanding the Default Algorithm

The built-in Controller.default_alloc implements a hybrid VLC/RF strategy:

  1. SNR Calculation: Computes Signal-to-Noise Ratio for all VLeds and RFs

  2. VLed Selection: Chooses VLed with best SNR if it has fewer than 5 active connections

  3. RF Fallback: Uses best RF if all VLeds are busy and the RF has fewer than 12 active connections

  4. TDM Allocation: Automatically assigns frame/slice positions

Algorithm Behavior:

  • ✅ Prefers VLC over RF when SNR is better

  • ✅ Load balances by limiting to 5 connections per VLed and 12 per RF

  • ✅ Automatically finds free frame/slice positions

  • ✅ Handles capacity requirements and slice calculations

When the default algorithm works well:

  • General VLC network simulations

  • SNR-based resource allocation research

  • Standard indoor VLC scenarios with hybrid VLC/RF

When you might need a custom algorithm:

  • Testing novel allocation strategies (e.g., fairness-based, QoS-aware)

  • Implementing specific load balancing policies

  • Research on optimization algorithms

Configuring Simulation Parameters

Traffic Parameters

Control connection arrivals and service times:

sim.lambdaS = 3  # Arrival rate (λ) - Poisson process
                 # Mean inter-arrival time = 1/λ seconds

sim.mu = 10      # Service rate (μ) - Exponential distribution
                 # Mean service time = 1/μ seconds

sim.goalConnections = 1000  # Stop after N connections complete

Capacity Requirements

Set the range of bandwidth requirements for connections:

sim.lower_capacity_required = 1e5   # 100 Kbps minimum
sim.upper_capacity_required = 5e5   # 500 Kbps maximum

Random Wait Bounds

Configure retry wait times for unallocated connections:

sim.lower_random_wait = 2    # Minimum 2 seconds before retry
sim.upper_random_wait = 20   # Maximum 20 seconds before retry

Creating a Multi-Room Scenario

Example with 4 VLeds in corners and central RF:

from vlcsim import Simulator, VLed, RF

# 20x20m room, 2.15m height
sim = Simulator(20.0, 20.0, 2.15, 10, 0.8)

# VLeds in four corners
positions = [(-7.5, -7.5), (-7.5, 7.5), (7.5, -7.5), (7.5, 7.5)]

for x, y in positions:
    vled = VLed(x, y, 2.15, 60, 60, 20, 70)
    vled.sliceTime = 0.2
    vled.slicesInFrame = 10
    vled.B = 5e4
    sim.scenario.addVLed(vled)

# Central RF
rf = RF(0, 0, 0.85)
rf.sliceTime = 0.2
rf.slicesInFrame = 10
rf.B = 5e4
sim.scenario.addRF(rf)

# Run simulation
sim.lambdaS = 1
sim.mu = 30
sim.goalConnections = 500
sim.init()
sim.run()

Accessing Results

After running the simulation, you can access various metrics:

# Definitively blocked connections (NOT_ALLOCATED)
bp = sim.get_Blocking_Probability()
print(f"Blocking Probability: {bp:.4f}")

# Connections waiting for a future retry (WAIT)
waiting = sim.get_Waiting_Probability()
print(f"Waiting Probability: {waiting:.4f}")

# Connection counts
attempted = sim.get_Attempted_Connections()
allocated = sim.get_Allocated_Connections()
waiting_connections = sim.get_Waiting_Connections()
blocked = sim.get_Blocked_Connections()
print(f"Attempted Connections: {attempted}")
print(f"Allocated Connections: {allocated}")
print(f"Waiting Connections: {waiting_connections}")
print(f"Blocked Connections: {blocked}")

# Simulation duration
duration = sim.time_duration()
print(f"Simulation time: {duration:.2f} seconds")

# Access point utilization
metrics = sim.aggregated_metrics()
print("AP Utilization:")
for ap_id, utilization in enumerate(metrics):
    print(f"  AP {ap_id}: {utilization:.2%}")

Example Files

VLCSim includes several ready-to-run examples in the examples/ directory:

Basic Example

File: examples/basic_example.py

Minimal workflow demonstrating core simulation features:

  • 4 VLEDs positioned in room corners

  • 1 RF access point in the center

  • Default allocation algorithm

  • 100 simulated connections

  • Basic metrics output (blocking probability, waiting probability, simulation time)

Perfect for learning the fundamental VLCSim workflow.

Advanced Example

File: examples/advanced_example.py

Sophisticated features demonstration:

  • Heterogeneous device configuration (different power levels, bandwidths)

  • Custom SNR-based allocation algorithm

  • 4 VLEDs with 2 RF femtocells

  • 200 connections for statistical significance

  • Per-access-point utilization statistics

Ideal for understanding custom algorithms and advanced configurations.

Interactive Jupyter Notebook

File: examples/vlc_simulation_example.ipynb

Step-by-step interactive tutorial:

  • Detailed explanations for each simulation step

  • Custom allocation algorithm with load balancing (5 connections per VLED)

  • TDM resource allocation demonstration

  • 3 VLEDs + 1 RF fallback configuration

  • Results analysis and troubleshooting notes

Best for hands-on learning in Jupyter or Google Colab environments.

Running Examples

From the repository root:

# Run basic example
$ python examples/basic_example.py

# Run advanced example
$ python examples/advanced_example.py

# Open Jupyter notebook
$ jupyter notebook examples/vlc_simulation_example.ipynb

See examples/README.md for detailed documentation of each example.

Next Steps

  • See Advanced Usage for advanced topics including custom allocation algorithms

  • Explore API Reference for complete API reference

  • Check the example files in examples/ directory for hands-on learning

  • Visit the GitLab repository for more resources