Main Content

NR PUSCH FDD Scheduling

This example evaluates the throughput and resource share fairness performance of an uplink (UL) scheduling strategy in frequency division duplexing (FDD) mode with radio link control (RLC) layer integrated. The UL scheduling strategy assigns the physical uplink shared channel resources (PUSCH) resources to a set of user equipments (UEs) connected to a gNB. The example uses unacknowledged mode (UM) of RLC layer and a passthrough physical (PHY) layer. The passthrough PHY layer does not involve any physical layer processing and adopts a probability-based approach to model packet reception failures. The example logs the events in the simulation and also shows the run time visualizations to observe the network performance.

Introduction

This example shows how a scheduling strategy (controlled by the gNB) assigns UL resources among the UEs. The example considers the following operations within the gNB and UEs that facilitate UL transmissions and receptions.

The complete PUSCH packet is transmitted in the first symbol of its allocated symbol set. Receiver processes the packet in the symbol just after the last symbol in the allocated symbol set.

The scheduler runs every p slots to assign the UL resources, where p is the configured periodicity of the scheduler. In each run, the number of slots scheduled is equal to the periodicity of scheduler run, p. The first slot, among the p slots to be scheduled in a run, is the next upcoming slot which satisfies the PUSCH preparation time capability of UEs. For example, the figure shows the way scheduler selects the slots during two consecutive runs. It assumes scheduler periodicity (p) of 3 slots. Hence, the scheduler runs after every 3 slots, and schedules resources for 3 slots. PUSCH preparation time capability for all the UEs is assumed as greater than 1 slot (14 symbols) but less than 2 slots (28 symbols).

  • Run-1: When scheduler runs at the start of Slot-A, it schedules 3 slots starting from Slot-C, because for Slot-A and Slot-B the UEs do not get enough PUSCH preparation time (UEs gets a time of 0 symbols at start of Slot-A and 14 symbols at start of Slot-B). For Slot-C, UEs get 28 symbols for PUSCH preparation and this satisfies the PUSCH preparation time capability. Hence, Slot-C, D, and E are scheduled in this run.

  • Run-2: When scheduler runs at the start of Slot-D, it schedules the next 3 contiguous slots starting from Slot-F (Slot-F, G, and H).

You can choose any one of the implemented scheduling strategies: proportional fair (PF), best CQI, or round robin (RR). The various supported inputs to the UL scheduler are listed along with the scheduling strategies that consider them.

The two control packets, the buffer status report (BSR) and UL assignment, are assumed to be sent out of band without the need of resources for transmission.

Demodulation reference signal (DM-RS) is not modeled in this example. However, one symbol is kept unused for it in the PUSCH assignments.

This example models:

  • Slot-based and symbol-based UL scheduling. UL scheduler ensures that the UEs get the required PUSCH preparation time.

  • Noncontiguous allocation of frequency-domain resources in terms of resource block groups (RBGs).

  • Configurable subcarrier spacing resulting in different slot durations.

  • Asynchronous UL hybrid automatic repeat request (HARQ) mechanism.

  • UL reception success or failure detection by UEs using new data indicator (NDI) flag present in UL assignment.

  • Multiple logical channels to support different application traffic patterns.

  • Logical channel prioritization (LCP) at UE to distribute the received UL assignment among logical channels.

  • Periodic UL application traffic pattern.

  • RLC operating in UM mode.

Scenario Configuration

For the simulation, set these key configuration parameters:

  • Simulation time

  • Number of UEs

  • Distance of UEs from gNB (affects the UL CQI values for UEs)

  • Application traffic pattern at UEs to generate traffic

  • RLC configuration for Tx and Rx entities at UEs and gNB respectively

  • Logical channel configuration of UEs and gNB

  • Scheduling strategy: PF, Best CQI, RR

  • Periodicity of BSRs sent by UEs to inform gNB about pending buffer amount

  • PUSCH preparation time for UEs

  • PUSCH bandwidth in terms of number of resource blocks (RBs)

  • Subcarrier spacing

  • RBG size configuration type

  • Initial UL channel quality and its update mechanism

rng('default'); % Reset the random number generator
simParameters = []; % Clear the simulation parameters
simParameters.NumFramesSim = 200; % Simulation time in terms of number of 10 ms frames
simParameters.SchedulingType = 0; % Set the value to 0 (slot-based scheduling) or 1 (symbol-based scheduling)

Specify the number of UEs in the cell, assuming that UEs have sequential radio network temporary identifiers (RNTIs) from 1 to simParameters.NumUEs. If you change the number of UEs, ensure that the number of rows in simParameters.UEPosition parameter equals to the value of simParameters.NumUEs; and appDataRate, simParameters.RLCConfig, and simParameters.LCHConfig consists of number of rows equal to simParameters.NumUEs.

