RF and traffic scenarios

A scenario describes what happens to a reservation’s radios while it runs. An RF scenario sets the channel between each pair of nodes over time, such as the path loss from one node to another. A traffic scenario describes the network traffic that the nodes send each other. You can run either kind in a running reservation, as described below, or have a batch reservation run them for you.

Listing scenarios

The Traffic Scenarios and RF Scenarios links on the Grid web page list the scenarios you can use. The commands gridcli tg scenarios and gridcli rf scenarios list them too, with each scenario’s duration and, for an RF scenario, its number of nodes.

Public scenarios are named by their file name without its suffix, e.g., single1MB. Your own scenarios are named by your username and their file name, e.g., USERNAME/single1MB. You can name a scenario by either its name or its unique identifier.

Adding your own scenarios

Put your traffic scenarios in a directory named tgscenarios in your home directory, and your RF scenarios in a directory named rfscenarios. The Grid finds new and changed files in these directories automatically. Only files directly in these directories are used, not files in subdirectories. As with images, the files must be readable by all users, which you can accomplish by running chmod 0444 FILE. Other users still cannot use your scenarios on the Grid.

Traffic scenarios

A traffic scenario is a YAML or JSON file whose name ends in .yaml, .yml, or .json. The following scenario has two nodes. After 15 seconds, node 2 sends node 1 one flow of 1,000,000 bytes per second in 625-byte UDP packets until the scenario ends at 75 seconds.

name: "Single 1 MBps flow"
description: |-
  After 15 seconds, node 2 sends node 1 one flow at 1 MBps for 60 seconds.
duration: 75
phases:
  - start: 15
    flows:
      1001:
        src: 2
        dst: 1
        rate: 1000000
        size: 625
  • duration is the scenario’s length in seconds.
  • phases is a list of phases, each of which begins start seconds after the scenario does.
  • flows maps each flow’s number to the flow. A flow runs from the phase that starts it until a phase that does not list it, or until the scenario ends. A later phase that lists the flow again can change its rate or packet size.
  • src and dst are scenario node numbers, which start at 1.
  • rate is the flow’s rate in bytes per second, 1,048,576 by default, and size is its packet size in bytes, 1,024 by default.
  • port is the UDP port that the flow is sent to. It is the flow’s number by default.

RF scenarios

An RF scenario is an HDF5 file whose name ends in .h5. It gives the gain of the channel from each node to every other node over time, along with the scenario’s name, description, and number of nodes.

Running a scenario in a reservation

To run a traffic scenario, every node in the reservation must have a traffic interface, so schedule the reservation with the --traffic option. Then, once the reservation is running, start the scenario with gridcli tg start SCENARIO RESERVATION, where RESERVATION is the reservation’s unique identifier or name. You may leave out RESERVATION if you have only one active reservation. If your image runs Dragon Radio, add the --routes option so that the traffic is routed over the radios. gridcli tg info shows the traffic session, and gridcli tg stop stops it.

To run an RF scenario, use gridcli rf start SCENARIO RESERVATION. The --duration DURATION option stops the scenario after DURATION, and the --cycle option repeats it.

Both commands start the scenario immediately unless you give a later start time with --start TIME. A reservation can run one traffic scenario and one RF scenario at a time.

Choosing which node plays which part

By default, the reservation’s nodes, sorted by name, become scenario nodes 1, 2, and so on, so in a reservation of grid07 and grid12, grid07 is node 1. To choose differently, write a YAML file that maps each node to its scenario node, and pass it with --node-map PATH:

grid12: 1
grid07: 2