run

Run simulation

Since R2022b

Syntax

run(networkSimulator,simDuration)

run(networkSimulator,simDuration,IsLastStep=flag)

Description

run(networkSimulator,simDuration) runs the wireless network simulation in a single step for the specified duration and performs the scheduled actions. simDuration specifies the simulation duration in seconds. networkSimulator is an object of type wirelessNetworkSimulator.

Call this method only after initializing the wirelessNetworkSimulator object.

run(networkSimulator,simDuration,IsLastStep=flag) runs the wireless network simulation in multiple steps of variable durations. flag specifies whether the current run is the last step in the multi-step simulation.

Invoke the run function multiple times to advance the simulation in steps, where each call advances the simulation by simDuration seconds and resumes from the point where the previous call exited. For all steps except the last, specify flag as false. For the final simulation step, specify flag as true, which is also its default value.

The simulator executes any post-simulation actions scheduled using schedulePostSimulationAction only after the last simulation step. After the last step, you cannot call run again.

For an example, see Simulate Wireless Network in Multiple Steps.

Examples

Simulate Bluetooth BR Network with Default Channel Effects

Create a wirelessNetworkSimulator object by using the wirelessNetworkSimulator.init() function. By default, the wirelessNetworkSimulator object applies free-space path loss model for the channel effects.

networkSimulator = wirelessNetworkSimulator.init();

Create two Bluetooth BR nodes, one with the "central" role and other with the "peripheral" role. Specify the position of the Peripheral node in meters.

centralNode = bluetoothNode("central");
peripheralNode = bluetoothNode("peripheral",Position=[1 0 0]);

Create a default Bluetooth BR connection configuration object to configure and share a connection between Bluetooth BR Central and Peripheral nodes.

cfgConnection = bluetoothConnectionConfig;

Configure connection between the Central and the Peripheral nodes.

connection = configureConnection( ...
    cfgConnection,centralNode,peripheralNode);

Create and configure a networkTrafficOnOff object to generate an On-Off application traffic pattern.

traffic = networkTrafficOnOff( ...
    DataRate=200, ...
    PacketSize=27, ...
    OnTime=inf);

Add application traffic from the Central to the Peripheral node.

addTrafficSource(centralNode,traffic, ...
    DestinationNode=peripheralNode);

Add the Central and Peripheral nodes to the wireless network simulator.

addNodes(networkSimulator,[centralNode peripheralNode]);

Specify the simulation time in seconds.

simulationTime = 0.05;

Run the simulation for the specified simulation time.

run(networkSimulator,simulationTime);

Retrieve application, baseband, and physical layer (PHY) statistics corresponding to the Central and Peripheral nodes.

centralStats = statistics(centralNode)

centralStats = struct with fields:
        Name: "Node1"
          ID: 1
         App: [1×1 struct]
    Baseband: [1×1 struct]
         PHY: [1×1 struct]

peripheralStats = statistics(peripheralNode)

peripheralStats = struct with fields:
        Name: "Node2"
          ID: 2
         App: [1×1 struct]
    Baseband: [1×1 struct]
         PHY: [1×1 struct]

Schedule Action to Perform During Network Simulation

Simulate Bluetooth BR Network

Create a wirelessNetworkSimulator object by using the wirelessNetworkSimulator.init() function. By default, the wirelessNetworkSimulator object applies free-space path loss model for the channel effects.

networkSimulator = wirelessNetworkSimulator.init();

Create two Bluetooth BR nodes, one with the "central" role and other with the "peripheral" role. Specify the position of the Peripheral node in meters.

centralNode = bluetoothNode("central");
peripheralNode = bluetoothNode("peripheral",Position=[1 0 0]);

Create a default Bluetooth BR connection configuration object to configure and share a connection between Bluetooth BR Central and Peripheral nodes.

cfgConnection = bluetoothConnectionConfig;

Configure connection between the Central and the Peripheral nodes.

connection = configureConnection( ...
    cfgConnection,centralNode,peripheralNode);

Create and configure a networkTrafficOnOff object to generate an On-Off application traffic pattern.