simParameters.NumUEs = 4;
% Assign position to the UEs assuming that the gNB is at (0, 0, 0). N-by-3
% matrix where 'N' is the number of UEs. Each row has (x, y, z) position of
% a UE (in meters)
simParameters.UEPosition = [100 0 0;
                            250 0 0;
                            700 0 0;
                            750 0 0];
% Validate the UE positions
validateattributes(simParameters.UEPosition, {'numeric'}, {'nonempty', 'real', 'nrows', simParameters.NumUEs, 'ncols', 3, 'finite'}, 'simParameters.UEPosition', 'UEPosition');

Number of logical channels in each UE. If you change the number of logical channels, ensure that the simulation appDataRate, simParameters.RLCConfig, and simParameters.LCHConfig consists of number of columns equal to simParameters.NumLogicalChannels. The logical channels associated to data radio bearers use logical channel identifiers (LCIDs) starting from 4. So, the logical channels are assumed to have LCIDs starting from 4 to simParameters.NumLogicalChannels+3.

simParameters.NumLogicalChannels = 3;

Set the application traffic pattern for UEs. The N-by-P matrix represents the application data generated by the UE in each logical channel, where 'N' represents the number of UEs and 'P' represents the number of logical channels. A matrix element at position (i, j) represents data rate in kilo bits per second (kbps) generated by UE with RNTI 'i' for LCID 'j+3'. For example, the value 3200 at index (3, 1) represents a application datarate of 3200 kbps is generated by UE-3 for LCID 4

appDataRate = [800 1200 1600;
    200 3200 3200;
    3200 1600 800;
    800 4000 3200]; % Application data rate in kbps
% Validate the application data rate
validateattributes(appDataRate, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels, 'finite', '>', 0}, 'appDataRate', 'AppDataRate');

Set the RLC configuration. Each property of simParameters.RLCConfig must be an N-by-P matrix, where 'N' represents the number of UEs and 'P' represents the number of logical channels. A matrix element at position (i, j) corresponds to a property value of a UE with RNTI 'i' and LCID 'j+3'.

% Sequence number (SN) field length (in bits) to be used by each UE for their logical channels
simParameters.RLCConfig.SNFieldLength = [6 6 12;
    6 6 12;
    6 12 6;
    6 6 12];
% Reassembly timer to be used by each UE for their logical channels
simParameters.RLCConfig.ReassemblyTimer = [5 10 15;
    5  5 10;
    5  5  5;
    5 10 15];
% Max number of service data units (SDUs) in the Tx buffer of each logical channel (to model Tx buffer overflow)
simParameters.RLCConfig.MaxTxBufferSDUs = [4 3 11;
    3 5 4;
    6 1 3;
    11 6 26];

% Validate the RLC configuration
validateattributes(simParameters.RLCConfig.SNFieldLength, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels}, 'simParameters.RLCConfig.SNFieldLength', 'SNFieldLength');
validateattributes(simParameters.RLCConfig.ReassemblyTimer, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels}, 'simParameters.RLCConfig.ReassemblyTimer', 'ReassemblyTimer');
validateattributes(simParameters.RLCConfig.MaxTxBufferSDUs, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels, 'finite', '>', 0}, 'simParameters.RLCConfig.MaxTxBufferSDUs', 'MaxTxBufferSDUs');

Logical channel (LCH) configuration. Each property of simParameters.LCHConfig must be an N-by-P matrix, where 'N' represents the number of UEs and 'P' represents the number of logical channels. A matrix element at position (i, j) corresponds to a property value of a UE with RNTI 'i' and LCID 'j+3'.

% Mapping between logical channel and logical channel group (LCG) ID
simParameters.LCHConfig.LCGID = [1 3 2;
    1 2 2;
    1 2 3;
    5 1 2];
% Priority of each logical channel
simParameters.LCHConfig.Priority = [1 5 8;
    1 1 6;
    4 10 4;
    10 11 13];
% Prioritized bit rate (PBR) of each logical channel (in kilo bytes per second)
simParameters.LCHConfig.PBR = [8 16 32;
    8 128 32;
    8 16 32;
    8 16 32];
% Bucket size duration (BSD) of each logical channel (in ms)
simParameters.LCHConfig.BSD = [5 10 50;
    5 20 20;
    5 5 5;
    5 10 20];

