comm.RayTracingChannel

Filter signal through multipath fading channel defined by propagation rays

Since R2020b

Description

The comm.RayTracingChannel System object™ filters a signal through a multipath fading channel that is defined by propagation rays. For more information, see the section.

To filter an input signal through a fading channel defined by propagation rays:

1. Create the comm.RayTracingChannel object and set its properties.

2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

rtchan = comm.RayTracingChannel

rtchan = comm.RayTracingChannel(Name=Value)

rtchan = comm.RayTracingChannel(rays,tx,rx)

Description

rtchan = comm.RayTracingChannel creates a ray-tracing fading channel System object, which defines the multipath environment using a set of propagation rays.

rtchan = comm.RayTracingChannel(Name=Value) sets properties using one or more name-value arguments. For example, comm.RayTracingChannel(SampleRate=1e6) sets the sample rate to 1 MHz.

rtchan = comm.RayTracingChannel(rays,tx,rx) creates a ray-tracing fading channel System object given inputs rays, tx, and rx.

• rays, specified as a set of comm.Ray objects, is used to set the PropagationRays property.

• tx, specified as a txsite object, is used to set the TransmitArray and TransmitArrayOrientationAxes properties.

• rx, specified as an rxsite, is used to set the ReceiveArray and ReceiveArrayOrientationAxes properties.

When you use this syntax, to configure other properties set their values after creating the System object. For example, see Configure Sample Rate for Ray Tracing Channel.

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

SampleRate — Input signal sample rate

10000000 (default) | positive scalar

Input signal sample rate in hertz, specified as a positive scalar. The Configure Sample Rate for Ray Tracing Channel example shows workflows to set the sample rate.

PropagationRays — Propagation rays

comm.Ray object (default) | row vector of comm.Ray objects | row cell array of comm.Ray objects

Propagation rays, specified as a comm.Ray object, a row vector of comm.Ray objects, or a row cell array of comm.Ray objects. This property specifies the propagation rays between the transmit and receive antenna arrays. All of the specified comm.Ray objects must have the same Frequency property setting. Any of the specified comm.Ray objects that have their PathSpecification property set to 'Locations' must have the same CoordinateSystem, TransmitterLocation, and ReceiverLocation property settings.

For code generation, the PropagationRays property must be a cell array of comm.Ray objects.

MinimizePropagationDelay — Option to force zero minimum propagation delay

true or 1 (default) | false or 0

Option to force zero minimum propagation delay, specified as a logical 1 (true) or 0 (false). Set this property to true to subtract the minimum propagation delay from all of the propagation delays of the rays to force zero minimum delay. For more information, see the Tips section.

TransmitArray — Transmit antenna array

arrayConfig object (default) | phased.IsotropicAntennaElement System object | phased array antenna System object

Transmit antenna array, specified as one of these options.

• When you set TransmitArray to an arrayConfig object, you can adjust the Size property of the arrayConfig object to have the transmit array represent a uniform rectangular array (URA), uniform linear array (ULA), or single phased.IsotropicAntennaElement System object. The default configuration for an arrayConfig object is a 2-by-2 URA with an element spacing of 0.5 m.

• When you configure the TransmitArray to use a phased array antenna System object, you must have the Phased Array System Toolbox product. For a list of these additional supported values, see the Phased Array Antenna Options section.

TransmitArrayOrientationAxes — Orientation axes of transmit antenna array

eye(3) (default) | 3-by-3 unitary matrix

Orientation axes of the transmit antenna array, specified as a 3-by-3 unitary matrix indicating the rotation from the local coordinate system (LCS) to the global coordinate system (GCS). If the comm.Ray objects defined in the PropagationRays property set the CoordinateSystem property to 'Geographic', the GCS is the East-North-Up (ENU) coordinate system at the transmitter.

ReceiveArray — Receive antenna array

arrayConfig object | phased.IsotropicAntennaElement System object | phased array antenna System object | ...

Receive antenna array, specified as one of these options.

• When you set ReceiveArray to an arrayConfig object, you can adjust the Size property of the arrayConfig object to have the receive array represent a uniform rectangular array (URA), uniform linear array (ULA), or single phased.IsotropicAntennaElement System object. The default configuration for an arrayConfig object is a 2-by-2 URA with an element spacing of 0.5 m.

