Getting started

Get started with 5G-LENA in matter of minutes.

In order to start with the NR module you should have some confidence with the ns-3 environment. You can find on the ns-3 web site all the necessary information.

In the following instructions, we will download and build the 5G-LENA project, and we will point out to ns-3 and 5G-LENA documentation to help you enter the ns-3 and the NR world.

Download the ns-3 part of the 5G-LENA project

Download a brand new ns-3-dev repository

To download a working copy of the ns-3-dev repository, you can do the following:

$ git clone https://gitlab.com/nsnam/ns-3-dev.git
$ cd ns-3-dev

We try to keep in sync with the latest advancements in ns-3-dev. By the version 1.0, we have upstreamed all our patches to ns-3-dev, making our module independent from the ns-3 version used. However, since the version 1.3, we recommend the specific ns-3 release branch for each NR release, i.e., the ns-3 release branch with which are carried out all CI/CD tests for the specific NR release. Hence, at this step, you should check in RELEASE_NOTES.md of the NR module which is the recommended ns-3 release to use for the specific NR release, and then you can switch to the corresponding ns-3 release branch, e.g., in the following way:

$ git checkout ns-3.x

where x corresponds to the specific ns-3 release branch that you want to use, which has to be supported as indicated in the table in the README file. For example, you can use "git checkout ns-3.37" to switch to the ns-3.37 release branch, which is supported together with NR v2.3 release branch. If the recommended ns-3 release is not available yet (such in the case that NR is released before the recommended ns-3 release), then you can use ns-3 master until ns-3 recommended release is ready.

Test the installation

To test the installation, after following the previous steps, you can do a simple configuration and compilation test:

$ ./ns3 configure --enable-examples --enable-tests
$ ./ns3 build

A success for both previous commands indicates an overall success and you are ready to install the NR module.

Download the 5G-LENA core project

As a precondition to the following steps, you must have a working local ns-3 git repository as explained in the previous steps.

Clone the NR module:

cd contrib
git clone https://gitlab.com/cttc-lena/nr.git

At this step, you should switch to the NR release branch you want:

cd nr
git checkout 5g-lena-v2.x.y

where x corresponds to the specific NR release branch that you want to use, which has to be supported together with the configured ns-3-dev release branch as indicated in the table in the README file. For example, to switch to the NR version 2.3 (compatible with ns-3.37 release) you should do the following: "git checkout 5g-lena-v2.3.y".

Please note that the contrib/nr directory will be listed as "Untracked files" every time you do a git status command. Ignore it, as the directory lives as an independent module. This is normal, since you have two parallel git repositories, that of ns-3 and of nr. Notice that you can install the nr module also inside the contrib/ directory, as per standard ns-3 instructions.

To test the resulting repository, go back to the root ns-3 directory and configure the ns-3 project and build it again:

$ cd ../../
$ ./ns3 configure --enable-examples --enable-tests
$ ./ns3 build

If the NR module is recognized correctly, you should see "nr" in the list of built modules. If that is the case, Welcome to the NR world !!! :-)

Now, you can run some of NR examples (see nr/examples folder):

$ ./ns3 run cttc-nr-mimo-demo

For more examples see nr/examples folder.

Contributing to 5G-LENA

We would be very happy if you would contribute to 5G-LENA!

If you do some of the following with 5G-LENA:

  • find and solve some bug,
  • add some new parameter,
  • create a completely and different example or test,
  • parametrize existing piece of code,
  • develop a completely new feature,
  • extend the tracing system through files or the databases,
  • improve visualization of the scenario through the python scripts
  • or whatever else,

and you would like to contribute that to the open source NR module, please create a merge request (MR) or contact us to guide you through the contributing process.

Get familiar with ns-3 and the NR module

We recommend you to first get familiar with ns-3 and then with the NR module.

ns-3 tutorials

If it is the first time you work with the ns-3 environment, we recommend to take things slowly (but steady) and going forward through simple steps. The ns-3 documentation https://www.nsnam.org/documentation/ is divided into three categories tutorial, manual and documentation (describing models):

NR documentation

The NR documentation is divided into two categories:

The publications related to the NR module and its extensions are also very valuable source of information. The list of the publications can be found here: https://5g-lena.cttc.es/papers/.

Upgrading 5G-LENA

We assume that your work lives in a separate branch, and that the 'master' branch of the NR repository is left untouched as the first time you downloaded it. If it is not the case, then please move all your work in a separate branch.

A clean 'master' branch can be updated by simply running:

$ cd ns-3-dev/contrib/nr
$ git pull

Then checkout the latest NR release branch (e.g., git checkout 5g-lena-v2.2.y). With each release, we will also incorporate into the master branch all the work that is meant to be released.

For what regards ns-3-dev run git pull and switch to its release branch that is indicated in the NR RELEASE_NOTES.md for the corresponding NR release.