raypl

Calculate path loss and phase shift for ray

Syntax

[pl,phase] = raypl (ray)

[pl,phase] = raypl (ray,Name,Value)

Description

[pl,phase] = raypl (ray) returns the path loss in dB and phase shift in radians based on the properties specified by 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.

example

[pl,phase] = raypl (ray,Name,Value) calculates the path loss and phase shift with additional options specified by one or more name-value pair arguments.

Examples

collapse all

Reevaluate Path Loss Changing Reflection Materials and Frequency

Open Live Script

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.

rays = raytrace(tx,rx,"NumReflections",0:2);

Find the first ray with 2-order 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}.NumReflections] == 2,1))

ray = 
  Ray with properties:

      PathSpecification: 'Locations'
       CoordinateSystem: 'Geographic'
    TransmitterLocation: [3×1 double]
       ReceiverLocation: [3×1 double]
            LineOfSight: 0
    ReflectionLocations: [3×2 double]
              Frequency: 2.8000e+10
         PathLossSource: 'Custom'
               PathLoss: 122.1825
             PhaseShift: 4.5977

   Read-only properties:
       PropagationDelay: 8.3060e-07
    PropagationDistance: 249.0069
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
         NumReflections: 2

plot(ray);

By default, all buildings have concrete building material electrical characteristics. Change the material to metal for the second reflection and re-evaluate 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
    ReflectionLocations: [3×2 double]
              Frequency: 2.8000e+10
         PathLossSource: 'Custom'
               PathLoss: 117.4814
             PhaseShift: 4.5977

   Read-only properties:
       PropagationDelay: 8.3060e-07
    PropagationDistance: 249.0069
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
         NumReflections: 2

ray = 
  Ray with properties:

      PathSpecification: 'Locations'
       CoordinateSystem: 'Geographic'
    TransmitterLocation: [3×1 double]
       ReceiverLocation: [3×1 double]
            LineOfSight: 0
    ReflectionLocations: [3×2 double]
              Frequency: 2.8000e+10
         PathLossSource: 'Custom'
               PathLoss: 117.4814
             PhaseShift: 4.5977

   Read-only properties:
       PropagationDelay: 8.3060e-07
    PropagationDistance: 249.0069
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
         NumReflections: 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 crowd-sourced 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

collapse all

`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

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 | 1-by-NR string vector | 2-by-1 numeric vector | 2-by-NR numeric matrix

Reflection materials for a non-line-of-sight (NLOS) ray, specified as a string scalar, 1-by-NR string vector, 2-by-1 numeric vector, or 2-by-NR numeric matrix. NR represents the number of reflections as specified by the comm.Ray.NumReflections property.

When ReflectionMaterials is specified as a string scalar or string vector, the reflection material must be one of "concrete", "brick", "wood", "glass", "metal", "water", "vegetation", "loam", or "perfect-reflector". When specified as a string scalar, the setting applies to all the reflections.
When ReflectionMaterials is specified as a 2-by-1 numeric vector, the [relative permittivity; conductivity] value pair applies to all the reflections.
When ReflectionMaterials is specified as a 2-by-NR numeric matrix, the [relative permittivity; conductivity] value pair in each column applies for each of the NR reflection points, respectively.

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 2-by-1 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 right-hand circular polarization for the transmit antenna.

Data Types: double | char | string

`'ReceiverPolarization'` — Receive antenna polarization type
`"none"` (default) | `"H"` | `"V"` | `"RHCP"` | `"LHCP"` | normalized 2-by-1 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
3-by-3 identity matrix (default) | 3-by-3 unitary matrix

Orientation of the transmit antenna axes, specified as a 3-by-3 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 East-North-Up (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
3-by-3 identity matrix (default) | 3-by-3 unitary matrix

Orientation of the receive antenna axes, specified as a 3-by-3 unitary matrix indicating the rotation from the receiver local coordinate system (LCS) into the global coordinate system (GCS). The GCS orientation is the local East-North-Up (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 z-axis of the local receiver coordinate system with respect to the global coordinate system.

Data Types: double

Output Arguments

collapse all

`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