• When you set ReceiveArray to a phased array antenna System object configuration, you must have the Phased Array System Toolbox product. For a list of these additional supported values, see the Phased Array Antenna Options section.

ReceiveArrayOrientationAxes — Orientation axes of receive antenna array

eye(3) (default) | 3-by-3 unitary matrix

Orientation axes of the receive antenna array, specified as a 3-by-3 unitary matrix indicating the rotation from the LCS to the GCS. If the comm.Ray objects defined in the PropagationRays property set the CoordinateSystem property to 'Geographic', the GCS is the East-North-Up (ENU) coordinate system at the receiver.

ReceiverVirtualVelocity — Receive antenna array instantaneous velocity

[1; 1; 0] (default) | three-element column vector

Receive antenna array instantaneous velocity in the GCS in m/s, specified as a three-element column vector of the form [x; y; z]. The three elements in this vector specify the x-, y-, and z-velocity, respectively. This property is the velocity used in simulated environment and does not represent the physical movement of an actual receiver. The velocity is effected as a Doppler shift within the channel.

NormalizeImpulseResponses — Option to normalize channel impulse responses

true or 1 (default) | false or 0

Option to normalize channel impulse responses, specified as a logical 1 (true) or 0 (false). Set this property to true to normalize the gains of CIRs to 0 dB from each transmit array element to each receive array element.

NormalizeChannelOutputs — Option to normalize channel outputs by number of receive elements

true or 1 (default) | false or 0

Option to normalize channel outputs by the number of receive elements, specified as a logical 1 (true) or 0 (false). Set this property to true to normalize the channel output by the number of receive array elements.

ChannelFiltering — Channel filtering

true or 1 (default) | false or 0

Channel filtering, specified as one of these logical values:

• 1 (true) — The channel accepts an input signal and produces a filtered output signal.

• 0 (false) — The object does not accept an input signal, produces no filtered output signal, and outputs only channel impulse responses. You must specify the duration of the fading process by using the NumSamples property.

NumSamples — Number of samples

100 (default) | nonnegative integer

Number of samples used for the duration of the channel impulse responses, specified as a nonnegative integer.

Tunable: Yes

Dependencies

To enable this property, set the ChannelFiltering property to false.

OutputDataType — Channel impulse response output data type

'double' (default) | 'single'

Channel impulse response output data type, specified as 'double' or 'single'.

Dependencies

To enable this property, set the ChannelFiltering property to false.

Usage

Syntax

Y = rtchan(X)

Y = rtchan(X,starttime)

[Y,cir] = rtchan(___)

cir = rtchan()

cir = rtchan(starttime)

Description

Y = rtchan(X) filters the input signal through a multipath fading channel defined by a set of propagation rays and returns the result in Y.

Y = rtchan(X,starttime) specifies the start time of the input signal. When the last and current frames are not continuous in time, the System object resets the channel filter states.

[Y,cir] = rtchan(___) also returns the channel impulse response using an input argument combination from either of the prior syntaxes.

cir = rtchan() returns the channel impulse response. To enable this syntax, set the ChannelFiltering property to false.

cir = rtchan(starttime) specifies the start time for the channel impulse response generation. To enable this syntax set the ChannelFiltering property to false.

Input Arguments

X — Input signal

N_S-by-N_T matrix

Input signal, specified as an N_S-by-N_T matrix.

• N_S is the number of samples.

• N_T is the number of transmit array elements.

This object accepts variable-size inputs. After the object is locked, you can change the size of each input channel, but you cannot change the number of channels. For more information, see Variable-Size Signal Support with System Objects.

Data Types: single | double
Complex Number Support: Yes

starttime — Start time

0 (default) | nonnegative scalar

Start time of input signal in seconds, specified as a nonnegative scalar.

When mod(starttime/SampleRate) is nonzero, the start time is rounded up to the nearest sample position. The start time must be greater than the end time of the last frame processed by the channel. You can use the info function to obtain the end time of the last processed frame.

Data Types: double

Output Arguments

Y — Output signal

N_S-by-N_R matrix

Output signal, returned as an N_S-by-N_R matrix.

• N_S is the number of samples.

