raypl
Description
[
returns the path loss and phase shift for the specified RF propagation ray. The function
calculates the path loss and phase shift using free space loss and reflection loss derived
from the propagation path, reflection materials, and antenna polarizations.pl
,phase
] = raypl(ray
)
By default, the raypl
function assumes the antennas are
unpolarized. You can polarize the antennas by specifying the
TransmitterPolarization
and ReceiverPolarization
namevalue arguments.
For more information about the path loss computations, see Path Loss Computation.
[
specifies options using namevalue arguments. For example,
pl
,phase
] = raypl(ray
,Name=Value
)ReflectionMaterials="brick"
specifies the reflection material as
brick.
Examples
Reevaluate Path Loss Changing Reflection Materials and Frequency
Change the reflection materials and frequency for a ray, and then reevaluate the path loss and phase shift.
Launch Site Viewer with buildings in Hong Kong. For more information about the OpenStreetMap® file, see [1].
viewer = siteviewer(Buildings="hongkong.osm");
Create transmitter and receiver sites.
tx = txsite(Latitude=22.2789,Longitude=114.1625, ... AntennaHeight=10,TransmitterPower=5, ... TransmitterFrequency=28e9); rx = rxsite(Latitude=22.2799,Longitude=114.1617, ... AntennaHeight=1);
Create a ray tracing propagation model, which MATLAB® represents using a RayTracing
object. Configure the model to use the image method and to find paths with up to 2
surface reflections. Then, perform the ray tracing analysis.
pm = propagationModel("raytracing", ... Method="image", ... MaxNumReflections=2); rays = raytrace(tx,rx,pm);
Find the first ray with two path reflections. Then, display the properties of the ray object.
idx = find([rays{1}.NumInteractions] == 2,1); ray = rays{1}(idx)
ray = Ray with properties: PathSpecification: 'Locations' CoordinateSystem: 'Geographic' TransmitterLocation: [3×1 double] ReceiverLocation: [3×1 double] LineOfSight: 0 Interactions: [1×2 struct] Frequency: 2.8000e+10 PathLossSource: 'Custom' PathLoss: 121.8592 PhaseShift: 4.5669 Readonly properties: PropagationDelay: 8.3060e07 PropagationDistance: 249.0068 AngleOfDeparture: [2×1 double] AngleOfArrival: [2×1 double] NumInteractions: 2
Display the ray in Site Viewer.
plot(ray)
By default, the model uses concrete for the terrain material and uses building materials derived from the OpenStreetMap file. When the OpenStreetMap file does not specify materials, the model uses concrete. In this case, the ray encounters concrete as the material. You can find the interaction materials by querying the Interactions
property of the ray object.
ray.Interactions.MaterialName
ans = "concrete"
ans = "concrete"
You can calculate the path loss for different materials by using the raypl
function. For this example, use metal for the first reflection and glass for the second reflection.
[ray.PathLoss,ray.PhaseShift] = raypl(ray,ReflectionMaterials=["metal","glass"]); ray
ray = Ray with properties: PathSpecification: 'Locations' CoordinateSystem: 'Geographic' TransmitterLocation: [3×1 double] ReceiverLocation: [3×1 double] LineOfSight: 0 Interactions: [1×2 struct] Frequency: 2.8000e+10 PathLossSource: 'Custom' PathLoss: 114.9541 PhaseShift: 4.5669 Readonly properties: PropagationDelay: 8.3060e07 PropagationDistance: 249.0068 AngleOfDeparture: [2×1 double] AngleOfArrival: [2×1 double] NumInteractions: 2
Display the recalculated ray. The slight change in color indicates the change in path loss.
plot(ray)
Change the frequency of the ray. Then, recalculate the path loss and phase shift. Display the ray again and observe the color change.
ray.Frequency = 2e9; [ray.PathLoss,ray.PhaseShift] = raypl(ray,ReflectionMaterials=["metal","glass"]); plot(ray)
Appendix
[1] The OpenStreetMap file is downloaded from https://www.openstreetmap.org, which provides access to crowdsourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.
Input Arguments
ray
— RF propagation ray
comm.Ray
object
RF propagation ray, specified as a comm.Ray
object. The
PathSpecification
property of the object must be
"Locations"
. All interactions in the
Interactions
property of the ray must be of type
"Reflection"
.
Data Types: comm.Ray
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: raypl(ray,TransmitterPolarization="H",ReceiverPolarization="H")
,
specifies the horizontal polarizations for the transmit and receive antennas for
ray
.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: raypl(ray,"TransmitterPolarization","H","ReceiverPolarization","H")
,
specifies the horizontal polarizations for the transmit and receive antennas for
ray
.
ReflectionMaterials
— Reflection materials
"concrete"
(default)  string scalar  1byNR string vector  character vector  1byNR cell array of character vectors  2by1 numeric vector  2byNR numeric matrix
Reflection materials for a nonlineofsight (NLOS) ray, specified as a string
scalar, a 1byNR string vector, a character vector, a
1byNR cell array of character vectors, a 2by1 numeric vector,
or a 2byNR numeric matrix. NR is the number of
reflections stored in ray
.
When you specify one reflection material, the reflection material applies to all
the reflections. When you specify multiple reflection materials, each material applies
to the associated reflection point in ray
.
To use predefined reflection materials, specify
ReflectionMaterials
as a string scalar, a character vector, a string vector, or a cell array of character vectors. Specify each reflection material as one of these options:"concrete"
— Concrete"plasterboard"
— Plasterboard"ceilingboard"
— Ceiling board"chipboard"
— Chipboard"floorboard"
— Floorboard"brick"
— Brick"wood"
— Wood"glass"
— Glass"metal"
— Metal"marble"
— Marble (since R2024a)"plywood"
— Plywood (since R2024a)"water"
— Water"vegetation"
— Vegetation"loam"
— Loam"perfectreflector"
— Perfect electrical conductor
To use custom reflection materials, specify a 2by1 numeric vector or a 2byNR numeric matrix. Each column is of the form
[rp; cv]
, whererp
is the relative permittivity andcv
is the conductivity.
For more information, see ITU Permittivity and Conductivity Values for Common Materials.
Example: ReflectionMaterials=["concrete","water"]
, specifies
that a ray with two reflections uses the electrical characteristics of concrete at the
first reflection point and water at the second reflection point.
Data Types: string
 char
 double
