README.md 6.71 KB
Newer Older
Klaus-Tycho Förster's avatar
Klaus-Tycho Förster committed
1
# Resilionator
Philipp Zabka's avatar
Philipp Zabka committed
2
Resilionator is a small and portable Python application for identifying and mitigating potential weak points in networks. The application is built with Python's standard GUI toolkit [Tkinter](https://docs.python.org/3/library/tkinter.html) and [NetworkX](https://networkx.org/). The tool is intended primarily for university lecturers or students, but also for small and medium-sized companies and households.
Klaus-Tycho Förster's avatar
Klaus-Tycho Förster committed
3

Philipp Zabka's avatar
Philipp Zabka committed
4
# User Documentation
Klaus-Tycho Förster's avatar
Klaus-Tycho Förster committed
5

Philipp Zabka's avatar
Philipp Zabka committed
6
## Installation
Philipp Zabka's avatar
Philipp Zabka committed
7
Resilionator is available for Windows, macOS and Linux (64-bit operating system, x64-based processor). [Download](https://ucloud.univie.ac.at/index.php/s/d4vyPx5EKGnsyy3) the appropriate file for your operating system and follow the steps described above to run the application. 
Philipp Zabka's avatar
Philipp Zabka committed
8

Philipp Zabka's avatar
Philipp Zabka committed
9
10
**Windows**
Download the file located in ```windows/Resilionator.zip```. Unpack it and then double click on the file in order to run it.
Philipp Zabka's avatar
Philipp Zabka committed
11

Philipp Zabka's avatar
Philipp Zabka committed
12
13
14
15
16
**maOS**
Download the file located in ```macOS/Resilionator.zip```. Unpack it and then double click on the file in order to run it.

**Linux (Ubuntu)**
Download the file located in ```linux/Resilionator.zip```. Unpack it and then open the terminal and drag and drop the file into the terminal window then hit enter.
Philipp Zabka's avatar
Philipp Zabka committed
17

Klaus-Tycho Förster's avatar
Klaus-Tycho Förster committed
18

Philipp Zabka's avatar
Philipp Zabka committed
19
## Usage
Philipp Zabka's avatar
Philipp Zabka committed
20
21
22
23
Resilionator offers various functionalities, which are described below:

**Quickmenu (Top)**
The quick menu allows quick access to node/edge creation, creating a test graph or deleting a graph. There is also the option to change the layout of the graph.
Klaus-Tycho Förster's avatar
Klaus-Tycho Förster committed
24

Philipp Zabka's avatar
Philipp Zabka committed
25
**Menu: Graph**
Philipp Zabka's avatar
Philipp Zabka committed
26
27
28
29
- Show graph: Show the current graph.
- Create random graph: Creates a random graph for quick testing.
- Import graph: Import a graph from a ```.txt```, ```.gml``` or ```.graphml``` file. Text file syntax has to be NetworkX compatile. For more details please consult  [file format](https://networkx.org/documentation/stable/reference/readwrite/edgelist.html#format).
- Export graph: Export the graph into a ```.txt```, ```.gml``` or ```.graphml``` file.  
Philipp Zabka's avatar
Philipp Zabka committed
30
- Save graph as image: Save the current graph as ```.png or .jpg```.
Philipp Zabka's avatar
Philipp Zabka committed
31
- Remove graph: Remove the current graph.
Philipp Zabka's avatar
Philipp Zabka committed
32
33
34
35
36
37
38
39
40
- Node
  - Add node: Add a new node to the graph.
  - Remove node: Remove a node from the graph. 
- Edge
  - Add edge: Add a new edge to the graph. The edge endpoints will be created automatically if the do not exist yet.
  - Remove edge: Remove an edge from the graph.

**Menu: Analysis**
- Connectivity
Philipp Zabka's avatar
Philipp Zabka committed
41
42
  - Node connectivity: Check if the current graph is still connected after removing a specific node. This action is peformed for all nodes in the graph. 
  - Edge connectivity: Check if the current graph is still connected after removing a specific edge. This action is peformed for all edges in the graph.
Philipp Zabka's avatar
Philipp Zabka committed
43
- Augmentation
Philipp Zabka's avatar
Philipp Zabka committed
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
  - K-Node augmentation: Make the current graph resilient against one or two node failures.
  - K-Edge augmentation: Make the current graph resilient against one or two edge failures.

**Menu: Routing**
- Dijkstra - Original: Dijkstra shortest path algorithm. A ```source``` and ```target``` node need to be specified. Additionally nodes can be excluded from the path finding process. 
- Dijkstra - Recalulated distances: Dijkstra shortest path algortihm, however distances are recalculated. This prevents the algorithm to get stuck if nodes become unavailable during the routing process.
- Custom Routing: The user can specify his own simple routing process by providing a priority list. 
  - Priority list: A  ```.txt``` file containing the nodes of the graph with their neighbors ordered after their priority. The file doesn't have to contain all nodes or neighbors of a node. However, note that the routing algorithm will ignore nodes or neighbors that are not explicitly listed.
  - Syntax:  ```<node>{<neighbor 1>,<neighbor 2>,...,<neighbor n>}```. 

**Priority list example**
```python
b{c}
c{e,a}
e{l,f,c,a}
a{c,d,e}
l{f,e}
f{g,l,e}
g{j,h}
j{h,k}
k{i}
```

# Developer Documentation

For enhancing Resilionator we recommend a solid knowledge in Python as well as graph theory. Further we recommend some experience with Tkinter and NetworkX.
Resilionator is split into frontend and backend. All calculations concerning networks are processed in the backend. The results are then forwarded to the frontend where they are subsequently displayed. 

Now we introduce some functions in Resilionator, which can be used to out of the box:

## Frames 

- ```createMainFrame```: Creates a frame that is appended to the root window.
- ```createRightFrame``` and ```createLeftFrame```: Creates a paned window. If both frames are created, both will take up an equal amount of space. If only one frame is created it takes up the whole space.
- ```createDualFrameView```: A more convenient way of creating the frames specified above.
- ```createMenu```: Creates drop down menues. 
- ```createPopupWindow```: Creates a toplevel style window which is appended to the root window. 
- ```createCanvas```: Creates a canvas which is necessary form displaying figures which are generated from Matplotlib.
- ```createScrollingFrame```: Creates a scrollable frame, which is appended to the main frame. 

## Garbage collection for frames
Philipp Zabka's avatar
Philipp Zabka committed
85

Philipp Zabka's avatar
Philipp Zabka committed
86
Frames in Tkinter need to be deleted manually, if not done correctly it may cause performance issues.
Philipp Zabka's avatar
Philipp Zabka committed
87

Philipp Zabka's avatar
Philipp Zabka committed
88
89
- ```destroyFrame```: Destroys a specific frame. 
- ```destroyAllFrames```: This method is useful if you want to completely change views. For this method to work, frames need to be added to the ```frames``` list. However if you use any of the methods described above this will happend automatically. 
Philipp Zabka's avatar
Philipp Zabka committed
90

Philipp Zabka's avatar
Philipp Zabka committed
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
## Utility

- ```importGraph```: Imports a graph from a file. Files formats that are currently supported are ```.txt, .graphml and .gml```. 
- ```exportGraph```: Exports a graph to a file. Files formats that are currently supported are ```.txt, .graphml and .gml```. 
- ```saveGraphAsImage```: Saves the graph as an image, currently supported formats are ```.jpg and .png```. 

## Graph

An empty graph is automatically created in the ```init()``` function of the Resilionator class.

- ```addNode```: Adds a new node to the graph.
- ```addEdge```: Adds a new edge to the graph.
- ```removeNode```: Removes a node from the graph. 
- ```removeEdge```: Removes an edge from the graph. 
- ```deleteGraph```: Removes the current graph and creates a new empty graph.
- ```deleteGraph```: Checks if the current graph is empty - has no edges.

## Screenshots

**Homescreen**
![Homescreen](/screenshots/home.png?raw=true "Homescreen")

**Node Connectivity**
![Node connectivity](/screenshots/node_con.png?raw=true "Node connectivity")

**Dijkstra Routing**
![Dijkstra Routing](/screenshots/routing.png?raw=true "Dijkstra Routing")

**Failure Resistance**
![Failure Resistance](/screenshots/resistance.png?raw=true "Failure Resistance")
Philipp Zabka's avatar
Philipp Zabka committed
121

Philipp Zabka's avatar
Philipp Zabka committed
122
123
124
# Resilionator Project Website

Link to the website: https://www.netidee.at/resilionator
Philipp Zabka's avatar
Philipp Zabka committed
125

Philipp Zabka's avatar
Philipp Zabka committed
126
127
**The project Resilionator is funded by netidee.**