configureScheduler

Configure scheduler at gNB

Since R2023a

collapse all in page

    Syntax

    configureScheduler(gnb,Name=Value)

    Description

    configureScheduler(gnb,Name=Value) configures a scheduler at a 5G new radio (NR) base station (gNB) node. The function sets the scheduling parameters using one or more optional name-value arguments. For example, ResourceAllocationType=0 sets the resource allocation type to 0. You can configure a scheduler at multiple gNB nodes in a single configureScheduler function call. In this case, all the nodes use the same scheduling parameter values specified in the name-value arguments. This feature also requires the Wireless Network Toolbox™ product.

    Note

    System-level simulation dynamically selects the uplink and downlink rank based on the measured channel quality.

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    Initialize the wireless network simulator.

    networkSimulator = wirelessNetworkSimulator.init;

    Create a default gNB node.

    gnb = nrGNB;

    Create two UE nodes, specifying their positions.

    ue = nrUE(Position=[100 100 0; 5000 100 0]); % In Cartesian x, y, and z coordinates.

    Configure a scheduler at the gNB with the maximum number of users per transmission time interval (TTI) as 3.

    configureScheduler(gnb,MaxNumUsersPerTTI=3)

    Connect the UE nodes to the gNB node.

    connectUE(gnb,ue)

    Create voice over Internet protocol (VoIP) application traffic pattern objects to generate VoIP application traffic patterns between the gNB and UE nodes.

    traffic1 = networkTrafficVoIP(ExponentialMean=5);
traffic2 = networkTrafficVoIP(ExponentialMean=125);

    Add a data traffic source from the gNB node to the UE nodes.

    addTrafficSource(gnb,traffic1,DestinationNode=ue(1))
addTrafficSource(gnb,traffic2,DestinationNode=ue(2))

    Add the nodes to the network simulator.

    addNodes(networkSimulator,gnb)
addNodes(networkSimulator,ue)

    Set the simulation time, in seconds.

    simulationTime = 0.3;

    Run the simulation for the specified simulation time.

    run(networkSimulator,simulationTime)

    Obtain statistics for the gNB and UE nodes.

    gnbStats = statistics(gnb);
