simple-emulator 0.1.0

The competition system for MMGC 2021

Quickly Start

For pypi

We have package our repository into simple-emulator, which means that you can run order

pip install simple-emulator

to install it.

There may be some differences between this and below. But you can finished according to the next steps :

• create your module

from simple_emulator import BlockSelection, CongestionControl


# Your solution should include packet selection and congestion control.
# So, we recommend you to achieve it by inherit the objects we provided and overwritten necessary method.
class Solution(BlockSelection, CongestionControl):
    pass

• create emulator

from simple_emulator import SimpleEmulator


# Use the object you created above
my_solution = Solution()
emulator = SimpleEmulator(solution=my_solution)

• run emualtor

# You can specify the time for the emualtor's running.
# It will run until there is no packet can sent by default. 
emulator.run_for_dur()

Here is an complete demo about the using of pypi.

For this repository

For players, you need to finish the code both of "congestion_control_algorithm.py" and "block_selection.py" files in path of "/player".

Here we provide you some congestion control algorithm. By default the congestion control is "reno" and block selection algorithm is selecting block which is closest to it's deadline.

Then, just run the order "python3 run_this.py".

You will get some output in the path "/output/" and should fix your code according to the output.

Here is an complete demo about the using of this repository.

For Detail

player

Here are the 3 methods that players need to finished.

aitrans_solution.py

It should be implemented with these method :

• select_block
• on_packet_sent
• cc_trigger

In case you forget, we recommend you implement by inheriting the objects from Solution in block_selection.py and Solution in congestion_control_algorithm.py and overwrite these methods.

Here is the explanations of Input and Output .

block_selection.py

In this module, you have to implement the function "select_block" with the parameters "cur_time, block_queue" and return an integer value which means the block index in block queue, which will be sent at the time "cur_time".

Here we provided a example of selecting block by the create time firstly, and radio of rest life time to deadline secondly.

select_block

For every block in block queue, it's implement in "objects/block.py". But we recommend you to get more information at Block .

congestion_control_algorithm.py

In this module, you have to implement a class with member function "on_packet_sent" and "cc_trigger". So we recommend you to accomplish this by inheriting from the object of "CongestionControl" implemented in "cc_base.py" in case you forget these.

Here we provided some simple algorithms about congestion control to help you being familiar with this competition. Like Reno and an example about reinforcement learning implemented by tensorflow.

on_packet_sent

For the member function "on_packet_sent", we will call it every time I want to send a packet. And it should return a dictionary with window size and send rate according to the information from "_input_list", just like below.

{
    "cwnd" : 10,
    "send_rate" : 10
}

cc_trigger

For every item information in "_input_list", it is a two-tuple of (cur_time, event_info).

• cur_time

  The time when the packet arrived.

• event_info

  • event_type

    We divide the packet into three categories : PACKET_TYPE_FINISHED, PACKET_TYPE_TEMP, PACKET_TYPE_DROP.

    PACKET_TYPE_FINISHED : The acknowledge packet that successfully reached the source point;

    PACKET_TYPE_TEMP : The packet that have not yet reached the source point;

    PACKET_TYPE_DROP : The packet used to inform the source point of packet loss.

  • packet_information_dict

    The packet it the object implemented in "objects/packet.py". But we recommend you to get more information at Packet .

Why we design a individual function to add element to "_input_list"?

It's because there are some congestion control algorithm that need to update window size and send rate immediately. So you need to return a dictionary with window size and send rate if you want to do some changes as soon as the data is received , like here.

The calculation of score

We use this QOE function to calculate score of your solution : $$ QOE = \sum_{block \in Blocks} \alphapriority + \betaMiss_ddl $$ And here is parameters' explanation.

config

constant

Here are some constants that may be help for you：

• USE_CWND

  Set "True" if your congestion control algorithm use cwnd.

• ENABLE_LOG

  Set "False" if you don't want to generate packet log in path "output/packet_log".

• MAX_PACKET_LOG_ROWS

  The number of rows for a single packet log. If you just want to use one file to log, set it "None".

All of these constants can be set on the create of emulator by the key words arguments.

Block data

We create the block by using the file "data_audio.csv" and "data_video.csv" which are record from WebRTC.

For "data_audio.csv", the first columns is the created time of block and the second columns is the block size.

Time (s)	Block Size (B)
0.0	514
0.06	305
...	...