traffic = networkTrafficOnOff( ...
    DataRate=200, ...
    PacketSize=27, ...
    OnTime=inf);

Add application traffic from the Central to the Peripheral node.

addTrafficSource(centralNode,traffic, ...
    DestinationNode=peripheralNode);

Add the Central and Peripheral nodes to the wireless network simulator.

addNodes(networkSimulator,[centralNode peripheralNode]);

Schedule Action

Create a custom function displayInfo to define the actions for the simulator to perform during simulation. You can define an one time action, periodic action, and action when simulator advances in time. The input data for the custom function is stored as a structure and passed using the scheduleAction function.

A) Schedule One Time Action

For the one time action, the displayInfo function displays the details of the nodes in the network.

Specify the ActionType input argument value of displayInfo function as "A". Specify the names of the nodes in the network as input to displayInfo function.

userdata = struct( ...
    ActionType="A", ...
    Nodes=[centralNode peripheralNode]);

Configure the simulator by using the scheduleAction function to display the node details when the simulation time is 0.001s.

startTime = 0.001;
scheduleAction(networkSimulator,@displayInfo,userdata,startTime);

B) Schedule Periodic Action

For the periodic action, the displayInfo function displays the physical layer statistics of the central node in the Bluetooth BR network.

Specify the ActionType input argument value of displayInfo function as "B". Specify the central node and the simulator as inputs to displayInfo function.

userdata = struct( ...
    ActionType="B", ...
    CentralNode=centralNode, ...
    Simulator=networkSimulator);

Configure the simulator by using the scheduleAction function to display the physical layer statistics of the central node at a time interval of 0.002s starting from the beginning of the simulation.

startTime = 0;
periodicity = 0.002;
scheduleAction( ...
    networkSimulator,@displayInfo,userdata,startTime,periodicity);

C) Schedule Action When Simulator Advances in Time

When the simulator advances in time, the displayInfo function displays the next event time of the simulator.

Specify the ActionType input argument value of displayInfo function as "C". Specify the simulator as input to the displayInfo function.

userdata = struct( ...
    ActionType="C", ...
    Simulator=networkSimulator);

Set the periodicity value to 0. Configure the simulator by using the scheduleAction function to display the time of the next event.

startTime = 0;
periodicity = 0;
scheduleAction( ...
    networkSimulator,@displayInfo,userdata,startTime,periodicity);

Run Simulation

Specify the simulation time in seconds.

simulationTime = 0.003;

Run the simulation for the specified simulation time.

run(networkSimulator,simulationTime);

-------Periodic Action -------
Statistics of Node1 at time 0.000 seconds:
                   ReceivedPackets: 0
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 1
                   TransmittedBits: 366

-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00037 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00063 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00075 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00100 seconds
-------End-------
-------One Time Action -------
Node details:
Name: Node1 ID: 1 Role: central
Name: Node2 ID: 2 Role: peripheral
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00108 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00125 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00162 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00187 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00200 seconds
-------End-------
-------Periodic Action -------
Statistics of Node1 at time 0.002 seconds:
                   ReceivedPackets: 2
                    DecodeFailures: 0
                  PacketCollisions: 0
               CoChannelCollisions: 0
               CollisionsWithBREDR: 0
            CollisionsWithNonBREDR: 0
    CollisionsWithBREDRAndNonBREDR: 0
                TransmittedPackets: 2
                   TransmittedBits: 732

-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00200 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00216 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00250 seconds
-------End-------
-------Action When Simulator Advances in Time-------
Simulator next event time is at 0.00287 seconds
-------End-------

function displayInfo(~,userdata)
switch(userdata.ActionType)
    case "A"
        fprintf("-------One Time Action -------\n")
        fprintf("Node details:\n")
        for idx=1:numel(userdata.Nodes)
            fprintf("Name: %s ID: %d Role: %s\n", ...
                userdata.Nodes(idx).Name, ...
                userdata.Nodes(idx).ID, ...
                userdata.Nodes(idx).Role)
        end
        fprintf("-------End-------\n")
        
    case "B"
        fprintf("-------Periodic Action -------\n")
        fprintf("Statistics of %s at time %.3f seconds:\n", ...
            userdata.CentralNode.Name, ...
            userdata.Simulator.CurrentTime);
        stats = statistics(userdata.CentralNode);
        disp(stats.PHY)
        fprintf("-------End-------\n")
    
    case "C"
        fprintf("-------Action When Simulator Advances in Time-------\n")
        fprintf("Simulator next event time is at %.5f seconds\n", ...
            userdata.Simulator.CurrentTime)
        fprintf("-------End-------\n")
