Main Content

comm.RayTracingChannel

Filter signal through multipath fading channel defined by propagation rays

Since R2020b

expand all in page

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 Channel Impulse Response 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.

example

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

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

expand all

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

example

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

expand all

Input signal, specified as an NS-by-NT matrix.

  • NS is the number of samples.

  • NT 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

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

expand all

Output signal, returned as an NS-by-NR matrix.

  • NS is the number of samples.

  • NR is the number of receive array elements.

Y is the same data type as input X.

Channel impulse response, returned as an NS-by-NP-by-NT-by-NR array.

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

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

  • NT is the number of transmit array elements.

  • NR 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 Channel Impulse Response 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)

expand all

infoCharacteristic information about ray-tracing channel
showProfilePlot temporal and spatial profiles of ray-tracing channel
cloneCreate duplicate System object
isLockedDetermine if System object is in use
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Open Live Script

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");

Site Viewer with buildings

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);

Figure contains 3 axes objects. Axes object 1 with title Power Delay Profile contains an object of type stem. Axes object 2 with title Angle of Departure contains 7 objects of type quiver, text. Axes object 3 with title Angle of Arrival contains 7 objects of type quiver, text.

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);

Figure contains 3 axes objects. Axes object 1 with title Power Delay Profile contains an object of type stem. Axes object 2 with title Angle of Departure contains 7 objects of type quiver, text. Axes object 3 with title Angle of Arrival contains 7 objects of type quiver, text.

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.0110i
   1.0137 - 0.0002i
  -1.0413 - 2.0091i
  -3.0858 + 0.0390i
      ⋮


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

Open Live Script

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)

Site Viewer with model of conference room. Many propagation paths connect the transmitter and receiver sites.

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);

Figure contains 3 axes objects. Axes object 1 with title Power Delay Profile contains an object of type stem. Axes object 2 with title Angle of Departure contains 7 objects of type quiver, text. Axes object 3 with title Angle of Arrival contains 7 objects of type quiver, text.

Filter randomly generated 16-QAM signals through the channel. With the default sample rate of 10e6, the channel frequency response is flat. Increasing the sample rate to 1e9 results in a frequency selective channel. Show the filtered signal for the flat frequency response channel and the frequency selective channel 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);

release(rtchan);
rtchan.SampleRate = 1e9;
y_samprate1e9 = rtchan(x);
constellationdiag = comm.ConstellationDiagram( ...
    NumInputPorts=2, ...
    ChannelNames={ ...
    "Flat frequency response channel","Frequency selective channel"}, ...
    XLimits=[-5 5], ...
    YLimits=[-5 5], ...
    ReferenceConstellation=qammod(0:M-1,M));
constellationdiag(y_samprate10e6(:),y_samprate1e9);

Open Live Script

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

expand all

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

Version History

Introduced in R2020b

See Also

Objects

Functions

Topics