raypl
Path loss and phase change for RF propagation ray
Description
[
returns the path loss in dB and phase shift in radians based on the properties specified by
pl
,phase
] = raypl(ray
)ray
. The path loss and path shift computations consider the free
space loss and reflection loss derived from the propagation path, reflection materials, and
polarizations. The function accounts for geometric coupling between horizontal and vertical
polarizations only when both transmit and receive antennas are polarized. For more
information, see Path Loss Computation.
[
calculates the path loss and phase shift with additional options specified by one or more
namevalue pair arguments.pl
,phase
] = raypl(ray
,Name,Value
)
Examples
Reevaluate Path Loss Changing Reflection Materials and Frequency
Change the reflection materials and frequency for a ray and reevaluate the path loss and phase shift.
Launch Site Viewer with buildings in Hong Kong. For more information about the osm file, see [1]. Specify transmitter and receiver sites.
viewer = siteviewer("Buildings","hongkong.osm"); tx = txsite("Latitude",22.2789,"Longitude",114.1625, ... "AntennaHeight",10,"TransmitterPower",5, ... "TransmitterFrequency",28e9); rx = rxsite("Latitude",22.2799,"Longitude",114.1617, ... "AntennaHeight",1);
Perform ray tracing between the sites.
pm = propagationModel("raytracing", ... "Method","image", ... "MaxNumReflections",2); rays = raytrace(tx,rx,pm);
Find the first ray with 2order reflections from the result. Display the ray characteristics. Plot the ray to see the ray reflect off two buildings.
ray = rays{1}(find([rays{1}.NumInteractions] == 2,1))
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: 122.1824 PhaseShift: 4.5669 Readonly properties: PropagationDelay: 8.3060e07 PropagationDistance: 249.0068 AngleOfDeparture: [2×1 double] AngleOfArrival: [2×1 double] NumInteractions: 2
plot(ray);
By default, all buildings have concrete building material electrical characteristics. Change the material to metal for the second reflection and reevaluate path loss. Use the raypl
function to reevaluate the pathloss for the ray. Display the ray path to compare the change in path loss. Replot to show the slight change in color due to the path loss change of the ray.
[ray.PathLoss,ray.PhaseShift] = raypl(ray, ... "ReflectionMaterials",["concrete","metal"])
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: 117.4814 PhaseShift: 4.5669 Readonly properties: PropagationDelay: 8.3060e07 PropagationDistance: 249.0068 AngleOfDeparture: [2×1 double] AngleOfArrival: [2×1 double] NumInteractions: 2
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: 117.4814 PhaseShift: 4.5669 Readonly properties: PropagationDelay: 8.3060e07 PropagationDistance: 249.0068 AngleOfDeparture: [2×1 double] AngleOfArrival: [2×1 double] NumInteractions: 2
plot(ray);
Change the frequency and reevaluate the path loss and phase shift. Plot the ray again and observe the obvious color change.
ray.Frequency = 2e9; [ray.PathLoss,ray.PhaseShift] = raypl(ray, ... "ReflectionMaterials",["concrete","metal"]); plot(ray);
Appendix
[1] The osm 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
— Ray configuration
comm.Ray
object
Ray configuration, specified as one comm.Ray
object. The object must have the
PathSpecification
property set to
"Locations"
.
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.
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, 1byNR string vector, character vector,
1byNR cell array of character vectors, 2by1 numeric vector,
or 2byNR numeric matrix. NR represents the
number of reflections as specified by the comm.Ray
.NumReflections
property.
When
ReflectionMaterials
is specified as a string scalar, string vector, or an equivalent character vector or cell array of character vectors, the reflection material must be one of"concrete"
,"brick"
,"wood"
,"glass"
,"plasterboard"
,"ceilingboard"
,"chipboard"
,"floorboard"
,"metal"
,"water"
,"vegetation"
,"loam"
, or"perfectreflector"
. When specified as a string scalar or char vector, the setting applies to all the reflections.When
ReflectionMaterials
is specified as a 2by1 numeric vector, the [relative permittivity; conductivity] value pair applies to all the reflections.When
ReflectionMaterials
is specified as a 2byNR numeric matrix, the [relative permittivity; conductivity] value pair in each column applies for each of the NR reflection points, respectively.
For more information, see ITU Permittivity and Conductivity Values for Common Materials.
Example: "ReflectionMaterials",["concrete","water"]
, specifies
that a ray with two reflections will use 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)  "H"
 "V"
 "RHCP"
 "LHCP"
 normalized 2by1 Jones vector