For "data_video.csv", it has the same columns like "data_audio.csv" except the third columns, which means P frame or I frame.

Time (s)	Block_size (B)	Frame Type
0.0	9584	P
0.033	8069	P
...	...	...

Trace data

We use the generated trace data by using the Hidden Markov algorithm to simulate the bandwidth changing of the network, which is implemented in "scripts/network.py".

For the trace file, the first columns is the changed time of bandwidth. The second columns is the bandwidth whose unit is megabytes. And the third columns is the link random loss rate. Finally, the last columns is the fixed propagation delay of link whose unit is seconds.

Time (s)	Bandwidth (MB)	Loss Rate(%)	Propagation Delay (s)
0	19.38592070201254	0	0.001
1	24.832955411664393	0	0.001
...	...	...	...

objects

Here are all the objects that our system uses. You can get more details from our powerpoint presentation.

What I want to emphasize here is that, your congestion control module, which implemented in "player/congestion_control_algorithm.py", should inherit from the object of "CongestionControl" implemented in "cc_base.py".

We've provided some examples of classic congestion control algorithms in path "player/examples", like Reno.

output

packet log

We will output all the packet log into the directory. Here you can get one packet all life time.

Because of there may be so many packet information that logging file is big. So we split all information into different files if its rows exceed MAX_PACKET_LOG_ROWS which you can reset in "config/constant.py".

For every row, it's form like below：

{
    "Time": 0.0, 
    "Waiting_for_ack_nums": 0, 
    "Sender_id": 1, 
    "Type": "S", 
    "Position": 0, 
    "Send_delay": 0.0, 
    "Pacing_delay": 0.0, 
    "Latency": 0.0, 
    "Drop": 0, 
    "Packet_id": 1, 
    "Create_time": 0.0, 
    "Offset": 0, 
    "Payload": 1480, 
    "Packet_size": 1500, 
    "Extra": {
        "Cwnd": 1
    }, 
    "Block_info": {
        "Block_id": 1, 
        "Priority": "0", 
        "Deadline": 0.2, 
        "Create_time": 0.0, 
        "Size": 200000.0
    }
}

Here is every key's explanation：

• Time : The time handle this event;
• Waiting_for_ack_nums : The numbers of packets that sended but not acknowledged by source.
• Sender_id : The sender's id that sent this packet;
• Type : To distinguish sending or acknowledge packet;
• Position : The position that packet on. It's 0 if packet on source'
• Send_delay : The time that packet sent into window;
• Pacing_delay : The time that packet send into network. It's used in the congestion control like BBR.
• Latency : The time that packet spending on links including queue delay and propagation delay;
• Drop : Label whether the packet is dropped;
• Packet_id : The Identity of packet;
• Create_time : The time when the packet is created;
• Offset : The offset of the packet in its block;
• Payload : The size of valid data in packet whose unit is bytes;
• Packet_size : The size of the packet whose unit is bytes;
• Extra : The filed we provided for your congestion control. We will fill it when system need to send packet (equals to calling "on_packet_sent" method in your solution).
  • Cwnd : The size of crowded window at sender.Its unit is packet;
• Block_info : The block information that the packet belong to. You can get more from below.

block log

Here is all of the blocks that the system sent.

For every row, it's form like below：

{
    "Block_id": 4, 
    "Priority": "0", 
    "Deadline": 0.2, 
    "Create_time": 3.0, 
    "Size": 200000.0, 
    "Send_delay": 0.0, 
    "Latency": 1.4900000000000104, 
    "Finish_timestamp": 3.0425, 
    "Miss_ddl": 0, 
    "Split_nums": 136, 
    "Finished_bytes": 200000.0
}

Here is every key's explanation：

• Priority : The degree of emergency of block;
• Block_id : The identity of block;
• Size : The size of block whose unit is bytes;
• Deadline : The block's failure time size;
• Create_time : The time when block is created;
• Send_delay : The sum of all packets's "send_delay" which belong to the block;
• Latency : The sum of all packets's "latency" which belong to the block;
• Finish_timestamp : The time when block is finished if it don't miss deadine; Otherwise, it's the time when the block was detected failure;
• Miss_ddl : Whether the block is miss deadline;
• Split_nums : The count of packets that the block is divided;
• Finished_bytes : The number of bytes received by the receiver.

cwnd_changing.png

Here we provided a simple schematic diagram of window change process according to partial packet log.

