Simulation Tesbed Plan

Overview

This project has two major deliverables:

(1) a MAC Scheduling Evaluation Testbed written in C
(2) an AI Scheduler trained and evaluated against traditional baselines. This document covers the full plan for Part 1 — the Simulation Testbed, which must be built first since it is the engine that generates training data and validates all scheduler algorithms.

The testbed is not a full LTE network simulator. It is a focused, lightweight environment that accurately models only the MAC/PHY layer components necessary to run and evaluate scheduling decisions — specifically RB allocation, CQI feedback, UE traffic, and LTE frame timing.

Why C, LTE-Sim, and OAI?

C is the correct implementation language for this phase because the topic expects high proficiency in C/C++ for a concurrent, low-latency MAC-layer environment, and our team also wants the project in C.
LTE-Sim is a suitable behavioral reference because the current plan already uses it as a guide for scheduler structure, CQI behavior, and UE/traffic simulation patterns.
OpenAirInterface is a suitable architectural reference because it provides a real eNodeB codebase and helps ground the design in practical LTE Layer 2 and MAC/PHY structure.

Layer 2 coverage

This simulator remains MAC-focused, but it should not ignore Layer 2 behaviors that directly affect scheduler input, decision quality, or performance evaluation.

Layer 2 item	Full implementation?	What your testbed should do
MAC scheduler	Yes	This is the project core, including RR, Max C/I, PF, QoS-aware, and later AI-based scheduling.
MAC queues/buffers	Yes	Model per-UE and per-bearer backlog because scheduling decisions depend on queue state and latency.
Logical channel awareness	Partial	Track traffic class and bearer priority so QoS-aware scheduling has meaningful inputs.
RLC segmentation/reassembly	No, but abstract	Represent its effect through buffer occupancy, packet size evolution, and delay accumulation.
RLC retransmission/ARQ	Optional abstraction	If not implemented, document it as a limitation because it affects delay and throughput realism.
PDCP header/ciphering	No	Safe to abstract out because the topic says upper-layer processing should be simplified.
Control overhead	Partial	Include at least simplified CCE/control constraints because the topic explicitly mentions CCE modeling.
HARQ interaction	Strongly recommended abstraction	Even a simplified HARQ success/failure state improves MAC realism because scheduling and retransmission are tightly related to MAC behavior.
MAC-PHY timing	Yes	Keep TTI/subframe timing, CQI feedback, RB allocation, and frame structure accurate.
FDD/TDD support	Start with FDD, design for TDD later	The topic mentions LTE frame structure in FDD/TDD modes, so FDD-first is fine if your architecture can later extend to TDD.

High-Level Architecture of the Testbed

Before any coding, we need to understand what modules the testbed consists of. Think of it like a clock-driven loop where every 1 millisecond (1 subframe = 1 TTI in LTE), the system wakes up, asks “what is the current state of each UE?”, runs the scheduler, allocates resource blocks, and records results.

Scenario / Config Manager

Cân nhắc nhiều UE, nhiều điều kiện/config khác nhau. This component defines a simulation run before execution starts. It contains settings such as:

Scheduler type
Number of UEs
Channel profile mix
Traffic mix
LTE bandwidth
Duplex mode
Simulation duration
Run identifiers for repeatability Its role is to make experiments reproducible and to ensure that different schedulers are compared under the same conditions.

Simulation Engine

Multithreading or … This is the controller of the whole testbed. It drives the per-TTI loop, coordinates the other components, and enforces the correct order of operations in every scheduling interval. In practice, it:

Advances time
Updates UE-related inputs
Triggers the scheduler
Applies the allocation
Invokes metrics collection

LTE Frame/Subframe Time Manager

Time sync for UE/eNODEB This component keeps the LTE time structure valid during the run.
It tracks the current frame, subframe, and TTI context so that the rest of the simulator operates as an LTE timing system rather than as a generic loop.
The initial implementation should focus on FDD first, because the training material and the current plan already emphasize understanding FDD/TDD frame structure and recommend starting from a manageable subset.

UE Manager / L2 State

This component stores the current state of every active UE relevant to scheduling. That state should include:

UE identity
Traffic class
Buffer occupancy
HOL (Head-of-Line) delay
Scheduling history
Throughput history
Other simplified Layer 2 state variables needed by PF and QoS-aware policies The reason this block is important is that the scheduler does not decide based on CQI alone; it also needs queue pressure, fairness history, and service priority.

Traffic Generator

This component models how packets arrive into UE buffers over time. It should support at least:

Full-buffer traffic
VoIP
Video streaming
Best-effort traffic These traffic types represent different LTE bearer-like behaviors. Its output is demand-oriented state such as:
Packet arrivals
Queue growth
Class-specific traffic pressure per UE

CQI Engine

This component models how radio conditions change over time for each UE.
Its purpose is to produce time-varying CQI values or derived achievable-rate estimates that the scheduler can use to judge how efficiently a UE can use allocated RBs.
The current plan already frames this with slow and fast channel fluctuation behavior and channel profiles such as stationary and mobile UEs, so that should remain part of the revised design.

Scheduler Module

This component is the decision engine of the simulator. It receives:

Demand state from the Traffic Generator
Radio opportunity state from the CQI Engine
Fairness or delay context from the UE/L2 block Then decides how RBs should be assigned in the current TTI. In this phase, the scheduler module should support only the baseline policies:
RR (Round Robin)
Max C/I (Maximum Channel Quality Indicator)
PF (Proportional Fair)
QoS-aware scheduling Note: The AI scheduler (Part 2) will be integrated as an additional pluggable scheduler module. For Part 1, the architecture should include a placeholder for AI scheduler integration (function pointer interface), but no AI model training or implementation is required in this phase.

Resource Block Allocation Grid

This component represents the concrete scheduling result for the current TTI. It maps scheduler decisions into actual RB assignments while respecting:

The selected LTE bandwidth
Simplified resource or control constraints This block is necessary because the scheduler’s abstract priority result must eventually become a measurable RB allocation that can be evaluated.

Metrics Collector, Logger & Exporter

This component converts simulator behavior into observable outputs. It performs three functions:

Metrics Collector: Computes per-TTI and aggregate metrics
Logger: Stores structured logs (CSV format) for debugging or offline inspection
Exporter: Exports machine-readable metric streams in Prometheus format for real-time dashboarding This revised plan treats the exporter as part of the core architecture rather than an optional tool, because readable results are now a formal requirement of the project workflow.

Prometheus (Time-Series Database)

Prometheus acts as the time-series collection layer between the simulator output and the dashboards. Its role is to:

Ingest or scrape exported metrics from the C simulator
Store time-series data efficiently
Make them queryable over time This is much more suitable for repeated scenario comparison than raw log reading. Integration approach:
The C simulator exposes metrics via a Prometheus-compatible HTTP endpoint (e.g., using a lightweight HTTP server library like libmicrohttpd or simply writing metrics to a text file in Prometheus format that can be scraped)
Prometheus scrapes this endpoint at regular intervals (e.g., every 1 second)
Metrics are stored in Prometheus’s time-series database

Grafana Dashboard (Visualization Layer)

Grafana is the UI layer for result exploration and presentation. It should visualize:

Throughput (cell-wide and per-UE) - Fairness (Jain’s Fairness Index over time) - Delay (average packet delay, HOL delay)
CQI distribution across UEs
UE behavior (buffer occupancy, scheduling frequency)
Allocation trends (RB utilization, scheduler decisions) This integration directly addresses the weakness of relying only on CSV or text logs for understanding simulation behavior. Why this is important:
Real-time monitoring during long simulation runs
Immediate feedback during development and debugging
Professional presentation for final project reporting
Comparative analysis across different scheduler runs Grafana queries Prometheus for time-series data and presents it in customizable dashboards with graphs, gauges, and tables.

Key LTE Concepts

Before building anything, the team needs to internalize these concepts (from 3GPP 36.211, 36.212, 36.321):