Transmit antenna polarization type, specified as "none"
,
"H"
, "V"
, "RHCP"
,
"LHCP"
, or a normalized [H; V] Jones vector. For more
information, 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)  "H"
 "V"
 "RHCP"
 "LHCP"
 normalized 2by1 Jones vector
Receive antenna polarization type, specified as "none"
,
"H"
, "V"
, "RHCP"
,
"LHCP"
, or a normalized [H; V] Jones vector. For more
information, 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
scalar
Path loss in dB, returns the path loss calculated for the input ray object,
accounting for any modifications specified by Name,Value
pairs.
phase
— Phase shift
scalar
Phase shift in radians, returns the phase shift calculated for the input ray object,
accounting for any modifications specified by Name,Value
pairs.
More About
ITU Permittivity and Conductivity Values for Common Materials
ITUR P.20401 [2] and ITUR P.5275 [3] present methods, equations, and values used to calculate real relative permittivity, conductivity, and complex relative permittivity for the common materials.
For information about the values computed for building materials specified in ITUR P.20401, see
buildingMaterialPermittivity
.For information about the values computed for terrain materials specified in ITUR P.5275, 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 path loss computations in raypl follow the path loss and reflection matrix computations as described in IEEE Document 802.1109/0334r8 [1]. The function accounts for geometric coupling between horizontal and vertical polarizations only when both transmit and receive antennas are polarized.
For a first order signal reflection, the reflection matrix, H_{ref1}, is computed as
$${H}_{ref1}=\left[\begin{array}{cc}\mathrm{cos}({\psi}_{rx})& \mathrm{sin}({\psi}_{rx})\\ \mathrm{sin}({\psi}_{rx})& \mathrm{cos}({\psi}_{rx})\end{array}\right]\times \left[\begin{array}{cc}{R}_{\perp}({\alpha}_{inc})& 0\\ 0& {R}_{\parallel}({\alpha}_{inc})\end{array}\right]\times \left[\begin{array}{cc}\mathrm{cos}({\psi}_{tx})& \mathrm{sin}({\psi}_{tx})\\ \mathrm{sin}({\psi}_{tx})& \mathrm{cos}({\psi}_{tx})\end{array}\right]$$
The terms in the channel propagation matrix computation represent
RX geometric coupling matrix — Recalculation of the polarization vector from the plane of incidence basis to RX coordinates.
Polarization matrix — Matrix includes the reflection coefficients R⟂ and R∥ for the perpendicular and parallel components of the electric field E ⟂ and E ∥ respectively.
TX geometric coupling matrix — Recalculation of the polarization vector from the TX coordinates basis to the plane of incidence.
This figure illustrates a first order reflected signal path.
Where
The reflection plane is offset from the global coordinate system origin.
k represents the waveform propagation vector.
n represents the vector normal to the incident plane.
E_{θ} and E_{φ} represent the vertical and horizontal electromagnetic field vectors.
α_{inc} represents the incident angle of k.
ψ_{tx} represents the angle between E_{θ} and a normal to the incident plane.
TX represents the transmit antenna.
RX represents the receive antenna.
The reflection matrix computations for second order signal reflections extend from the first order signal reflection computations. For more information, see IEEE Document 802.1109/0334r8 [1].
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] Maltsev, A., et al. "Channel models for 60 GHz WLAN systems." IEEE Document 802.1109/0334r8, May 2010.
[2] International Telecommunications Union Radiocommunication Sector. Effects of building materials and structures on radiowave propagation above about 100MHz. Recommendation P.20401. ITUR, approved July 29, 2015. https://www.itu.int/rec/RRECP.20401201507I/en.
[3] International Telecommunications Union Radiocommunication Sector. Attenuation by atmospheric gases. Recommendation P.67611. ITUR, approved September 30, 2016. https://www.itu.int/rec/RRECP.67611201609S/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
See Also
Functions
Objects
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
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)