% Validate the logical channel configuration
validateattributes(simParameters.LCHConfig.LCGID, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels, '>=', 0, '<=', 7}, 'simParameters.LCHConfig.LCGID', 'LCGID');
validateattributes(simParameters.LCHConfig.Priority, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels, '>=', 1, '<=', 16}, 'simParameters.LCHConfig.Priority', 'Priority');
validateattributes(simParameters.LCHConfig.PBR, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels}, 'simParameters.LCHConfig.PBR', 'PBR');
validateattributes(simParameters.LCHConfig.BSD, {'numeric'}, {'nonempty', 'integer', 'nrows', simParameters.NumUEs, 'ncols', simParameters.NumLogicalChannels}, 'simParameters.LCHConfig.BSD', 'BSD');

Medium access control (MAC) configuration.

% Set the scheduler run periodicity in terms of number of slots. Value must be
% less than the number of slots in a 10 ms frame
simParameters.SchedulerPeriodicity = 4;
simParameters.SchedulerStrategy = 'PF'; % Supported scheduling strategies: 'PF', 'RR' and 'BestCQI'
% Moving average weight parameter within the range [0, 1] calculates
% average data rate for a UE. The value is used in the PF scheduling strategy.
% Parameter value closer to 1 implies more weight on the instantaneous
% data rate. Parameter value closer to 0 implies more weight on the past
% data rate
% AverageDataRate = ((1 - MovingAvgDataRateWeight) * PastDataRate) + (MovingAvgDataRateWeight * InstantaneousDataRate)
simParameters.MovingAvgDataRateWeight = 0.5;
simParameters.BSRPeriodicity = 5; % In ms
simParameters.EnableHARQ = true; % Flag to enable or disable HARQ. If disabled, there are no retransmissions
simParameters.NumHARQ = 16; % Number of HARQ processes in each UE

Specify the PUSCH preparation time. gNB ensures that PUSCH assignment is received at the UEs at least PUSCHPrepTime ahead of the transmission time.

simParameters.PUSCHPrepTime = 200; % In microseconds

Maximum RBs allotted to a UE in a slot for a PUSCH transmission (limit is applicable for new PUSCH assignments and not for the retransmissions)

simParameters.RBAllocationLimitUL = 15;

Set the channel bandwidth to 5 MHz and subcarrier spacing (SCS) to 15 kHz as defined in 3GPP TS 38.104 Section 5.3.2. The complete bandwidth is assumed to be allotted for PUSCH.

simParameters.NumRBs = 25;
simParameters.SCS = 15; % kHz
simParameters.ULBandwidth = 5e6; % Hz
simParameters.ULCarrierFreq = 2.515e9; % Hz
% Set the RBG size configuration to 1 (configuration-1 RBG table) or 2
% (configuration-2 RBG table) as defined in 3GPP TS 38.214 Section
% 5.1.2.2.1
simParameters.RBGSizeConfig = 1;

Configure parameters to update channel conditions for the UEs. Channel quality is periodically improved or deteriorated by CQIDelta every ChannelUpdatePeriodicity seconds for all RBs of a UE. Whether channel conditions for a particular UE improve or deteriorate is randomly determined.

RBCQI = RBCQI +/- CQIDelta

simParameters.ChannelUpdatePeriodicity = 0.5; % In sec
simParameters.CQIDelta = 1;

Configure a mapping between distance from gNB (first column in meters) and maximum achievable UL CQI value (second column). For example, if a UE is 700 meters away from the gNB, it can achieve a maximum CQI value of 10 as the distance falls within the [501, 800] meters range, as per the mapping. Set the distance in increasing order and the maximum achievable CQI value in decreasing order. This mapping is only applicable when passthrough PHY is used.

simParameters.CQIvsDistance = [
    200  15;
    500  12;
    800  10;
    1000  8;
    1200  7];

Logging and visualization configuration

The CQIVisualization and RBVisualization parameters control the display of the CQI visualization and the RB assignment visualization respectively. To enable the RB visualization plot, set the RBVisualization field to true.

simParameters.CQIVisualization = true;
simParameters.RBVisualization = true;

Set the enableTraces as true to log the traces. If the enableTraces is set to false, then CQIVisualization and RBVisualization are disabled automatically and traces are not logged in the simulation. To speed up the simulation, set the enableTraces to false.

enableTraces = true;

The example updates the metrics plots periodically. Set the number of updates during the simulation.

simParameters.NumMetricsSteps = 20;

Write the logs to MAT-files. The example uses these logs for post simulation analysis and visualization.

parametersLogFile = 'simParameters'; % For logging the simulation parameters
simulationLogFile = 'simulationLogs'; % For logging the simulation traces
simulationMetricsFile = 'simulationMetrics'; % For logging the simulation metrics

Derived Parameters

Based on the primary configuration parameters, compute the derived parameters.