ue1Stats = statistics(ue(1));
ue2Stats = statistics(ue(2));

    Input Arguments

    collapse all

    gNB node, specified as an nrGNB object or a vector of nrGNB objects.

    Name-Value Arguments

    collapse all

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: configureScheduler(gnb,ResourceAllocationType=0) sets the resource allocation type to 0

    Scheduler strategy, specified as one of these options.

    • "RoundRobin" — Enable the round-robin (RR) scheduler. This scheduler provides equal scheduling opportunities to all the UE nodes.

    • "BestCQI" — Enable the best channel quality indicator (CQI) scheduler. This scheduler gives priority to the UE node with the best CQI.

    • "ProportionalFair" — Enable the proportional-fair (PF) scheduler. This scheduler is a compromise between the round-robin and best CQI schedulers.

    • An object of a subclass of nrScheduler. (since R2024b)

    The scheduling strategies RR, best CQI, and PF attempt to schedule MaxNumUsersPerTTI UE nodes in each slot. For a custom scheduler, the scheduling logic determines the number of UE nodes to be scheduled, but it cannot exceed MaxNumUsersPerTTI.

    Note

    Important considerations for the Scheduler name-value include:

    • When you specify the Scheduler name-value argument as an object of a subclass of nrScheduler, the applicable name-value arguments are RVSequence, ResourceAllocationType, CSIMeasurementSignalDL, MaxNumUsersPerTTI, and MUMIMOConfigDL.

    • Built-in schedulers, such as "RoundRobin", "BestCQI", and "ProportionalFair", do not use subband-level modulation and coding scheme (MCS) and channel quality indicator (CQI) measurements for scheduling. Even if you configure them, built-in schedulers use only wideband MCS and CQI measurements for scheduling. However, custom schedulers can use subband-level MCS and CQI measurements if you configure these measurements.

    Redundancy version sequence, specified as a vector of any length with integer elements in the range [0, 3]. To disable retransmissions, set RVSequence to a scalar value.

    Note

    Since R2026a, you can set RVSequence to a vector of any length with integer elements in the range [0, 3]. In R2025b and earlier releases, you must set RVSequence as a vector containing up to four unique integers from 0 to 3.

    Data Types: double

    Time constant of an exponential moving average, specified as a positive integer, in number of slots. The proportional-fair scheduler uses this time constant to calculate the average data rate.

    Dependencies

    To enable this name-value argument, specify the Scheduler argument as "ProportionalFair".

    Data Types: double

    Resource allocation type, specified as 1 (resource allocation type 1) or 0 (resource allocation type 0).

    Data Types: double

    Maximum number of users per transmission time interval (TTI), specified as a positive integer.

    Data Types: double

    Modulation and coding scheme (MCS) index for downlink (DL), specified as an integer in the range [0, 27]. The MCS index corresponds to a row in TS 38.214, table 5.1.3.1-2 [1]. The gNB node stores the MCS table as the static property MCSTable. The default value of [] indicates for the gNB to select the MCS based on the CSI-RS measurement report.

    Dependencies

    This name-value argument is not applicable when you specify the Scheduler name-value argument as an object of a subclass of nrScheduler.

    Data Types: double

    Modulation and coding scheme (MCS) index for uplink ( UL), specified as an integer in the range [0, 27]. The MCS index corresponds to a row in TS 38.214, table 5.1.3.1-2. The gNB node stores the MCS table as static property MCSTable. The default value of [] indicates for the gNB to select the MCS based on the sounding reference signal (SRS) measurements.

    Dependencies

    This name-value argument is not applicable when you specify the Scheduler name-value argument as an object of a subclass of nrScheduler.

    Data Types: double

    Since R2024b

    DL channel state information (CSI) measurement signal, specified as "SRS" or "CSI-RS". Note that you can set an unequal number of transmit and receive antennas at a UE node for both measurement signal types: SRS and CSI-RS. For more information about the SRS-based DL channel measurements, see SRS-Based Downlink Channel Measurements for TDD System.

    Note

    Important considerations for the Scheduler name-value argument include:

    • While integrating a custom scheduler or using a built-in scheduler, setting CSIMeasurementSignalDL to "SRS" populates the SRS field of the CSIMeasurementDL structure of the UEContext property of the nrScheduler base class. By default, the built-in schedulers use the CSI-RS-based measurements for the DL scheduling. However, the responsibility for using these SRS-based measurements for custom scheduling falls to the developer of the custom scheduler.

    • Enabling the SRSMeasurementConfigDL property of the nrGNB object sets the default value of CSIMeasurementSignalDL to "SRS". (since R2026a)

    Configuration of DL multi-user multiple-input and multiple-output (MU-MIMO), specified as a structure. The structure must contain these fields.

    • MaxNumUsersPaired — The maximum number of users that the scheduler can pair for a MU-MIMO transmission, specified as integer in the range [2, 4]. The default value is 2. This field applies to both the CSI-RS and SRS-based DL MU-MIMO.

    • MinNumRBs — The minimum number of resource blocks (RBs) the scheduler must allocate to a UE to consider it as an MU-MIMO candidate, specified as a positive integer. The default value is 6. The scheduler calculates the number of RBs based on the buffer occupancy and the CSI reported by the UE node. This field applies to both the CSI-RS and SRS-based DL MU-MIMO.

    • MaxNumLayers — The maximum number of layers that a DL MU-MIMO transmission supports, specified as an integer in the range [2, 16]. The default value is 8. This field applies to both the CSI-RS and SRS-based DL MU-MIMO. (since R2025a)

    • MinCQI — The minimum channel quality indicator (CQI) required for considering a UE as an MU-MIMO candidate, specified as an integer in the range [1, 15]. The default value is 7. For more information about the CQI table, see TS 38.214 Table 5.2.2.1-2 [1]. This field applies to CSI-RS-based DL MU-MIMO.

    • SemiOrthogonalityFactor — Inter-user interference (IUI) orthogonality factor, specified as a numeric scalar in the range [0, 1]. The scheduler uses this value to decide whether to pair up the UE nodes for MU-MIMO. SemiOrthogonalityFactor values of 0 and 1 indicate nonorthogonality and orthogonality between the UE nodes, respectively. The default value of SemiOrthogonalityFactor is 0.75. This field applies to CSI-RS-based DL MU-MIMO

    • MinSINR — The minimum signal-to-interference-plus-noise ratio (SINR) in dB for a UE node in the DL direction to qualify as a MU-MIMO candidate, specified as a scalar in the range [-7, 25]. The default value is 10. The data type is double. This field applies to SRS-based DL MU-MIMO. (since R2025a)

    • EffectiveMCSAndPrecoder — Effective MCS and precoder calculation option, specified as logical 1 (true) or 0 (false). Set this field to true to enable the option, or to false to disable it. The default value is false. This field applies to the CSI-RS-based DL MU-MIMO. (since R2026a)

      When you disable EffectiveMCSAndPrecoder, the node uses the reported CQI and precoders directly for MU-MIMO transmissions. When you enable it, a heuristic algorithm adjusts the reported CQI and precoders based on the actual user pairing to better suit MU-MIMO. Note that this feature does not support "type1SinglePanel" as CodebookType in CSIReportConfig.

    Note

    Since release 2026a, you configure the codebook type for measurements through the CodeBookType property of the CSIReportConfig name-value argument in the connectUE function. This approach allows you to access CSI reports with the configured codebook type, but you remain responsible for MU-MIMO scheduling when you use a custom scheduler. In contrast, when you use built-in schedulers, MUMIMOConfigDL both enables CSI reporting with the specified CodeBookType and implements the MU-MIMO algorithm. Built-in schedulers do not support MU-MIMO with subband measurements. In releases R2025b and earlier, when you integrate a custom scheduler, providing MUMIMOConfigDL (either empty or as a structure with defined fields) only activates type-II CSI reporting. However, the responsibility for MU-MIMO scheduling still falls to the developer of the custom scheduler.

    Link adaptation (LA) configuration structure for DL transmissions, specified as a structure. To enable LA for DL transmissions, create an LA configuration structure and specify it to this argument. If not set, LA remains disabled. The LinkAdaptationConfigDL value of [] enables LA with default configuration parameters. If you configure LA, do not specify the FixedMCSIndexDL argument. An LA structure must contain these fields.

    • InitialOffset — Initial MCS offset applied to all UEs, specified as an integer in the range [-27, 27]. This offset considers the errors in channel measurements at the UE node. Upon receiving the CSI report, the gNB node resets the MCS offset to the InitialOffset value. The scheduler then determines the MCS for the physical downlink shared channel (PDSCH) transmission by subtracting the MCS offset from the MCS obtained from the channel measurements. The default value is 0.

    • StepUp — Incremental value for the MCS offset when a packet reception fails, specified as a numeric scalar in the range [0, 27]. LA considers only the failure of new transmissions while ignoring any retransmission feedback. The default value is 0.27.

    • StepDown — Decremental value for the MCS offset when a packet reception is successful, specified as numeric scalar in the range [0, 27]. LA considers only the success of new transmissions while ignoring any retransmission feedback. The default value is 0.03.

    • ResetOffsetOnCSIReport — LA MCS offset resetting upon CSI measurement report reception, specified as a logical 1 (true) or 0 (false). To enable the LA MCS offset resetting, set the value of this field to true. The default value is true. (since R2026a)

    Dependencies

    This name-value argument is not applicable when you specify the Scheduler name-value argument as an object of a subclass of nrScheduler.

    LA configuration structure for UL transmissions, specified as a structure. To enable LA for UL transmissions, create an LA configuration structure and specify it to this argument. The LinkAdaptationConfigUL value of [] enables LA with default configuration parameters. If you configure LA, do not specify the FixedMCSIndexUL argument. The LinkAdaptationConfigUL structure must contain these fields.

    • InitialOffset — Initial MCS offset applied to all UEs, specified as an integer in the range [-27, 27]. This offset considers the errors in channel measurements at the UE node. Upon receiving the CSI report, the gNB node resets the MCS offset to the InitialOffset value. The scheduler then determines the MCS for the physical downlink shared channel (PDSCH) transmission by subtracting the MCS offset from the MCS obtained from the channel measurements. The default value is 0.

    • StepUp — Incremental value for the MCS offset when a packet reception fails, specified as a numeric scalar in the range [0, 27]. LA considers only the failure of new transmissions while ignoring any retransmission feedback. The default value is 0.27.

    • StepDown — Decremental value for the MCS offset when a packet reception is successful, specified as numeric scalar in the range [0, 27]. LA considers only the success of new transmissions while ignoring any retransmission feedback. The default value is 0.03.

    • ResetOffsetOnCSIReport — LA MCS offset resetting upon CSI measurement report reception, specified as a logical 1 (true) or 0 (false). To enable the LA MCS offset resetting, set the value of this field to true. The default value is true. (since R2026a)

    Dependencies

    This name-value argument is not applicable when you specify the Scheduler name-value argument as an object of a subclass of nrScheduler.

    More About

    collapse all

    References

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

    [2] Sarret, Marta Gatnau, Davide Catania, Frank Frederiksen, Andrea F. Cattoni, Gilberto Berardinelli, and Preben Mogensen. “Dynamic Outer Loop Link Adaptation for the 5G Centimeter-Wave Concept.” In Proceedings of European Wireless 2015; 21st European Wireless Conference, 1–6, 2015. https://ieeexplore.ieee.org/document/7147668

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

    Version History

    Introduced in R2023a

    expand all

    See Also

    Objects

    Classes

    Functions

    Topics