Concept	What It Is	Why It Matters
Resource Element (RE)	1 subcarrier × 1 OFDM symbol — the smallest unit	Foundation of capacity calculation
Resource Block (RB)	12 subcarriers × 7 OFDM symbols (1 slot = 0.5ms)	The unit the scheduler allocates to UEs
Resource Block Group (RBG)	Group of RBs (size depends on bandwidth)	How the eNodeB actually signals DL allocations
CCE	Control Channel Element — carries DCI (downlink control info)	Needed if model PDCCH overhead
TTI	Transmission Time Interval = 1 subframe = 1ms	One scheduling tick
SFN	System Frame Number (0–1023), each = 10ms	The simulation’s clock reference

In FDD, all 10 subframes per frame are available for DL scheduling (unlike TDD where some are UL). Our testbed will focus on FDD initially.

CQI is a value from 0 to 15 reported by each UE every few milliseconds, telling the eNodeB how good its channel is. A higher CQI means better channel → higher-order modulation (e.g., 64-QAM) → more bits per RB. The testbed must simulate realistic CQI behavior (slow fading + fast fluctuation) per UE.

CQI Value	Modulation	Approximate Bits/RB
1–6	QPSK	Low
7–9	16-QAM	Medium
10–15	64-QAM	High

Phase-by-Phase Implementation Plan

The testbed is built in 5 phases, each producing a testable increment. Never move to the next phase until the current one is validated.

Phase 0 — Study & Environment Setup

This phase is zero-code. Its purpose is to ensure all three team members share the same understanding before touching a keyboard.

Learning tasks:

Read the LTE-Sim paper and browse its source code:
- Focus on src/entity/, src/scheduler/, and src/flows/ directories
- See how UEs, traffic, and schedulers are structured
Browse OAI’s MAC layer at openair2/LAYER2/MAC/:
- Especially schedule_dlsch.c and pre_processor.c
- Understand real scheduler structure
Study 3GPP specifications:
- 36.321 Section 5 (MAC procedures)
- CQI-to-MCS table from 36.213 Table 7.2.3-1
- LTE frame structure from 36.211 Section 4

Tools to set up:

GCC toolchain on Linux (Ubuntu recommended)
Git repository (GitHub/GitLab) — one repo, three branches per person
valgrind for memory checking
make for build system
Prometheus (download and install)
Grafana (download and install, configure Prometheus as data source)

Phase 1 — Core Data Structures & Time Engine

This phase establishes the skeleton of the entire testbed. Every later module depends on the structs defined here.

What to build Remember that the file naming here is a draft to describe the generic structure of the initialization of the project.

lte_config.h: constants for bandwidth, RB count, max UEs, simulation duration, duplex mode, and random seed.
scenario.h: SimulationConfig containing scheduler type, UE count, channel mix, traffic mix, bandwidth, duplex mode, duration, and run ID.
ue.h / ue.c: UE identity, CQI, buffer occupancy, traffic/QCI class, HOL delay, average throughput, last scheduled TTI, and counters for delivered data.
time_context.h: frame/subframe/absolute TTI context for FDD-first execution.
rb_grid.h / rb_grid.c: per-TTI RB ownership plus simple allocation summary data.
scheduler.h: common scheduler API and function pointer typedef for RR, Max C/I, PF, and QoS later.
time_engine.c: loop order should be advance_time -> generate_traffic -> update_cqi -> run_scheduler -> apply_allocation -> collect_metrics -> export/log.
lte_config.h — A single header defining system-wide constants: number of RBs (based on bandwidth), TTIs per simulation, number of UEs, etc.

Phase 2 — CQI Engine & Traffic Generator

This phase makes the simulation dynamic — UEs are no longer static, they fluctuate in channel quality and generate packets.

CQI Engine CQI must change realistically each TTI. The standard model used in LTE simulators (and in LTE-Sim) combines:

Slow fading (changes over hundreds of ms — models UE moving through the cell)
Fast fading (changes every few ms — models multipath interference)

A simplified but acceptable model for this project is a Markov chain or autoregressive model where CQI[t] = clip(CQI[t-1] + noise, 1, 15). LTE-Sim’s channel model in src/channel/ is a reference for this. Remember that this is how the simulator generates time-varying radio conditions so the scheduler has realistic input, not the actual AI scheduling model.

The testbed should support at least two UE channel profiles:

STATIONARY — CQI fluctuates mildly around a high value (good channel, near base station)
MOBILE — CQI swings widely (UE at cell edge or moving fast)

Traffic Generator Model three traffic types (matching real-world LTE bearers):

Traffic Type	Model	Packet Size	Arrival Rate	QCI Class
Full Buffer	Always full buffer	N/A	Constant	Best Effort
VoIP	CBR (Constant Bit Rate)	~40 bytes	50 pkt/s	QCI 1 (real-time)
Video Streaming	Variable Bit Rate	500–1500 bytes	Bursty	QCI 4
Best Effort Data	Poisson arrivals	500 bytes	Variable	QCI 9

Each UE is assigned one traffic type. The generator adds packets to the UE’s buffer each TTI based on the model.

Validation

Plot CQI over time for 5 UEs
Verify stationary UEs stay high, mobile UEs swing
Plot buffer occupancy over time for VoIP UE vs. Best Effort UE Deliverable
CQI engine with STATIONARY and MOBILE profiles
Traffic generator supporting all four traffic types
Validation plots (CQI traces, buffer occupancy)

Phase 3 — Baseline Schedulers

This is the most intellectually critical phase. Each scheduler must be implemented as a separate C function with the same interface signature, allowing the time engine to call any of them interchangeably via a function pointer.

Scheduler Algorithms

Round Robin (RR): Round Robin is the simplest baseline scheduler and mainly serves as a fairness reference in the simulator. It keeps track of the last UE that was served and, in each TTI, assigns RBs one by one to the next UE in sequence, wrapping back to the beginning when necessary. Because it does not consider CQI, queue pressure, or packet delay, it usually shares resources evenly across users but often delivers lower total throughput when channel conditions differ significantly among UEs.
Maximum Carrier-to-Interference Ratio (Max C/I): Max C/I is the throughput-oriented baseline and always prioritizes UEs with the best instantaneous channel quality. At each TTI, it ranks users by current CQI and allocates RBs to the highest-ranked UEs first, which allows the system to exploit favorable radio conditions as aggressively as possible. Its priority rule can be written as $p r i or i t y (i) = CQ I (i)$ making it simple and efficient, but it is also highly unfair because users in poor channel conditions may receive very little service.
Proportional Fair (PF): Proportional Fair is the most important conventional baseline because it balances throughput and fairness instead of optimizing only one of them. In each TTI, it compares a UE’s current achievable rate with its historical average throughput, so a user that has been underserved in recent TTIs can gain priority even if its channel is not currently the strongest. Its priority is defined as $p r i or i t y (i) = \frac{R _{i} ( t )}{T ˉ _{i} ( t )}$ where $R_{i} (t)$ is the instantaneous achievable rate derived from CQI and $\overset{ˉ}{T}_{i} (t)$ is the exponentially weighted moving average throughput of UE $i$ .
QoS-Aware Scheduler: The QoS-aware scheduler extends PF by incorporating delay sensitivity so that latency-critical traffic such as VoIP and real-time video is less likely to be starved. In addition to instantaneous rate and historical throughput, it considers Head-of-Line (HOL) delay, meaning that UEs with packets waiting too long in the buffer receive extra urgency in the scheduling decision.

Validation: Run each scheduler for 1000 TTIs with 10 UEs (mix of STATIONARY and MOBILE). Plot:

Total cell throughput per TTI (line chart)
Per-UE throughput (bar chart — check fairness for RR vs Max C/I vs PF)
Average packet delay per traffic type Expected results:
RR: Equal per-UE throughput, lower total throughput
Max C/I: Highest total throughput, highly unfair
PF: Balanced throughput and fairness
QoS: Low delay for VoIP/video

Phase 4 — Metrics Collection, Output System & Prometheus Integration

The metrics system is what transforms the simulation from a “black box” into a data-generation engine for the AI. It must log every TTI’s state precisely.

Metrics to collect per TTI