simParameters.NCellID = 1; % Physical cell ID
simParameters.DLCarrierFreq = 2.635e9; % Hz
simParameters.DLBandwidth = 10e6; % Hz
simParameters.GNBPosition = [0 0 0]; % Position of gNB in (x,y,z) coordinates
% Slot duration for the selected SCS and number of slots in a 10 ms frame
slotDuration = 1/(simParameters.SCS/15); % Slot duration in ms
numSlotsFrame = 10/slotDuration; % Number of slots in 10 ms frame
numSlotsSim = simParameters.NumFramesSim * numSlotsFrame; % Number of slots in the simulation

% Specify the RLC entity type in the range [0, 2]. The values 0, 1, and 2
% indicate RLC UM unidirectional DL entity, RLC UM unidirectional UL
% entity, and RLC UM bidirectional entity, respectively.
simParameters.RLCConfig.EntityType = ones(simParameters.NumUEs, simParameters.NumLogicalChannels);

% LCID (LCID of data radio bearers starts from 4) 
simParameters.LCHConfig.LCID = ones(simParameters.NumUEs, simParameters.NumLogicalChannels) .* (4:4+simParameters.NumLogicalChannels-1);

% Construct information for RLC logger and visualizer
lchInfo = repmat(struct('RNTI', [], 'LCID', [], 'EntityDir', []), [simParameters.NumUEs 1]);
for idx = 1:simParameters.NumUEs
    lchInfo(idx).RNTI = idx;
    lchInfo(idx).LCID = simParameters.LCHConfig.LCID(idx, :);
    lchInfo(idx).EntityDir = simParameters.RLCConfig.EntityType(idx, :);
end

% Find maximum achievable CQI value for UEs based on their distance from
% the gNB
maxUECQIs = zeros(simParameters.NumUEs, 1); % To store the maximum achievable CQI value for UEs
for ueIdx = 1:simParameters.NumUEs
    % Based on the distance of the UE from gNB, find matching row in
    % CQIvsDistance mapping
    ueDistance = norm(simParameters.UEPosition(ueIdx, :) - simParameters.GNBPosition);
    matchingRowIdx = find(simParameters.CQIvsDistance(:, 1) > ueDistance);
    if isempty(matchingRowIdx)
        maxUECQIs(ueIdx) = simParameters.CQIvsDistance(end, 2);
    else
        maxUECQIs(ueIdx) = simParameters.CQIvsDistance(matchingRowIdx(1), 2);
    end
end

% Define initial UL channel quality as an N-by-P matrix,
% where 'N' is the number of UEs and 'P' is the number of RBs in the carrier
% bandwidth. The initial value of CQI for each RB, for each UE, is given
% randomly and is limited by the maximum achievable CQI value corresponding
% to the distance of the UE from gNB
simParameters.InitialChannelQualityUL = zeros(simParameters.NumUEs, simParameters.NumRBs); % To store current UL CQI values on the RBs for different UEs
for ueIdx = 1:simParameters.NumUEs
    % Assign random CQI values for the RBs, limited by the maximum achievable CQI value
    simParameters.InitialChannelQualityUL(ueIdx, :) = randi([1 maxUECQIs(ueIdx)], 1, simParameters.NumRBs);
end

% Interval at which metrics visualization updates in terms of number of
% slots. Make sure that MetricsStepSize is an integer
simParameters.MetricsStepSize = ceil(numSlotsSim / simParameters.NumMetricsSteps);
if mod(numSlotsSim, simParameters.NumMetricsSteps) ~= 0
    % Update the NumMetricsSteps parameter if numSlotsSim is not
    % completely divisible by it
    simParameters.NumMetricsSteps = floor(numSlotsSim / simParameters.MetricsStepSize);
end

if ~isfield(simParameters, 'SchedulingType') || simParameters.SchedulingType == 0 % If no scheduling type is specified or slot-based scheduling is specified
    tickGranularity = 14;
    simParameters.PUSCHMappingType = 'A';
    simParameters.PDSCHMappingType = 'A';
else % Symbol-based scheduling
    tickGranularity = 1;
    simParameters.PUSCHMappingType = 'B';
end

gNB and UEs Setup

Create the gNB and UE objects, initialize the UL channel condition information for UEs at gNB, and set up the logical channels at gNB and UE. The helper classes hNRGNB.m and hNRUE.m create gNB and UE nodes respectively, containing the RLC and MAC layer. For MAC layer, hNRGNB.m uses the helper class hNRGNBMAC.m to implement the gNB MAC functionality and hNRUE.m uses hNRUEMAC.m to implement the UE MAC functionality. Schedulers are implemented in hNRSchedulerRoundRobin.m (Round robin), hNRSchedulerProportionalFair.m (Proportional fair), hNRSchedulerBestCQI.m (Best CQI) . All the schedulers inherit from the base class hNRScheduler.m which contains the core scheduling functionality. For RLC layer, both hNRGNB.m and hNRUE.m use hNRUMEntity.m to implement the functionality of the RLC transmitter and receiver. Passthrough PHY layer for UE and gNB is implemented in hNRUEPassThroughPhy.m and hNRGNBPassThroughPhy.m, respectively.

