losses_complete#

pycraf.pathprof.losses_complete(freq, temperature, pressure, lon_t, lat_t, lon_r, lat_r, h_tg, h_rg, hprof_step, timepercent, G_t=<Decibel 0. dB>, G_r=<Decibel 0. dB>, omega=<Quantity 0. %>, d_tm=None, d_lm=None, d_ct=None, d_cr=None, zone_t=CLUTTER.UNKNOWN, zone_r=CLUTTER.UNKNOWN, polarization=0, version=16, delta_N=None, N0=None, hprof_dists=None, hprof_heights=None, hprof_bearing=None, hprof_backbearing=None, generic_heights=False, base_water_density=<Quantity 7.5 g / m3>)[source]#

Calculate propagation losses for a fixed path using a parallelized method.

The difference to the usual PathProp + loss_complete approach is, that losses_complete supports full numpy broad-casting. This allows perform many calculations at once, e.g., if one interested in a statistics plot of L vs. time_percent, without querying the height profile over and over.

Parameters:

freqQuantity: Frequency of radiation [GHz]
temperatureQuantity: Ambient temperature at path midpoint [K]
pressureQuantity: Ambient pressure at path midpoint [hPa]
lon_t, lat_tQuantity, scalar: Geographic longitude/latitude of transmitter [deg]
lon_r, lat_rQuantity, scalar: Geographic longitude/latitude of receiver [deg]
h_tg, h_rgQuantity: Transmitter/receiver height over ground [m]
hprof_stepQuantity, scalar: Distance resolution of height profile along path [m]
timepercentQuantity: Time percentage [%] (maximal 50%)
G_t, G_rQuantity, optional: Antenna gain (transmitter, receiver) in the direction of the horizon(!) along the great-circle interference path [dBi]
omegaQuantity, optional: Fraction of the path over water [%] (see Table 3) (default: 0%)
d_tmQuantity, optional: longest continuous land (inland + coastal) section of the great-circle path [km] (default: distance between Tx and Rx)
d_lmQuantity, optional: longest continuous inland section of the great-circle path [km] (default: distance between Tx and Rx)
d_ct, d_crQuantity, optional: Distance over land from transmitter/receiver antenna to the coast along great circle interference path [km] (default: 50000 km)
zone_t, zone_rndarray of int (aka CLUTTER enum), optional: Clutter type for transmitter/receiver terminal. (default: CLUTTER.UNKNOWN)
polarizationndarray of int, optional: Polarization (default: 0) Allowed values are: 0 - horizontal, 1 - vertical
versionndarray of int, optional: ITU-R Rec. P.452 version. Allowed values are: 14, 16
delta_NQuantity, scalar, optional: Average radio-refractive index lapse-rate through the lowest 1 km of the atmosphere [N-units/km = 1/km] (default: query deltaN_N0_from_map)
N_0Quantity, scalar, optional: Sea-level surface refractivity [N-units = dimless] (default: query deltaN_N0_from_map)
hprof_distsQuantity, optional: Distance vector associated with the height profile hprof_heights. (default: query srtm_height_profile)
hprof_heightsQuantity, optional: Terrain heights profile for the distances in hprof_dists. (default: query srtm_height_profile)
hprof_bearingQuantity, optional: Start bearing of the height profile path. (default: query srtm_height_profile)
hprof_backbearingQuantity, optional: Back-bearing of the height profile path. (default: query srtm_height_profile)
generic_heightsbool: If generic_heights is set to True, heights will be set to zero. This can be useful for generic (aka flat-Earth) computations. The option is only meaningful, if the hprof_xxx parameters are set to None (which means automatic querying of the profiles). (Default: False)
base_water_densityQuantity, optional: For atmospheric attenuation, the water vapor content plays a role. In Rec. ITU-R P.452, Eq. (9a), the water content is variable (depending on the fraction of the path over the water). However, the base level is set to \(7.5~\mathrm{g}/\mathrm{m}^3\). For extraordinarily dry places, which are often used for radio astronomy, this value can be too high. (Default: 7.5 g / m^3)

Returns:

resultsdict

Results of the path attenuation calculation. Each entry in the dictionary is a nD Quantity containing the associated values for the path. The following entries are contained:

L_b0p - Free-space loss including focussing effects (for p% of time) [dB]
L_bd - Basic transmission loss associated with diffraction
not exceeded for p% time [dB]; L_bd = L_b0p + L_dp
L_bs - Tropospheric scatter loss [dB]
L_ba - Ducting/layer reflection loss [dB]
L_b - Complete path propagation loss [dB]
L_b_corr - As L_b but with clutter correction [dB]
eps_pt - Elevation angle of paths w.r.t. Tx [deg]
eps_pr - Elevation angle of paths w.r.t. Rx [deg]
d_lt - Distance to horizon w.r.t. Tx [km]
d_lr - Distance to horizon w.r.t. Rx [km]
path_type - Path type (0 - LoS, 1 - Trans-horizon)

Notes

It is extremely important how the broadcasting axes are chosen! There are six entities - freq, h_tg, h_rg, version, zone_t, zone_r - that have influence on the propagation path geometry. In the broadcasted arrays, the associated axes should vary as slow as possible. The internal Cython routine will trigger a re-computation of the path geometry if one of these parameters changes. Therefore, if the axes for frequency and time_percent would have been chosen in the opposite manner, the function would run about an order of magnitude slower!
The diffraction-loss algorithm was changed between ITU-R P.452 version 14 and 15. The former used a Deygout method, the new one is based on a Bullington calculation with correction terms.
In future versions, more entries may be added to the results dictionary.

Examples

A typical usage would be:

import numpy as np
import matplotlib.pyplot as plt
from pycraf import pathprof
from astropy import units as u

frequency = np.logspace(-1, 2, 200) * u.GHz
temperature = 290. * u.K
pressure = 980 * u.hPa
lon_t, lat_t = 6.8836 * u.deg, 50.525 * u.deg
lon_r, lat_r = 7.3334 * u.deg, 50.635 * u.deg
h_tg, h_rg = 20 * u.m, 30 * u.m
hprof_step = 100 * u.m
time_percent = np.logspace(-3, np.log10(50), 100) * u.percent
zone_t, zone_r = pathprof.CLUTTER.URBAN, pathprof.CLUTTER.SUBURBAN

# as frequency and time_percent are arrays, we need to add
# new axes to allow proper broadcasting
results = pathprof.losses_complete(
    frequency[:, np.newaxis],
    temperature,
    pressure,
    lon_t, lat_t,
    lon_r, lat_r,
    h_tg, h_rg,
    hprof_step,
    time_percent[np.newaxis],
    zone_t=zone_t, zone_r=zone_r,
    )

# 2D plot of L_b vs frequency and time_percent
# (proper axes labels and units omitted!)
plt.imshow(results['L_b'].value)
plt.show()