The horizontal axis is the time(seconds), the left vertical axis is the number of packets, and the right vertical axis is the bandwidth (unit is packet).So solid lines represent window changes and dashed lines represent bandwidth changes.

We put the draw function in the "plot_cwnd" of "utils.py". You can specify the value of "raws" to set the amount of data to be processed, specify the value of "time_range" to set the the time interval you want see, and specify the value of "scatter" to use a line chart or scatter chart.

emulator-analysis.png

Here we provided a simple schematic diagram of latency of packets change process according to partial packet log.

The horizontal axis is the time(seconds), the left vertical axis is the latency of packets. So solid lines represent latency changes. And the cross indicates that the packet was lost at this time.

We put the draw function in the "analyze_emulator" of "utils.py". You also can describe these parameters mentioned above and do some customization, like "rows", "time_range" and "scatter".

throughput_changing.png

Appendix

Input

Variable	Explanation	Sample
cur_time	current time(s)	0.0（s）
block_queue	The block queue currently to be sent at the sender, the field information of each packet is shown in the table packet_queue	[packet_1, packet_2]
event_info	For the ACK or Lost information returned by the receiving end, the field information of each packet is shown in the table event_info	[event_type, packet_information_dict]

Output

Variable	Explanation	Sample
block_index	The index value of the block to be sent at the current moment in block_queue	1(int)
Cwnd	The current congestion window size of the sender	10（packet）
Send_rate	The sending rate of the sender at the current moment	5（packet/s）

Table : block_queue

Variable	Explanation	Sample
create_time	The time when the packet was created	0.1（s）
offset	The offset of the packet in the block to which it belongs	1（int）
packet_id	ID of the packet, globally unique	1（int）
payload	The actual effective data size of the packet in block（Bytes）	1480（Bytes）
packet_size	The actual size of the packet(Bytes)	1500（Bytes）
block_info	The information of the block to which the packet belongs, the type is dict, and the field information contained in it is shown in the table block_info	0.0（s）
retrans	Indicates whether the packet is a retransmission packet	False (Bool)

Table : block_info

Variable	Explanation	Sample
Block_id	Block ID, globally unique	1（int）
Priority	The priority of the block, the values are 0, 1, and 2	1（int）
Deadline	Block expiration time size	0.2（s）
Create_time	The time when the block was created	0.1（s）
Size	Block size(Bytes)	200000（Bytes）
Split_nums	The number of packets that the block is splitter	5 (int)

Table : event_info

Variable	Explanation	Sample
event_type	The event type of the packet, the values can be F, D, and T, which represent completed packets, dropped packets, and intermediate state packets (that is, packets other than the first two types)	F（str）
packet_information_dict	A dictionary composed of the brief information of the packet, the field information of each packet is shown in the table packet_information_dict

Table : packet_information_dict

Variable	Explanation	Sample
Send_delay	Send delay	0.1（s）
Latency	The delay spent by the packet on the link, including the queuing delay of all hops that have passed and the propagation delay of the link	0.2（s）
Drop	Whether the packet is a packet indicating discarded information	0（int)
Packet_id	ID of the packet, globally unique	100（int）
Create_time	The time when the packet was created	0.0（s）
Offset	The offset of the packet in the block to which it belongs	0（int）
Payload	The actual effective data size of the packet in block(Bytes)	1480（Byte）
Packet_size	The actual size of the packet(Bytes)	1500（Byte）
Block_info	The information of the block to which the packet belongs, the type is dict, and the field information contained in it is shown in the table block_info
Extra	Additional information. This field provides players with customized information. Each time a packet is sent, the "on_packet_sent" function in the player module will be called to obtain the latest Extra field information returned by it. Fill in the packet, which may contain See the table for field information Extra

Table : Extra

Variable	Explanation	Sample
Cwnd	The size of the congestion window of the sender at the current moment, the unit is a packet, which is valid only when the congestion window is used	5 (packet)
Send_rate	The sending rate of the sender at the current moment, the unit is packet/s, currently only valid when the player uses the rate-based congestion algorithm	10 (packet/s)
inflight	The number of packets that have been sent by the sender but have not received ack or lost information at the current moment	10 (packet)

Table : QOE_parameters

Variable	Explanation	Sample
Priority	The priority of the block, the values are 0, 1, and 2	0 (int)
Miss_ddl	whether the block miss deadline	1 (int)