P2108.h File Reference

Interface header for this library. More...

Go to the source code of this file.

Enumerations
enum	ITS::ITU::PSeries::P2108::ClutterType {   ITS::ITU::PSeries::P2108::WATER_SEA = 1 , ITS::ITU::PSeries::P2108::OPEN_RURAL = 2 , ITS::ITU::PSeries::P2108::SUBURBAN = 3 , ITS::ITU::PSeries::P2108::URBAN = 4 ,   ITS::ITU::PSeries::P2108::TREES_FOREST = 5 , ITS::ITU::PSeries::P2108::DENSE_URBAN = 6 }
	Clutter type enum, based on Table 3 in Section 3.1. More...
enum	ITS::ITU::PSeries::P2108::RepresentativeClutterHeight {   ITS::ITU::PSeries::P2108::R__WATER_SEA = 10 , ITS::ITU::PSeries::P2108::R__OPEN_RURAL = 10 , ITS::ITU::PSeries::P2108::R__SUBURBAN = 10 , ITS::ITU::PSeries::P2108::R__URBAN = 15 ,   ITS::ITU::PSeries::P2108::R__TREES_FOREST = 15 , ITS::ITU::PSeries::P2108::R__DENSE_URBAN = 20 }
	Default values of the representative clutter height \( R \), in meters, by clutter type. More...
enum	ITS::ITU::PSeries::P2108::ReturnCode {   ITS::ITU::PSeries::P2108::SUCCESS = 0 , ITS::ITU::PSeries::P2108::ERROR31__FREQUENCY = 32 , ITS::ITU::PSeries::P2108::ERROR31__ANTENNA_HEIGHT , ITS::ITU::PSeries::P2108::ERROR31__STREET_WIDTH ,   ITS::ITU::PSeries::P2108::ERROR31__CLUTTER_HEIGHT , ITS::ITU::PSeries::P2108::ERROR31__CLUTTER_TYPE , ITS::ITU::PSeries::P2108::ERROR32__FREQUENCY = 48 , ITS::ITU::PSeries::P2108::ERROR32__DISTANCE ,   ITS::ITU::PSeries::P2108::ERROR32__PERCENTAGE , ITS::ITU::PSeries::P2108::ERROR33__FREQUENCY = 64 , ITS::ITU::PSeries::P2108::ERROR33__THETA , ITS::ITU::PSeries::P2108::ERROR33__PERCENTAGE }
	Return Codes defined by this software (0-127) More...

Functions
ReturnCode	ITS::ITU::PSeries::P2108::AeronauticalStatisticalModel (const double f__ghz, const double theta__deg, const double p, double &L_ces__db)
	The Earth-space and aeronautical statistical clutter loss model as described in Section 3.3.
ReturnCode	ITS::ITU::PSeries::P2108::TerrestrialStatisticalModel (const double f__ghz, const double d__km, const double p, double &L_ctt__db)
	Statistical clutter loss model for terrestrial paths as described in Section 3.2.
ReturnCode	ITS::ITU::PSeries::P2108::HeightGainTerminalCorrectionModel (const double f__ghz, const double h__meter, const double w_s__meter, const double R__meter, const ClutterType clutter_type, double &A_h__db)
	Height gain terminal correction model as described in Section 3.1.
char *	ITS::ITU::PSeries::P2108::GetReturnStatusCharArray (const int code)
	Get an error message string (as C-style string) from a return code.
void	ITS::ITU::PSeries::P2108::FreeReturnStatusCharArray (char *c_msg)
	Free the memory allocated by GetReturnStatusCharArray.
std::string	ITS::ITU::PSeries::P2108::GetReturnStatus (const int code)
	Get an error message string from a return code.
double	ITS::ITU::PSeries::P2108::cot (const double x)
	Helper function to calculate \( \cot(x) \).
double	ITS::ITU::PSeries::P2108::InverseComplementaryCumulativeDistribution (const double q)
	Compute the inverse complementary cumulative distribution function approximation as described in Recommendation ITU-R P.1057.
double	ITS::ITU::PSeries::P2108::Equation_2a (const double nu)
	Equation (2a) of Section 3.1.
double	ITS::ITU::PSeries::P2108::Equation_2b (const double K_h2, const double h__meter, const double R__meter)
	Equation (2b) of Section 3.1.
ReturnCode	ITS::ITU::PSeries::P2108::Section3p1_InputValidation (const double f__ghz, const double h__meter, const double w_s__meter, const double R__meter)
	Input validation for the height gain terminal correction model (Section 3.1).
ReturnCode	ITS::ITU::PSeries::P2108::Section3p2_InputValidation (const double f__ghz, const double d__km, const double p)
	Input validation for the statistical clutter loss model for terrestrial paths (Section 3.2).
ReturnCode	ITS::ITU::PSeries::P2108::Section3p3_InputValidation (const double f__ghz, const double theta__deg, const double p)
	Inputs-in-range validation for the Earth-space and aeronautical statistical clutter loss model (Section 3.3).
