Getting Started

Installation

VLCSim can be installed via PyPI or from source.

Via PyPI (Recommended)

The easiest way to install VLCSim:

$ pip install vlcSim

Or with Poetry:

$ poetry add vlcSim

From Source

For development or the latest features:

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

Paper Evaluation

The comprehensive paper evaluation script lives in paper_evaluation/. Versioned results and their limitations are described in paper_evaluation/README.md. New runs write to the ignored paper_evaluation/output/ directory by default. Install VLCSim from source before running it so the script can import the local package:

$ python -m venv .venv
$ source .venv/bin/activate
$ pip install --upgrade pip
$ pip install -e .

Run computational performance benchmarks sequentially when execution time is the measured response variable:

$ python paper_evaluation/comprehensive_evaluation.py \
    --evaluation performance \
    --replications 30 \
    --master-seed 20260903 \
    --performance-workers 1 \
    --warmup-runs 1

Run the case study with configurable parallelism for network metrics:

$ python paper_evaluation/comprehensive_evaluation.py \
    --evaluation case-study \
    --replications 30 \
    --master-seed 20260903 \
    --case-study-workers auto \
    --warmup-runs 1

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      # Mean inter-arrival time (exponential scale)
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 capacity-based transmission requirements:

sim.lambdaS = 3  # Mean inter-arrival time / exponential scale
                 # Implied Poisson arrival rate = 1/lambdaS

# ``mu`` is deprecated and retained only for compatibility.
# Service completion is capacity/TDM based.

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.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.

Reproducible Replications Example

File: examples/reproducible_replications.py

Small experiment script demonstrating reproducible replication orchestration outside the simulator core:

• Derives deterministic stream seeds from one master seed

• Creates one fresh Simulator per replication

• Writes a detailed CSV with one row per policy and replication

• Writes an aggregated CSV with mean, sample standard deviation, standard error, and 95% confidence interval bounds

• Uses Student t critical values for finite replication counts

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

# Run reproducible replications example
$ python examples/reproducible_replications.py

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