pathloss

Path loss of radio wave propagation

Syntax

pl = pathloss(propmodel,rx,tx)

pl = pathloss(___,Name=Value)

[pl,info] = pathloss(___)

Description

pl = pathloss(propmodel,rx,tx) returns the path loss of radio wave propagation at the receiver site from the transmitter site.

pl = pathloss(___,Name=Value) returns the path loss using additional options specified by name-value arguments.

[pl,info] = pathloss(___) additionally returns information about the propagation paths.

Examples

Path Loss of Receiver In Heavy Rain

Create a transmitter site and a receiver site.

tx = txsite(Name="MathWorks Apple Hill", ...
    Latitude=42.3001,Longitude=-71.3504, ...
    TransmitterFrequency=2.5e9);

rx = rxsite(Name="Fenway Park", ...
    Latitude=42.3467,Longitude=-71.0972);

Create a propagation model for heavy rain. Then, calculate the path loss at the receiver site using the propagation model.

pm = propagationModel("rain",RainRate=50);
pl = pathloss(pm,rx,tx)

pl = 127.3208

Input Arguments

propmodel — Propagation model

propagation model object

Propagation model, specified as a FreeSpace, Rain, Gas, Fog, CloseIn, LongleyRice, TIREM (Antenna Toolbox), or RayTracing object.

Create propagation models by using the propagationModel function.

rx — Receiver site

rxsite object | array of rxsite objects

Receiver site, specified as an rxsite object or an array of rxsite objects.

tx — Transmitter site

txsite object | array of txsite objects

Transmitter site, specified as a txsite object or an array txsite objects.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: pathloss(propmodel,rx,tx,Map="none")

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: pathloss(propmodel,rx,tx,"Map","none")

Map — Map for visualization or surface data

siteviewer object | triangulation object | string scalar | character vector

Map for visualization or surface data, specified as a siteviewer object, a triangulation object, a string scalar, or a character vector. Valid and default values depend on the coordinate system.

Coordinate System	Valid map values	Default map value
"geographic"	A siteviewer objecta A terrain name, if the function is called with an output argument. Valid terrain names are "none", "gmted2010", or the name of the custom terrain data added using addCustomTerrain.	The current siteviewer object or a new siteviewer object if none are open "gmted2010", if the function is called with an output
"cartesian"	"none" A siteviewer object The name of a glTF™ file The name of an STL file A triangulation object	"none"
a Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.

In most cases, if you specify this argument as a value other than a siteviewer or "none", then you must also specify an output argument.

Data Types: char | string

Output Arguments

pl — Path loss

scalar | M-by-N cell array

Path loss, returned as a scalar or as an M-by-N cell array, where each cell contains a row vector of path losses in decibels. M is the number of transmitter sites and N is the number of receiver sites.

The function computes the path loss along the shortest propagation paths through space by connecting the centers of the transmitters and receivers.

For terrain propagation models, the function computes path loss using a terrain elevation profile that it creates from sample locations on the great circle path between the transmitter and receiver. If Map is a siteviewer object with buildings specified, the function adjusts the elevation to include the heights of the buildings.

info — Information corresponding to each propagation path

M-by-N structure array | M-by-N cell array

Information corresponding to each propagation path, returned as an M-by-N structure array or cell array.

• For most propagation models, info is a structure array.

• For ray tracing propagation models, info is a cell array, where each cell contains a vector of structures.

The structures contain these fields:

• PropagationDistance — Total length of the propagation path, returned as a double scalar in meters.

• AngleOfDeparture — Angle of departure of the signal from the transmitter site, returned as a 2-by-1 double vector of azimuth and elevation angles in degrees.

• AngleOfArrival — Angle of arrival of the signal at the receiver site, returned as a 2-by-1 double vector of azimuth and elevation angles in degrees.

• NumReflections — Number of reflections along the propagation path, returned as a nonnegative integer. This field and value is applicable only for ray tracing propagation models.

• NumDiffractions — Number of diffractions along the propagation path, returned as 0, 1, or 2. This field and value is applicable only for ray tracing propagation models.

The angle values in the structure depend on CoordinateSystem.

• When CoordinateSystem is "geographic", the angle values are defined using the local east-north-up coordinate system of the antenna. The azimuth angle is measured from east.

• When CoordinateSystem is "cartesian", the angle values are defined using the global Cartesian coordinate system. The azimuth angle is measured from the global x-axis around the global z-axis.

The elevation angle is measured from the horizontal (or xy) plane to the x-axis of the antenna, in the range –90 to 90.

References

[1] International Telecommunications Union Radiocommunication Sector. Effects of Building Materials and Structures on Radiowave Propagation Above About 100MHz. Recommendation P.2040. ITU-R, approved August 23, 2023. https://www.itu.int/rec/R-REC-P.2040/en.

[2] International Telecommunications Union Radiocommunication Sector. Electrical Characteristics of the Surface of the Earth. Recommendation P.527. ITU-R, approved September 27, 2021. https://www.itu.int/rec/R-REC-P.527/en.

Version History

Introduced in R2019b

R2024a: Ray tracing functions model materials using updated ITU recommendations

When calculating path loss using ray tracing models, the pathloss function models materials using the methods and equations in International Telecommunication Union Recommendations (ITU-R) P.2040-3 [1] and ITU-R P.527-5 through ITU-R P.527-6 [2].

In previous releases, the function used ITU-R P.2040-1. As a result of these changes, the pathloss function can return different values in R2024a compared to previous releases.

R2024a: Get number of diffractions along ray tracing propagation paths

When you specify propmodel as a RayTracing object, info stores the number of diffractions along propagation paths in the NumDiffractions field.

R2023a: Ray tracing models discard paths based on path loss

Ray tracing propagation models discard propagation paths based on path loss thresholds. By default, when you specify the propmodel input argument as a RayTracing object, the propagation model discards paths that are more than 40 dB weaker than the strongest path.

As a result, the pathloss function can return different values in R2023a compared to previous releases. To avoid discarding propagation paths based on relative path loss thresholds, set the MaxRelativePathLoss property of the ray tracing object to Inf.

R2022b: Ray tracing models using SBR method find paths with exact geometric accuracy

Ray tracing models that find propagation paths by using the shooting and bouncing rays (SBR) method correct the results so that the geometric accuracy of each path is exact, using single-precision floating-point computations. In previous releases, the paths have approximate geometric accuracy.

As a result, when you use a ray tracing model as input to the pathloss function, the function can return different results than in previous releases.