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) calculates the path loss of radio wave propagation at the receiver site from the transmitter site using the specified propagation model.

pl = pathloss(___,Name=Value) calculates 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

FreeSpace object | Rain object | Gas object | Fog object | CloseIn object | LongleyRice object | TIREM object | RayTracing object

Propagation model to use for the path loss calculations, specified as one of these objects:

• FreeSpace object — Free space propagation model

• Rain object — Rain propagation model

• Gas object — Gas propagation model

• Fog object — Fog propagation model

• CloseIn object — Close-in propagation model

• LongleyRice object — Longley-Rice propagation model

• TIREM (Antenna Toolbox) object — TIREM™ propagation model

• RayTracing object — Ray tracing propagation model

Create propagation models by using the propagationModel function.

When you specify propmodel as a propagation model that incorporates terrain, the function computes path loss by creating a terrain elevation profile with sample locations on the great circle path between rx and tx. The function uses the terrain specified by the Map argument. When Map is a Site Viewer object with buildings data, the function adjusts the elevation profile to include the buildings profile.

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.

info — Supplementary information about path loss

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

Supplementary information about the path loss, returned as an M-by-N structure array or an M-by-N cell array. M is the number of transmitter sites and N is the number of receiver sites.

The format of info depends on the value of propmodel.

Value of propmodel	Format of info
FreeSpace object Rain object Gas object Fog object CloseIn object LongleyRice object TIREM object	info is an M-by-N structure array with these fields: PropagationDistance — Distance between the transmitter site and receiver site, returned as a double scalar in meters. AngleOfDeparture — Angle of departure from the transmitter site, returned as a 2-by-1 double vector of azimuth and elevation angles in degrees. AngleOfArrival — Angle of arrival to the receiver site, returned as a 2-by-1 double vector of azimuth and elevation angles in degrees. The function calculates PropagationDistance, AngleOfDeparture, and AngleOfArrival using the Euclidean path between the sites.
RayTracing object	info is an M-by-N cell array. Each cell array contains a structure array that corresponds to a propagation path. The structure arrays have these fields: PropagationDistance — Length of the propagation path, returned as a double scalar in meters. AngleOfDeparture — Angle of the propagation path departing the transmitter, returned as a 2-by-1 double vector of azimuth and elevation angles in degrees. AngleOfArrival — Angle of the propagation path arriving at the receiver, 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. NumDiffractions — Number of diffractions along the propagation path, returned as 0, 1, or 2.

For all propagation models, the interpretation of AngleOfDeparture and AngleOfArrival depends on the CoordinateSystem property of tx and rx.

• 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.

[3] Mohr, Peter J., Eite Tiesinga, David B. Newell, and Barry N. Taylor. “Codata Internationally Recommended 2022 Values of the Fundamental Physical Constants.” NIST, May 8, 2024. https://www.nist.gov/publications/codata-internationally-recommended-2022-values-fundamental-physical-constants.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™. (since R2025a)

The pathloss function supports ray tracing analysis on a GPU with these usage notes and limitations:

• The function runs on the GPU when you specify a RayTracing propagation model object as input and the UseGPU property of the object is "on" or "auto".

• For information about when the GPU can accelerate ray tracing analysis, see the UseGPU property of the RayTracing object.

• In some cases, the GPU and local CPU results can differ due to small differences in algorithms and hardware implementations.

For an example that shows how to perform ray tracing analysis on a GPU, see Accelerate Ray Tracing Analysis Using GPU.

Version History

Introduced in R2019b

R2025a: Ray tracing functions perform analysis using additional materials

When calculating path loss using ray tracing models, the pathloss function performs the analysis using additional materials. As a result of this change, depending on the materials in the scene, the pathloss function can return different values in R2025a compared to previous releases.

R2025a: Ray tracing functions use improved algorithms

When calculating path loss using ray tracing models, the pathloss function uses improved algorithms and constant values.

• The SBR method uses additional edges in the scene as candidates for diffraction. As a result, the SBR method can find more rays in R2025a compared to previous releases.

• When you specify transmitters and receivers that have polarized antennas from Antenna Toolbox™ or Phased Array System Toolbox™, the function calculates the phase shifts of rays using an improved algorithm that differently incorporates the far-field patterns of the antennas.

• The function uses the constant values that are recommended by the 2022 Committee on Data of the International Science Council (CODATA) adjustment of fundamental constants [3]. In previous releases, the function used constant values from International Telecommunication Union Recommendations (ITU-R) P.2040 and P.527.

As a result of these changes, the pathloss function can return different values in R2025a compared to previous releases.

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 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.