Introduction - Anuka Hettiarachchi - GSoC2026

[Anuka Hettiarachchi]

Dear all,

I am Anuka Hettiarachchi, a final-year undergraduate student pursuing a BSc. Hons. degree in Computer Science at the Faculty of Science, University of Peradeniya, Sri Lanka.

For GSoC 2026, I am working on the project Integrating 5G NR module with ns-3-ai. The primary objective of this work is to implement a high-performance, zero-serialization bridge between the 5G-LENA NR MAC scheduler and Python-based ML frameworks via the ns-3-ai Message Interface. This implementation aims to minimize communication latency, support rich observation spaces, and enable framework-independent ML integration for radio resource management.

Further details regarding the project scope, objectives, and ongoing progress reports are available on my project WIKI page.

I look forward to collaborating with the community, receiving feedback on my implementation strategy, and contributing effectively to the ns-3 ecosystem.

Best regards,

Anuka Hettiarachchi

[Anuka Hettiarachchi]

Dear all,

As a first Merge Request, I have created MR!387, which lays the groundwork for connecting the 5G NR MAC scheduler to a Python agent through the ns3-ai Message Interface. It contains two related, self-contained pieces. The Observation/Action structs,  and an opt-in RRC change that makes per-bearer uplink buffer information available to those observations. 

1. Observation and Action structs

A new header, defines three plain-old-data structs placed byte-for-byte in shared memory (ns3-ai vector-based interface, one element per UE).

• NrSchedulerObservation (C++ -> Python) - per-UE observation, wide band CQI, historical average throughput, instantaneous achievable throughput, bytes assigned in the previous allocation (feedback), RNTI, and an array of up to 4 per-bearer entries.
• NrSchedulerLcObservation - per-bearer (logical channel) QoS - HOL delay, 5QI delay budget, LC id, 5QI, priority, resource type (non-GBR/GBR/DC-GBR), and buffer size (BSR).
• NrSchedulerAction (Python -> C++) - the agent's per-UE scheduling weight, matched to UE's by RNTI.

Key design decisions:

• Per-UE, not per-flow. The vector length is dynamic, so there is no fixed maximum UE count.
• Only the per-UE bearer list is bounded(MAX_LCS_PER_UE = 4) and the agent emits one weight per UE, since the NR scheduler allocates resources per UE - distributing the transport block among a UE's bearers stays the job of the configured LC algorithm.
• Bearers are reported most-urgent-first , so the agent sees the QoS-relevant bearers even when a UE has more than 4.

The layout is a binary contract with the future pybind11 bindings, so the MR adds a test suite (nr-mac-scheduler-ai-msg-structs-test-suite.cc) verifying every field offset, size,  the overall struct size, and copyability. All fields are fully Doxygen-documented.

2. Opt-in per-bearer UL LCG mapping (nr-gnb-rrc)
On the uplink, only the static QoS fields and the per-LCG Buffer Status Report are meaningful, and the stock LCG mapping lumps all GBR (or all non-GBR) bearers into a single group,  so the BSR cannot report per-bearer buffer sizes. To make the per-bearer UL observations possible, I added a new boolean RRC attribute PerBearerUlLcg.

• When enabled, NrGnbRrc::GetLogicalChannelGroupPerBearer() maps each data radio bearer to its own LCG (1..3, with LCG 0 reserved for SRBs) so the UL BSR carries per-bearer buffer sizes.
• It is opt-in, therefore, the stock GetLogicalChannelGroup() mapping is left untouched, so default behaviour is unchanged for everyone not using the AI scheduler 

I would very much appreciate feedback on the field set, the per-UE design, and the per-bearer LCG approach before I wire these into the scheduler in the next MR.

Regards,
Anuka

[Anuka Hettiarachchi]

Hi all,

Following up on my earlier post and the foundational work in MR !387, I've now opened the second merge request for this GSoC project.

MR !395 - Runtime AI scheduling decisions over the ns3-ai Message Interface

Where MR !387 introduced the shared-memory observation/action structs and the opt-in per-bearer UL LCG support, this MR wires them into the live scheduling loop so a Python agent can actually drive scheduling decisions at runtime. The main additions are:

1. Per-iteration scheduler state callback - a new NotifyCbMsg callback that hands the bridge the active-UE vector, so the agent sees the complete per-UE scheduler state on each assignment iteration.
2. TDMA & OFDMA AI scheduler integration - both variants now expose the message-interface callback via new attributes (NotifyCbDlMsg / NotifyCbUlMsg) and setter methods, keeping the AI path entirely opt-in.
3. Shared-memory environment - NrMacSchedulerAiNs3MsgInterfaceEnv exchanges observations and AI decisions over shared memory, packaging per-UE metrics (CQI, throughput, TB size) and ordering logical channels by urgency.

I'd really appreciate feedback on the callback design and on how the per-UE/per-LC state is laid out for the agent before I move on to the end-to-end example and the training loop.

Regards,
Anuka Hettiarachchi
University of Peradeniya