def water_vapour_pressure(T, P, H): """ Method to determine the water vapour pressure Parameters ---------- - T : number or Quantity Temperature (°C) - P : number or Quantity Total atmospheric pressure (hPa) - H : number or Quantity Relative humidity (%) Returns ------- - e_ice: Quantity Water vapour pressure for ice (hPa) - e_water: Quantity Water vapour pressure for water (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, 'Temperature') P = prepare_quantity(P, u.hPa, 'Total atmospheric pressure') H = prepare_quantity(H, u.percent, 'Total atmospheric pressure') e_ice, e_water = __model.water_vapour_pressure(T, P, H) return e_ice * u.hPa, e_water * u.hPa
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 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 : sequence, array Temperature (degrees C) Returns ------- - Kl: numpy.ndarray Specific attenuation coefficient (dB/km)/(g/m3) 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 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] ** d = d1 + d2 ** - 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 saturation_vapour_pressure(T, P): """ Method to determine the saturation water vapour pressure Parameters ---------- - T : number or Quantity temperature (°C) - P : number or Quantity Total atmospheric pressure (hPa) Returns ------- - es_ice: Quantity Saturation vapour pressure for ice (hPa) - es_water: Quantity Saturation vapour pressure for water (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, 'Temperature') P = prepare_quantity(P, u.hPa, 'Total atmospheric pressure') es_ice, es_water = __model.saturation_vapour_pressure(T, P) return es_ice * u.hPa, es_water * u.hPa
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 Total atmospheric pressure (hPa)(Ptot = Pdry + e) - rho : number or Quantity Water vapor density (g/m3) - T : number or Quantity Absolute temperature (K) Returns ------- - gamma_0 : 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, 'Total 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 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 or Quantity Total Atmospheric Pressure (hPa)(Ptot = Pdry + e) Returns ------- - ho, hw : Quantity Equivalent height for oxygen and water vapour (km) 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') P = prepare_quantity(P, u.hPa, 'Total atmospheric pressure') val = __model.slant_inclined_path_equivalent_height(f, P) return prepare_output_array(val, type_output) * u.km
def dry_term_radio_refractivity(P, e, T): """ Method to determine the dry term of the radio refractivity Parameters ---------- - P : number or Quantity Total atmospheric pressure (hPa) - T : number or Quantity Absolute temperature (K) - e : number or Quantity water vapour partial pressure (hPa) 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 P = prepare_quantity(P, u.hPa, 'Total atmospheric pressure') T = prepare_quantity(T, u.K, 'Absolute temperature') e = prepare_quantity(e, u.hPa, 'Water vapour partial pressure') val = __model.dry_term_radio_refractivity(P, e, T) return val * u.dimensionless_unscaled
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 absolute temperature (K) Returns ----------- - T: Quantity Absolute 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 inverse_rain_attenuation(lat, lon, d, f, el, Ap, tau, R001=None): """ Estimate the percentage of time a given attenuation is exceeded due to rain events. 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) - Ap : 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') Ap = prepare_quantity(Ap, u.dB, 'Fade depth') R001 = prepare_quantity(R001, u.mm / u.hr, 'Rainfall Rate') val = __model.inverse_rain_attenuation(lat, lon, d, f, el, Ap, tau, R001) return prepare_output_array(val, type_output) * u.percent
def fit_rain_attenuation_to_lognormal(lat, lon, f, el, tau, hs=None, P_k=None): """ 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) - tau : number Polarization tilt angle relative to the horizontal (degrees) (tau = 45 deg for circular polarization). - 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, sequence, or numpy.ndarray, optional Rain probability on k-th path (percent [%]). if the local data for the earth station is not available, an estimate is obtained from the maps given in Recommendation ITU-R P.837. 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') P_k = prepare_quantity(P_k, u.pct, 'Rain probability on k-th path') tau = prepare_quantity(tau, u.one, 'Polarization tilt angle') sigma_lna, m_lna = __model.fit_rain_attenuation_to_lognormal( lat, lon, f, el, tau, hs, P_k) return sigma_lna, m_lna
def cloud_attenuation_synthesis(lat, lon, f, el, Ns, Ts=1, n=None, rain_contribution=False): """ The time series synthesis method generates a time series that reproduces the spectral characteristics, rate of change and duration statistics of cloud attenuation events. 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 : number, sequence, or numpy.ndarray Elevation angle (degrees) - Ns : int Number of samples - Ts : int Time step between consecutive samples (seconds) - n : list, np.array, optional Additive White Gaussian Noise used as input for the - rain_contribution: bool, optional Determines whether rain effect is considered in cloud attenuation or not. default value is False. when the value is True the effect of rain is considered in cloud attenuation. Returns ------- - cloud_att: numpy.ndarray Synthesized cloud attenuation time series (dB) References ---------- [1] P.1853 : Time series synthesis of tropospheric impairments https://www.itu.int/rec/R-REC-P.1853/en """ global __model # prepare the input array lon = np.mod(lon, 360) lat = prepare_input_array(lat).flatten() lon = prepare_input_array(lon).flatten() f = prepare_input_array(f).flatten() el = prepare_input_array(el).flatten() # prepare quantity f = prepare_quantity(f, u.GHz, 'Frequency') el = prepare_quantity(el, u.deg, 'Elevation angle') Ts = prepare_quantity(Ts, u.second, 'Time step between samples') # calculate the output val = __model.cloud_attenuation_synthesis(lat, lon, f, el, Ns, Ts, n,\ rain_contribution) return val * u.dB
def rain_attenuation_probability(lat, lon, el, hs=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. - P0 : number, sequence, or numpy.ndarray, optional Probability of rain at the earth station, (%) 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') P0 = prepare_quantity(P0, u.pct, 'Point rainfall rate') val = __model.rain_attenuation_probability(lat, lon, el, hs, P0) return prepare_output_array(val, type_output) * 100 * u.pct
def zenith_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 time exceeded for p% of the average year for calculation of total water vapour content(Vt) - 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 Zenith Water vapour attenuation along the slant path (dB) References -------- [1] Attenuation by atmospheric gases: https://www.p.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') p = prepare_quantity(p, u.pct, 'Percentage of the time') 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.zenith_water_vapour_attenuation(lat, lon, p, f, V_t=V_t, h=h) return prepare_output_array(val, type_output) * u.dB
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 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_cross_polarization_discrimination(Ap, f, el, p, tau): """ 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 (GHz) - el : number, sequence, or numpy.ndarray Elevation angle (degrees) - p : number Percetage of the time the XPD is exceeded. - tau : number Polarization tilt angle relative to the horizontal (degrees) (tau = 45 deg for circular polarization). Returns ------- - XPD: 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) return prepare_output_array(val, type_output) * u.dB
def rain_specific_attenuation(R, f, el, tau): """ Specific attenuation model for rain for use in prediction methods A method to compute the specific attenuation γ_R (dB/km) from rain. The value is obtained from the 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 """ R = prepare_quantity(R, u.mm / u.hr, 'Rain rate') f = prepare_quantity(f, u.GHz, 'Frequency') k, alpha = rain_specific_attenuation_coefficients(f, el, tau) val = k * (R**alpha) return val * u.dB / u.km
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 at altitude h1 (degrees) - rho : number or Quantity Water vapor density (g/m3) - P : number or Quantity Total atmospheric pressure (hPa) (Ptot = Pdry + e) - 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, 'Total Atmospheric 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) return prepare_output_array(val, type_output) * u.dB
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 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 blockages 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_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 absolute 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') 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 DN65(lat, lon, p): """ Method to determine the statistics of the vertical gradient of radio refractivity in the lowest 65 m from 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 Returns ------- - DN65_p: Quantity Vertical gradient of radio refractivity in the lowest 65 m from the surface of the Earth exceeded for p% of the average year References ---------- [1] The radio refractive index: its formula and refractivity data https://www.itu.int/rec/R-REC-P.453/en """ global __model type_output = type(lat) lat = prepare_input_array(lat) lon = prepare_input_array(lon) lon = np.mod(lon, 360) p = prepare_quantity(p, units=u.pct, name_val='percentage of time exceeded') val = __model.DN65(lat, lon, p) return prepare_output_array(val, type_output) * u.one
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.p.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 rain_attenuation(lat, lon, d, f, el, p, tau, R001=None): """ Estimate long-term statistics of rain attenuation. Attenuation can also occur as a result of absorption and scattering by such hydrometeors as rain, snow, hail and fog. Although rain attenuation can be ignored at frequencies below about 5 GHz, it must be included in design calculations at higher frequencies, where its importance increases rapidly. 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) - p : number 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 : Drizzle * 2.5 mm/h : Light rain * 12.5 mm/h : Medium rain * 25.0 mm/h : Heavy rain * 50.0 mm/h : Downpour * 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 ------- - A_r: Quantity Attenuation exceeded during p percent of the time [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(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') R001 = prepare_quantity(R001, u.mm / u.hr, 'Rainfall Rate') val = __model.rain_attenuation(lat, lon, d, f, el, p, tau, R001) return prepare_output_array(val, type_output) * u.dB
def XPD_outage_precipitation(lat, lon, d, f, el, C0_I, tau, 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] (frequency should be 8<= f<=35 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, el, C0_I, tau, U0, XPIF) return prepare_output_array(val, type_output) * u.percent
def total_attenuation_synthesis(lat, lon, f, el, p, D, Ns, tau, eta, Ts=1, hs=None, rho=None, H=None, P=None, hL=1000, return_contributions=False): """ The time series synthesis method generates a time series that reproduces the spectral characteristics, rate of change and duration statistics of the total atmospheric attenuation events. The time series is obtained considering the contributions of gaseous, cloud, rain, and scintillation attenuation. Parameters ---------- - lat : number Latitudes of the receiver points - lon : number Longitudes of the receiver points - f : number or Quantity Frequency (GHz) - el : number Elevation angle (degrees) - p : number Percetage of the time the rain attenuation value is exceeded. - D: number or Quantity Physical diameter of the earth-station antenna (m) - Ns : int Number of samples - Ts : int Time step between consecutive samples (seconds) - tau : number Polarization tilt angle relative to the horizontal (degrees) (tau = 45 deg for circular polarization). - eta: number Antenna efficiency. - 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. Deafult value is None. - rho : number or Quantity, optional Water vapor density (g/m3). If not provided, an estimate is obtained from Recommendation Recommendation ITU-R P.836.Default value is None. - 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.Default value is None. - 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. Deafult value is None - hL : number, optional Height of the turbulent layer (m). Default value 1000 m - return_contributions: bool, optional Determines whether individual contributions from gases, rain, clouds and scintillation are returned in addition ot the total attenuation (True), or just the total atmospheric attenuation (False). Default is False Returns --------- - A : Quantity Synthesized total atmospheric attenuation time series (dB) - Ag, Ac, Ar, As, A : tuple Synthesized Gaseous, Cloud, Rain, Scintillation contributions to total attenuation time series, and synthesized total attenuation time seires (dB). References ---------- [1] Characteristics of precipitation for propagation modelling https://www.itu.int/rec/R-REC-P.1853/en """ global __model # prepare the input array lon = np.mod(lon, 360) lat = prepare_input_array(lat).flatten() lon = prepare_input_array(lon).flatten() f = prepare_input_array(f).flatten() el = prepare_input_array(el).flatten() tau = prepare_input_array(tau).flatten() eta = prepare_input_array(eta).flatten() D = prepare_input_array(D).flatten() # prepare quantity f = prepare_quantity(f, u.GHz, 'Frequency') el = prepare_quantity(el, u.deg, 'Elevation angle') Ts = prepare_quantity(Ts, u.second, 'Time step between samples') D = prepare_quantity(D, u.m, 'Antenna diameter') hs = prepare_quantity(hs, u.km, 'Heigh above mean sea level of the earth station') eta = prepare_quantity(eta, u.one, 'Antenna efficiency') rho = prepare_quantity(rho, u.g / u.m**3, 'Water vapor density') 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') # calculate the output val = __model.total_attenuation_synthesis( lat, lon, f, el, p, D, Ns, tau, eta, Ts=Ts, hs=hs, rho=rho, H=H, P=P, hL=hL, return_contributions=return_contributions) if return_contributions: return tuple([v * u.dB for v in val]) else: return val * u.dB
def scintillation_attenuation_sigma(lat, lon, f, el, D, eta, T=None, H=None, P=None, hL=1000): """ Calculation of the standard deviation of the amplitude of the scintillations attenuation 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 : number, sequence, or numpy.ndarray Elevation angle (degrees) - 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 lat = prepare_input_array(lat) lon = prepare_input_array(lon) type_output = type(lat) 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_sigma( lat, lon, f, el, D, 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, 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). - 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') el1 = prepare_quantity(el1, u.deg, 'Elevation angle 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') el2 = prepare_quantity(el2, u.deg, 'Elevation angle in ground station 2') f = prepare_quantity(f, u.GHz, 'Frequency') tau = prepare_quantity(tau, u.one, 'Polarization tilt angle') 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, el1, lat2, lon2, a2, el2, f, tau, hs1=hs1, hs2=hs2) return prepare_output_array(val, type_output) * u.pct