|
1 | | -# The Network Simulator, Version 3 |
| 1 | +# mmWave ns-3 module # |
2 | 2 |
|
3 | | -## Table of Contents |
| 3 | +This is an [ns-3](https://www.nsnam.org "ns-3 Website") module for the simulation |
| 4 | +of 5G cellular networks operating at mmWaves. A description of this module can be found in [this paper](https://ieeexplore.ieee.org/document/8344116/ "mmwave paper"). |
4 | 5 |
|
5 | | -1) [An overview](#an-open-source-project) |
6 | | -2) [Building ns-3](#building-ns-3) |
7 | | -3) [Running ns-3](#running-ns-3) |
8 | | -4) [Getting access to the ns-3 documentation](#getting-access-to-the-ns-3-documentation) |
9 | | -5) [Working with the development version of ns-3](#working-with-the-development-version-of-ns-3) |
| 6 | +Main features: |
10 | 7 |
|
11 | | -> **NOTE**: Much more substantial information about ns-3 can be found at |
12 | | -<https://www.nsnam.org> |
| 8 | +* Support of a wide range of channel models, including the model based on 3GPP TR 38.901 for frequencies between 0.5 and 100 GHz. Ray tracing and measured traces can also be used. |
13 | 9 |
|
14 | | -## An Open Source project |
| 10 | +* Custom PHY and MAC classes supporting the 3GPP NR frame structure and numerologies. |
15 | 11 |
|
16 | | -ns-3 is a free open source project aiming to build a discrete-event |
17 | | -network simulator targeted for simulation research and education. |
18 | | -This is a collaborative project; we hope that |
19 | | -the missing pieces of the models we have not yet implemented |
20 | | -will be contributed by the community in an open collaboration |
21 | | -process. |
| 12 | +* Custom schedulers for supporting dynamic TDD formats |
22 | 13 |
|
23 | | -The process of contributing to the ns-3 project varies with |
24 | | -the people involved, the amount of time they can invest |
25 | | -and the type of model they want to work on, but the current |
26 | | -process that the project tries to follow is described here: |
27 | | -<https://www.nsnam.org/developers/contributing-code/> |
| 14 | +* Carrier Aggregation at the MAC layer |
28 | 15 |
|
29 | | -This README excerpts some details from a more extensive |
30 | | -tutorial that is maintained at: |
31 | | -<https://www.nsnam.org/documentation/latest/> |
| 16 | +* Enhancements to the RLC layer with re-segmentation of packets for retransmissions |
32 | 17 |
|
33 | | -## Building ns-3 |
| 18 | +* Dual Connectivity with LTE base stations, with fast secondary cell handover and channel tracking |
34 | 19 |
|
35 | | -The code for the framework and the default models provided |
36 | | -by ns-3 is built as a set of libraries. User simulations |
37 | | -are expected to be written as simple programs that make |
38 | | -use of these ns-3 libraries. |
| 20 | +* Simulation of core network elements (with also the MME as a real node) |
39 | 21 |
|
40 | | -To build the set of default libraries and the example |
41 | | -programs included in this package, you need to use the |
42 | | -tool 'ns3'. Detailed information on how to use ns3 is |
43 | | -included in the file doc/build.txt |
| 22 | +## Installation |
| 23 | +This repository contains a complete ns-3 installation with the addition of the mmwave module. |
44 | 24 |
|
45 | | -However, the real quick and dirty way to get started is to |
46 | | -type the command |
47 | | - |
48 | | -```shell |
49 | | -./ns3 configure --enable-examples |
| 25 | +Use these commands to download and build `ns3-mmwave`: |
50 | 26 | ``` |
51 | | - |
52 | | -followed by |
53 | | - |
54 | | -```shell |
55 | | -./ns3 |
| 27 | +git clone https://github.com/nyuwireless-unipd/ns3-mmwave.git |
| 28 | +cd ns3-mmwave |
| 29 | +./ns3 configure --disable-python --enable-examples && ./ns3 build |
56 | 30 | ``` |
57 | 31 |
|
58 | | -in the directory which contains this README file. The files |
59 | | -built will be copied in the build/ directory. |
60 | | - |
61 | | -The current codebase is expected to build and run on the |
62 | | -set of platforms listed in the [release notes](RELEASE_NOTES.md) |
63 | | -file. |
| 32 | +## Usage example |
| 33 | +You can use the following command to run the `mmwave-simple-epc` example. |
| 34 | +``` |
| 35 | +./ns3 --run mmwave-simple-epc |
| 36 | +``` |
| 37 | +Other examples are included in `src/mmwave/examples/` |
64 | 38 |
|
65 | | -Other platforms may or may not work: we welcome patches to |
66 | | -improve the portability of the code to these other platforms. |
| 39 | +## Documentation |
| 40 | +The documentation of this module is available at [this link](./src/mmwave/doc/mmwave-doc.md). |
67 | 41 |
|
68 | | -## Running ns-3 |
| 42 | +## Related modules |
| 43 | +- MilliCar is an ns-3 module for the simulation of mmWave NR V2X networks. Check [this repo](https://github.com/signetlabdei/millicar) for further details. |
| 44 | +- A seperate module is being developed for [mmWave UE Energy Consumption](https://github.com/arghasen10/mmwave-energy "mmwave-energy"). You can use this module for analyzing |
| 45 | +Energy Consumption behaviour of mmwave UE. Check this repository for further details. |
| 46 | +- `ns3-mmwave-iab` is an extended version of `ns3-mmWave` adding wireless relaying capabilities to an ns-3 NetDevice, and the possibility of simulating in-band relaying at mmWave frequencies. Check [this repo](https://github.com/signetlabdei/ns3-mmwave-iab) for further details. |
69 | 47 |
|
70 | | -On recent Linux systems, once you have built ns-3 (with examples |
71 | | -enabled), it should be easy to run the sample programs with the |
72 | | -following command, such as: |
| 48 | +## References |
| 49 | +The following papers describe in detail the features implemented in the mmWave |
| 50 | +module: |
| 51 | +- [End-to-End Simulation of 5G mmWave Networks](https://ieeexplore.ieee.org/document/8344116/ "comst paper") is a comprehensive tutorial with a detailed description of the whole module. We advise the researchers interested in this module to start reading from this paper; |
| 52 | +- [Integration of Carrier Aggregation and Dual Connectivity for the ns-3 mmWave Module](https://arxiv.org/abs/1802.06706 "wns3 2018") describes the Carrier Aggregation implementation; |
| 53 | +- [Implementation of A Spatial Channel Model for ns-3](https://arxiv.org/abs/2002.09341 "wns3 2020") describes the integration of the spatial channel model based on the 3GPP specifications TR 38.901 V15.0.0; |
| 54 | +- [Performance Comparison of Dual Connectivity and Hard Handover for LTE-5G Tight Integration](https://arxiv.org/abs/1607.05425 "simutools paper") describes the Dual Connectivity feature. |
73 | 55 |
|
74 | | -```shell |
75 | | -./ns3 run simple-global-routing |
76 | | -``` |
| 56 | +These other papers describe features that were implemented in older releases: |
| 57 | +- [ns-3 Implementation of the 3GPP MIMO Channel Model for Frequency Spectrum above 6 GHz](https://dl.acm.org/citation.cfm?id=3067678 "wns3 2017") describes the implementation of the 3GPP channel model based on TR 38.900; |
| 58 | +- [Multi-Sector and Multi-Panel Performance in 5G mmWave Cellular Networks](https://arxiv.org/abs/1808.04905 "globecom2018") describes the multi-sector addition to the 3GPP channel model; |
77 | 59 |
|
78 | | -That program should generate a `simple-global-routing.tr` text |
79 | | -trace file and a set of `simple-global-routing-xx-xx.pcap` binary |
80 | | -pcap trace files, which can be read by `tcpdump -tt -r filename.pcap` |
81 | | -The program source can be found in the examples/routing directory. |
| 60 | +If you use this module in your research, please cite: |
82 | 61 |
|
83 | | -## Getting access to the ns-3 documentation |
| 62 | +M. Mezzavilla, M. Zhang, M. Polese, R. Ford, S. Dutta, S. Rangan, M. Zorzi, _"End-to-End Simulation of 5G mmWave Networks,"_ in IEEE Communications Surveys & Tutorials, vol. 20, no. 3, pp. 2237-2263, thirdquarter 2018. [bibtex available here](https://ieeexplore.ieee.org/document/8344116/) |
84 | 63 |
|
85 | | -Once you have verified that your build of ns-3 works by running |
86 | | -the simple-point-to-point example as outlined in 3) above, it is |
87 | | -quite likely that you will want to get started on reading |
88 | | -some ns-3 documentation. |
| 64 | +## Future work |
| 65 | +We are actively developing new features for the mmWave module, including: |
| 66 | +- 3GPP NR beam tracking |
| 67 | +- 3GPP NR Integrated Access and Backhaul feature (see [this repo](https://github.com/signetlabdei/ns3-mmwave-iab) for more details) |
89 | 68 |
|
90 | | -All of that documentation should always be available from |
91 | | -the ns-3 website: <https://www.nsnam.org/documentation/>. |
| 69 | +## About |
| 70 | +This module is being developed by [NYU Wireless](http://wireless.engineering.nyu.edu/) and the [University of Padova](http://mmwave.dei.unipd.it/). |
| 71 | +This work was supported in part by the U.S. Department of Commerce National Institute of Standards and Technology through the Project “An End-to-End Research Platform for Public Safety Communications above 6 GHz” under Award 70NANB17H16. |
92 | 72 |
|
93 | | -This documentation includes: |
94 | 73 |
|
95 | | -- a tutorial |
96 | | -- a reference manual |
97 | | -- models in the ns-3 model library |
98 | | -- a wiki for user-contributed tips: <https://www.nsnam.org/wiki/> |
99 | | -- API documentation generated using doxygen: this is |
100 | | - a reference manual, most likely not very well suited |
101 | | - as introductory text: |
102 | | - <https://www.nsnam.org/doxygen/index.html> |
103 | 74 |
|
104 | | -## Working with the development version of ns-3 |
| 75 | +<!-- The new-handover branch offers integration between LTE and mmWave and dual connectivity features. |
| 76 | + --> |
105 | 77 |
|
106 | | -If you want to download and use the development version of ns-3, you |
107 | | -need to use the tool `git`. A quick and dirty cheat sheet is included |
108 | | -in the manual, but reading through the git |
109 | | -tutorials found in the Internet is usually a good idea if you are not |
110 | | -familiar with it. |
| 78 | +## Authors ## |
111 | 79 |
|
112 | | -If you have successfully installed git, you can get |
113 | | -a copy of the development version with the following command: |
| 80 | +The ns-3 mmWave module is the result of the development effort carried out by different people. The main contributors are: |
| 81 | +- Tommaso Zugno, University of Padova |
| 82 | +- Michele Polese, University of Padova |
| 83 | +- Matteo Pagin, University of Padova |
| 84 | +- Mattia Lecci, University of Padova |
| 85 | +- Matteo Drago, University of Padova |
| 86 | +- Mattia Rebato, University of Padova |
| 87 | +- Menglei Zhang, NYU Wireless |
| 88 | +- Marco Giordani, University of Padova |
| 89 | +- Marco Mezzavilla, NYU Wireless |
| 90 | +- Sourjya Dutta, NYU Wireless |
| 91 | +- Russell Ford, NYU Wireless |
| 92 | +- Gabriel Arrobo, Intel |
114 | 93 |
|
115 | | -```shell |
116 | | -git clone https://gitlab.com/nsnam/ns-3-dev.git |
117 | | -``` |
| 94 | +## License ## |
118 | 95 |
|
119 | | -However, we recommend to follow the Gitlab guidelines for starters, |
120 | | -that includes creating a Gitlab account, forking the ns-3-dev project |
121 | | -under the new account's name, and then cloning the forked repository. |
122 | | -You can find more information in the [manual](https://www.nsnam.org/docs/manual/html/working-with-git.html). |
| 96 | +This software is licensed under the terms of the GNU GPLv2, as like as ns-3. See the LICENSE file for more details. |
0 commit comments