• N_R is the number of receive array elements.

Y is the same data type as input X.

cir — Channel impulse response

N_S-by-N_P-by-N_T-by-N_R array

Channel impulse response, returned as an N_S-by-N_P-by-N_T-by-N_R array.

• N_S is the number of samples. When you set the ChannelFiltering property to true, N_S is the length of the input. When you set ChannelFiltering to false, N_S is specified by the NumSamples property.

• N_P is the number of paths (specifically, the number of rays as indicated by the length of the PropagationRays property).

• N_T is the number of transmit array elements.

• N_R is the number of receive array elements.

When you set ChannelFiltering to true, the data type for this output is the same data type as input X. When you set ChannelFiltering to false, the data type for this output is specified by the OutputDataType property.

For more information, see the section.

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Specific to comm.RayTracingChannel

info	Characteristic information about ray-tracing channel
showProfile	Plot temporal and spatial profiles of ray-tracing channel
clone	Create duplicate System object
isLocked	Determine if System object is in use

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Remove Minimum Propagation Path Delay from Multipath Ray Trace Channel

Show the impact of not forcing the smallest propagation delay to be zero for a multipath channel model. Filter signals through a multipath ray tracing channel between two sites in Hong Kong, China. Build two multipath channel models by using the result from ray tracing. For the first ray tracing channel model, force the minimum propagation delay to zero. For the second ray tracing channel model, do not force the minimum propagation delay to zero.

Create a Site Viewer map display of buildings in Hong Kong. For more information about the OSM file, see [1].

sv = siteviewer("Buildings","hongkong.osm");

tx = txsite( ...
    "Latitude",22.2789, ...
    "Longitude",114.1625, ...
    "AntennaAngle",30, ...        % Azimuth angle
    "AntennaHeight",10, ...
    "TransmitterFrequency",28e9);