simParameters.Position = simParameters.GNBPosition;
gNB = hNRGNB(simParameters); % Create gNB node
% Create and add scheduler
switch(simParameters.SchedulerStrategy)
    case 'RR' % Round robin scheduler
        scheduler = hNRSchedulerRoundRobin(simParameters);
    case 'PF' % Proportional fair scheduler
        scheduler = hNRSchedulerProportionalFair(simParameters);
    case 'BestCQI' % Best CQI scheduler
        scheduler = hNRSchedulerBestCQI(simParameters);
    otherwise
        error('Invalid scheduler strategy "%s"', simParameters.SchedulerStrategy);
end
addScheduler(gNB, scheduler); % Add scheduler to gNB

gNB.PhyEntity = hNRGNBPassThroughPhy(simParameters); % Create passthrough PHY
configurePhy(gNB, simParameters);
setPhyInterface(gNB); % Set the interface to PHY layer

% Create the set of UE nodes
UEs = cell(simParameters.NumUEs, 1);
for ueIdx = 1:simParameters.NumUEs
    simParameters.Position = simParameters.UEPosition(ueIdx, :); % Position of UE
    UEs{ueIdx} = hNRUE(simParameters, ueIdx);
    simParameters.InitialChannelQualityDL = simParameters.InitialChannelQualityUL;
    UEs{ueIdx}.PhyEntity = hNRUEPassThroughPhy(simParameters, ueIdx); % Add passthrough PHY
    configurePhy(UEs{ueIdx}, simParameters);
    setPhyInterface(UEs{ueIdx}); % Set the interface to PHY layer
    
    % Initialize the UL CQI values at gNB
    channelQualityInfo = struct('RNTI', ueIdx, 'CQI', simParameters.InitialChannelQualityUL(ueIdx, :));
    updateChannelQualityUL(gNB.MACEntity.Scheduler, channelQualityInfo);

    % Setup logical channels
    for lcIdx = 1:simParameters.NumLogicalChannels
        % Create RLC channel configuration structure
        rlcChannelConfigStruct.EntityType = simParameters.RLCConfig.EntityType(ueIdx, lcIdx);
        rlcChannelConfigStruct.LogicalChannelID = simParameters.LCHConfig.LCID(ueIdx, lcIdx);
        rlcChannelConfigStruct.SeqNumFieldLength = simParameters.RLCConfig.SNFieldLength(ueIdx, lcIdx);
        rlcChannelConfigStruct.MaxTxBufferSDUs = simParameters.RLCConfig.MaxTxBufferSDUs(ueIdx, lcIdx);
        rlcChannelConfigStruct.ReassemblyTimer = simParameters.RLCConfig.ReassemblyTimer(ueIdx, lcIdx);
        rlcChannelConfigStruct.LCGID = simParameters.LCHConfig.LCGID(ueIdx, lcIdx);
        rlcChannelConfigStruct.Priority = simParameters.LCHConfig.Priority(ueIdx, lcIdx);
        rlcChannelConfigStruct.PBR = simParameters.LCHConfig.PBR(ueIdx, lcIdx);
        rlcChannelConfigStruct.BSD = simParameters.LCHConfig.BSD(ueIdx, lcIdx);
        
        % Setup logical channel at gNB for the UE
        configureLogicalChannel(gNB, ueIdx, rlcChannelConfigStruct);
        % Setup logical channel at UE
        configureLogicalChannel(UEs{ueIdx}, ueIdx, rlcChannelConfigStruct);
        
        % Add data traffic pattern generators to UE nodes. Application data
        % is pumped to RLC layer as per the installed traffic pattern
        % Limit the size of the generated application packet to the maximum
        % RLC SDU size. The maximum supported RLC SDU size is 9000 bytes
        packetSize = 9000;
 
        % Create an object for On-Off network traffic pattern and add it to the
        % specified UE. This object generates the uplink (UL) data traffic on the UE
        app = networkTrafficOnOff('PacketSize', packetSize, 'GeneratePacket', true, ...
            'OnTime', simParameters.NumFramesSim/100, 'OffTime', 0, 'DataRate', appDataRate(ueIdx, lcIdx));
        UEs{ueIdx}.addApplication(ueIdx, simParameters.LCHConfig.LCID(ueIdx, lcIdx), app);
    end
