def saturation_vapour_pressure(T, P, type_hydrometeor='water'):
"""
Method to determine the saturation water vapour pressure
Parameters
----------
T : number or Quantity
Absolute temperature (C)
P : number or Quantity
Total atmospheric pressure (hPa)
type_hydrometeor : string
Type of hydrometeor. Valid strings are 'water' and 'ice'
Returns
-------
e_s: Quantity
Saturation water vapour pressure (hPa)
References
----------
[1] The radio refractive index: its formula and refractivity data
https://www.itu.int/rec/R-REC-P.453/en
"""
global __model
T = prepare_quantity(T, u.deg_C, 'Absolute temperature')
P = prepare_quantity(P, u.hPa, 'Total atmospheric pressure')
val = __model.saturation_vapour_pressure(T, P, type_hydrometeor)
return val * u.hPa
def rain_attenuation_synthesis(lat, lon, f, el, hs, Ns, Ts=1, tau=45, n=None):
"""
A method to generate a synthetic time series of rain attenuation values.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
f : number or Quantity
Frequency (GHz)
el : sequence, or number
Elevation angle (degrees)
hs : number, sequence, or numpy.ndarray, optional
Heigh above mean sea level of the earth station (km). If local data for
the earth station height above mean sea level is not available, an
estimate is obtained from the maps of topographic altitude
given in Recommendation ITU-R P.1511.
Ns : int
Number of samples
Ts : int
Time step between consecutive samples (seconds)
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
n : list, np.array, optional
Additive White Gaussian Noise used as input for the
Returns
-------
rain_att: numpy.ndarray
Synthesized rain attenuation time series (dB)
References
----------
[1] Characteristics of precipitation for propagation modelling
https://www.itu.int/rec/R-REC-P.1853/en
"""
global __model
lon = np.mod(lon, 360)
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(el, u.deg, 'Elevation angle')
hs = prepare_quantity(hs, u.km,
'Heigh above mean sea level of the earth station')
Ts = prepare_quantity(f, u.second, 'Time step between samples')
val = __model.rain_attenuation_synthesis(lat,
lon,
f,
el,
hs,
Ns,
Ts=Ts,
tau=tau,
n=n)
return val * u.dB
def fresnel_ellipse_radius(d1, d2, f):
"""
Computes the radius of the first Fresnel ellipsoid.
Parameters
----------
d1 : number, sequence, or numpy.ndarray
Distances from the first terminal to the path obstruction. [km]
d2 : number, sequence, or numpy.ndarray
Distances from the second terminal to the path obstruction. [km]
f : number
Frequency of the link [GHz]
Returns
-------
F1: Quantity
Radius of the first Fresnel ellipsoid [m]
References
----------
[1] Propagation data and prediction methods required for the design of
terrestrial line-of-sight systems: https://www.itu.int/rec/R-REC-P.530/en
"""
global __model
type_output = type(d1)
d1 = prepare_quantity(d1, u.km, 'Distance to the first terminal')
d2 = prepare_quantity(d2, u.km, 'Distance to the second terminal')
f = prepare_quantity(f, u.GHz, 'Frequency')
val = __model.fresnel_ellipse_radius(d1, d2, f)
return prepare_output_array(val, type_output) * u.m
def wet_term_radio_refractivity(e, T):
"""
Method to determine the wet term of the radio refractivity
Parameters
----------
e : number or Quantity
Water vapour pressure (hPa)
T : number or Quantity
Absolute temperature (K)
Returns
-------
N_wet: Quantity
Wet term of the radio refractivity (-)
References
----------
[1] The radio refractive index: its formula and refractivity data
https://www.itu.int/rec/R-REC-P.453/en
"""
global __model
e = prepare_quantity(e, u.hPa, 'Water vapour pressure ')
T = prepare_quantity(T, u.K, 'Absolute temperature')
val = __model.wet_term_radio_refractivity(e, T)
return val * u.dimensionless_unscaled
def multipath_loss_for_A(lat, lon, h_e, h_r, d, f, A):
""" Method for predicting the single-frequency (or narrow-band) fading
distribution at large fade depths in the average worst month in any part
of the world. Given a fade depth value 'A', determines the amount of time
it will be exceeded during a year
This method does not make use of the path profile and can be used for
initial planning, licensing, or design purposes.
This method is only valid for small percentages of time.
Multipath fading and enhancement only need to be calculated for path
lengths longer than 5 km, and can be set to zero for shorter paths.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
h_e : number
Emitter antenna height (above the sea level) [m]
h_r : number
Receiver antenna height (above the sea level) [m]
d : number, sequence, or numpy.ndarray
Distances between antennas [km]
f : number
Frequency of the link [GHz]
A : number
Fade depth [dB]
Returns
-------
p_w: Quantity
percentage of time that fade depth A is exceeded in the average
worst month [%]
References
----------
[1] Propagation data and prediction methods required for the design of
terrestrial line-of-sight systems: https://www.itu.int/rec/R-REC-P.530/en
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
h_e = prepare_quantity(h_e, u.m,
'Emitter antenna height (above sea level)')
h_r = prepare_quantity(h_r, u.m,
'Receiver antenna height (above sea level)')
d = prepare_quantity(d, u.km, 'Distance between antennas')
f = prepare_quantity(f, u.GHz, 'Frequency')
A = prepare_quantity(A, u.dB, 'Fade depth')
val = __model.multipath_loss_for_A(lat, lon, h_e, h_r, d, f, A)
return prepare_output_array(val, type_output) * u.percent
def standard_temperature(h, T_0=288.15):
"""
Method to compute the temperature of an standard atmosphere at
a given height.
The reference standard atmosphere is based on the United States Standard
Atmosphere, 1976, in which the atmosphere is divided into seven successive
layers showing linear variation with temperature.
Parameters
----------
h : number or Quantity
Height (km)
T_0 : number or Quantity
Surface temperature (K)
Returns
-------
T: Quantity
Temperature (K)
References
----------
[1] Reference Standard Atmospheres
https://www.itu.int/rec/R-REC-P.835/en
"""
global __model
h = prepare_quantity(h, u.km, 'Height')
T_0 = prepare_quantity(T_0, u.Kelvin, 'Surface temperature')
return __model.standard_temperature(h, T_0) * u.Kelvin
def specific_attenuation_coefficients(f, T):
"""
A method to compute the specific attenuation coefficient. The method is
based on Rayleigh scattering, which uses a double-Debye model for the
dielectric permittivity of water.
This model can be used to calculate the value of the specific attenuation
coefficient for frequencies up to 1000 GHz:
Parameters
----------
f : number
Frequency (GHz)
T : number
Temperature (degrees C)
Returns
-------
Kl: numpy.ndarray
Specific attenuation coefficient (dB/km)
References
----------
[1] Attenuation due to clouds and fog:
https://www.itu.int/rec/R-REC-P.840/en
"""
global __model
f = prepare_quantity(f, u.GHz, 'Frequency')
T = prepare_quantity(T, u.deg_C, 'Temperature')
return __model.specific_attenuation_coefficients(f, T)
def gamma0_exact(f, P, rho, T):
"""
Method to estimate the specific attenuation due to dry atmosphere using
the line-by-line method described in Annex 1 of the recommendation.
Parameters
----------
f : number or Quantity
Frequency (GHz)
P : number or Quantity
Atmospheric pressure (hPa)
rho : number or Quantity
Water vapor density (g/m3)
T : number or Quantity
Absolute temperature (K)
Returns
-------
gamma_w : Quantity
Dry atmosphere specific attenuation (dB/km)
References
--------
[1] Attenuation by atmospheric gases:
https://www.itu.int/rec/R-REC-P.676/en
"""
global __model
type_output = type(f)
f = prepare_quantity(f, u.GHz, 'Frequency')
P = prepare_quantity(P, u.hPa, 'Atmospheric pressure')
rho = prepare_quantity(rho, u.g / u.m**3, 'Water vapour density')
T = prepare_quantity(T, u.K, 'Temperature')
val = __model.gamma0_exact(f, P, rho, T)
return prepare_output_array(val, type_output) * u.dB / u.km
def dry_term_radio_refractivity(Pd, T):
"""
Method to determine the dry term of the radio refractivity
Parameters
----------
Pd : number or Quantity
Dry atmospheric pressure (hPa)
T : number or Quantity
Absolute temperature (K)
Returns
-------
N_dry: Quantity
Dry term of the radio refractivity (-)
References
----------
[1] The radio refractive index: its formula and refractivity data
https://www.itu.int/rec/R-REC-P.453/en
"""
global __model
Pd = prepare_quantity(Pd, u.hPa, 'Dry atmospheric pressure')
T = prepare_quantity(T, u.K, 'Absolute temperature')
val = __model.dry_term_radio_refractivity(Pd, T)
return val * u.dimensionless_unscaled
def XPD_outage_precipitation(lat, lon, d, f, el, C0_I, tau=45, U0=15, XPIF=0):
""" Estimate the probability of outage due to cross-polar discrimnation
reduction due to clear-air effects, assuming that a targe C0_I is
required.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
d : number, sequence, or numpy.ndarray
Distances between antennas [km]
f : number
Frequency of the link [GHz]
el : sequence, or number
Elevation angle (degrees)
C0_I : number
Carrier-to-interference ratio for a reference BER [dB]
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
U0 : number, optional
Coefficient for the cumulative distribution of the co-polar attenuation
(CPA) for rain. Default 15 dB.
XPIF : number, optional
Laboratory-measured cross-polarization improvement factor that gives
the difference in cross-polar isolation (XPI) at sufficiently large
carrier-to-noise ratio (typically 35 dB) and at a specific BER for
systems with and without cross polar interference canceller (XPIC).
A typical value of XPIF is about 20 dB. Default value 0 dB (no XPIC)
[dB]
Returns
-------
p_XP: Quantity
Probability of outage due to clear-air cross-polarization
References
----------
[1] Propagation data and prediction methods required for the design of
terrestrial line-of-sight systems: https://www.itu.int/rec/R-REC-P.530/en
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
d = prepare_quantity(d, u.km, 'Distance between antennas')
f = prepare_quantity(f, u.GHz, 'Frequency')
C0_I = prepare_quantity(C0_I, u.dB, 'Carrier-to-interference ratio')
U0 = prepare_quantity(U0, u.dB, 'Coefficient for the CPA')
XPIF = prepare_quantity(XPIF, u.dB,
'Cross-polarization improvement factor')
val = __model.XPD_outage_precipitation(lat, lon, d, f, C0_I, tau, U0, XPIF)
return prepare_output_array(val, type_output) * u.percent
def radio_refractive_index(P, e, T):
"""
Method to compute the radio refractive index
Parameters
----------
P : number or Quantity
Total atmospheric pressure (hPa)
e : number or Quantity
Water vapour pressure (hPa)
T : number or Quantity
Absolute temperature (K)
Returns
-------
n: Quantity
Radio refractive index (-)
References
----------
[1] The radio refractive index: its formula and refractivity data
https://www.itu.int/rec/R-REC-P.453/en
"""
global __model
P = prepare_quantity(P, u.hPa, 'Total atmospheric pressure')
e = prepare_quantity(e, u.hPa, 'Water vapour pressure ')
T = prepare_quantity(T, u.K, 'Absolute temperature')
val = __model.radio_refractive_index(P, e, T)
return val * u.dimensionless_unscaled
def rain_event_count(lat, lon, d, f, el, A, tau=45, R001=None):
""" Estimate the number of fade events exceeding attenuation 'A'
for 10 seconds or longer.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
d : number, sequence, or numpy.ndarray
Path length [km]
f : number
Frequency of the link [GHz]
el : sequence, or number
Elevation angle (degrees)
A : number
Fade depth
R001: number, optional
Point rainfall rate for the location for 0.01% of an average year
(mm/h). If not provided, an estimate is obtained from Recommendation
Recommendation ITU-R P.837. Some useful values:
* 0.25 mm/h : Drizle
* 2.5 mm/h : Light rain
* 12.5 mm/h : Medium rain
* 25.0 mm/h : Heavy rain
* 50.0 mm/h : Dwonpour
* 100 mm/h : Tropical
* 150 mm/h : Monsoon
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
Returns
-------
p: Quantity
Percentage of time that the attenuation A is exceeded.
References
----------
[1] Propagation data and prediction methods required for the design of
terrestrial line-of-sight systems: https://www.itu.int/rec/R-REC-P.530/en
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
d = prepare_quantity(d, u.km, 'Distance between antennas')
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(el, u.deg, 'Elevation Angle')
A = prepare_quantity(A, u.dB, 'Fade depth')
R001 = prepare_quantity(R001, u.mm / u.hr, 'Rainfall Rate')
val = __model.rain_event_count(lat, lon, d, f, el, A, tau, R001)
return prepare_output_array(val, type_output) * u.percent
def rain_attenuation_probability(lat, lon, el, hs=None, Ls=None, P0=None):
"""
The following procedure computes the probability of non-zero rain
attenuation on a given slant path Pr(Ar > 0).
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
el : sequence, or number
Elevation angle (degrees)
hs : number, sequence, or numpy.ndarray, optional
Heigh above mean sea level of the earth station (km). If local data for
the earth station height above mean sea level is not available, an
estimate is obtained from the maps of topographic altitude
given in Recommendation ITU-R P.1511.
Ls : number, sequence, or numpy.ndarray, optional
Slant path length from the earth station to the rain height (km). If
data about the rain height is not available, this value is estimated
automatically using Recommendation ITU-R P.838
P0 : number, sequence, or numpy.ndarray, optional
Probability of rain at the earth station, (0 ≤ P0 ≤ 1)
Returns
-------
p: Quantity
Probability of rain attenuation on the slant path (%)
References
----------
[1] Propagation data and prediction methods required for the design of
Earth-space telecommunication systems:
https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.618-12-201507-I!!PDF-E.pdf
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
el = prepare_quantity(prepare_input_array(el), u.deg, 'Elevation angle')
hs = prepare_quantity(hs, u.km,
'Heigh above mean sea level of the earth station')
Ls = prepare_quantity(Ls, u.km,
'Heigh above mean sea level of the earth station')
P0 = prepare_quantity(P0, u.pct, 'Point rainfall rate')
val = __model.rain_attenuation_probability(lat, lon, el, hs, Ls, P0)
return prepare_output_array(val, type_output) * 100 * u.pct
def fit_rain_attenuation_to_lognormal(lat, lon, f, el, hs, P_k, tau):
"""
Compute the log-normal fit of rain attenuation vs. probability of
occurrence.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
f : number or Quantity
Frequency (GHz)
el : sequence, or number
Elevation angle (degrees)
hs : number, sequence, or numpy.ndarray, optional
Heigh above mean sea level of the earth station (km). If local data for
the earth station height above mean sea level is not available, an
estimate is obtained from the maps of topographic altitude
given in Recommendation ITU-R P.1511.
P_k : number
Rain probability
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
Returns
-------
sigma_lna:
Standar deviation of the lognormal distribution
m_lna:
Mean of the lognormal distribution
References
----------
[1] Propagation data and prediction methods required for the design of
Earth-space telecommunication systems:
https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.618-12-201507-I!!PDF-E.pdf
"""
global __model
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(prepare_input_array(el), u.deg, 'Elevation angle')
hs = prepare_quantity(hs, u.km,
'Heigh above mean sea level of the earth station')
tau = prepare_quantity(tau, u.one, 'Polarization tilt angle')
sigma_lna, m_lna = __model.fit_rain_attenuation_to_lognormal(
lat, lon, f, el, hs, P_k, tau)
return sigma_lna, m_lna
def slant_inclined_path_equivalent_height(f, p):
""" Computes the equivalent height to be used for oxygen and water vapour
gaseous attenuation computations.
Parameters
----------
f : number or Quantity
Frequency (GHz)
p : number
Percentage of the time the gaseous attenuation value is exceeded.
Returns
-------
ho, hw : Quantity
Equivalent height for oxygen and water vapour (m)
References
--------
[1] Attenuation by atmospheric gases:
https://www.itu.int/rec/R-REC-P.676/en
"""
type_output = type(f)
f = prepare_quantity(f, u.GHz, 'Frequency')
val = __model.slant_inclined_path_equivalent_height(f, p)
return prepare_output_array(val, type_output) * u.m
def pressure(lat, h, season='summer'):
"""
Method to determine the pressure as a function of altitude and latitude,
for calculating gaseous attenuation along an Earth-space path.
This method is recommended when more reliable local data are not available.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
h : number or Quantity
Height (km)
season : string
Season of the year (available values, 'summer', and 'winter').
Default 'summer'
Returns
-------
P: Quantity
Pressure (hPa)
References
----------
[1] Reference Standard Atmospheres
https://www.itu.int/rec/R-REC-P.835/en
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
h = prepare_quantity(h, u.km, 'Height')
val = __model.pressure(lat, h, season)
return prepare_output_array(val, type_output) * u.hPa
def rain_specific_attenuation_coefficients(f, el, tau):
"""
A method to compute the values for the coefficients k and α to compute
the specific attenuation γ_R (dB/km)
Parameters
----------
f : number or Quantity
Frequency (GHz)
el : number, sequence, or numpy.ndarray
Elevation angle of the receiver points
tau : number, sequence, or numpy.ndarray
Polarization tilt angle relative to the horizontal (degrees). Tau = 45
deg for circular polarization)
Returns
-------
k: number
Zero isoterm height (km)
alpha: number
Zero isoterm height (km)
References
----------
[1] Rain height model for prediction methods:
https://www.itu.int/rec/R-REC-P.838/en
"""
global __model
f = prepare_quantity(f, u.GHz, 'Frequency')
return __model.rain_specific_attenuation_coefficients(f, el, tau)
def zenit_water_vapour_attenuation(lat, lon, p, f, V_t=None, h=None):
"""
An alternative method may be used to compute the slant path attenuation by
water vapour, in cases where the integrated water vapour content along the
path, ``V_t``, is known.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
p : number
Percentage of the time the zenit water vapour attenuation value is
exceeded.
f : number or Quantity
Frequency (GHz)
V_t : number or Quantity, optional
Integrated water vapour content along the path (kg/m2 or mm).
If not provided this value is estimated using Recommendation
ITU-R P.836. Default value None
h : number, sequence, or numpy.ndarray
Altitude of the receivers. If None, use the topographical altitude as
described in recommendation ITU-R P.1511
Returns
-------
A_w : Quantity
Water vapour attenuation along the slant path (dB)
References
--------
[1] Attenuation by atmospheric gases:
https://www.itu.int/rec/R-REC-P.676/en
"""
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
f = prepare_quantity(f, u.GHz, 'Frequency')
V_t = prepare_quantity(V_t, u.kg / u.m**2,
'Integrated water vapour content along the path')
h = prepare_quantity(h, u.km, 'Altitude')
val = __model.zenit_water_vapour_attenuation(lat, lon, p, f, V_t=V_t, h=h)
return prepare_output_array(val, type_output) * u.dB
def rain_cross_polarization_discrimination(Ap, f, el, p, tau=45):
"""
Calculation of the cross-polarization discrimination (XPD) statistics from
rain attenuation statistics. The following procedure provides estimates of
the long-term statistics of the cross-polarization discrimination (XPD)
statistics for frequencies up to 55 GHz and elevation angles lower than 60
deg.
Parameters
----------
Ap : number, sequence, or numpy.ndarray
Rain attenuation (dB) exceeded for the required percentage of time, p,
for the path in question, commonly called co-polar attenuation (CPA)
f : number
Frequency
el : number, sequence, or numpy.ndarray
Elevation angle (degrees)
p : number
Percetage of the time the XPD is exceeded.
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
Returns
-------
attenuation: Quantity
Cross-polarization discrimination (dB)
References
----------
[1] Propagation data and prediction methods required for the design of
Earth-space telecommunication systems:
https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.618-12-201507-I!!PDF-E.pdf
"""
global __model
type_output = type(Ap)
Ap = prepare_input_array(Ap)
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(el, u.deg, 'Elevation angle')
tau = prepare_quantity(tau, u.one, 'Polarization tilt angle')
val = __model.rain_cross_polarization_discrimination(Ap, f, el, p, tau=tau)
return prepare_output_array(val, type_output) * u.dB
def cloud_attenuation(lat, lon, el, f, p):
"""
A method to estimate the attenuation due to clouds along slant paths for
a given probability.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
el : number, sequence, or numpy.ndarray
Elevation angle of the receiver points (deg)
f : number
Frequency (GHz)
p : number
Percentage of time exceeded for p% of the average year
Returns
-------
p: numpy.ndarray
Rainfall rate exceeded for p% of the average year
References
----------
[1] Attenuation due to clouds and fog:
https://www.itu.int/rec/R-REC-P.840/en
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
el = prepare_quantity(el, u.deg, 'Elevation angle')
f = prepare_quantity(f, u.GHz, 'Frequency')
val = __model.cloud_attenuation(lat, lon, el, f, p)
return prepare_output_array(val, type_output) * u.dB
def diffraction_loss(d1, d2, h, f):
"""
Diffraction loss over average terrain. This value is valid for losses
greater than 15 dB.
Parameters
----------
d1 : number, sequence, or numpy.ndarray
Distances from the first terminal to the path obstruction. [km]
d2 : number, sequence, or numpy.ndarray
Distances from the second terminal to the path obstruction. [km]
h : number, sequence, or numpy.ndarray
Height difference between most significant path blockage
and the path trajectory. h is negative if the top of the obstruction
of interest is above the virtual line-of-sight. [m]
f : number
Frequency of the link [GHz]
Returns
-------
A_d: Quantity
Diffraction loss over average terrain [dB]
References
----------
[1] Propagation data and prediction methods required for the design of
terrestrial line-of-sight systems: https://www.itu.int/rec/R-REC-P.530/en
"""
global __model
type_output = type(d1)
d1 = prepare_quantity(d1, u.km, 'Distance to the first terminal')
d2 = prepare_quantity(d2, u.km, 'Distance to the second terminal')
h = prepare_quantity(h, u.m, 'Height difference')
f = prepare_quantity(f, u.GHz, 'Frequency')
val = __model.diffraction_loss(d1, d2, h, f)
return prepare_output_array(val, type_output) * u.m
def standard_water_vapour_pressure(h, h_0=2, rho_0=7.5):
"""
Method to compute the water vapour pressure of an standard atmosphere at
a given height.
The reference standard atmosphere is based on the United States Standard
Atmosphere, 1976, in which the atmosphere is divided into seven successive
layers showing linear variation with temperature.
Parameters
----------
h : number or Quantity
Height (km)
h_0 : number or Quantity
Scale height (km)
rho_0 : number or Quantity
Surface water vapour density (g/m^3)
Returns
-------
e: Quantity
Water vapour pressure (hPa)
References
----------
[1] Reference Standard Atmospheres
https://www.itu.int/rec/R-REC-P.835/en
"""
global __model
h = prepare_quantity(h, u.km, 'Height')
h_0 = prepare_quantity(h_0, u.km, 'Scale height')
rho_0 = prepare_quantity(
rho_0,
u.g / u.m**3,
'Surface water vapour density')
return __model.standard_water_vapour_pressure(h, h_0, rho_0) * u.hPa
def standard_pressure(h, T_0=288.15, P_0=1013.25):
"""
Method to compute the total atmopsheric pressure of an standard atmosphere
at a given height.
The reference standard atmosphere is based on the United States Standard
Atmosphere, 1976, in which the atmosphere is divided into seven successive
layers showing linear variation with temperature.
Parameters
----------
h : number or Quantity
Height (km)
T_0 : number or Quantity
Surface temperature (K)
P_0 : number or Quantity
Surface pressure (hPa)
Returns
-------
P: Quantity
Pressure (hPa)
References
----------
[1] Reference Standard Atmospheres
https://www.itu.int/rec/R-REC-P.835/en
"""
global __model
type_output = type(h)
h = prepare_quantity(h, u.km, 'Height')
h = np.atleast_1d(h)
T_0 = prepare_quantity(T_0, u.Kelvin, 'Surface temperature')
P_0 = prepare_quantity(P_0, u.hPa, 'Surface pressure')
val = __model.standard_pressure(h, T_0, P_0)
return prepare_output_array(val, type_output) * u.hPa
def rain_specific_attenuation(R, f, el, tau):
"""
A method to compute the specific attenuation γ_R (dB/km) from rain. The
value is obtained from hte rain rate R (mm/h) using a power law
relationship.
..math:
\\gamma_R = k R^\\alpha
Parameters
----------
R : number, sequence, numpy.ndarray or Quantity
Rain rate (mm/h)
f : number or Quantity
Frequency (GHz)
el : number, sequence, or numpy.ndarray
Elevation angle of the receiver points
tau : number, sequence, or numpy.ndarray
Polarization tilt angle relative to the horizontal (degrees). Tau = 45
deg for circular polarization)
Returns
-------
gamma_R: numpy.ndarray
Specific attenuation from rain (dB/km)
References
----------
[1] Rain height model for prediction methods:
https://www.itu.int/rec/R-REC-P.838/en
"""
global __model
R = prepare_quantity(R, u.mm / u.hr, 'Rain rate')
f = prepare_quantity(f, u.GHz, 'Frequency')
return __model.rain_specific_attenuation(R, f, el, tau) * u.dB / u.km
def gaseous_attenuation_terrestrial_path(r, f, el, rho, P, T, mode):
"""
Estimate the attenuation of atmospheric gases on terrestrial paths.
This function operates in two modes, 'approx', and 'exact':
* 'approx': a simplified approximate method to estimate gaseous attenuation
that is applicable in the frequency range 1-350 GHz.
* 'exact': an estimate of gaseous attenuation computed by summation of
individual absorption lines that is valid for the frequency
range 1-1,000 GHz
Parameters
----------
r : number or Quantity
Path length (km)
f : number or Quantity
Frequency (GHz)
el : sequence, number or Quantity
Elevation angle (degrees)
rho : number or Quantity
Water vapor density (g/m**3)
P : number or Quantity
Atmospheric pressure (hPa)
T : number or Quantity
Absolute temperature (K)
mode : string, optional
Mode for the calculation. Valid values are 'approx', 'exact'. If
'approx' Uses the method in Annex 2 of the recommendation (if any),
else uses the method described in Section 1. Default, 'approx'
Returns
-------
attenuation: Quantity
Terrestrial path attenuation (dB)
References
--------
[1] Attenuation by atmospheric gases:
https://www.itu.int/rec/R-REC-P.676/en
"""
type_output = type(el)
r = prepare_quantity(r, u.km, 'Path Length')
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(prepare_input_array(el), u.deg, 'Elevation angle')
rho = prepare_quantity(rho, u.g / u.m**3, 'Water vapor density')
P = prepare_quantity(P, u.hPa, 'Atospheric pressure')
T = prepare_quantity(T, u.K, 'Temperature')
val = __model.gaseous_attenuation_terrestrial_path(r, f, el, rho, P, T,
mode)
return prepare_output_array(val, type_output) * u.dB
def total_water_vapour_content(lat, lon, p, alt=None):
"""
Method to compute the total water vapour content along a path at any
desired location on the surface of the Earth.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
p : number
Percentage of time exceeded for p% of the average year
alt : number, sequence, or numpy.ndarray
Altitude of the receivers. If None, use the topographical altitude as
described in recommendation ITU-R P.1511
Returns
-------
V: Quantity
Total water vapour content (kg/m2)
References
----------
[1] Water vapour: surface density and total columnar content
https://www.itu.int/rec/R-REC-P.836/en
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
alt = prepare_input_array(alt)
alt = prepare_quantity(alt, u.km, 'Altitude of the receivers')
val = __model.total_water_vapour_content(lat, lon, p, alt)
return prepare_output_array(val, type_output) * u.kg / u.m**2
def gaseous_attenuation_inclined_path(f, el, rho, P, T, h1, h2, mode='approx'):
"""
Estimate the attenuation of atmospheric gases on inclined paths between two
ground stations at heights h1 and h2. This function operates in two modes,
'approx', and 'exact':
* 'approx': a simplified approximate method to estimate gaseous attenuation
that is applicable in the frequency range 1-350 GHz.
* 'exact': an estimate of gaseous attenuation computed by summation of
individual absorption lines that is valid for the frequency
range 1-1,000 GHz
Parameters
----------
f : number or Quantity
Frequency (GHz)
el : sequence, number or Quantity
Elevation angle (degrees)
rho : number or Quantity
Water vapor density (g/m3)
P : number or Quantity
Atmospheric pressure (hPa)
T : number or Quantity
Absolute temperature (K)
h1 : number or Quantity
Height of ground station 1 (km)
h2 : number or Quantity
Height of ground station 2 (km)
mode : string, optional
Mode for the calculation. Valid values are 'approx', 'exact'. If
'approx' Uses the method in Annex 2 of the recommendation (if any),
else uses the method described in Section 1. Default, 'approx'
Returns
-------
attenuation: Quantity
Inclined path attenuation (dB)
References
--------
[1] Attenuation by atmospheric gases:
https://www.itu.int/rec/R-REC-P.676/en
"""
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(el, u.deg, 'Elevation angle')
type_output = type(el)
rho = prepare_quantity(rho, u.g / u.m**3, 'Water vapor density')
P = prepare_quantity(P, u.hPa, 'Atospheric pressure')
T = prepare_quantity(T, u.K, 'Temperature')
h1 = prepare_quantity(h1, u.km, 'Height of Ground Station 1')
h2 = prepare_quantity(h2, u.km, 'Height of Ground Station 2')
val = __model.gaseous_attenuation_inclined_path(f,
el,
rho,
P,
T,
h1,
h2,
mode=mode)
return prepare_output_array(val, type_output) * u.dB
def rain_attenuation(lat,
lon,
f,
el,
hs=None,
p=0.01,
R001=None,
tau=45,
Ls=None):
"""
Calculation of long-term rain attenuation statistics from point rainfall
rate.
The following procedure provides estimates of the long-term statistics of
the slant-path rain attenuation at a given location for frequencies up
to 55 GHz.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
f : number
Frequency (GHz)
el : sequence, or number
Elevation angle (degrees)
hs : number, sequence, or numpy.ndarray, optional
Heigh above mean sea level of the earth station (km). If local data for
the earth station height above mean sea level is not available, an
estimate is obtained from the maps of topographic altitude
given in Recommendation ITU-R P.1511.
p : number, optional
Percetage of the time the rain attenuation value is exceeded.
R001: number, optional
Point rainfall rate for the location for 0.01% of an average year
(mm/h).
If not provided, an estimate is obtained from Recommendation
Recommendation ITU-R P.837. Some useful values:
* 0.25 mm/h : Drizle
* 2.5 mm/h : Light rain
* 12.5 mm/h : Medium rain
* 25.0 mm/h : Heavy rain
* 50.0 mm/h : Dwonpour
* 100 mm/h : Tropical
* 150 mm/h : Monsoon
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
Ls :number, optional
Slant path length (km). If not provided, it will be computed using the
rain height and the elevation angle. The ITU model does not require
this parameter as an input.
Returns
-------
attenuation: Quantity
Attenuation due to rain (dB)
References
--------
[1] Propagation data and prediction methods required for the design of
Earth-space telecommunication systems:
https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.618-12-201507-I!!PDF-E.pdf
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(prepare_input_array(el), u.deg, 'Elevation angle')
hs = prepare_quantity(hs, u.km,
'Heigh above mean sea level of the earth station')
R001 = prepare_quantity(R001, u.mm / u.hr, 'Point rainfall rate')
tau = prepare_quantity(tau, u.one, 'Polarization tilt angle')
Ls = prepare_quantity(Ls, u.km, 'Slant path length')
val = __model.rain_attenuation(lat,
lon,
f,
el,
hs=hs,
p=p,
R001=R001,
tau=tau,
Ls=Ls)
return prepare_output_array(val, type_output) * u.dB
def scintillation_attenuation(lat,
lon,
f,
el,
p,
D,
eta=0.5,
T=None,
H=None,
P=None,
hL=1000):
"""
Calculation of monthly and long-term statistics of amplitude scintillations
at elevation angles greater than 5° and frequencies up to 20 GHz.
Parameters
----------
lat : number, sequence, or numpy.ndarray
Latitudes of the receiver points
lon : number, sequence, or numpy.ndarray
Longitudes of the receiver points
f : number or Quantity
Frequency (GHz)
el : sequence, or number
Elevation angle (degrees)
p : number
Percetage of the time the scintillation attenuation value is exceeded.
D: number
Physical diameter of the earth-station antenna (m)
eta: number, optional
Antenna efficiency. Default value 0.5 (conservative estimate)
T: number, sequence, or numpy.ndarray, optional
Average surface ambient temperature (°C) at the site. If None, uses the
ITU-R P.453 to estimate the wet term of the radio refractivity.
H: number, sequence, or numpy.ndarray, optional
Average surface relative humidity (%) at the site. If None, uses the
ITU-R P.453 to estimate the wet term of the radio refractivity.
P: number, sequence, or numpy.ndarray, optional
Average surface pressure (hPa) at the site. If None, uses the
ITU-R P.453 to estimate the wet term of the radio refractivity.
hL : number, optional
Height of the turbulent layer (m). Default value 1000 m
Returns
-------
attenuation: Quantity
Attenuation due to scintillation (dB)
References
----------
[1] Propagation data and prediction methods required for the design of
Earth-space telecommunication systems:
https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.618-12-201507-I!!PDF-E.pdf
"""
global __model
type_output = type(lat)
lat = prepare_input_array(lat)
lon = prepare_input_array(lon)
lon = np.mod(lon, 360)
f = prepare_quantity(f, u.GHz, 'Frequency')
el = prepare_quantity(prepare_input_array(el), u.deg, 'Elevation angle')
D = prepare_quantity(D, u.m, 'Antenna diameter')
eta = prepare_quantity(eta, u.one, 'Antenna efficiency')
T = prepare_quantity(T, u.deg_C, 'Average surface temperature')
H = prepare_quantity(H, u.percent, 'Average surface relative humidity')
P = prepare_quantity(P, u.hPa, 'Average surface pressure')
hL = prepare_quantity(hL, u.m, 'Height of the turbulent layer')
val = __model.scintillation_attenuation(lat,
lon,
f,
el,
p,
D,
eta=eta,
T=T,
H=H,
P=P,
hL=hL)
return prepare_output_array(val, type_output) * u.dB
def site_diversity_rain_outage_probability(lat1,
lon1,
a1,
el1,
lat2,
lon2,
a2,
el2,
f,
tau=45,
hs1=None,
hs2=None):
"""
Calculate the link outage probability in a diversity based scenario (two
ground stations) due to rain attenuation. This method is valid for
frequencies below 20 GHz, as at higher frequencies other impairments might
affect affect site diversity performance.
This method predicts Pr(A1 > a1, A2 > a2), the joint probability (%) that
the attenuation on the path to the first site is greater than a1 and the
attenuation on the path to the second site is greater than a2.
Parameters
----------
lat1 : number or Quantity
Latitude of the first ground station (deg)
lon1 : number or Quantity
Longitude of the first ground station (deg)
a1 : number or Quantity
Maximum admissible attenuation of the first ground station (dB)
el1 : number or Quantity
Elevation angle to the first ground station (deg)
lat2 : number or Quantity
Latitude of the second ground station (deg)
lon2 : number or Quantity
Longitude of the second ground station (deg)
a2 : number or Quantity
Maximum admissible attenuation of the second ground station (dB)
el2 : number or Quantity
Elevation angle to the second ground station (deg)
f : number or Quantity
Frequency (GHz)
tau : number, optional
Polarization tilt angle relative to the horizontal (degrees)
(tau = 45 deg for circular polarization). Default value is 45
hs1 : number or Quantity, optional
Altitude over the sea level of the first ground station (km). If not
provided, uses Recommendation ITU-R P.1511 to compute the toporgraphic
altitude
hs2 : number or Quantity, optional
Altitude over the sea level of the first ground station (km). If not
provided, uses Recommendation ITU-R P.1511 to compute the toporgraphic
altitude
Returns
-------
probability: Quantity
Joint probability (%) that the attenuation on the path to the first
site is greater than a1 and the attenuation on the path to the second
site is greater than a2
References
----------
[1] Propagation data and prediction methods required for the design of
Earth-space telecommunication systems:
https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.618-12-201507-I!!PDF-E.pdf
"""
global __model
type_output = type(lat1)
lon1 = np.mod(lon1, 360)
lat1 = prepare_quantity(lat1, u.deg, 'Latitude in ground station 1')
lon1 = prepare_quantity(lon1, u.deg, 'Longitude in ground station 1')
a1 = prepare_quantity(a1, u.dB, 'Attenuation margin in ground station 1')
lon2 = np.mod(lon2, 360)
lat2 = prepare_quantity(lat2, u.deg, 'Latitude in ground station 2')
lon2 = prepare_quantity(lon2, u.deg, 'Longitude in ground station 2')
a2 = prepare_quantity(a2, u.dB, 'Attenuation margin in ground station 2')
f = prepare_quantity(f, u.GHz, 'Frequency')
tau = prepare_quantity(tau, u.one, 'Polarization tilt angle')
el1 = prepare_quantity(el1, u.deg, 'Elevation angle in ground station 1')
el2 = prepare_quantity(el2, u.deg, 'Elevation angle in ground station 2')
hs1 = prepare_quantity(hs1, u.km,
'Altitude over the sea level for ground station 1')
hs2 = prepare_quantity(hs2, u.km,
'Altitude over the sea level for ground station 2')
val = __model.site_diversity_rain_outage_probability(lat1,
lon1,
a1,
lat2,
lon2,
a2,
f,
el1,
el2,
tau=tau,
hs1=hs1,
hs2=hs2)
return prepare_output_array(val, type_output) * u.pct
