You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+75-26Lines changed: 75 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,51 +1,71 @@
1
1
# ns3-ai
2
+
2
3
## Online Tutorial:
3
-
Join us in this [online recording](https://vimeo.com/566296651) to get better knowledge about ns3-ai! The slides introduce the ns3-ai model could also be found [here](https://www.nsnam.org/wp-content/uploads/2021/tutorials/ns3-ai-tutorial-June-2021.pdf)!
4
+
5
+
Join us in this [online recording](https://vimeo.com/566296651) to get better knowledge about ns3-ai! The slides
6
+
introduce the ns3-ai model could also be
7
+
found [here](https://www.nsnam.org/wp-content/uploads/2021/tutorials/ns3-ai-tutorial-June-2021.pdf)!
8
+
4
9
## Description
5
-
The [ns–3](https://www.nsnam.org/) simulator is an open-source networking simulation tool implemented by C++ and wildly used for network research and education. Currently, more and more researchers are willing to apply AI algorithms to network research. Most AI algorithms are likely to rely on open source frameworks such as [TensorFlow](https://www.tensorflow.org/) and [PyTorch](https://pytorch.org/). These two parts are developed independently and extremely hard to merge, so it is more reasonable and convenient to connect these two tasks with data interaction. Our model provides a high-efficiency solution to enable the data interaction between ns-3 and other python based AI frameworks.
6
10
7
-
This module does not provide any AI algorithms or rely on any frameworks but instead is providing a Python module that enables AI interconnect, so the AI framework needs to be separately installed. You only need to clone or download this work, then import the Python modules, you could use this work to exchange data between ns-3 and your AI algorithms.
11
+
The [ns–3](https://www.nsnam.org/) simulator is an open-source networking simulation tool implemented by C++ and wildly
12
+
used for network research and education. Currently, more and more researchers are willing to apply AI algorithms to
13
+
network research. Most AI algorithms are likely to rely on open source frameworks such
14
+
as [TensorFlow](https://www.tensorflow.org/) and [PyTorch](https://pytorch.org/). These two parts are developed
15
+
independently and extremely hard to merge, so it is more reasonable and convenient to connect these two tasks with data
16
+
interaction. Our model provides a high-efficiency solution to enable the data interaction between ns-3 and other python
17
+
based AI frameworks.
8
18
19
+
This module does not provide any AI algorithms or rely on any frameworks but instead is providing a Python module that
20
+
enables AI interconnect, so the AI framework needs to be separately installed. You only need to clone or download this
21
+
work, then import the Python modules, you could use this work to exchange data between ns-3 and your AI algorithms.
9
22
10
-
Inspired by [ns3-gym](https://github.com/tkn-tub/ns3-gym), but using a different approach which is faster and more flexible.
23
+
Inspired by [ns3-gym](https://github.com/tkn-tub/ns3-gym), but using a different approach which is faster and more
24
+
flexible.
11
25
12
26
### Features
13
-
- High-performance data interaction module (using shared memory).
27
+
28
+
- High-performance data interaction module (using shared memory).
14
29
- Provide a high-level interface for different AI algorithms.
15
30
- Easy to integrate with other AI frameworks.
16
31
17
-
18
32
## Installation
33
+
19
34
### 1. Install this module in ns-3
20
-
#### Get ns-3:
35
+
36
+
#### Get ns-3:
37
+
21
38
This module needs to be built within ns-3, so you need to get a ns-3-dev or other ns-3 codes first.
22
39
23
40
Check [ns-3 installation wiki](https://www.nsnam.org/wiki/Installation) for detailed instructions.
Python 3 is used and tested. It's recommended to use ns3-ai under a Conda environment.
41
61
42
62
```Shell
43
63
cd$YOUR_NS3_CODE/contrib/ns3-ai/py_interface
44
-
45
64
pip3 install . --user
46
65
```
47
66
48
-
#### Baisc usage
67
+
#### Basic usage
68
+
49
69
```Python
50
70
import py_interface
51
71
mempool_key =1234# memory pool key, arbitrary integer large than 1000
@@ -59,9 +79,21 @@ with v as o:
59
79
print(*o)
60
80
py_interface.FreeMemory()
61
81
```
82
+
62
83
## Shared Memory Pool
63
-
The ns3-ai module interconnects the ns-3 and AI frameworks by transferring data through the shared memory pool. The memory can be accessed by both sides and controlled mainly in ns-3. The shared memory pool is defined in `ns3-ai/model/memory-pool.h`.
64
-
The `CtrlInfoBlock` is the control block of the all shared memory pool, the `SharedMemoryCtrl` is the control block of each shared memory, and the `SharedMemoryLockable` is the actual shared memory used for data exchange. In each memory block, we use version and nextVersion as the lock indicator. The synchronization for reading/writing locks and the events update are accomplished by the lock indicator. For every process that wants to access or modify the data, it will compare the `version` variable and the `nextVersion` variable. If they are the same, it means that the memory is reachable. Then it will add one to the next version atomically to lock the memory and also add one to the version after its operation to the memory to unlock the memory. Besides the version of the memory acts as the signal to tell different processes the current state of the memory block, which provides different methods to synchronize.
84
+
85
+
The ns3-ai module interconnects the ns-3 and AI frameworks by transferring data through the shared memory pool. The
86
+
memory can be accessed by both sides and controlled mainly in ns-3. The shared memory pool is defined
87
+
in `ns3-ai/model/memory-pool.h`.
88
+
The `CtrlInfoBlock` is the control block of the all shared memory pool, the `SharedMemoryCtrl` is the control block of
89
+
each shared memory, and the `SharedMemoryLockable` is the actual shared memory used for data exchange. In each memory
90
+
block, we use version and nextVersion as the lock indicator. The synchronization for reading/writing locks and the
91
+
events update are accomplished by the lock indicator. For every process that wants to access or modify the data, it will
92
+
compare the `version` variable and the `nextVersion` variable. If they are the same, it means that the memory is
93
+
reachable. Then it will add one to the next version atomically to lock the memory and also add one to the version after
94
+
its operation to the memory to unlock the memory. Besides the version of the memory acts as the signal to tell different
95
+
processes the current state of the memory block, which provides different methods to synchronize.
96
+
65
97
```
66
98
|SharedMemoryBlock1|
67
99
|SharedMemoryBlock2|
@@ -75,44 +107,59 @@ The `CtrlInfoBlock` is the control block of the all shared memory pool, the `Sha
75
107
|MemoryPoolContrlBlk|
76
108
```
77
109
110
+
## Examples
78
111
112
+
### Quick Start on how to us ns3-ai - [a_plus_b](https://github.com/hust-diangroup/ns3-ai/tree/master/examples/a_plus_b)
79
113
80
-
## Examples
81
-
### Quick Statrt on how to us ns3-ai - [a_plus_b](https://github.com/hust-diangroup/ns3-ai/tree/master/examples/a_plus_b)
82
-
This example show how you can use ns3-ai by a very simple case that you transfer the data from ns-3 to python side and calculate a + b in the python to put back the results. Please check the README in it for more details.
114
+
This example show how you can use ns3-ai by a very simple case that you transfer the data from ns-3 to python side and
115
+
calculate a + b in the python to put back the results. Please check the README in it for more details.
This example is inspired by [ns3-gym example](https://github.com/tkn-tub/ns3-gym#rl-tcp). We bulid this example for the benchmarking and to compare with their module.
118
+
119
+
This example is inspired by [ns3-gym example](https://github.com/tkn-tub/ns3-gym#rl-tcp). We build this example for the
This original work is done based on [5G NR](https://5g-lena.cttc.es/) branch in ns-3. We made some changes to make it also run in LTE codebase in ns-3 mainline. We didn't reproduce all the experiments on LTE, and the results used in this document are based on NR work.
133
+
134
+
This original work is done based on [5G NR](https://5g-lena.cttc.es/) branch in ns-3. We made some changes to make it
135
+
also run in LTE codebase in ns-3 mainline. We didn't reproduce all the experiments on LTE, and the results used in this
136
+
document are based on NR work.
96
137
97
138
#### Build and Run
98
139
99
140
Run ns-3 example:
100
-
If you want to test the LSTM, you can run another python script but you may need to install [TensorFlow](https://www.tensorflow.org/) environment first.
141
+
If you want to test the LSTM, you can run another python script but you may need to
0 commit comments