double	ITS::ITU::PSeries::P2108::TerrestrialStatisticalModelHelper (const double f__ghz, const double d__km, const double p)
	Compute the clutter loss.

Variables
constexpr double	ITS::ITU::PSeries::P2108::PI = 3.14159265358979323846
	Approximate value of \( \pi \).

Detailed Description

Interface header for this library.

Enumeration Type Documentation

ClutterType

enum ITS::ITU::PSeries::P2108::ClutterType

Clutter type enum, based on Table 3 in Section 3.1.

Enumerator
WATER_SEA	Water/sea clutter type.
OPEN_RURAL	Open/rural clutter type.
SUBURBAN	Suburban clutter type.
URBAN	Urban clutter type.
TREES_FOREST	Trees/forest clutter type.
DENSE_URBAN	Dense urban clutter type.

RepresentativeClutterHeight

enum ITS::ITU::PSeries::P2108::RepresentativeClutterHeight

Default values of the representative clutter height \( R \), in meters, by clutter type.

These should be used as inputs to the height gain terminal correction model when local information is not available.

Enumerator
R__WATER_SEA	\( R \) for the trees/forest clutter type
R__OPEN_RURAL	\( R \) for the open/rural clutter type
R__SUBURBAN	\( R \) for the suburban clutter type
R__URBAN	\( R \) for the urban clutter type
R__TREES_FOREST	\( R \) for the trees/forest clutter type
R__DENSE_URBAN	\( R \) for the dense urban clutter type

ReturnCode

enum ITS::ITU::PSeries::P2108::ReturnCode

Return Codes defined by this software (0-127)

Enumerator
SUCCESS	Successful execution.
ERROR31__FREQUENCY	Frequency must be between 0.3 and 3 GHz.
ERROR31__ANTENNA_HEIGHT	Antenna height must be \( \geq \) 0 meters.
ERROR31__STREET_WIDTH	Street width must be \( > \) 0 meters.
ERROR31__CLUTTER_HEIGHT	Representative clutter height must be \( > \) 0 meters.
ERROR31__CLUTTER_TYPE	Invalid value for clutter type.
ERROR32__FREQUENCY	Frequency must be between 2 and 67 GHz.
ERROR32__DISTANCE	Path distance must be \( \geq \) 0.25 km.
ERROR32__PERCENTAGE	Percentage must be between 0 and 100.
ERROR33__FREQUENCY	Frequency must be between 10 and 100 GHz.
ERROR33__THETA	Elevation angle must be between 0 and 100 GHz.
ERROR33__PERCENTAGE	Percentage must be between 0 and 100.

Function Documentation

AeronauticalStatisticalModel()

PROPLIB_API ReturnCode ITS::ITU::PSeries::P2108::AeronauticalStatisticalModel	(	const double	f__ghz,
		const double	theta__deg,
		const double	p,
		double &	L_ces__db )

The Earth-space and aeronautical statistical clutter loss model as described in Section 3.3.

This model is applicable when one end of the path is within man-made clutter and the other end is a satellite, aeroplane, or other platform above the Earth.

Frequency range: \( 10 < f < 100 \) (GHz)
Elevation angle range: \( 0 < \theta < 90 \) (degrees)
Percentage locations range: \( 0 < p < 100 \) (%)

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	theta__deg	Elevation angle, in degrees
[in]	p	Percentage of locations, in %
[out]	L_ces__db	Additional loss (clutter loss), in dB

Returns

Return code

cot()

double ITS::ITU::PSeries::P2108::cot

(

const double

x

)

Helper function to calculate \( \cot(x) \).

The calculation is implemented simply as \( 1 / \cot(x) \).

Parameters

[in]

x

Argument, in radians

Returns

Cotangent of the argument, \( \cot(x) \)

Equation_2a()

double ITS::ITU::PSeries::P2108::Equation_2a

(

const double

nu

)

Equation (2a) of Section 3.1.

Parameters

[in]

nu

Dimensionless diffraction parameter

Returns

Additional loss (clutter loss), in dB

Equation_2b()

double ITS::ITU::PSeries::P2108::Equation_2b	(	const double	K_h2,
		const double	h__meter,
		const double	R__meter )

Equation (2b) of Section 3.1.

Parameters

[in]	K_h2	Intermediate parameter
[in]	h__meter	Antenna height, in meters
[in]	R__meter	Representative clutter height, in meters

Returns

Additional loss (clutter loss), in dB

FreeReturnStatusCharArray()

PROPLIB_API void ITS::ITU::PSeries::P2108::FreeReturnStatusCharArray

(

char *

c_msg

)

Free the memory allocated by GetReturnStatusCharArray.

Parameters

[in]

c_msg

The status message C-style string to delete

GetReturnStatus()

std::string ITS::ITU::PSeries::P2108::GetReturnStatus

(

const int

code

)