end

% Setup the UL and DL packet distribution mechanism
simParameters.MaxReceivers = simParameters.NumUEs + 1; % Number of nodes
% Create packet distribution object
packetDistributionObj = hNRPacketDistribution(simParameters);
hNRSetUpPacketDistribution(simParameters, gNB, UEs, packetDistributionObj);

Processing Loop

Simulation is run slot by slot. In each slot, these operations are executed:

  • Run the MAC and PHY layers of gNB

  • Run the MAC and PHY layers of UEs

  • Layer specific logging and visualization

  • Advance the timer for the nodes. Every 1 ms it also sends trigger to application and RLC layers. Application layer and RLC layer execute their scheduled operations based on 1 ms timer trigger.

Create objects to log and visualize RLC and MAC traces.

linkDir = 1; % UL direction is represented as 1
if enableTraces
    % Create an object for RLC traces logging
    simRLCLogger = hNRRLCLogger(simParameters, lchInfo);
    % Create an object for MAC traces logging
    simSchedulingLogger = hNRSchedulingLogger(simParameters, linkDir);
    % Create an object for CQI and RB grid visualization
    if simParameters.CQIVisualization || simParameters.RBVisualization
        gridVisualizer = hNRGridVisualizer(simParameters, 'MACLogger', simSchedulingLogger, 'VisualizationFlag', linkDir);
    end
end

Create an object for RLC and MAC metrics visualization.

nodes = struct('UEs', {UEs}, 'GNB', gNB);
metricsVisualizer = hNRMetricsVisualizer(simParameters, 'Nodes', nodes, 'EnableSchedulerMetricsPlots', true, 'EnableRLCMetricsPlots', true, 'LCHInfo', lchInfo, 'VisualizationFlag', linkDir);

Run processing loop.

slotNum = 0;
numSymbolsSim = numSlotsSim * 14; % Simulation time in units of symbol duration (assuming normal cyclic prefix)

% Execute all the symbols in the simulation
for symbolNum = 1 : tickGranularity : numSymbolsSim
    if mod(symbolNum - 1, 14) == 0
        slotNum = slotNum + 1;
    end
    
    % Run MAC and PHY of gNB
    run(gNB);
    
    % Run MAC and PHY layers of UEs
    for ueIdx = 1:simParameters.NumUEs
        run(UEs{ueIdx}); 
    end
    
    if enableTraces
        % RLC logging (only at slot boundary)
        if (simParameters.SchedulingType == 1 && mod(symbolNum, 14) == 0) || (simParameters.SchedulingType == 0 && mod(symbolNum-1, 14) == 0)
            logCellRLCStats(simRLCLogger, gNB, UEs); % Update RLC statistics logs
        end

        % MAC logging
        logCellSchedulingStats(simSchedulingLogger, symbolNum, gNB, UEs, linkDir);
    end
    
    % Visualization    
    % Check slot boundary
    if symbolNum > 1 && ((simParameters.SchedulingType == 1 && mod(symbolNum, 14) == 0) || (simParameters.SchedulingType == 0 && mod(symbolNum-1, 14) == 0))
        if mod(slotNum, simParameters.MetricsStepSize) == 0
            % If the update periodicity is reached, plot RLC metrics and scheduler metrics at slot boundary
            plotLiveMetrics(metricsVisualizer);
        end
    end
    
    % Advance timer ticks for gNB and UEs by 14 symbols
    advanceTimer(gNB, tickGranularity);
    for ueIdx = 1:simParameters.NumUEs
        advanceTimer(UEs{ueIdx}, tickGranularity);
    end
end

Figure Channel Quality Visualization contains objects of type heatmap, uigridlayout. The chart of type heatmap has title Channel Quality Visualization for Cell ID - 1.

Figure Resource Grid Allocation contains an axes object and another object of type uigridlayout. The axes object contains 232 objects of type text, line.

Get the simulation metrics and save it in a MAT-file. The simulation metrics are saved in a MAT-file with the file name as simulationMetricsFile.

metrics = getMetrics(metricsVisualizer);
save(simulationMetricsFile, 'metrics'); % Save simulation metrics in a MAT-file

Simulation Visualization