rx = rxsite( ...
    "Latitude",22.2799, ...
    "Longitude",114.1617, ...
    "AntennaAngle",120, ...       % Azimuth angle
    "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. Perform ray tracing to find rays by using the propagation model.

pm = propagationModel("raytracing", ...
    "Method","image", ...
    "MaxNumReflections",2);
rays = raytrace(tx,rx,pm);

Create a channel model using the calculated rays in between the transmitter and receiver sites. The default configuration forces zero minimum propagation delay. Show the temporal and spatial profiles of the channel.

rtchan = comm.RayTracingChannel(rays{1},tx,rx);
rtchan.SampleRate = 50e6;
showProfile(rtchan);

Create a clone of the ray tracing channel model and reconfigure it to not force zero minimum propagation delay. Show the temporal and spatial profiles of the channel. The angle of departure and arrival plots do not change, but the power delay profile plot shows the updated delay profile result when the minimum delay profile is not forced to zero.

rtchandelayed= clone(rtchan);
rtchandelayed.MinimizePropagationDelay = false;
showProfile(rtchandelayed);

Filter randomly generated 16-QAM signals through the channel models. Display the leading 15 elements of y and ydelayed, which are output by the ray tracing channel objects rtchan and rtchandelayed, respectively. The leading samples in the delayed signal, ydelayed, are all zeros. When you model your communications system, you must account for this signal delay to avoid losing trailing signal data.

M = 16;       % Modulation order
frmLen = 1e3; % Frame length
numTx = rtchan.info.NumTransmitElements;

x = qammod(randi([0,M-1],frmLen,numTx),M);
y = rtchan(x);
numTxdelayed = rtchandelayed.info.NumTransmitElements;
x = qammod(randi([0,M-1],frmLen,numTxdelayed),M);
ydelayed = rtchandelayed(x);
y(1:15)

ans = 15×1 complex

  -0.0000 - 0.0000i
   0.0000 + 0.0000i
  -0.0000 - 0.0000i
   0.0000 + 0.0000i
  -0.0000 - 0.0000i
   0.0003 + 0.0011i
  -0.0022 - 0.0111i
   1.0158 + 0.0042i
  -1.0347 - 2.0177i
  -3.0922 + 0.0258i
      ⋮

ydelayed(1:15)

ans = 15×1

     0
     0
     0
     0
     0
     0
     0
     0
     0
     0
      ⋮

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

Show Multipath Ray Trace Channel Modeling in Conference Room

Filter signals through a multipath ray tracing channel model between two sites in a conference room. Build the multipath channel model by using the result from ray tracing.

Define a 3-D map for a conference room with one table and four chairs by using a standard tessellation language (STL) data file. Define a transmitter site close to the wall and a receiver site above the table.

mapFileName = "conferenceroom.stl";

tx = txsite("cartesian", ...
    "AntennaPosition",[-1.45; -1.4; 2.3], ...
    "TransmitterFrequency",2.8e9);
rx = rxsite("cartesian", ...
    "AntennaPosition",[.6; .2; 1.0]);

Use the siteviewer object and the show object function to visualize the 3-D scenario. The transmitter and receiver sites are colored in red and blue, respectively.

siteviewer(SceneModel=mapFileName);
show(tx,"ShowAntennaHeight",false)
show(rx,"ShowAntennaHeight",false)

Create a ray tracing propagation model, which MATLAB represents using a RayTracing object. Configure the model to find paths with up to 3 surface reflections. By default, the model uses the shooting and bouncing rays (SBR) method.

pm = propagationModel("raytracing", ...
    "CoordinateSystem","cartesian", ...
    "MaxNumReflections",3);

Perform ray tracing to find rays by using the propagation model.

rays = raytrace(tx,rx,pm,"Map",mapFileName);

Extract the computed rays from the returned cell array, and then plot the rays. Each ray is colored based on its path loss value.

rays = rays{1,1};
plot(rays)

Create a channel model using the calculated rays in between the transmitter and receiver sites. Show the temporal and spatial profiles of the channel.

rtchan = comm.RayTracingChannel(rays,tx,rx);
showProfile(rtchan);

Show the filtered signal in a constellation diagram.

M = 16;       % Modulation order
frmLen = 1e3; % Frame length

numTx = rtchan.info.NumTransmitElements;
x = qammod(randi([0,M-1],frmLen,numTx),M);
y_samprate10e6 = rtchan(x);
constellationdiag = comm.ConstellationDiagram( ...
    ...NumInputPorts=2=1, ...ChannelNames={
    ..."Frequency response channel"}, ...
    XLimits=[-5 5], ...
    YLimits=[-5 5], ...
    ReferenceConstellation=qammod(0:M-1,M));
constellationdiag(y_samprate10e6(:));

At 10e6 sample rate, the diagram shows well-defined and tightly clustered points around the ideal 16-QAM constellation positions. This indicates that the channel has not significantly altered the signal and that the channel introduces minimal ISI and distortion. In a conference room where the primary focus is on maintaining a stable and predictable channel behavior this delay profile is ideal.

For the selected sample rate (10e6), the delay spread of the multiple rays is too low. A higher sample rate would capture the temporal variations and also introduce significant ISI and distortion.

Configure Sample Rate for Ray Tracing Channel

To modify the sample rate of the ray tracing channel, you can set the SampleRate property by using a name-value argument when you create the object or you can create a channel model by using the rays and site and set the SampleRate property after you create the object.

Set Sample Rate when Creating Ray Tracing Channel Object

Create a ray tracing channel model, specifying the sample rate as 20 MHz.

rtchan1 = comm.RayTracingChannel(SampleRate=2e7)

rtchan1 = 
  comm.RayTracingChannel with properties:

                      SampleRate: 20000000
                 PropagationRays: [1×1 comm.Ray]
        MinimizePropagationDelay: true
                   TransmitArray: [1×1 arrayConfig]
    TransmitArrayOrientationAxes: [3×3 double]
                    ReceiveArray: [1×1 arrayConfig]
     ReceiveArrayOrientationAxes: [3×3 double]
         ReceiverVirtualVelocity: [3×1 double]
       NormalizeImpulseResponses: true
         NormalizeChannelOutputs: true
                ChannelFiltering: true

Set Sample Rate After Creating Ray Tracing Channel Object

Create a channel model by using the transmitter site, receiver site, and calculated rays between the sites. After creating the object, set the sample rate to 20 MHz.

tx = txsite( ...
    Latitude=22.2789, ...
    Longitude=114.1625, ...
    AntennaAngle=30, ...        % Azimuth angle
    AntennaHeight=10, ...
    TransmitterFrequency=28e9);
rx = rxsite( ...
    Latitude=22.2799, ...
    Longitude=114.1617, ...
    AntennaAngle=120, ...       % Azimuth angle
    AntennaHeight=1);
pm = propagationModel("raytracing", ...
    Method="sbr", ...
    MaxNumReflections=3);
rays = raytrace(tx,rx,pm);

rtchan2 = comm.RayTracingChannel(rays{1},tx,rx);
rtchan2.SampleRate = 2e7

rtchan2 = 
  comm.RayTracingChannel with properties:

                      SampleRate: 20000000
                 PropagationRays: [1×2 comm.Ray]
        MinimizePropagationDelay: true
                   TransmitArray: [1×1 arrayConfig]
    TransmitArrayOrientationAxes: [3×3 double]
                    ReceiveArray: [1×1 arrayConfig]
     ReceiveArrayOrientationAxes: [3×3 double]
         ReceiverVirtualVelocity: [3×1 double]
       NormalizeImpulseResponses: true
         NormalizeChannelOutputs: true
                ChannelFiltering: true

After configuring the channel object, you would typically filter a modulated signal through the channel. Here a 16-QAM signal is passed through the rtchan2 ray tracing channel.

modOrd = 16;
frmLen = 1e3;
numTx = rtchan2.info.NumTransmitElements;
x = qammod(randi([0,modOrd-1],frmLen,numTx),modOrd);
y = rtchan2(x);

More About

Channel Impulse Response (CIR)

The channel impulse response (CIR) output characterizes the effects of multipath propagation, including reflections and diffractions, by detailing the path delays and path gains of the signal components. CIR equation is:

$$a[t]={\displaystyle \sum _{p=1}^{Np}{a}_p\delta [t-{\tau }_p]}$$

, where:

• h(t) ) is the Channel Impulse Response (CIR) at time (t).