end
end

Simulate Wireless Network in Multiple Steps

Create a wireless network simulator.

simulator = wirelessNetworkSimulator.init;

Consider a total simulation duration of 3 seconds. Run the simulation in two steps - 1 second and 2 seconds.

stepDurations = [1 2]; 

Create a custom local function actionCallback to define the action for the simulator to perform during simulation.

function actionCallback(~,userData)
% Print the action type and its execution timeStamp
fprintf("t=%.3f seconds: ActionType=%s executed \n",userData.SimulatorObj.CurrentTime,userData.ActionType);
end

Schedule a pre-simulation action. This action runs only before the first simulation step.

userData = struct(ActionType="PreSimulationAction",SimulatorObj=simulator);
schedulePreSimulationAction(simulator,@actionCallback,userData);

Schedule a post-simulation action. This action runs only after the last simulation step completes.

userData = struct(ActionType="PostSimulationAction",SimulatorObj=simulator);
schedulePostSimulationAction(simulator,@actionCallback,userData);

Create 5G UE and gNB nodes.

gNB = nrGNB;
ue = nrUE;

Connect the UE and gNB nodes.

gNB.connectUE(ue,FullBufferTraffic="on");

Add the nodes to the wireless network simulator.

addNodes(simulator,gNB);
addNodes(simulator,ue);

Run the simulation in multiple steps, and display the gNB medium access control (MAC) layer statistics after each step.

numSimulationSteps = numel(stepDurations);
for i=1:numSimulationSteps
    run(simulator,stepDurations(i),IsLastStep=(i==numSimulationSteps));
    fprintf("t=%.3f seconds: gNB MAC stats after simulation step = %d \n",simulator.CurrentTime,i);
    disp(statistics(gNB).MAC);
end

t=0.000 seconds: ActionType=PreSimulationAction executed 

t=1.000 seconds: gNB MAC stats after simulation step = 1 

     TransmittedPackets: 1000
       TransmittedBytes: 3191700
        ReceivedPackets: 998
          ReceivedBytes: 3523417
        Retransmissions: 0
    RetransmissionBytes: 0

t=3.000 seconds: ActionType=PostSimulationAction executed 

t=3.000 seconds: gNB MAC stats after simulation step = 2 

     TransmittedPackets: 3000
       TransmittedBytes: 9593700
        ReceivedPackets: 2998
          ReceivedBytes: 10591017
        Retransmissions: 0
    RetransmissionBytes: 0

Input Arguments

networkSimulator — Wireless network simulator

wirelessNetworkSimulator object

Wireless network simulator, specified as a wirelessNetworkSimulator object.

simDuration — Duration of simulation

positive scalar

Duration of simulation, specified as a positive scalar. Units are in seconds. The function rounds simDuration to the nearest nanosecond.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

flag — Simulation exit status

true or 1 (default) | false or 0

Simulation exit status after the current run, specified as a numeric or logical 1 (true) or 0 (false). Specifying this argument as false enables you to continue a simulation across multiple steps.

Data Types: logical

Version History

Introduced in R2022b

R2026a: Run simulation in multiple steps

The run function now supports running the simulation in multiple steps by using the new flag argument.

R2026a: Moved to Wireless Network Toolbox from Communications Toolbox Wireless Network Simulation Library

Previously, this feature was available through the Communications Toolbox™ Wireless Network Simulation Library add-on.

R2023a: Moved to Communications Toolbox Wireless Network Simulation Library from Bluetooth Toolbox

Previously, this wirelessNetworkSimulator object function required Bluetooth^® Toolbox.