The four types of run-time visualization shown are:

  • Display of CQI values for UEs over the PUSCH bandwidth: For details, see the 'Channel Quality Visualization' figure for more details.

  • Display of resource grid assignment to UEs: The 2-D time-frequency grid updates every 10 ms (frame length) and shows the RB allocation to the UEs in the previous frame. The HARQ process for the PUSCH assignments is also shown alongside with the RNTI of the UEs. New transmissions are shown in black and retransmissions are shown in blue using the HARQ process ID of each UE, a retransmission assignment can be mapped to its previously failed transmission. For details, see the 'Resource Grid Allocation' figure for more details.

  • Display of UL scheduling metrics plots: The 'Uplink Scheduler Performance Metrics' figure includes plots of the: UL throughput (per UE and cell), UL goodput (per UE and cell), resource share percentage among UEs (out of the total UL resources) to convey the fairness of scheduling, and pending UL buffer status of the UEs to show whether UEs are getting sufficient resources. The maximum achievable data rate value for UL throughput is shown with a dashed line in throughput and goodput plots. The performance metrics plots update for every metricsStepSize slots.

  • Display of RLC metrics plot: The 'RLC Metrics Visualization' figure represents the number of bytes transmitted by RLC layer (per logical channel) for each UE. The RLC metrics plot updates for every metricsStepSize slots.

Simulation Logs

The parameters used for the simulation and simulation logs are saved in MAT files for post simulation analysis and visualization. The simulation parameters are saved in a MAT file with the filename as the value of configuration parameter parametersLogFile. The per time step logs, scheduling assignment logs and RLC logs are saved in MAT file simulationLogFile. After the simulation, open the file to load ULTimeStepLogs, SchedulingAssignmentLogs and RLCLogs in the workspace.

Time step logs: The table shows a sample time step entry. Each row of the table represents a slot.

Each row of the table represents a slot and contains the following information:

  • Timestamp: Time (in milliseconds) since the start of simulation.

  • Frame: Frame number.

  • Slot: Slot number in the frame.

  • RBG Allocation Bitmap: N-by-P bitmap matrix, where N is the number of UEs and P is the number of RBGs. If an RBG is assigned to a particular UE, the corresponding bit is set to 1. For example, [ 0 0 1 1 0 1 0 1 0 1 0 0 0; 1 1 0 0 0 0 0 0 0 0 1 0 0; 0 0 0 0 1 0 1 0 1 0 0 1 1; 0 0 0 0 0 0 0 0 0 0 0 0 0] means that the UL bandwidth has 13 RBGs and UE-1 is assigned RBG indices: 2, 3, 5, 7 and 9; UE-2 is assigned the RBG indices 0, 1 and 10; UE-3 is assigned the RBG indices 4, 6, 8, 11 and 12 and UE-4 is not assigned any RBG.

  • MCS: Row vector of length N, where N is the number of UEs. Each value corresponds to the modulation and coding scheme (MCS) index for the PUSCH transmission. For example, [10 12 8 -1] means that only UE-1, UE-2, and UE-3 are assigned UL resources for this slot and use MCS values 10, 12, and 8, respectively.

  • HARQ Process: Row vector of length N, where N is the number of UEs. The value is the HARQ process ID used by UE for the PUSCH transmission. For example, [0 3 6 -1] means that only UE-1, UE-2, and UE-3 are assigned UL resources for this slot and use the HARQ process IDs 0, 3, and 6, respectively.

  • NDI: Row vector of length N, where N is the number of UEs. The value is the NDI flag value in the UL assignment for PUSCH transmission. For example, [0 0 1 -1] means that only UE-1, UE-2, and UE-3 are assigned UL resources for this slot and use the NDI flag values (which determine whether a new transmission or a retransmission is used) 0, 0, and 1, respectively.

  • Tx Type: Tx Type specifies the transmission type (new transmission or retransmission). Row vector of length N, where N is the number of UEs. Possible values are either 'newTx', 'reTx', or 'noTx'. 'noTx' means that the UE is not allocated PUSCH resources. For example, ['newTx' 'newTx' 'reTx' 'noTx'] means that only UE-1, UE-2, and UE-3 are assigned UL resources for this slot. UE-1 and UE-2 transmit a new packet from the specified HARQ process, while UE-3 retransmits the packet in the buffer of the specified HARQ process.

  • CQI for UEs: N-by-P matrix, where N is the number of UEs and P is the number of RBs in the bandwidth. A matrix element at position (i, j) corresponds to the UL CQI value for UE with RNTI i at RB j.

  • HARQ NDI Status: N-by-P matrix, where N is the number of UEs and P is the number of HARQ processes on UEs. A matrix element at position (i, j) is the last received NDI flag at UE i for HARQ process ID j. For new transmissions, this value and the NDI flag in the PUSCH assignment must toggle. For example, in slot 1 of frame 5 described in the scheduling log, UE-1 uses the HARQ ID 0 and the last NDI flag value for HARQ ID 0 at UE-1 is 1. To indicate a new transmission, the NDI flag values changes to 0 in the PUSCH assignment.

  • Throughput Bytes: Row vector of length N, where N is the number of UEs. The values represent MAC bytes transmitted by UEs in this slot.

  • Goodput Bytes: Row vector of length N, where N is the number of UEs. The values represent new transmission MAC bytes transmitted by UEs in this slot.

  • Buffer Status of UEs: Row vector of length N, where N is the number of UEs. The values represent the amount of pending buffers at UEs.