collapse all

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 East-North-Up (ENU) coordinate system at observer. The path loss computation accounts for the round-earth 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.11-09/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_{r e f 1} = [\begin{matrix} \cos (ψ_{r x}) & \sin (ψ_{r x}) \\ - \sin (ψ_{r x}) & \cos (ψ_{r x}) \end{matrix}] \times [\begin{matrix} R_{⊥} (α_{i n c}) & 0 \\ 0 & R_{∥} (α_{i n c}) \end{matrix}] \times [\begin{matrix} \cos (ψ_{t x}) & \sin (ψ_{t x}) \\ - \sin (ψ_{t x}) & \cos (ψ_{t x}) \end{matrix}]$

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.11-09/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	$(\begin{matrix} H \\ V \end{matrix}) = (\begin{matrix} 0 \\ 1 \end{matrix})$
Linear polarized in the φ direction	$(\begin{matrix} H \\ V \end{matrix}) = (\begin{matrix} 1 \\ 0 \end{matrix})$
Left-hand circular polarized (LHCP)	$(\begin{matrix} H \\ V \end{matrix}) = \frac{1}{\sqrt{2}} (\begin{matrix} j \\ 1 \end{matrix})$
Right-hand circular polarized (RHCP)	$(\begin{matrix} H \\ V \end{matrix}) = \frac{1}{\sqrt{2}} (\begin{matrix} - j \\ 1 \end{matrix})$

References

[1] Maltsev, A., et al. "Channel models for 60 GHz WLAN systems." IEEE Document 802.11-09/0334r8, May 2010.

Documentation

raypl

Syntax

Description

Examples

Reevaluate Path Loss Changing Reflection Materials and Frequency

Input Arguments

`ray` — Ray configuration
`comm.Ray` object

Name-Value Pair Arguments

`'ReflectionMaterials'` — Reflection materials
`"concrete"` (default) | string scalar | 1-by-NR string vector | 2-by-1 numeric vector | 2-by-NR numeric matrix

`'TransmitterPolarization'` — Transmit antenna polarization type
`"none"` (default) | `"H"` | `"V"` | `"RHCP"` | `"LHCP"` | normalized 2-by-1 Jones vector

`'ReceiverPolarization'` — Receive antenna polarization type
`"none"` (default) | `"H"` | `"V"` | `"RHCP"` | `"LHCP"` | normalized 2-by-1 Jones vector

`'TransmitterAxes'` — Orientation of transmit antenna axes
3-by-3 identity matrix (default) | 3-by-3 unitary matrix

`'ReceiverAxes'` — Orientation of receive antenna axes
3-by-3 identity matrix (default) | 3-by-3 unitary matrix

Output Arguments

`pl` — Path loss
scalar

`phase` — Phase shift
scalar

More About

Coordinate System Orientation

Path Loss Computation

Jones Vector Notation

References

See Also

Functions

Objects

Antenna Toolbox Documentation

Support

Documentation

raypl

Syntax

Description

Examples

Reevaluate Path Loss Changing Reflection Materials and Frequency

Input Arguments

ray — Ray configuration comm.Ray object

Name-Value Pair Arguments

'ReflectionMaterials' — Reflection materials "concrete" (default) | string scalar | 1-by-NR string vector | 2-by-1 numeric vector | 2-by-NR numeric matrix

'TransmitterPolarization' — Transmit antenna polarization type "none" (default) | "H" | "V" | "RHCP" | "LHCP" | normalized 2-by-1 Jones vector

'ReceiverPolarization' — Receive antenna polarization type "none" (default) | "H" | "V" | "RHCP" | "LHCP" | normalized 2-by-1 Jones vector

'TransmitterAxes' — Orientation of transmit antenna axes 3-by-3 identity matrix (default) | 3-by-3 unitary matrix

'ReceiverAxes' — Orientation of receive antenna axes 3-by-3 identity matrix (default) | 3-by-3 unitary matrix

Output Arguments

pl — Path loss scalar

phase — Phase shift scalar

More About

Coordinate System Orientation

Path Loss Computation

Jones Vector Notation

References

See Also

Functions

Objects

Antenna Toolbox Documentation

Support

`ray` — Ray configuration
`comm.Ray` object

`'ReflectionMaterials'` — Reflection materials
`"concrete"` (default) | string scalar | 1-by-NR string vector | 2-by-1 numeric vector | 2-by-NR numeric matrix

`'TransmitterPolarization'` — Transmit antenna polarization type
`"none"` (default) | `"H"` | `"V"` | `"RHCP"` | `"LHCP"` | normalized 2-by-1 Jones vector

`'ReceiverPolarization'` — Receive antenna polarization type
`"none"` (default) | `"H"` | `"V"` | `"RHCP"` | `"LHCP"` | normalized 2-by-1 Jones vector

`'TransmitterAxes'` — Orientation of transmit antenna axes
3-by-3 identity matrix (default) | 3-by-3 unitary matrix

`'ReceiverAxes'` — Orientation of receive antenna axes
3-by-3 identity matrix (default) | 3-by-3 unitary matrix

`pl` — Path loss
scalar

`phase` — Phase shift
scalar