TransmitterPolarization
— Transmit antenna polarization type
"none"
(default)  "V"
 "H"
 "LHCP"
 "RHCP"
 normalized 2by1 Jones vector
Transmit antenna polarization type, specified as one of these values:
"none"
— Unpolarized"V"
— Linearly polarized in the vertical (θ) direction"H"
— Linearly polarized in the horizontal (φ) direction"LHCP"
— Lefthand circular polarized"RHCP"
— Righthand circular polarizedA normalized 2by1 Jones vector (also called a polarization matrix) of the form
[H;V]
, whereH
is the horizontal component andV
is the vertical component.
For more information about polarization types and Jones vectors, see Jones Vector Notation.
Example: TransmitterPolarization="RHCP"
specifies righthand
circular polarization for the transmit antenna.
Data Types: double
 char
 string
ReceiverPolarization
— Receive antenna polarization type
"none"
(default)  "V"
 "H"
 "LHCP"
 "RHCP"
 normalized 2by1 Jones vector
Receive antenna polarization type, specified as one of these values:
"none"
— Unpolarized"V"
— Linearly polarized in the vertical (θ) direction"H"
— Linearly polarized in the horizontal (φ) direction"LHCP"
— Lefthand circular polarized"RHCP"
— Righthand circular polarizedA normalized 2by1 Jones vector (also called a polarization matrix) of the form
[H;V]
, whereH
is the horizontal component andV
is the vertical component.
For more information about polarization types and Jones vectors, see Jones Vector Notation.
Example: ReceiverPolarization=[1;0]
specifies horizontal
polarization for the receive antenna by using Jones vector notation.
Data Types: double
 char
 string