Get an error message string from a return code.

Parameters

[in]

code

Integer return code.

Returns

A status message corresponding to the input code.

GetReturnStatusCharArray()

PROPLIB_API char * ITS::ITU::PSeries::P2108::GetReturnStatusCharArray

(

const int

code

)

Get an error message string (as C-style string) from a return code.

Parameters

[in]

code

Integer return code.

Returns

A status message corresponding to the input code.

HeightGainTerminalCorrectionModel()

PROPLIB_API ReturnCode ITS::ITU::PSeries::P2108::HeightGainTerminalCorrectionModel	(	const double	f__ghz,
		const double	h__meter,
		const double	w_s__meter,
		const double	R__meter,
		const ClutterType	clutter_type,
		double &	A_h__db )

Height gain terminal correction model as described in Section 3.1.

This method gives the median loss due to different terminal surroundings. This model can be applied to both transmitting and receiving ends of the path.

Frequency range: \( 0.03 \leq f \leq 3 \) (GHz)
Antenna height range: \( 0 \leq h \) (m)
Street width range: \( 0 < w_s \) (m)
Representative clutter height range: \( 0 < R \) (m)

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	h__meter	Antenna height, in meters
[in]	w_s__meter	Street width, in meters
[in]	R__meter	Representative clutter height, in meters
[in]	clutter_type	Clutter type
[out]	A_h__db	Additional loss (clutter loss), in dB

Returns

Return code

InverseComplementaryCumulativeDistribution()

double ITS::ITU::PSeries::P2108::InverseComplementaryCumulativeDistribution

(

const double

q

)

Compute the inverse complementary cumulative distribution function approximation as described in Recommendation ITU-R P.1057.

This approximation is sourced from Formula 26.2.23 in Abramowitz & Stegun. This approximation has an error of \( |\epsilon(p)| < 4.5\times 10^{-4} \)

Parameters

q	Percentage, \( 0.0 < q < 1.0 \)

Returns

Q(q)^-1

Exceptions

std::out_of_range

if the input is outside the range [0.0, 1.0]

Section3p1_InputValidation()

ReturnCode ITS::ITU::PSeries::P2108::Section3p1_InputValidation	(	const double	f__ghz,
		const double	h__meter,
		const double	w_s__meter,
		const double	R__meter )

Input validation for the height gain terminal correction model (Section 3.1).

Note: Input parameter 'clutter_type' is validated in the main function's switch statement through the use of default to simplify code structure.

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	h__meter	Antenna height, in meters
[in]	w_s__meter	Street width, in meters
[in]	R__meter	Representative clutter height, in meters

Returns

Return code

Section3p2_InputValidation()

ReturnCode ITS::ITU::PSeries::P2108::Section3p2_InputValidation	(	const double	f__ghz,
		const double	d__km,
		const double	p )

Input validation for the statistical clutter loss model for terrestrial paths (Section 3.2).

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	d__km	Path distance, in km
[in]	p	Percentage of locations, in %

Returns

Return code

Section3p3_InputValidation()

ReturnCode ITS::ITU::PSeries::P2108::Section3p3_InputValidation	(	const double	f__ghz,
		const double	theta__deg,
		const double	p )

Inputs-in-range validation for the Earth-space and aeronautical statistical clutter loss model (Section 3.3).

Returns SUCCESS if all parameters are valid. Otherwise, invalid inputs will return unique error codes.

Frequency range: \( 10 < f < 100 \) (GHz)
Elevation angle range: \( 0 < \theta < 90 \) (degrees)
Percentage locations range: \( 0 < p < 100 \) (%)

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	theta__deg	Elevation angle, in degrees
[in]	p	Percentage of locations, in %

Returns

Return code

TerrestrialStatisticalModel()

PROPLIB_API ReturnCode ITS::ITU::PSeries::P2108::TerrestrialStatisticalModel	(	const double	f__ghz,
		const double	d__km,
		const double	p,
		double &	L_ctt__db )

Statistical clutter loss model for terrestrial paths as described in Section 3.2.

This model can be applied for urban and suburban clutter loss modeling.

Frequency range: \( 0.5 \leq f \leq 67 \) (GHz)
Path distance range: \( 0.25 \leq d \) (km) (must be \( \geq 1 \) to apply the correction at both ends of the path)
Percentage locations range: \(0 < p < 100 \) (%)

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	d__km	Path distance, in km
[in]	p	Percentage of locations, in %
[out]	L_ctt__db	Additional loss (clutter loss), in dB

Returns

Return code

TerrestrialStatisticalModelHelper()

double ITS::ITU::PSeries::P2108::TerrestrialStatisticalModelHelper	(	const double	f__ghz,
		const double	d__km,
		const double	p )

Compute the clutter loss.

Parameters

[in]	f__ghz	Frequency, in GHz
[in]	d__km	Path distance, in km
[in]	p	Percentage of locations, in %

Returns

Clutter loss, in dB