Plug In Custom Scheduler in System-Level Simulation
This example shows how to create a custom scheduling strategy, and drive it using the interfaces offered by the medium access control (MAC) scheduler. The example also shows how to integrate the custom scheduling strategy into the 5G system-level simulation framework and evaluate the network performance.
Scheduler Interface
The scheduler offers a function-based interface that enables the MAC layer to drive the scheduler. The function calls fall in any of the two categories as described below. Each call has a unique role.
Interface to Update Scheduler Context
A set of function calls update the scheduler context. This context contains the information used by the scheduler to make scheduling decisions.
Interface to Run DL and UL Scheduler to Obtain Resource Assignments
These interface calls (to run the DL and UL scheduler) provide the scheduling decisions, which consists of the DL and UL resource assignments.
For a detailed description of the input and output format of these functions, see hNRScheduler.m.
Custom Scheduling Strategy
This section describes the sample scheduling strategy that this example uses.
The scheduling strategy considered in this example is a round-robin strategy, without support for retransmissions. Each UE gets every Nth resource block group (RBG) in the bandwidth, where N is the number of UEs in the cell. UL and DL schedulers assign RBGs to a UE if there is a nonzero buffer amount in the corresponding direction. The hCustomScheduler.m helper class is used to implement this scheduling strategy.
Follow these steps to create and implement this scheduling strategy.
Create Custom Scheduler Class
Create a new class hCustomScheduler
, and inherit it from hNRScheduler.m super class. Implement the constructor of the class to call the super class constructor.
function obj = hCustomScheduler(simParameters)
% Invoke the super class constructor to initialize the properties
obj = obj@hNRScheduler(simParameters);
% Initialize the properties that are specific to this custom scheduling strategy
end
Implement Custom UL Scheduling
Customizing UL scheduling involves overriding the super class functions in hCustomScheduler
to select the UL slots to be scheduled, and to schedule the selected slots.
Override the function selectULSlotsToBeScheduled
with your custom logic to select the slots to be scheduled in the current run.
function slotNum = selectULSlotsToBeScheduled(obj)
% Select the set of slots to be scheduled in this UL scheduler run
end
If you do not override this function, the default slot selection strategy is implemented in the super class (hNRScheduler.m).
Override the scheduleULResourcesSlot
function with your custom logic to schedule the selected slots. If selectULSlotsToBeScheduled
selects multiple slots, then the scheduler engine calls this function for each of the selected slots. One slot is scheduled per call with input parameter slotNum
as the scheduled slot. Your custom logic must output an array of valid UL assignments for the scheduled slot. Each UL assignment is a structure that contains fields to define a physical uplink shared channel (PUSCH) transmission. For a detailed description of the structure fields, see the scheduleULResourcesSlot
function in hNRScheduler.m class.
function uplinkGrants = scheduleULResourcesSlot(obj,slotNum)
% Implement custom UL scheduling to populate the output uplink grants
end
To learn how the UL scheduling is customized by overriding the scheduleULResourcesSlot
as per the described strategy, see hCustomScheduler.m. The custom strategy does not override the selectULSlotsToBeScheduled
function and uses default slot selection strategy in the hNRScheduler.m super class.
Implement Custom DL Scheduling
Follow the steps (similar to UL scheduling) to customize DL scheduling. The process involves overriding the selectDLSlotsToBeScheduled
and scheduleDLResourcesSlot
functions in hCustomScheduler
to select the DL slots to be scheduled, and to schedule the selected slots.
function slotNum = selectDLSlotsToBeScheduled(obj)
% Select the set of slots to be scheduled in this DL scheduler run
end
function downlinkGrants = scheduleDLResourcesSlot(obj,slotNum)
% Implement custom DL scheduling to populate the output downlink grants
end
To learn how the DL scheduling is customized by overriding the scheduleDLResourcesSlot
as per the described strategy, see hCustomScheduler.m. The custom strategy does not override the selectDLSlotsToBeScheduled
function and uses default slot selection strategy in the hNRScheduler.m super class.
Create Custom Scheduler Object
param.NumUEs = 4; % Number of UEs in the cell param.NumRBs = 160; % Number of resource blocks in the bandwidth scheduler = hCustomScheduler(param); % Scheduler object
Drive Custom Scheduler
This section updates the scheduler context and runs the scheduler using scheduler interface.
Run Scheduler (Without Updating Context)
Run the DL and UL schedulers. These calls take information about the current time as an input structure.
% Current system frame number currentTimeInfo.SFN = 0; % Current slot number currentTimeInfo.CurrSlot = 0; % Current symbol number currentTimeInfo.CurrSymbol = 0; % Assign UL resources to UEs for the slot to be scheduled ulResourceAssignments = runULScheduler(scheduler,currentTimeInfo); disp(length(ulResourceAssignments));
0
% Assign DL resources to UEs for the slot to be scheduled
dlResourceAssignments = runDLScheduler(scheduler,currentTimeInfo);
disp(length(dlResourceAssignments));
0
Because the scheduler does not have any information about the UL and DL buffer status, it assumes the buffer status as zero and does not schedule any resource.
Update DL Buffer Status
Run the DL scheduler after updating the DL buffer status of three UEs.
% Update DL buffer status for UE-1 lcBufferStatus.RNTI = 1; lcBufferStatus.LogicalChannelID = 20; lcBufferStatus.BufferStatus = 2000; % In bytes updateLCBufferStatusDL(scheduler,lcBufferStatus); % Update DL buffer status for UE-2 lcBufferStatus.RNTI = 2; lcBufferStatus.LogicalChannelID = 25; lcBufferStatus.BufferStatus = 3000; % In bytes updateLCBufferStatusDL(scheduler,lcBufferStatus); % Update DL buffer status for UE-3 lcBufferStatus.RNTI = 3; lcBufferStatus.LogicalChannelID = 28; lcBufferStatus.BufferStatus = 8000; % In bytes updateLCBufferStatusDL(scheduler,lcBufferStatus); % Run DL scheduler to see the scheduled assignments dlResourceAssignments = runDLScheduler(scheduler,currentTimeInfo); for i = 1:length(dlResourceAssignments) disp(dlResourceAssignments{i}); end
RNTI: 1 Type: 'newTx' RBGAllocationBitmap: [1 0 0 0 1 0 0 0 1 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 PrecodingMatrix: 1 MCS: 9 FeedbackSlotOffset: 2 RV: 0 HARQID: 0 NDI: 1 RNTI: 2 Type: 'newTx' RBGAllocationBitmap: [0 1 0 0 0 1 0 0 0 1] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 PrecodingMatrix: 1 MCS: 9 FeedbackSlotOffset: 2 RV: 0 HARQID: 0 NDI: 1 RNTI: 3 Type: 'newTx' RBGAllocationBitmap: [0 0 1 0 0 0 1 0 0 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 PrecodingMatrix: 1 MCS: 9 FeedbackSlotOffset: 2 RV: 0 HARQID: 0 NDI: 1
UE-4 did not get any resources because the DL buffer status is updated only for UE-1, UE-2, and UE-3.
Update UL Buffer Status
Run the UL scheduler after updating the UL buffer status of all of the UEs. This information comes in the form of a buffer status report (BSR) CE from the UEs.
% Update UL buffer status for UE-1 macCEInfo.RNTI = 1; macCEInfo.LCID = 60; % Long Truncated BSR macCEInfo.Packet = [15;21;88;108]; % BSR packet content priority = [2, 3, 4, 1, 6, 7, 9, 5]; % Priority of each logical channel group (LCG) processMACControlElement(scheduler,macCEInfo,priority); % Update UL buffer status for UE-2 macCEInfo.RNTI = 2; macCEInfo.LCID = 62; % Long BSR macCEInfo.Packet = [53;34;78;101;103]; % BSR packet content processMACControlElement(scheduler,macCEInfo); % Update UL buffer status for UE-3 macCEInfo.RNTI = 3; macCEInfo.LCID = 60; % Long Truncated BSR macCEInfo.Packet = [38;48;55]; % BSR packet content priority = [6, 7, 9, 5, 2, 3, 4, 1]; % Priority of each LCG processMACControlElement(scheduler,macCEInfo,priority); % Update UL buffer status for UE-4 macCEInfo.RNTI = 4; macCEInfo.LCID = 62; % Long BSR macCEInfo.Packet = [65;21;55]; % BSR packet content processMACControlElement(scheduler,macCEInfo); % Run UL scheduler to see the scheduled assignments ulResourceAssignments = runULScheduler(scheduler,currentTimeInfo); for i = 1:length(ulResourceAssignments) disp(ulResourceAssignments{i}); end
RNTI: 1 Type: 'newTx' RBGAllocationBitmap: [1 0 0 0 1 0 0 0 1 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 9 TPMI: 0 RV: 0 HARQID: 0 NDI: 1 RNTI: 2 Type: 'newTx' RBGAllocationBitmap: [0 1 0 0 0 1 0 0 0 1] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 9 TPMI: 0 RV: 0 HARQID: 0 NDI: 1 RNTI: 3 Type: 'newTx' RBGAllocationBitmap: [0 0 1 0 0 0 1 0 0 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 9 TPMI: 0 RV: 0 HARQID: 0 NDI: 1 RNTI: 4 Type: 'newTx' RBGAllocationBitmap: [0 0 0 1 0 0 0 1 0 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 9 TPMI: 0 RV: 0 HARQID: 0 NDI: 1
Update UL Channel Quality
Run the UL scheduler after updating the UL channel quality, and then observe the modulation and coding scheme (MCS) index in the resource assignments.
% Update the UL channel quality for UE-2 channelQualityInfo.RNTI = 2; channelQualityInfo.CQI = 8*ones(1,param.NumRBs); updateChannelQualityUL(scheduler,channelQualityInfo); % Update the UL channel quality for UE-3 channelQualityInfo.RNTI = 3; channelQualityInfo.CQI = 15*ones(1,param.NumRBs); updateChannelQualityUL(scheduler,channelQualityInfo); % Run UL scheduler to see the scheduled assignments ulResourceAssignments = runULScheduler(scheduler,currentTimeInfo); for i = 1:length(ulResourceAssignments) disp(ulResourceAssignments{i}); end
RNTI: 1 Type: 'newTx' RBGAllocationBitmap: [1 0 0 0 1 0 0 0 1 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 9 TPMI: 0 RV: 0 HARQID: 1 NDI: 1 RNTI: 2 Type: 'newTx' RBGAllocationBitmap: [0 1 0 0 0 1 0 0 0 1] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 11 TPMI: 0 RV: 0 HARQID: 1 NDI: 1 RNTI: 3 Type: 'newTx' RBGAllocationBitmap: [0 0 1 0 0 0 1 0 0 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 25 TPMI: 0 RV: 0 HARQID: 1 NDI: 1 RNTI: 4 Type: 'newTx' RBGAllocationBitmap: [0 0 0 1 0 0 0 1 0 0] StartSymbol: 0 NumSymbols: 14 SlotOffset: 1 MappingType: 'A' DMRSLength: 1 NumLayers: 1 NumCDMGroupsWithoutData: 2 NumAntennaPorts: 1 MCS: 9 TPMI: 0 RV: 0 HARQID: 1 NDI: 1
The assignments show that the modulation coding scheme (MCS) of the UL resource assignment to UE-3 is greater than that of UE-2. Similarly, you can observe the effect of channel quality on the MCS for DL resource assignments by using the updateChannelQualityDL
function to update the DL channel quality.
Plug In Scheduler
Plug in the scheduler to 5G Toolbox™ system-level simulation example NR FDD Scheduling Performance Evaluation.
Copy the hCustomScheduler.m file to the example folder.
Create and Install Custom Scheduler
Create a custom scheduler object and install it on the gNB (as described in the "gNB and UEs Setup" section of the NR FDD Scheduling Performance Evaluation example).
scheduler = hCustomScheduler(simParameters);
addScheduler(gNB,scheduler);
% Add scheduler to gNB
Run Example with Custom Scheduler
Run the main script of the simulation example NR FDD Scheduling Performance Evaluation, and then observe the scheduler performance.
The resulting plots show that the throughput and goodput (which accounts for only new transmissions) is the same for all of the UEs because the custom scheduling strategy does not support retransmissions.
References
[1] 3GPP TS 38.321. “NR; Medium Access Control (MAC) protocol specification.” 3rd Generation Partnership Project; Technical Specification Group Radio Access Network.