TransmitterAxes
— Orientation of transmit antenna axes
3by3 identity matrix (default)  3by3 unitary matrix
Orientation of the transmit antenna axes, specified as a 3by3 unitary matrix
indicating the rotation from the transmitter local coordinate system (LCS) into the
global coordinate system (GCS). When the CoordinateSystem
property
of the comm.Ray
is set to
"Geographic"
, the GCS orientation is the local EastNorthUp
(ENU) coordinate system at transmitter. For more information, see Coordinate System Orientation.
Example: TransmitterAxes=eye(3)
, specifies that the local
coordinate system for the transmitter axes is aligned with the global coordinate
system. This is the default orientation.
Data Types: double
ReceiverAxes
— Orientation of receive antenna axes
3by3 identity matrix (default)  3by3 unitary matrix
Orientation of the receive antenna axes, specified as a 3by3 unitary matrix
indicating the rotation from the receiver local coordinate system (LCS) into the
global coordinate system (GCS). The GCS orientation is the local EastNorthUp (ENU)
coordinate system at receiver when the CoordinateSystem
property of
the comm.Ray
is set to
"Geographic"
. For more information, see Coordinate System Orientation.
Example: ReceiverAxes=[0 1 0; 1 0 0; 0 0 1]
, specifies a 90°
rotation around the zaxis of the local receiver coordinate system
with respect to the global coordinate system.
Data Types: double
Output Arguments
pl
— Path loss in dB
nonnegative scalar
Path loss in dB, returned as a nonnegative scalar.
Data Types: double
phase
— Phase shift in radians
scalar
Phase shift in radians, returned as a scalar in the range [–π, π] radians. The argument uses the e^{iωt} time convention.
Data Types: double
More About
ITU Permittivity and Conductivity Values for Common Materials
International Telecommunications Union Recommendations (ITUR) P.20403 [2] and ITUR P.5275 through ITUR P.5276 [3] present methods, equations, and values used to calculate real relative permittivity, conductivity, and complex relative permittivity for common materials.
For information about the values computed for building materials specified in ITUR P.2040, see
buildingMaterialPermittivity
.For information about the values computed for terrain materials specified in ITUR P.527, see
earthSurfacePermittivity
.
Coordinate System Orientation
This image shows the orientation of the electromagnetic fields in the global coordinate system (GCS) and the local coordinate systems of the transmitter and receiver.
When the CoordinateSystem
property of the comm.Ray
is set to
"Geographic"
, the GCS orientation is the local EastNorthUp (ENU)
coordinate system at observer. The path loss computation accounts for the roundearth
differences between ENU coordinates at the transmitter and receiver.
Path Loss Computation
The ray tracing model used by the raypl
function calculates
reflection losses by tracking the horizontal and vertical polarizations of signals through
the propagation path. Total power loss is the sum of free space loss and reflection
loss.
This image shows a reflection path from a transmitter site tx to a receiver site rx.
The model determines polarization and reflection loss using these steps.
Track the propagation of the ray in 3D space by calculating the propagation matrix P. The matrix is a repeating product, where i is the number of reflection points.
$$P={\displaystyle \prod _{i}{P}_{i}}$$
For each reflection, calculate P_{i} by transforming the global coordinates of the incident electromagnetic field into the local coordinates of the reflection plane, multiplying the result by a reflection coefficient matrix, and transforming the coordinates back into the original global coordinate system [1]. The equations for P_{i} and P_{0} are:
$${P}_{i}=\begin{array}{ccc}{\left[\begin{array}{ccc}{s}_{out}& {p}_{out}& {k}_{out}\end{array}\right]}_{i}& {\left[\begin{array}{ccc}{R}_{V}\left(\alpha \right)& 0& 0\\ 0& {R}_{H}\left(\alpha \right)& 0\\ 0& 0& 1\end{array}\right]}_{i}& {\left[\begin{array}{ccc}{s}_{in}& {p}_{in}& {k}_{in}\end{array}\right]}_{i}^{1}\end{array}$$
$${P}_{0}=\left[\begin{array}{ccc}1& 0& 0\\ 0& 1& 0\\ 0& 0& 1\end{array}\right]$$
where:
s, p, and k form a basis for the plane of incidence (the plane created by the incident ray and the surface normal of the reflection plane). s and p are perpendicular and parallel, respectively, to the plane of incidence.
k_{in} and k_{out} are the directions (in global coordinates) of the incident and exiting rays, respectively.
s_{in} and s_{out} are the directions (in global coordinates) of the horizontal polarizations for the incident and exiting rays, respectively.
p_{in} and p_{out} are the directions (in global coordinates) of the vertical polarizations for the incident and exiting rays, respectively.
R_{H} and R_{V} are the Fresnel reflection coefficients for the horizontal and vertical polarizations, respectively. α is the incident angle of the ray and ε_{r} is the complex relative permittivity of the material.
$${R}_{H}(\alpha )=\frac{\mathrm{cos}(\alpha )\sqrt{({\epsilon}_{r}{\mathrm{sin}}^{2}(\alpha ))/{\epsilon}_{r}{}^{2}}}{\mathrm{cos}(\alpha )+\sqrt{({\epsilon}_{r}{\mathrm{sin}}^{2}(\alpha ))/{\epsilon}_{r}{}^{2}}}$$
$${R}_{V}(\alpha )=\frac{\mathrm{cos}(\alpha )\sqrt{{\epsilon}_{r}{\mathrm{sin}}^{2}(\alpha )}}{\mathrm{cos}(\alpha )+\sqrt{{\epsilon}_{r}{\mathrm{sin}}^{2}(\alpha )}}$$
Project the propagation matrix P into a 2by2 polarization matrix R. The model rotates the coordinate systems for the transmitter and receiver so that they are in global coordinates.
$$R=\left[\begin{array}{cc}{H}_{in}\cdot {H}_{rx}& {V}_{in}\cdot {H}_{rx}\\ {H}_{in}\cdot {V}_{rx}& {V}_{in}\cdot {V}_{rx}\end{array}\right]$$
$${H}_{in}=P({V}_{tx}\times {k}_{tx})$$
$${V}_{in}=P{V}_{tx}$$
where:
H_{rx} and V_{rx} are the directions (in global coordinates) of the horizontal (E_{θ}) and vertical (E_{ϕ}) polarizations, respectively, for the receiver.
H_{in} and V_{in} are the directions (in global coordinates) of the propagated horizontal and vertical polarizations, respectively.
V_{tx} is the direction (in global coordinates) of the nominal vertical polarization for the ray departing the transmitter.
k_{tx} is the direction (in global coordinates) of the ray departing the transmitter.
Specify the normalized horizontal and vertical polarizations of the electric field at the transmitter and receiver by using the 2by1 Jones polarization vectors J_{tx} and J_{rx}, respectively. If either the transmitter or receiver are unpolarized, then the model assumes $${J}_{tx}={J}_{rx}=\frac{\sqrt{2}}{2}\left[\begin{array}{c}1\\ 1\end{array}\right]$$.
Calculate the polarization and reflection loss IL by combining R, J_{tx}, and J_{rx}.
$$IL=20{\mathrm{log}}_{10}\left{J}_{rx}^{1}R{J}_{tx}\right$$
Jones Vector Notation
For Jones vector notation, the raypl function describes signal polarization using Jones calculus.
The orthogonal components of Jones vectors are defined for E_{θ} and E_{φ}. This table shows the Jones vector corresponding to various antenna polarizations.
Antenna Polarization Type  Corresponding Jones Vector 

