Documentation
The whole package is contained in a single class:
Before running one of the proposed models, it is recommended to initialize the class with the following parameters:
- reference_distance (float): reference distance used to nondimensionalize the signal power value (meters). By default, use 1.0.
- n (float): default path loss exponent. If not overridden: n = 2.0.
- c (float): default speed of light (m/s). If not overridden: c = 299792458.0.
First steps
To initialize it, for example, you can use:
import uav_radio
calculator = PathLossCalculator(reference_distance=1.0, n=2.0)
calculator.free_space_pl(100, 868000000)
This should return:
All the defined functions and methods are now accessible through the calculator object. For a detailed description of the available functions continue reading below.Available Ground-to-Air Models
| Models | Guidelines | |
|---|---|---|
| 1 | Free Space Path Loss model | The simplest theoretical path loss model available. |
| 2 | Log-distance Path Loss model | Recommended for open flat or hilly area with light suburban, rural or no terrain cover, and for over water. |
| 3 | Log-distance alpha-beta (AB) model | Recommended for certain specialized environments with PL model predictions only for a given area. |
| 4 | Two Ray Path Loss model | Recommended for open flat or hilly area with light suburban, rural or no terrain cover, and for over water. |
| 5 | Modified Two Ray Path Loss Model | Recommended for certain specialized environments in which there the TX and RX heights are relevant. |
| 6 | PL Dual Slope Model | Recommended for complex geometrical environments with large number of scatterers in a LOS path between the GS and the UAV. |
| 7 | PL as a function of the elevation angle | Recommended for open flat or hilly area with light suburban, rural or no terrain cover, and for over water., when considering the elevation angle. |
Free Space Path Loss model
where \(d\) is the distance between TX and RX; and \(\lambda\) is the wavelength.
Parameters:
- distance (float): distance between the TX and the RX meters.
- frequency (float): operating frequency of the TX-RX in Hz.
Returns:
- float: free space path loss in dB.
- None: corresponding to the standard deviation, undefined in this case.
Log-distance Path Loss Model
where \(f\) is the frequency of interest; \(d\) is the distance between TX and RX; \(d_{0}\) the reference distance, usually \(d_{0} = 1\)m, \(PL_{0} = 10*\log_{10}[\frac{4 \pi d_{0}}{\lambda}]\); \(n\) the path loss exponent; \(\lambda\) is the wavelength; and \(X_{\sigma} \approx N(0,\sigma^{2})\).
PathLossCalculator.log_distance_pl(distance, frequency, scenario="open_field", n_custom = None, sigma_custom = None, speed=None, tx_height=None, foliage=0)
Parameters:
- distance (float): Distance between transmitter and receiver (meters).
- frequency (float): Signal frequency (Hz).
- scenario (string): "open_field", "urban_rural", "urban", "suburban", "hilly_with_ridge", "dry_hilly", "very_mountainous", "fresh_water", "sea", "custom".
- n_custom (float): custom path loss exponent, use with scenario="custom".
- sigma_custom (float): custom standard-deviation, use with scenario="custom".
- speed (float): UAV speed (mph) for "urban" and "suburban" cases.
- tx_height (float): < 1.0 or >= 1.0 (meters depending on whether the TX is standing on the ground or elevated. For "urban" and "suburban" cases.
- foliage (int): either 0 (False) or 1 (True) for "open_field" and "suburban" cases.
Returns:
- float: free space path loss in dB.
- None: corresponding to the standard deviation, returns value if applicable, otherwise 0 or custom value.
Pre-defined cases:
| Scenarios | Options | n | \(\sigma\) (dB) | Ref. |
|---|---|---|---|---|
| Open field | 2.01 | - | [1] | |
| Urban/Rural | 4.10 | 5.24 | [2] | |
| Urban Freq = L-band (0.9–1.2 GHz) | 1.7 | 2.6 | [3] | |
| Urban Freq = C-band (5.03–5.091 GHz) | 2.0 | 3.2 | [3] | |
| Suburban Freq = L-band (0.9–1.2 GHz) | 1.7 | 3.1 | [3] | |
| Suburban Freq = C-band (5.03–5.091 GHz) | 1.5 | 2.9 | [3] | |
| Open field Freq = 3.1-5.3GHz v = 0 mph | -GCS at 1.5m height in foliage | 2.6471 | 3.37 | [4] |
| -GCS at 1.5m height no foliage | 2.5418 | 3.06 | [4] | |
| -GCS at 7cm height from ground | 2.9442 | 2.799 | [4] | |
| Open field Freq = 3.1-5.3GHz v = 20 mph | -GCS at 1.5m height in foliage | 2.6533 | 4.02 | [4] |
| -GCS at 1.5m height no foliage | 2.6621 | 3.91 | [4] | |
| -GCS at 7cm height from ground | 2.9423 | 3.44 | [4] | |
| Suburban Freq = 3.1-5.3GHz v = 0 mph | -GCS at 1.5m height in foliage | 2.7601 | 4.8739 | [4] |
| -GCS at 1.5m height no foliage | 2.606 | 4.31 | [4] | |
| -GCS at 7cm height from ground | 3.0374 | 4.897 | [4] | |
| Suburban Freq = 3.1-5.3GHz v = 20 mph | -GCS at 1.5m height in foliage | 2.8350 | 5.3 | [4] |
| -GCS at 1.5m height no foliage | 2.667 | 4.96 | [4] | |
| -GCS at 7cm height from ground | 2.961 | 4.71 | [4] | |
| Hilly terrain with mountain ridge. Freq = L-band (0.9–1.2 GHz) | 1.6 | 3.5 | [5] | |
| Hilly terrain with mountain ridge. Freq = C-band (5.03–5.091 GHz) | 1.7 | 2.8 | [5] | |
| Dry, hilly terrain. Freq = L-band (0.9–1.2 GHz) | 1.3 | 3.9 | [5] | |
| Dry, hilly terrain. Freq = C-band (5.03–5.091 GHz) | 1.0 | 2.2 | [5] | |
| Very mountainous terrain. Freq = L-band (0.9–1.2 GHz) | 1.6 | 3.5 | [5] | |
| Very mountainous terrain. Freq = C-band (5.03–5.091 GHz) | 1.7 | 2.8 | [5] | |
| Over fresh water Freq = L-band (0.9–1.2 GHz) | 1.9 | 3.8 | [6] | |
| Over fresh water Freq = C-band (5.03–5.091 GHz) | 1.9 | 3.1 | [6] | |
| Over sea Freq = L-band (0.9–1.2 GHz) | 1.9 | 4.2 | [6] | |
| Over sea Freq = C-band (5.03–5.091 GHz) | 1.5 | 2.6 | [6] |
Log-distance Alpha-Beta (AB) Model
where \(d\) is the distance between TX and RX; \(\alpha\) the path loss exponent; \(\beta\) the intercept point with the line \(d=1\)m; and \(X_{\sigma} \approx N(0,\sigma^{2})\).
PathLossCalculator.log_distance_alpha_beta_pl(distance, frequency, scenario="lightly_hilly_rural", rx_height=None, alpha_custom=None, beta_custom=None, sigma_custom=None)
Parameters:
- distance (float): Distance between transmitter and receiver (meters).
- frequency (float): Signal frequency (Hz).
- scenario (string): "lightly_hilly_rural".
- rx_height (float): UAV height, from 0 to 120 meters (higher values are approximated by the 120 m model).
- alpha_custom (float): alpha path loss exponent custom value, if scenario="custom".
- beta_custom (float): beta path loss term custom value, if scenario="custom".
- sigma_custom (float): path loss standard deviation custom value, if scenario="custom".
Returns:
- float: Path Loss value in dB.
- float: Standard deviation value (if applicable).
Pre-defined cases:
| Scenario | UAV height (m) | \(\alpha\) | \(\beta\) (dB) | \(\sigma\) (dB) | Ref. |
|---|---|---|---|---|---|
| Lightly hilly rural | 1.5 | 3.7 | -1.3 | 7.7 | [7] |
| 15 | 2.9 | 7.4 | 6.2 | ||
| 30 | 2.5 | 20.4 | 5.2 | ||
| 60 | 2.1 | 32.8 | 4.4 | ||
| 120 | 2.0 | 35.3 | 3.4 |
Two Ray Path Loss Model
where \(d\) is the distance between TX and RX; \(\lambda\) is the wavelength; \(h_{T}\) is the TX height above ground; and \(h_{R}\) is the RX height above ground.
Parameters:
- distance (float): Distance between transmitter and receiver (meters).
- frequency (float): Signal frequency (Hz)
- h_t (float): height of the transmitter (meters)
- h_r (float): height of the receiver (meters)
Returns:
- float: Path Loss value in dB.
- float: Standard deviation value (not applicable) = 0.
Modified Two Ray Path Loss Model
Two Ray modified path loss model that considers the drone height and the Ground Control Station height, defining three zones:
- Zone 1 (\(h_{r} <= h_{t}\)): Drone height approximately lower than the Ground Control Station height.
- Zone 2 (\(h_{t} < h_{r} <= 2 h_{t}\)): Drone height over Ground Control Station height and below two times the Ground Control Station height.
- Zone 3 (\(h_{r} > 2 h_{t}\)): Drone height over two times the Ground Control Station height.
The formulation proposed in the literature [11] provides the Received Power (\(P_{r}^{HD^{2}-A2G}\)) as a function of the Transmitted Power (\(P_{t}\)):
where
and
In the above-mentioned Equations, \(\lambda\) is the signal frequency, \(d\) the ground distance between the transmitter and the receiver, and \(\Delta \phi\) is the phase angle. The remaining parameters are functions of the receiver height. With the proper simplifications, this equation can be expressed in terms of Path Loss by:
The direct path is specified by \(G_{l}(h)\); the reflected path by \(G_{r}(h)\); the height-dependent propagation coefficient by \(\gamma(h)\); and the ground reflection coefficient \(R\). The cases shown in the table have been extracted from the literature and are ready to use in the model.
| Scenarios | \(G_{l}(h)\) | \(G_{r}(h)\) | \(\gamma(h)\) | \(R\) |
|---|---|---|---|---|
| Zone 1 (\(h\leq30\)) | 15 | 5 | 3.5 | -1 |
| Zone 2 (\(30<h\leq60\)) | 7 | 7 | 2.75 | -1 |
| Zone 3 (\(h>60\)) | 0 | 3.5 | 2 | -1 |
PathLossCalculator.modified_two_ray_pl(distance, frequency, h_t, h_r, G_l_custom=None, G_r_custom=None, R_custom=None, gamma_h_custom=None)
Parameters:
- distance (float): Ground distance between transmitter and receiver (meters).
- frequency (float): Signal frequency (Hz)
- h_t (float): height of the transmitter (meters)
- h_r (float): height of the receiver (meters)
- G_l_custom (float): direct path coefficient (optional).
- G_r_custom (float): reflected path coefficient (optional).
- R_custom (float): ground reflection coefficient (optional).
- gamma_h_custom (float): height-dependent propagation coefficient (optional).
Returns:
- float: Path Loss value in dB.
- float: Standard deviation value (not applicable) = 0.
Path Loss Dual Slope Model
with
where \(d_{0}\) is the reference distance; \(d_{b}\) is the break distance; and \(\gamma_{1}\) and \(\gamma_{2}\) are the path loss exponents.
Parameters:
- distance (float): Distance between transmitter and receiver (meters).
- frequency (float): Signal frequency (Hz).
- d_b (float): Break distance, default to 9.0 (meters).
- gamma_1 (float): Path loss exponent 1.
- gamma_2 (float): Path loss exponent 2.
- default (int): default UAV height case. Only available: 20, 30 (meters).
Returns:
- float: Path Loss value in dB.
- float: Zero-mean Gauss-distributed shadow fading in dB (psi).
The available setups from the literature are shown in the following table:
| Scenario | UAV height (m) | \(\gamma_{1}\) | \(\gamma_{2}\) | \(\psi\) (dB) | Ref. |
|---|---|---|---|---|---|
| Ensemble of containers | 20 | 0.74 | 2.29 | 5.5 | [9] |
| 30 | 0.74 | 2.29 | 3.9 | [9] |
Path Loss as a function of the Elevation Angle
where \(\Delta h = h_{R} - h_{T}\) is the difference between the height of the UAV and the height of the GS in meters; \(f\) is the frequency in MHz; \(\theta\) is the elevation angle between the UAV and the GS; and \(\frac{\Delta h}{\sin{\theta}}\) is the link distance expressed as a function of the elevation angle.
Parameters:
- frequency (float): Signal frequency (Hz).
- elev_angle (float): Elevation angle between the UAV and the GS (degrees).
- h_t (float): Height of the transmitter (meters).
- h_r (float): Height of the receiver (meters).
Returns:
- float: Path Loss value in dB.
- float: Standard deviation value (not applicable) = 0.
Auxiliary Functions and Tools
Calculate distance in 2D
Calculates the 2D distance between two sets of \((x,y)\) coordinates.
Parameters:
- tx_position (tuple): 2D position of transmitter (x, y) in meters.
- rx_position (tuple): 2D position of receiver (x, y) in meters.
Returns:
- float: 2D distance between transmitter and receiver (meters).
Calculate distance in 3D
Calculates the 3D distance between two sets of \((x,y,z)\) coordinates.
Parameters:
- tx_position (tuple): 3D position of transmitter (x, y, z) in meters.
- rx_position (tuple): 3D position of receiver (x, y, z) in meters.
Returns:
- float: 3D distance between transmitter and receiver (meters).
2D Path Loss Contour Plot
Create a path loss contour plot centered around the transmitter.
PathLossCalculator.create_path_loss_contour(self, tx_position, rx_position, h_tx, h_rx, range_x, range_y, points, pl_func='free_space_pl', **kwParameters)
- tx_position (tuple): 2D position of transmitter (x, y) in meters.
- rx_position (tuple): 2D position of receiver (x, y) in meters.
- h_tx (float): Transmitter height in meters.
- h_rx (float): Receiver height in meters.
- range_x (float): range in meters from the tx_position[0].
- range_y (float): range in meters from the tx_position[1].
- points (int): number of points to simulate in both directions.
- pl_func (str): "free_space_pl", "log_distance_pl", "log_distance_alpha_beta_pl", "two_ray_perfect_reflection_pl", "two_ray_non_perfect_reflection_pl", "dual_slope_pl", "elevation_angle_pl"
- kwParameters (dict): dictionary containing as many parameters as required by the employed pl_func. For reference, check each function description.
Returns:
Bibliography
[1] E. Yanmaz, R. Kuschnig, and C. Bettstetter, “Achieving air-ground communications in 802.11 networks with three-dimensional aerial mobility,” in Proc. IEEE INFOCOM, 2013, pp. 120–124.
[2] W. G. Newhall et al., “Wideband air-to-ground radio channel measurements using an antenna array at 2 GHz for low-altitude operations,” in Proc. IEEE Mil. Commun. Conf. (MILCOM), vol. 2. Boston, MA, USA, 2003, pp. 1422–1427.
[3] D. W. Matolak and R. Sun, “Air–ground channel characterization for unmanned aircraft systems—Part III: The suburban and nearurban environments,” IEEE Trans. Veh. Technol., vol. 66, no. 8, pp. 6607–6618, Aug. 2017.
[4] W. Khawaja, I. Guvenc, and D. W. Matolak, “UWB channel sounding and modeling for UAV air-to-ground propagation channels,” in Proc. IEEE Glob. Commun. Conf. (GLOBECOM), Washington, DC, USA, Dec. 2016, pp. 1–7.
[5] R. Sun and D. W. Matolak, “Air–ground channel characterization for unmanned aircraft systems—Part II: Hilly and mountainous settings,” IEEE Trans. Veh. Technol., vol. 66, no. 3, pp. 1913–1925, Mar. 2017.
[6] D. W. Matolak and R. Sun, “Air–ground channel characterization for unmanned aircraft systems—Part I: Methods, measurements, and models for over-water settings,” IEEE Trans. Veh. Technol., vol. 66, no. 1, pp. 26–44, Jan. 2017.
[7] R. Amorim, H. Nguyen, P. Mogensen, I. Z. Kovács, J. Wigard, and T. B. Sørensen, “Radio channel modeling for UAV communication over cellular networks,” IEEE Wireless Commun. Lett., vol. 6, no. 4, pp. 514–517, Aug. 2017.
[8] D. W. Matolak and R. Sun, “Antenna and frequency diversity in the unmanned aircraft systems bands for the over-sea setting,” in Proc. IEEE Digit. Avionics Syst. Conf. (DASC), Oct. 2014, pp. 6A4-1–6A4-10.
[9] X. Cai et al., “Low altitude UAV propagation channel modelling,” in Proc. IEEE 11th Eur. Conf. Antennas Propag. (EUCAP), Paris, France, 2017, pp. 1443–1447.
[10] W. Khawaja, I. Guvenc, D. W. Matolak, U. -C. Fiebig and N. Schneckenburger, "A Survey of Air-to-Ground Propagation Channel Modeling for Unmanned Aerial Vehicles," in IEEE Communications Surveys & Tutorials, vol. 21, no. 3, pp. 2361-2391, thirdquarter 2019, doi: 10.1109/COMST.2019.2915069.
[11] N. Goddemeier, K. Daniel and C. Wietfeld, "Role-Based Connectivity Management with Realistic Air-to-Ground Channels for Cooperative UAVs," in IEEE Journal on Selected Areas in Communications, vol. 30, no. 5, pp. 951-963, June 2012, doi: 10.1109/JSAC.2012.120610.
