search

adfeel220 / Saihu-TSN-Analysis-Tool-Integration

A common interface to easily use multiple TSN analysis tools with simple Python commands
MIT License
15 stars 4 forks source link

readme

Saihu: A Common Interface of Worst-Case Delay Analysis Tools for Time-Sensitive Networks

Author: Chun-Tso Tsai

Advisors: Seyed Mohammadhossein Tabatabaee, Stéphan Plassart, Jean-Yves Le Boudec

Institute: Computer Communications and Applications Laboratory 2 (LCA2), École Polytechnique Fédérale de Lausane (EPFL)

Table of Contents

Introduction

Time-Sensitive Networking (TSN) analysis focuses on giving deterministic delay or backlog guarantees. This project integrates 4 different TSN analysis tools, including Linear TFA Solver, NetCal/DNC, xTFA, and panco. The users can use a common interface to compute network delay bounds obtained by different tools, and write the results into a formated report. All these actions requires only a few lines of code.

A introductory video of the Saihu project is available on YouTube.

The name SAIHU comes from Superimposed worst-case delay Analysis Interface for Human-friendly Usage." It’s also inspired by the Taiwanese word ‘師傅 (sai-hū)’, which means a master, an expert, or a qualified worker.

Cite this project

This repo is the official implementation of Saihu: A Common Interface of Worst-Case Delay Analysis Tools for Time-Sensitive Networks. To cite this project, please use the following information

@misc{tsai2023saihu,
      title={Saihu: A Common Interface of Worst-Case Delay Analysis Tools for Time-Sensitive Networks}, 
      author={Chun-Tso Tsai and Seyed Mohammadhossein Tabatabaee and Stéphan Plassart and Jean-Yves Le Boudec},
      year={2023},
      eprint={2303.14565},
      archivePrefix={arXiv},
      primaryClass={cs.NI}
}

Pipeline

Below states the pipeline and structure of Saihu.

pipeline

From the bottom up, users have the option to use the interface according to the attributes and arrows labelled in red. The blue parts are the functions being handled inside Saihu interface, which integrates the tools labelled in green. The yellow part labels the work one need to do to include more tools in Saihu.

Credit

Here are the authors that implemented the individual tools used in this project.

Project Structure

.
└- README.md
└- tool-usage.md
└- LICENSE.txt
└- src/
   └- environment.yml
   └- setup.py
   └- main.py
   └- example/
   │  └- example.py
   │  └- demo.json
   │  └- demo.xml
   │  └- demo_report.md
   │  └- demo_data.json
   │
   └- saihu/
      └- interface.py
      └- result.py
      └- javapy/
      │  └- dnc_analysis.jar
      │  └- dnc_exe.py
      │  └- NetworkAnalysis
      │     └- NetArgParser.java
      │     └- NetworkScriptHandler.java
      │     └- NetworkAnalysis.java
      │     └- FileGetter.java
      │
      └- Linear_TFA/
      │  └- Linear_TFA.py
      │  └- ...
      │
      └- xTFA/
      │  └- ...
      │
      └- panco/
      │  └- lp_solve
      │  └- lpSolvePath.py
      │  └- panco_analyzer.py
      │  └- ...
      │
      └- netscript/
      │  └- netdef.py
      │  └- netscript.py
      │  └- net_gen.py
      │  └- unit_util.py
      │
      └- resources/
         └- paths.json

File description

Credits to Packages

Installation

Please install the following requirements on your machine.

You can quickly build the project using setup.py by

pip install -e .

Requirements

Dependencies

You may also choose to not install the environment if you choose not to use all tools included in this module. Here are the list of dependency to each tool, you may refer to this list to decide which environment setting you need.

How to Use

You need to write your network in one of the network description format specified below. Then use the Python interface to do the analysis. You would also be able to generate a network by the built-in network generating functions specified in Network Generation.

Network Description File

The tool accepts 2 formats of network description files. The first is Physical Network and the other is Output Port Network. Please find the detail below.

Network Definition

In this section, we briefly introduce the relation between the 2 formats.

Take the following network as an example Demo network This network consists of

Each source of flow (src[x]) provides data flow modelled as an arrival curve composed of token-bucket curves; while each output port provides service to process these data with a service curve composed of rate-latency curves.

A Physical Network aims at directly describing the above network.

On the other hand, since the delay are mostly caused by data flows competing the resource of output ports, we can directly model the network as output ports as follows

output-port-network

Here we remove most details and only focus on the output ports. The 3 flows provides data modelled by an arrival curve, and the 3 involved output ports process them with under the model of their service curves. This abstraction still captures the essential of the network, one can derive the same delay bound at each output port as the completed physical network. We refer this abstracted network as an Output Port Network.

Physical Network

In this section, we introduce the format to define a physical network.