Linear polarized in the θ direction 
$$\left(\begin{array}{c}H\\ V\end{array}\right)=\left(\begin{array}{c}0\\ 1\end{array}\right)$$

Linear polarized in the φ direction 
$$\left(\begin{array}{c}H\\ V\end{array}\right)=\left(\begin{array}{c}1\\ 0\end{array}\right)$$

Lefthand circular polarized (LHCP) 
$$\left(\begin{array}{c}H\\ V\end{array}\right)=\frac{1}{\sqrt{2}}\left(\begin{array}{c}j\\ 1\end{array}\right)$$

Righthand circular polarized (RHCP) 
$$\left(\begin{array}{c}H\\ V\end{array}\right)=\frac{1}{\sqrt{2}}\left(\begin{array}{c}j\\ 1\end{array}\right)$$

References
[1] Chipman, Russell A., Garam Young, and Wai Sze Tiffany Lam. "Fresnel Equations." In Polarized Light and Optical Systems. Optical Sciences and Applications of Light. Boca Raton: Taylor & Francis, CRC Press, 2019.
[2] International Telecommunications Union Radiocommunication Sector. Effects of Building Materials and Structures on Radiowave Propagation Above About 100MHz. Recommendation P.2040. ITUR, approved August 23, 2023. https://www.itu.int/rec/RRECP.2040/en.
[3] International Telecommunications Union Radiocommunication Sector. Electrical Characteristics of the Surface of the Earth. Recommendation P.527. ITUR, approved September 27, 2021. https://www.itu.int/rec/RRECP.527/en.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
When you specify multiple reflective materials, you must define each value as a
character vector (char
data type) in a cell array.
Version History
Introduced in R2020aR2024a: Model materials using updated ITU recommendations
The raypl
function models materials using the methods and equations
in ITUR P.20403 and ITUR P.5275 through ITUR P.5276.
In previous releases, the function used ITUR P.20401. As a result of these changes,
the raypl
function can return different values in R2024a compared to
previous releases.
R2024a: Specify marble and plywood materials
Specify the reflection materials as marble or plywood by using the
ReflectionMaterials
namevalue argument and specifying
"marble"
or "plywood"
as input.
R2022b: Ray tracing models using SBR method find paths with exact geometric accuracy
When you find propagation paths using the raytrace
function and a
ray tracing model that uses the shooting and bouncing rays (SBR) method, MATLAB^{®} corrects the results so that the geometric accuracy of each path is exact,
using singleprecision floatingpoint computations. In previous releases, the paths have
approximate geometric accuracy.
As a result, when you use rays returned by the raytrace
function as
input to the raypl
function, the raypl
function
can return different results than in previous releases.
See Also
Functions
Objects
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)