Release v1.0 for NYUSIM in ns-3
NYUSIM is a groundbreaking open-source sub-THz and mmWave wireless channel simulator that is free to download and use by global industrial and academic institutions.NYUSIM is specifically designed to help accelerate the standardization efforts for 6G wireless communications, which is expected to kick off in 2025. NYUSIM comes with a myriad of new features that allow for the simulation of wireless channels in various scenarios, including urban microcell (UMi), urban macrocell (UMa), rural macrocell (RMa), indoor hotspot (InH), and indoor factory (InF) environments. The simulator offers indoor and outdoor channel models for each scenario, supporting carrier frequencies ranging from 0.5 to 150 GHz with an RF bandwidth from 0 Hz (CW) to 1 GHz. The inclusion of drop-based channel simulations for all five simulation scenarios further enhances the simulator's capabilities. NYUSIM in ns-3 based on the very popular and widely used open-source MATLAB based channel simulator "NYUSIM". Since its first release in 2016, NYUSIM has been downloaded more than 100,000 times and is used an alternative to 3GPP channel models.
MATLAB based NYUSIM can be downloaded @ https://wireless.engineering.nyu.edu/nyusim/
Advantage of using NYUSIM
Currently, ns-3 uses the 3GPP TR 38.901 SCM to model the wireless channel for the frequency range of 0.5-100 GHz for all 3GPP-listed scenarios namely urban microcell (UMi), urban microcell (UMa), rural microcell (RMa), indoor hotspot (InH), and indoor factory (InF). Research conducted at NYU WIRELESS shows that 3GPP SCM provides an oversimplification of the actual wireless channel in outdoor scenarios. In addition, the limited frequency range of the 3GPP SCM does not allow researchers to study future networks above 100 GHz. Furthermore, there needs to be more understanding of how the wireless channel model impacts overall network performance as ns-3 users are restricted to using only the 3GPP SCM for simulations. To enable the research community to explore and analyze networks of the future based on real-world channel measurement-based models that cover the frequency range of 0.5-150 GHz in 3GPP-listed scenarios, we present the implementation of drop-based NYUSIM in ns-3.
Steps to use NYUSIM in ns-3 on ns-3 mainline: (Successfully Tested on ns-3 version 3.39)
- Download/Clone ns-3 mainline on your local machine. NYUSIM files are tested on ns-3 version 3.39 thus users are recommended to download ns-3 version 3.39.
- Copy all the files from the current repository present in the directory propagation/model to ns-3 mainline src/propagation/model
- Copy all the files from the current repository present in the directory propagation/example to ns-3 mainline src/propagation/examples
- On ns-3 mainline in the directory src/propagation add the following lines to the CMakeLists.txt file under:
SOURCE_FILES
model/nyu-channel-condition-model.cc
model/nyu-propagation-loss-model.cc
HEADER_FILES
model/nyu-channel-condition-model.h
model/nyu-propagation-loss-model.h - Copy all the files from the current repository present in the directory spectrum/model to ns-3 mainline src/spectrum/model
- Copy all the files from the current repository present in the directory spectrum/example to ns-3 mainline src/spectrum/examples
- On ns-3 mainline in the directory src/spectrum add the following lines to the CMakeLists.txt file under:
SOURCE_FILES
model/nyu-channel-model.cc
model/nyu-spectrum-propagation-loss-model.cc
HEADER_FILES
model/nyu-channel-model.h
model/nyu-spectrum-propagation-loss-model.h - You can run the example files from Step 3 or Step 6 to see the usage of NYUSIM channel model from the ns-3-dev folder using:
./ns3 run src/spectrum/examples/nyu-channel-example
Steps to use NYUSIM in ns-3 on ns3-mmWave module: (Successfully Tested on ns3-mmWave module version 3.38)
- Download/Clone ns3-mmWave module mainline on your local machine. NYUSIM files are tested on ns3-mmWave module version 3.38 thus users are recommended to download ns3-mmWave module version 3.38.
- Copy all the files from the current repository present in the directory propagation/model to ns3-mmwave/src/propagation/model
- Copy all the files from the current repository present in the directory propagation/example to ns3-mmwave/src/propagation/examples
- On ns3-mmWave module mainline in the directory ns3-mmwave/src/propagation add the following lines to the CMakeLists.txt file under:
SOURCE_FILES
model/nyu-channel-condition-model.cc
model/nyu-propagation-loss-model.cc
HEADER_FILES
model/nyu-channel-condition-model.h
model/nyu-propagation-loss-model.h - Copy all the files from the current repository present in the directory spectrum/model to ns3-mmwave/src/spectrum/model
- Copy all the files from the current repository present in the directory spectrum/example to ns3-mmwave/src/spectrum/examples
- On ns3-mmWave module mainline in the directory src/spectrum add the following lines to the CMakeLists.txt file under:
SOURCE_FILES
model/nyu-channel-model.cc
model/nyu-spectrum-propagation-loss-model.cc
HEADER_FILES
model/nyu-channel-model.h
model/nyu-spectrum-propagation-loss-model.h - To use the NYUSIM channel model with ns3-mmWave module: copy the file from the current repository present in mmwave/helper to ns3-mmwave/src/mmwave/helper.
In the mmwave-helper-nyusim.cc file the parameters that need to be changed are:
a. Large scale propagation model. Default is "NYUUmaPropagationLossModel". Supported are NYUUmaPropagationLossModel,NYUUmiPropagationLossModel,NYURmaPropagationLossModel,NYUInHPropagationLossModel,NYUInFPropagationLossModel
b. The scenario for NYUSIM channel generation. Default is "Uma". Supported are Uma,Umi,Rma,InH and InF.
Note large scale propagation model and scenario should be the same,i.e, if you select "NYUUmiPropagationLossModel" then set scenario as "Umi". - Add the following line in the CMakeLists.txt file present in the ns3-mmwave/src/mmwave on your local machine :
SOURCE_FILES
model/mmwave-helper-nyusim.cc - Comment the following line in the CMakeLists.txt file present in the ns3-mmwave/src/mmwave on your local machine :
SOURCE_FILES
# model/mmwave-helper.cc - Now you can run any example present in ns3-mmwave module in the folder ns3-mmwave/src/mmwave/examples. The example file will automatically use the NYUSIM channel model under the hood.
For example: Copy the file ns3-mmwave/src/mmwave/examples/mmwave-simple-epc.cc to ns3-mmwave/scratch and run the following command:
NS_LOG=* ./ns3 run scratch/mmwave-simple-epc.cc > nyutest.out 2>&1
Once execution is over you will see a file named "nyutest.out" in the ns3-mmwave folder.
Open the file using any text editor and search for the string "NYUChannelModel". This will show the channel generation debug prints for NYUSIM channel model.
The following describes in detail the implementation of NYUSIM in n3:
- ns-3 Implementation of Sub-Terahertz and Millimeter Wave Drop-based NYU Channel Model (NYUSIM) provides a detailed description of the implementation of NYUSIM channel model in ns-3. We encourage the readers to read this paper to get an overview of the implementation of NYUSIM in ns-3.
- NYUSIM Wireless Channel Simulator Extension above 100 GHz and Implementation in ns-3 provides a detailed description of the implementation of NYUSIM channel model above 100 GHz in MATLAB and NYUSIM channel model for the frequency range of 0.5 GHz - 150 GHz in ns-3.
- Full-Stack End-To-End mmWave Simulations Using 3GPP and NYUSIM Channel Model in ns-3 provides insights on using NYUSIM with ns-3 mmWave module and a compares the end-to-end throuhgput, latency and packet-drop observed using the NYUSIM and 3GPP channel model at mmWave frequency.
To encourage fellow researchers to leverage the NYUSIM module within the ns-3 framework for their own studies, we kindly request that when incorporating this module into your research, you consider acknowledging its use by citing:
Poddar, H., Yoshimura, T., Pagin, M., Rappaport, T., Ishii, A., & Zorzi, M. (2023, June). ns-3 Implementation of Sub-Terahertz and Millimeter Wave Drop-based NYU Channel Model (NYUSIM). In Proceedings of the 2023 Workshop on ns-3 (pp. 19-27)
We plan to implement NYUSIM-based blockage models for all 3GPP listed scenarios and create LOS probability models for InH, RMa, and InF scenarios. In addition, we will also add spatial consistency-based models for NYUSIM in ns-3 and extend NYUSIM models above 150 GHz for 3GPP-listed scenarios.
This module is being developed by NYU WIRELESS and Sharp Laboratories of America. This work is supported and funded by the NYU WIRELESS Industrial Affiliates Program, and the commissioned research (No.04201) from the National Institute of Information and Communications Technology (NICT), Japan.
NYUSIM in ns-3 is the result of the development effort carried out by
- Hitesh Poddar, NYU WIRELESS
- Tomoki Yoshimura, Sharp Laboratories of America
Copyright (c) 2023 New York University and NYU WIRELESS
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. Users are encouraged to cite NYU WIRELESS publications regarding this work.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.