A physical network is defined in WOPANet format as a .xml file. It contains only one elements with the following attributes:

Output-Port Network

An Output-port network is defined as a .json file. It contains only one JSON Object with the following attributes:

Analysis Tools

Tool Specification

Command Line Exection

Use Saihu via command line is possible with main.py. Once you define a network in either of the formats mentioned in Network Description File, you can analyze your network file via the commands line tool below.

Arguments

The priority of the arguments are different. For the arguments regarding tool/method selection, the script search the arguments in the following order: all > method > tool > xtfa = dnc = panco. If a higher priority argument is found, the rest will not be considered.

For the report file related arguments, it's markdown = json-out > export. If non of the three arguments are specified, then it exports the result using the input file name networkFile as naming stem. i.e. python main.py <filename>.<ext> ... equals python main.py <filename>.<ext> -e <filename> ...

All names of tools and methods are case insentisive in Saihu.

Examples

For example, you have a network description file myNet.json

Public Methods

To use our general interface, you need to first import class TSN_Analyzer from the file saihu/interface.py.

from saihu.interface import TSN_Analyzer

Here is a list of all available methods

Init

An analyzer can be initialized by

analyzer = TSN_Analyzer(netfile, temp_path, shaping)

All arguments are optional, each of them represents

set_shaping_mode

analyzer.set_shaping_mode(mode)

Set the output shaping usage of the analyzer by a string of either AUTO, ON, or OFF. AUTO means considering output shaping if possible. ON and OFF are forcing analyzer to consider output shaping or not, and don't compute result if not possible.

convert_netfile

outputport_net_file, physical_net_file = analyzer.convert_netfile(in_netfile, out_netfile, target)

Convert a network description file from either physical network or output-port network and return both paths of network definition files, where one is converted from the original infile.

The 2 return values are paths to the network description files, one is the output-port network and the other is the physical network.

analyze_all

num_results = analyzer.analyze_all(methods, netfile, use_tfa, use_sfa)

Use all available tools to do analysis given the methods. Return number of results that are computed. All parameters are optional:

The function returns the number of results loaded from the process.

analyze_xtfa

analyzer.analyze_xtfa(methods, netfile)

Analyze the network with xTFA. All parameters are optional:

analyze_linear

analyzer.analyze_linear(methods, netfile)

Analyze the network with Linear TFA solver. All parameters are optional:

analyze_panco

analyzer.analyze_panco(methods, netfile, use_tfa, use_sfa)

Analyze the network with panco. All parameters are optional:

analyze_dnc

analyzer.analyze_panco(methods, netfile)

Analyze the network with DNC. All parameters are optional:

export

analyzer.export(default_name, result_json, report_md, clear)

Write the JSON result and Markdown report at the same time. All parameters are optional:

write_result_json

analyzer.write_result_json(output_file, clear)

Write the analyze result report from all the stored results.

write_report_md

analyzer.write_report_md(output_file, clear)

Write the analyze result report from all the stored results.

clear

Reset the analyzer.

analyzer.clear()

Network Generation

Certain Network Type

Use functions from src/netscript/net_gen.py, there are 3 types of network that can be generated automatically. All servers and flows would have the same arrival curve, service curve, and shaper. Networks will be generated into output-port network in .json format.

All 3 methods take the same parameters:

Random Network with Fixed Topology

One can also generate a random network from a fixed topology. The user can choose how many flows are going into this network and the arrival/service curve specifications, this function automatically generates a corresponding output-port network (JSON) to represent it.

Say one would like to randomly generate a network with this following switch inter-connection (source: Deficit Round-Robin: A Second Network Calculus Analysis):

industrial-network

Then one can generate a network as follows:

connections = {
    "S1": [      "S2", "S3",                         "S8"],
    "S2": ["S1",             "S4",                   "S8"],
    "S3": ["S1",             "S4", "S5",       "S7", "S8"],
    "S4": [      "S2", "S3",             "S6", "S7", "S8"],
    "S5": [            "S3",             "S6", "S7"],
    "S6": [                  "S4", "S5",       "S7"],
    "S7": [            "S3", "S4", "S5", "S6"],
    "S8": ["S1", "S2", "S3", "S4"]
}
generate_fix_topology_network(num_flows=30, connections=connections,
                              burst="10B", arrival_rate=("200bps", "20kbps"), max_packet_length="6kB",
                              latency=("2us", "200ms"), service_rate=("1Mbps", "50Mbps"), capacity="100Mbps",
                              save_dir="rand_net.json",
                              link_prob=0.9)

The above code generates 30 flows within the given topology, and dump the output port network as rand_net.json. Note that the flow/server parameters can be decided randomly or deterministically. The above example shows that for burst it's a constant "10B" (10 Bytes) whereas other parameters are decided uniform-randomly among a (min, max) value pair.

Parameters

Example