• (N_p ) is the number of multipath components or the total number of distinct paths through which the signal propagates from the transmitter to the receiver.

• a_p) is the amplitude (or gain) of the signal along the p^th path.

• δ(t - τ_p) is the Dirac delta function that is zero everywhere except at (t = τ_p), where it is infinitely high such that its integral over time equals one. It is used to indicate the presence of a signal component at a specific time delay τ_p.

• τ_p is the time delay associated with the p^th path. It represents the time taken by the signal to travel from the transmitter to the receiver along this path.

Phased Array Antenna Options

If you have the Phased Array System Toolbox product, you can specify any of these phased array antenna System object configurations for the TransmitArray and ReceiveArray properties.

• phased.IsotropicAntennaElement (Phased Array System Toolbox)

• phased.NRAntennaElement (Phased Array System Toolbox)

• phased.CustomAntennaElement (Phased Array System Toolbox)

• phased.URA (Phased Array System Toolbox) with the Element property set to a phased.IsotropicAntennaElement, phased.NRAntennaElement, or phased.CustomAntennaElement System object

• phased.ULA (Phased Array System Toolbox) with the Element property set to a phased.IsotropicAntennaElement, phased.NRAntennaElement, or phased.CustomAntennaElement System object

• phased.ConformalArray (Phased Array System Toolbox) with the Element property set to a phased.IsotropicAntennaElement, phased.NRAntennaElement, or phased.CustomAntennaElement System object

• phased.NRRectangularPanelArray (Phased Array System Toolbox) with the ElementSet property set to a phased.IsotropicAntennaElement, phased.NRAntennaElement, or phased.CustomAntennaElement System object

Tips

• When you set the MinimizePropagationDelay property to true, the System object shifts all propagation delay paths to remove the amount of delay that is associated with the minimum propagation delay path. Shifting the paths removes potential leading zeros in the channel output and eliminates the need to account for the delay to receive the trailing signal samples.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

• For code generation, the PropagationRays property must be a cell array of comm.Ray objects.

• For comm.Ray objects, when you set the PathSpecification property to 'Locations' and the LineOfSight property to false, the Type field setting must be the same (either all 'Reflection' or all 'Diffraction') in the structures specified by the Interactions property for each individual comm.Ray object.

Version History

Introduced in R2020b