Package `uavnoma`

A Python 3.8 implementation of a model of wireless communication system between an aerial base station and two users.

System Model of UAV-NOMA System with Two-users

A Python 3.8 implementation of the System Model of Unmanned Aerial Vehicle with Non-Orthogonal Multiple Access (UAV-NOMA) System and 2 ground users under considerations of non-ideal conditions, such as imperfect successive interference cancelation (SIC) and residual hardware impairments (RHI). We consider a downlink UAV-aided NOMA network, as illustrated in the figure below.

System model.

Features

The uavnoma package allows the user to study the modeling of a UAV-NOMA network and use it as a basis for implementing other technologies. This application can be used as a study tool to understand the behavior of the achievable rate by two users and the influence of the allocation of power coefficients in a UAV-NOMA system under non-ideal conditions. The communication model presented is a base of UAV-NOMA principles and can be expanded to several other scenarios, such as cooperative systems, full-duplex communication, and others in order to improve system performance.

The user can modify parameters and analyze the system's behavior. Based on this, new methods can be proposed to solve UAV trajectory problems, power allocation, user pairing, energy harvesting for UAV maintenance, decoding order and others.

The package contains functions to:

Calculate the position of the UAV and users;
Generate the channel gain between UAV and users;
Calculate of the Signal Interference Noise Ratio (SINR);
Analyze system performance using as metrics the instantaneous achievable rate and outage probability.

A command line script is also included, allowing for anyone to experiment with the model without knowing or using Python. The user can run a simulation with default parameters using the following command:

uavnoma

The script is fully parameterizable, and the available parameters can be listed with:

uavnoma --help

Requirements

The implementation requires Python 3.8+ to run. The following libraries are also required:

numpy
matplotlib
pandas
tabulate
argparse

How to install

From PyPI

pip install uavnoma

From source/GitHub

Directly using pip:

pip install git+https://github.com/limabrena/uavnoma.git#egg=uavnoma

Or each step at a time:

git clone https://github.com/limabrena/uavnoma.git
cd uavnoma
pip install .

Installing for development and/or improving the package

git clone https://github.com/limabrena/uavnoma.git
cd uavnoma
pip install -e .[dev]

This way, the package is installed in development mode. As a result, the pytest dependencies/plugins are also installed.

Documentation

License

MIT License

Developer's guide

How to use this application?

From PyPI

pip install uavnoma

From source/GitHub

Directly using pip:

pip install git+https://github.com/limabrena/uavnoma.git#egg=uavnoma

Or each step at a time:

git clone https://github.com/limabrena/uavnoma.git
cd uavnoma
pip install .

Installing for development and/or improving the package

git clone https://github.com/limabrena/uavnoma.git
cd uavnoma
pip install -e .[dev]

This way, the package is installed in development mode. As a result, the pytest dependencies/plugins are also installed.

Usage

After installing the package, to run the script on your terminal simply run the following command:

$ uavnoma

An example on how to use a package can be seen in the uavnoma folder. The script contains an implementation example of an UAV NOMA system using the uavnoma package.

$ command_line.py

Documentation

Project documentation is generated using pdoc3. To generate the project documentation, running the following command in the project folder uavnoma.

pdoc3 --html --output-dir docs uavnoma/

This comand generates the HTML documentation and salve it in the docs folder.

On the other hand, the documentation can be viewed here

Test

The pytest and pytest-cov packages are required for testing uavnoma package.

To run the unit tests, you can use the following command in the project's root folder:

pytest

To analyze test coverage, run the command below. The command will return an HTML file with test coverage information.

pytest --cov=uavnoma --cov-report=html

Scenario Description

In our scenario, a UAV is deployed as an air base station that communicates with two users, $N_1$ and $N_2$. For each Monte Carlo sample, users are randomly distributed in a 2D region ($x$-axis and $y$-axis). While the UAV has a flight path randomly defined at points in a circle, in a 3D region ($x$-axis, $y$-axis and $z$-axis). We consider that each node is equipped with a single antenna and both UAV and users operate in the half-duplex mode. $N_1$ is viewed as the primary user and $N_2$ is viewed as secondary user. On the others words, we assume that the primary user has priority to meet their quality of service requirements because they have the worst channel conditions. In order to guarantee primary user's Quality-of-Service requirements, the UAV first decodes the $N_1$'s message. Then, the UAV decodes the message from the secondary user $N_2$ without experiencing any performance degradation due to the primary user.