Metric	Description	Relevance
Cell Throughput	Total bits delivered across all UEs / TTI	Primary optimization target
Per-UE Throughput	Bits delivered to UE iii / TTI	Fairness analysis
Packet Delay	Time from packet arrival to delivery, per UE	Latency target
RB Utilization	% of RBs assigned vs. total available	Efficiency
HOL Delay	Age of oldest packet in each UE’s buffer	QoS metric / AI state input
CQI per UE	Current CQI of each UE	AI state input
Fairness Index	Jain’s Fairness Index	Comparative analysis

Output Format The C simulation produces two output streams:

CSV Log File (Offline Analysis). Each row = one TTI’s full system state. This CSV is read by Python for:
- Visualization (matplotlib charts for the report)
- AI training data (state/action/reward tuples for Part 2) Example CSV structure:

tti,scheduler,cell_throughput,ue_1_throughput,ue_1_cqi,ue_1_buffer,...
0,PF,15000000,2500000,12,8000,...
1,PF,14800000,2450000,11,7200,...

Prometheus Metrics Export (Real-time Monitoring). The simulator exposes metrics in Prometheus text format via one of two methods:
- Option A: HTTP Endpoint (Recommended) - Use a lightweight HTTP server library (e.g., libmicrohttpd) - Expose metrics at http:/localhost:9090/metrics - Prometheus scrapes this endpoint every 1 second.
- Option B: File-based Export (Simpler) - Write metrics to a text file in Prometheus format - Use Prometheus’s node_exporter textfile collector - Prometheus reads the file periodically.

Grafana Dashboard Setup

Add Prometheus as Data Source:
Create Dashboard with Panels (theoretically):
- Cell Throughput: Line chart of lte_cell_throughput_bps over time
- Per-UE Throughput: Multi-line chart of lte_ue_throughput_bps (one line per UE)
- CQI Distribution: Heatmap or multi-line of lte_ue_cqi
- Buffer Occupancy: Stacked area chart of lte_ue_buffer_bytes
- RB Utilization: Gauge showing lte_rb_utilization_percent
- Fairness Index: Line chart of lte_fairness_index
- Packet Delay: Histogram of lte_packet_delay_ms
Save and Export: Save dashboard as JSON for reproducibility. Include in project repository.

Phase 5 — Scenario Manager & Validation

The final testbed phase wraps everything into a configurable simulation runner.

Scenario Manager A scenario is defined by a config file (plain text or simple struct) that specifies:

Number of UEs
UE channel profiles (stationary / mobile mix)
Traffic types per UE
LTE bandwidth (thus number of RBs)
Simulation duration (number of TTIs)
Scheduler to use This allows running reproducible experiments — critical for fair comparison between schedulers and the AI.

Pre-defined Scenarios to Implement:

Scenario	UEs	Channel Mix	Traffic Mix	Purpose
S1: Baseline Low Load	5	All stationary	Full buffer	Sanity check
S2: Mixed Channel	10	5 stationary, 5 mobile	Full buffer	Fairness test
S3: QoS Stress	10	Mixed	3 VoIP + 3 Video + 4 BE	QoS scheduler test
S4: High Load	20	Mixed	Mixed	Throughput ceiling test
S5: AI Training	20	Random each run	Random	Data generation for Part 2

Final Validation Checklist:

All four schedulers produce correct results on S1–S4
CSV output format is consistent and parseable by Python
Prometheus metrics are exported correctly
Grafana dashboard displays all metrics accurately
Memory is clean (no leaks per valgrind)
Build is reproducible via make on a clean machine
Git history is clean with meaningful commit messages per module
Documentation is complete (README, architecture diagram, build instructions)

AI Scheduler Interface Preparation (Bridge to Part 2)

(Not yet)

Team Division of Responsibility

Member	Primary Ownership
Member 1	CQI Engine + Traffic Generator (Phase 2) + Metrics (Phase 4)
Member 2	Baseline Schedulers - RR, Max C/I (Phase 3, first half) + AI Scheduler Interface (Phase 6).
Member 3	Baseline Schedulers - PF, QoS (Phase 3, second half) + Scenario Manager (Phase 5)
All 3	Phase 0 study, Phase 1 core structs (joint work), final integration

Đơn giản hóa phase 2
Chia đều Scheduler ra cho cả 3 lẫn metrics đánh giá cho các bộ scheduler khác nhau.

Quartz 4

Explorer