Scheduling assignment logs: Information of all the scheduling assignments and related information is logged in this file. The table shows sample log entries.

RLC logs: Each row in the RLC logs represents a slot and contains this information:

  • Timestamp: Timestamp (in milliseconds)

  • Frame: Frame number.

  • Slot: Slot number in the frame.

  • UE RLC statistics: N-by-P cell, where N is the product of the number of UEs and the number of logical channels, and P is the number of statistics collected. Each row represents statistics of a logical channel in a UE. The last row contains the cumulative RLC statistics of the entire simulation.

  • gNB RLC statistics: N-by-P cell, where N is the product of the number of UEs and the number of logical channels, and P is the number of statistics collected. Each row represents statistics of a logical channel of a UE at gNB. The last row contains the cumulative RLC statistics of the entire simulation.

Each row of the UE and gNB RLC statistics table represents a logical channel of a UE and contains:

  • RNTI: Radio network temporary identifier of a UE.

  • LCID: Logical channel identifier.

  • TxDataPDU: Number of data PDUs sent by RLC to MAC layer.

  • TxDataBytes: Number of data bytes sent by RLC to MAC layer.

  • ReTxDataPDU: Number of data PDUs retransmitted by RLC to MAC layer.

  • ReTxDataBytes: Number of data bytes retransmitted by RLC to MAC layer.

  • TxControlPDU: Number of control PDUs sent by RLC to MAC layer.

  • TxControlBytes: Number of control bytes sent by RLC to MAC layer.

  • TxPacketsDropped: Number of RLC SDUs dropped by RLC due to Tx buffer overflow.

  • TxBytesDropped: Number of bytes dropped by RLC due to Tx buffer overflow.

  • TimerPollRetransmitTimedOut: Number of times the poll retransmit timer expired.

  • RxDataPDU: Number of data PDUs received by RLC from MAC layer.

  • RxDataBytes: Number of data bytes received by RLC from MAC layer.

  • RxDataPDUDropped: Number of received data PDUs from MAC which are dropped by RLC layer.

  • RxDataBytesDropped: Number of received data bytes from MAC which are dropped by RLC layer.

  • RxDataPDUDuplicate: Number of duplicate PDUs received by RLC from MAC layer.

  • RxDataBytesDuplicate: Number of duplicate data bytes received by RLC from MAC layer.

  • RxControlPDU: Number of control PDUs received by RLC from MAC layer.

  • RxControlBytes: Number of control bytes received by RLC from MAC layer.

  • TimerReassemblyTimedOut: Number of times the reassembly timer expired.

  • TimerStatusProhibitTimedOut: Number of times the status prohibit timer expired.

You can run the script NRPostSimVisualization to get a post simulation visualization of logs. In the post simulation script, you are provided with variable isLogReplay, which provides these options to visualize 'Resource Grid Allocation' and 'Channel Quality Visualization' figures.

  • Set isLogReplay to true for a replay of the simulation logs.

  • Set isLogReplay to false to analyze the simulation logs and input the frame number to visualize the scheduling information of the particular frame

if enableTraces
    % Read the logs and save them in MAT-files
    simulationLogs = cell(1, 1);
    simulationLogs{1} = struct('ULTimeStepLogs',[], 'SchedulingAssignmentLogs',[] ,'RLCLogs',[]);
    [~, simulationLogs{1}.ULTimeStepLogs] = getSchedulingLogs(simSchedulingLogger); % UL time step scheduling logs
    simulationLogs{1}.SchedulingAssignmentLogs = getGrantLogs(simSchedulingLogger); % Scheduling assignments log
    simulationLogs{1}.RLCLogs = getRLCLogs(simRLCLogger); % RLC statistics logs
    save(simulationLogFile, 'simulationLogs'); % Save simulation logs in a MAT-file
    save(parametersLogFile, 'simParameters'); % Save simulation parameters in a MAT-file
end

References

[1] 3GPP TS 38.214. “NR; Physical layer procedures for data.” 3rd Generation Partnership Project; Technical Specification Group Radio Access Network.

[2] 3GPP TS 38.321. “NR; Medium Access Control (MAC) protocol specification.” 3rd Generation Partnership Project; Technical Specification Group Radio Access Network.

[3] 3GPP TS 38.322. “NR; Radio Link Control (RLC) protocol specification.” 3rd Generation Partnership Project; Technical Specification Group Radio Access Network.

Related Topics