Main Content

pathloss

Path loss of radio wave propagation

Description

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

example

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

collapse all

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

collapse all

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

Create propagation models by using the propagationModel function.

Receiver site, specified as an rxsite object or an array of rxsite 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 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 SystemValid map valuesDefault 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

collapse all

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.

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 R2017b

expand all