The simplest way to use Saihu is via command line tool using main.py with flag -a (analyze with all methods and tools).

python main.py -a

To use Saihu as a Python package, please check example.py for the simple example. Here I present the basic usage.

from saihu.interface import TSN_Analyzer

if __name__ == "__main__":
    analyzer = TSN_Analyzer("./demo.json", temp_path="./temp/", use_shaper="AUTO")
    analyzer.analyze_all()
    analyzer.export("test")

Specific Tools

While analyze_all tries all possible tools, you may also specify which tool you want to use. For example,

analyzer = TSN_Analyzer("./demo.json")
analyzer.analyze_panco(methods=["TFA", "PLP"])
analyzer.analyze_dnc(methods="TFA")
analyzer.export("panco_dnc")     # Containing both panco and DNC results

Note that any function called analyze_xxx only puts the result into the analyzer's internal buffer. When you call export/write_result_json/write_report_md, it simply takes all the stored results and write them into the report. Under default setting, the buffer is cleaned after writing results.

You can also choose to not clearing the result buffer after writing a report.

analyzer = TSN_Analyzer("./demo.json")
analyzer.analyze_panco(methods=["TFA", "PLP"])
analyzer.export("panco", clear=False) # Write panco results

analyzer.analyze_dnc(methods="TFA")
analyzer.export("panco_dnc") # Write results including both panco and DNC

Selecting Shaper

You may change shaper selection any time you want.

analyzer = TSN_Analyzer("./demo.json", use_shaper="ON")
analyzer.analyze_panco(methods=["TFA", "PLP"]) # Analysis with shaper
analyzer.set_shaper_usage("OFF")               # Turn off using shaper
analyzer.analyze_xtfa(methods="TFA")           # Analysis without shaper
analyzer.write_report_md("./demo_report.md")      # panco TFA & PLP is with shaper, xtfa is without shaper

Specific Networks

Late assignment of network

You may assign different networks every time you want to analyze.

analyzer = TSN_Analyzer()
analyzer.analyze_linear(netfile="./demo.json")
analyzer.write_report_md("./linear_report.md")

Multiple networks

When there are multiple networks (different network names defined in network attributes of description files), the program generate multiple reports for each network. The extra report files are named by adding index to the original file. For example,

analyzer = TSN_Analyzer("./demo.xml", temp_path="./temp/", use_shaper="AUTO")
analyzer.analyze_all(methods=["TFA", "PLP"]) # Analyze "demo.xml"
analyzer.analyze_linear("./mesh.json")       # Analyze "mesh.json"
analyzer.write_report_md("./report.md")

Such code generates 2 files report.md and report-1.md, one reports demo and the other reports mesh. However, I suggest users to manually write each result when needed because the suitable multiplier is chosen among all results.

Incorrect type of network

The interface automatically converts the network description file when the input file is not in the right format for the tool. The desired input format for xTFA is physical network and all other tools take output-port network.

analyzer = TSN_Analyzer("./demo.xml", temp_path="./temp/", use_shaper="AUTO")
analyzer.analyze_linear()
analyzer.write_report_md("./report.md")

The above analysis still gives the report although linear TFA solver should take a output-port network in .json format.

Generate Network and Analysis

You can use the network generation functions to generate the following 3 types of networks interleave tandem, ring, and mesh. About their topology and how the flows are assigned, please see Network Generation. Say you would like to generate a ring network of 10 servers, you can do the following.

from saihu.interface import TSN_Analyzer
from saihu.netscript.net_gen import *

generate_ring(size=10,
              burst=1,
              arrival_rate=1,
              max_packet_length=0,
              latency=1,
              service_rate=20,
              capacity=20,
              save_dir="./ring.json")
analyzer = TSN_Analyzer("./ring.json", temp_path="./temp/", use_shaper="AUTO")
analyzer.analyze_all()
analyzer.write_report_md("./ring_report.md")

The arguments for each type of network are the same, you can simply change ring to other generating functions.

Extend this Project

This project is possible to extend for more functionality and possibly includes more TSN analysis tools. Here explains how can anyone extend the scope of this project.

Files

Here are some files you may use/edit to allow the tool to fit your new tool.

Depends on how your tool defines a network, you may need to implement the interface to take one of the network description file format, and load the analysis result into a TSN_result class.

Standard Analysis Result

Please refer to the file result.py, any analysis result should be stored as a TSN_result class. So that you don't need to worry about how to write your result. The method export/write_result_json/write_report_md automatically processes TSN_result and write the corresponding output. It's OK if your tool cannot fit all the properties of TSN_result, they all have default values, but you should at least specify name, tool, method, graph, and flow_delays to properly generate the report.

Here are the meaning of each property in TSN_result:

Contact

Regarding any question/problem about this project, please contact me via E-mail: academic, primary, or secondary.