Example:

$N_1$ may be an Internet of Things (IoT) healthcare device which needs to send health status changes.

$N_2$ an IoT device sending personal tasks records, where the transmission is a delay tolerant.

Different levels of power coefficients must be allocated to each user's signal, so that users' QoS requirements are satisfied.

Performance analysis metrics

The outage probability and achievable rate are used as performance metrics.

Outage Probability: the outage probability is estimated as the ratio between the number of outage events and the total number of Monte Carlo repetitions. An outage event happens when the supported user data rates for a particular instantaneous channel realization is less than the target data rate.
Achievable Rate: the achievable rate consists of the throughput of network users, while average achievable rate consists of the average throughput of all network users.

We consider the Rician distribution to model the fading model considering line-of-sight. If the Rician Factor K=0, fading is similar to Rayleigh's.

Description of the Simulation Parameters

monte_carlo_samples (integer) : Monte Carlo Samples.
number_user (integer) : number of users (in our case, two users).
number_uav(integer) : number of UAV (in our case, single uav).
snr_dB (array of integer, size[10:2:51]) : signal-to-noise ratio in dB.
path_loss (float) : path loss exponent.
power_los (float) : total power of LOS path & scattered paths.
rician_factor (integer) : Rician Factor.
target_rate_primary_user (float) : target rate in bits/s/Hertz of primary users.
target_rate_secondary_user (float) : target rate in bits/s/Hertz of secondary users.
radius_uav (float) : radius in meter of fly trajectory UAV.
radius_user (float) : radius of the cell of users in meters.
uav_heigth_mean(float) : Average UAV flight height
distance(array of float, size(N_users)) : distance between UAV and n-th user randomly calculated for each Monte Carlo sample.
power_coeff_primary (float) : power coefficient allocated to the Primary user.
power_coeff_secondary (float) : power coefficient allocated to the Secondary user.
small_scale_fading (complex number) : channel coefficients for each user generated by Rician distribution. This can be generated randomly using: np.sqrt((np.random.normal(s,sigma)**2) + 1j*(np.random.normal(0,sigma)**2)).
large_scale_fading (float): large scale fading
s (float) : Non-Centrality Parameter (mean) of Rician distribution, obtained by s=sqrt(rician_factor/(rician_factor+1)*power_los).
sigma (float) : Standard deviation of Rician distribution, obtained by sigma = power_los/sqrt(2*(rician_factor+1)).
h_n (array of float, size(N_users)) : channel coefficients over small_scale_fading and large scale fading.
channel_primary (float) : channel gain of the primary user.
channel_secondary (float) : channel gain of the secondary user.
hardw_ip(float) : Residual Hardware Impairment coefficient.
sic_ip (float) : Sucessice Interference Cancelation coefficient.

Expand source code

"""
   A Python 3.8 implementation of a model of wireless communication
   system between an aerial base station and two users.
   .. include:: ../README.md
   .. include:: ../doc/installationguide.md
   .. include:: ../doc/documentation.md
"""

from .generate_values import fading_rician
from .generate_values import random_position_uav
from .generate_values import random_position_users
from .generate_values import generate_channel
from .performance_metrics import calculate_instantaneous_rate_primary
from .performance_metrics import calculate_instantaneous_rate_secondary
from .performance_metrics import average_rate
from .performance_metrics import outage_probability

__pdoc__ = {}
__pdoc__["command_line.main"] = False
__pdoc__["command_line.validate"] = False

Sub-modules

uavnoma.command_line: This script performs a simulation of a UAV-NOMA system with two users …
uavnoma.generate_values: This module contains functions to generate simulation parameters.
uavnoma.performance_metrics: This module contains script to calculate performance metrics: achievable rate and outage probability .