gpuConstantGammaClutter

Simulate constant-gamma clutter using GPU

Since R2021a

Description

The gpuConstantGammaClutter System object™ simulates constant gamma clutter for a monostatic radar using a Graphical Processing Unit (GPU) to perform computations.

Note

To use this object, you must install a Parallel Computing Toolbox™ license and have access to an appropriate GPU. For more about GPUs, see GPU Computing (Parallel Computing Toolbox).

gpuConstantGammaClutter assumes that:

• The radar system is monostatic.

• The propagation is in free space.

• The terrain is homogeneous.

• The clutter patch is stationary during the coherence time. Coherence time indicates how frequently the software changes the set of random numbers in the clutter simulation.

• Because the signal is narrowband, the spatial response and Doppler shift can be approximated by phase shifts.

• The radar system maintains a constant height during simulation.

• The radar system maintains a constant speed during simulation.

To compute the clutter return:

1. Create the gpuConstantGammaClutter 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

gpuclutter = gpuconstantGammaClutter

gpuclutter = gpuconstantGammaClutter(Name=Value)

Description

gpuclutter = gpuconstantGammaClutter creates a constant gamma clutter simulation System object, gpuclutter. This object simulates the clutter return of a monostatic radar system using the constant gamma model.

gpuclutter = gpuconstantGammaClutter(Name=Value) creates a constant gamma clutter simulation system object, gpuclutter, with each specified Property Name set to the corresponding Value. You can specify additional pairs of arguments in any order as Name1=Value1,...,NameN=ValueN.

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.

Sensor — Handle of sensor

phased.ULA array with default property values (default) | sensor or array object

Specify the sensor element or array as a System object object whose Element property value is an antenna element object. A sensor array can contain subarrays.

Gamma — Terrain gamma value (dB)

0 (default) | scalar

Specify the $$\gamma$$ value used in the constant $$\gamma$$ clutter model. The $$\gamma$$ value depends on both terrain type and the operating frequency. Units are decibel (dB).

Data Types: double

EarthModel — Earth model

'Flat' (default) | 'Curved'

Specify the earth model used in the clutter simulation as 'Flat' or 'Curved'. When you set this property to 'Flat', the Earth is assumed to be a flat plane. When you set this property to 'Curved', the Earth is assumed to be a sphere.

Data Types: string | char

ClutterMinRange — Minimum range of clutter region (m)

0 (default) | positive scalar

The minimum range at which to computer clutter returns, specified as a positive scalar. This value is ignored if it is less than the value of PlatformHeight. Units are in meters (m).

Data Types: double

ClutterMaxRange — Maximum range of clutter region (m)

5000 (default) | positive scalar

The maximum range at which to compute clutter returns, specified as a positive scalar. The maximum range must be greater than the value specified in the PlatformHeight property. Units are in meters (m).

Data Types: double

ClutterAzimuthCenter — Azimuth center of clutter region (deg)

0 (default) | scalar

The azimuth angle in the ground plane about which clutter patches are generated. Patches are generated symmetrically about this angle. Units are degrees (deg).

Data Types: double

ClutterAzimuthSpan — Azimuth span of clutter region (deg)

60 (default) | positive scalar

The coverage of the clutter region in azimuth, specified as a positive scalar. The clutter simulation covers a region having the specified azimuth span, symmetric around ClutterAzimuthCenter. Typically, all clutter patches have their azimuth centers within the region, but the PatchAzimuthSpan value can cause some patches to extend beyond the region. Units are degrees (deg).

Data Types: double

PatchAzimuthSpan — Azimuth span of clutter patches (deg)

1 (default) | positive scalar

The azimuth span of each clutter patch, specified as a positive scalar. Units are degrees (deg).

Data Types: double

CoherenceTime — Clutter coherence time (s)

inf (default) | positive scalar

The coherence time for the clutter simulation, specified as a positive scalar. After the coherence time elapses, the next call to the system object updates the random numbers used for the clutter simulation at the next pulse. A value of inf means the random numbers are never updated. Units are seconds (s).

Data Types: double

PropagationSpeed — Signal propagation speed (m/s)

physconst('LightSpeed') (default) | positive scalar

Signal propagation speed, specified as a positive scalar. Units are in meters per second (m/s). The default propagation speed is the value returned by physconst('LightSpeed'). See physconst for more information.

Example: 3e8

Data Types: double

SampleRate — Sample rate of signal (Hz)

1e6 (default) | positive scalar

Sample rate of signal, specified as a positive scalar. Units are in Hz. The System object uses this quantity to calculate the propagation delay in units of samples. The default value corresponds to 1 MHz.

Example: 1e6

Data Types: double

PRF — Pulse repetition frequency (Hz)

10e3 (default) | positive scalar

Pulse repetition frequency, PRF, specified as a scalar or a row vector. Units are in Hz. You can select the value of PRF using property settings alone or using property settings in conjunction with the PRFIDX input argument.

• When PRFSelectionInputPort is false, you set the PRF using properties only. You can

  • Implement a constant PRF by specifying PRF as a positive real-valued scalar.

  • Implement a staggered PRF by specifying PRF as a row vector with positive real-valued entries. Then, each call to the System object uses successive elements of this vector for the PRF. If the last element of the vector is reached, the process continues cyclically with the first element of the vector.

• When PRFSelectionInputPort is true, you can implement a selectable PRF by specifying PRF as a row vector with positive real-valued entries. When you call the System object, select a PRF by passing the index input argument PRFIDX.

In all cases, the number of output samples is fixed when you set the OutputFormat property to 'Samples'. When you use a varying PRF and set the OutputFormat property to 'Pulses', the number of samples can vary.

Data Types: double

PRFSelectionInputPort — Enable PRF selection input

false (default) | true

Enable the PRF selection input, specified as true or false. The default value for this property is false and the value set in the PRF property is used. When you set this property to true, you pass the index input argument PRFIDX to the System object. PRFIDX specifies an index of the PRF vector so that one of the PRFs is selected from the PRF property as the PRF for the next transmission.

Data Types: logical

OutputFormat — Output signal format

'Pulses' (default) | 'Samples'

Specify the format of the output signal as one of 'Pulses' or 'Samples'. When you set the OutputFormat property to 'Pulses', the output of the System object is in the form of multiple pulses. In this case, the number of pulses is the value of the NumPulses property.

When you set the OutputFormat property to 'Samples', the output of the System object is in the form of multiple samples. In this case, the number of samples is the value of the NumSamples property. In staggered PRF applications, you might find the 'Samples' option more convenient because the System object output always has the same matrix size.

Data Types: string | char

NumPulses — Number of pulses in output

1 (default) | positive integer

Specify the number of pulses in the output of the System object as a positive integer. This property applies only when you set the OutputFormat property to 'Pulses'.

Data Types: double

NumSamples — Number of samples in output

100 (default) | positive integer

Specify the number of samples in the output of the System object as a positive integer. Typically, you use the number of samples in one pulse. This property applies only when you set the OutputFormat property to 'Samples'.

Data Types: double

OperatingFrequency — System operating frequency (Hz)

3e8 (default) | positive scalar

Specify the operating frequency of the system in hertz as a positive scalar. The default value corresponds to 300 MHz.

Data Types: double

TransmitSignalInputPort — Enable transmit signal input

false (default) | true

Enable transmit signal input, specified as false or true. Set this property to true to enable transmit signal input and use the input argument X to specify the transmit signal. If this property is set to true, then you must also specify the TransmitERP property. By default, this property is set to false to omit the transmit signal. The false option is less computationally expensive.

Data Types: logical

WeightsInputPort — Enable weights input

false (default) | true

Enable weights input, specified as false or true. Set this property to true to enable weights input and use the object input argument WS to specify weights. Weights are applied to individual array elements (or at the subarray level when subarrays are supported).

Data Types: logical

TransmitERP — Effective transmitted power (W)

5000 (default) | positive scalar

Effective transmitted power

Specify the transmitted effective radiated power (ERP) of the radar system in Watts as a positive scalar. This property applies only when you set the TransmitSignalInputPort property to false.

Data Types: double

PlatformHeight — Radar platform height from surface (m)

300 (default) | nonnegative scalar

Specify the radar platform height measured upward from the surface, in meters, as a nonnegative scalar.

Data Types: double

PlatformSpeed — Radar platform speed (m/s)

300 (default) | nonnegative scalar

Specify the radar platform speed as a nonnegative scalar in meters per second.

Data Types: double

PlatformDirection — Direction of radar platform motion (deg)

[90;0] (default) | 2-by-1 vector

Specify the direction of radar platform motion as a 2-by-1 vector in the form [AzimuthAngle; ElevationAngle] in degrees. The default value of this property indicates that the platform moves perpendicular to the radar antenna's broadside.

Both azimuth and elevation angle are measured in the local coordinate system of the radar antenna or antenna array. Azimuth angle must be between –180 and 180 degrees. Elevation angle must be between –90 and 90 degrees.

Data Types: double

MountingAngles — Sensor mounting angles (deg)

[0 0 0] (default) | 3-element vector

Specify a 3-element vector that gives the intrinsic yaw, pitch, and roll of the sensor frame from the inertial frame. The 3 elements define the rotations around the z, y, and x axes respectively, in that order. The first rotation, rotates the body axes around the z-axis. Because these angles define intrinsic rotations, the second rotation is performed around the y-axis in its new position resulting from the previous rotation. The final rotation around the x-axis is performed around the x-axis as rotated by the first two rotations in the intrinsic system.

Data Types: double

SeedSource — Source of seed for random number generator

'Auto' (default) | 'Property'

Specify how the object generates random numbers. Values of this property are:

'Auto'	The default MATLAB® random number generator produces the random numbers. Use 'Auto' if you are using this object with Parallel Computing Toolbox software.
'Property'	The object uses its own private random number generator to produce random numbers. The Seed property of this object specifies the seed of the random number generator. Use 'Property' if you want repeatable results and are not using this object with Parallel Computing Toolbox software.

Data Types: string | char

Seed — Seed for random number generator

0 (default) | scalar integer

Specify the seed for the random number generator as a scalar integer between 0 and 2³²–1. This property applies when you set the SeedSource property to 'Property'.

Data Types: double

Usage

Syntax

Y = gpuclutter

Y = gpuclutter(X)

Y = gpuclutter(STEERANGLE)

Y = gpuclutter(WS)

Y = gpuclutter(PRFIDX)

Y = gpuclutter(X,STEERANGLE,WS,PRFIDX)

Description

Y = gpuclutter returns the collected clutter return, Y, computed at each sensor or subarray. This syntax is available when you set the TransmitSignalInputPort property to false.

Y = gpuclutter(X) specifies the input transmit signal as X. This syntax is available when you set the TransmitSignalInputPort property to true.

Y = gpuclutter(STEERANGLE) specifies STEERANGLE as the input subarray steering angle. To use this syntax, set the Sensor property to an array that supports subarrays and set the SubarraySteering property of the array to either 'Phase' or 'Time'.

Y = gpuclutter(WS) specifies WS as the input weights applied to each element, subarray, or element within each subarray. This syntax is available when you set the WeightsInputPort property to true. To enable this argument for subarray element weights, also set the Sensor property to an array that contains subarrays and set the SubarraySteering property of that array to 'Custom'.

Y = gpuclutter(PRFIDX) uses the index PRFIDX to select the PRF from a predetermined list of PRFs specified by the PRF property. To enable this syntax, set the PRFSelectionInputPort to true.

Y = gpuclutter(X,STEERANGLE,WS,PRFIDX) combines optional input arguments. This syntax is available when enabling properties are set. Optional inputs must be listed in the same order as the order of enabling properties.

Input Arguments

gpuclutter — Constant gamma clutter object

gpuConstantGammaClutter object

Constant gamma clutter, specified as a gpuConstantGammaClutter System object.

X — Transmit signal

column vector (N-by-1, where N is a nonnegative integer)

Specify the transmit signal as a column vector. Transmit signal refers to the output of the transmitter while it is on during a given pulse. The System object handles data transfer between the CPU and GPU.

Dependencies

To enable this argument, set the set the TransmitSignalInputPort property to true.

STEERANGLE — Subarray steering angle (deg)

scalar | 2-by-1 real-valued vector

Subarray steering angle, specified as a scalar or length-2 column vector. Units are in degrees.

• If STEERANGLE is a length-2 vector, it has the form [AzimuthAngle;ElevationAngle]. The azimuth angle must be between –180 and 180 deg (inclusive), and the elevation angle must be between –90 and 90 deg (inclusive).

• If STEERANGLE is a scalar, it represents the azimuth angle. The elevation angle is assumed to be 0 deg.

Example: [20;15]

Dependencies

To enable this argument, set the Sensor property to an array that supports subarrays and set the SubarraySteering property of that array to either 'Phase' or 'Time'. That is, configure gpuclutter so that gpuclutter.Sensor is an array that contains subarrays and set glcutter.Sensor.SubarraySteering to either 'Phase' or 'Time'.

WS — Weights for each element, subarray, or element within each subarray

N-by-1 column vector | N_SE-by-N matrix | 1-by-N cell array

Specify weights applied to each element, subarray, or element within each subarray. Element or subarray weights are specified as an N-by-1 column vector, where N is the number of array elements (or subarrays when the array supports subarrays). Subarray element weights are specified as an N_SE-by-N matrix or 1-by-N cell array where N is the number of subarrays. These weights are applied to the individual elements within a subarray.

Subarray element weights

Sensor Array	Subarray weights
phased.ReplicatedSubarray	All subarrays have the same dimensions and sizes. Then WS is an NSE-by-N matrix, where NSE is the number of elements in each subarray and N is the number of subarrays. Each column of WS specifies the weights for the corresponding subarray.
phased.PartitionedArray	Subarrays may not have the same dimensions and sizes. In this case, you can specify WS as an NSE-by-N matrix, where NSE is now the number of elements in the largest subarray. The first Q entries in each column are the element weights for the subarray where Q is the number of elements in the subarray. a 1-by-N cell array. Each cell contains a column vector of weights for the corresponding subarray. The column vectors have lengths equal to the number of elements in the corresponding subarray.

Dependencies

To enable this argument, set the WeightsInputPort property to true.

To enable this argument for subarray element weights, also set the Sensor property to an array that contains subarrays and set the SubarraySteering property of that array to 'Custom'. That is, configure gpuclutter so that gpuclutter.Sensor is an array that contains subarrays and set glcutter.Sensor.SubarraySteering to 'Custom'.

PRFIDX — Index of pulse repetition frequency (PRF)

positive integer

Index of pulse repetition frequency, specified as a positive integer. The index selects one of the entries specified in the PRF property as the PRF for the next transmission. Use this syntax for the cases in which the transmit pulse needs to be dynamically selected and the PRF property includes a list of predetermined choices of PRFs.

Example: 3

Dependencies

To enable this argument, set the PRFSelectionInputPort to true.

Output Arguments

Y — Collected clutter return at each sensor

N-by-M

Collected clutter return at each sensor, returned as a matrix of dimensions N-by-M, where M is the number of sensors or subarrays in the radar system. When you set the OutputFormat property to 'Samples', N is defined by the NumSamples property. When you set the OutputFormat property to 'Pulses', N is the total number of samples in the next L pulses, where L is defined by the NumPulses property.

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)

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

GPU Clutter Simulation of Radar System with Known Power

Simulate the clutter return from terrain with a gamma value of 0 dB. The effective transmitted power of the radar system is 5 kW.

Set up the characteristics of the radar system. This system uses a 4-element uniform linear array (ULA). The sample rate is 1 MHz, and the PRF is 10 kHz. The propagation speed is the speed of light, and the operating frequency is 300 MHz. The radar platform is flying 1 km above the ground with a path parallel to the ground along the array axis. The platform speed is 2000 m/s. The mainlobe has a depression angle of 30$${}^{\circ }$$.

Nele = 4;
c = physconst('Lightspeed');
fc = 300e6;
lambda = c/fc;
array = phased.ULA('NumElements',Nele,'ElementSpacing',lambda/2);
fs = 1e6;
prf = 10e3;
height = 1000.0;
direction = [90;0];
speed = 2.0e3;
depang = 30.0;
mountingAng = [0,30,0];

Create the GPU clutter simulation object. The configuration assumes the earth is flat. The maximum clutter range of interest is 5 km, and the maximum azimuth coverage is $$\pm 60^{\circ }$$.

Rmax = 5000;
Azcov = 120;
tergamma = 0;
tpower = 5000;
clutter = gpuConstantGammaClutter('Sensor',array, ...
    'PropagationSpeed',c,'OperatingFrequency',fc,'PRF',prf, ...
    'SampleRate',fs,'Gamma',tergamma,'EarthModel','Flat' ,...
    'TransmitERP',tpower,'PlatformHeight',height, ...
    'PlatformSpeed',speed,'PlatformDirection',direction, ...
    'MountingAngles',mountingAng,'ClutterMaxRange',Rmax, ...
    'ClutterAzimuthSpan',Azcov,'SeedSource','Property', ...
    'Seed',40547);

Simulate the clutter return for 10 pulses.

Nsamp = fs/prf;
Npulse = 10;
clsig = zeros(Nsamp,Nele,Npulse);
for m = 1:Npulse
    clsig(:,:,m) = clutter();
end

Plot the angle-Doppler response of the clutter at the 20th range bin.

response = phased.AngleDopplerResponse('SensorArray',array, ...
    'OperatingFrequency',fc,'PropagationSpeed',c,'PRF',prf);
plotResponse(response,shiftdim(clsig(20,:,:)),'NormalizeDoppler',true);

The results are not identical to the results obtained by using constantGammaClutter because of differences between CPU and GPU computations.

GPU Clutter Simulation With Known Transmit Signal

Simulate the clutter return from terrain with a gamma value of 0 dB. You input the transmit signal of the radar system when creating clutter. In this case, you do not specify the effective transmitted power of the signal in a property.

Set up the characteristics of the radar system. This system has a 4-element uniform linear array (ULA). The sample rate is 1 MHz, and the PRF is 10 kHz. The propagation speed is the speed of light, and the operating frequency is 300 MHz. The radar platform is flying 1 km above the ground with a path parallel to the ground along the array axis. The platform speed is 2000 m/s. The mainlobe has a depression angle of 30°.

Nele = 4;
c = physconst('LightSpeed');
fc = 300e6;
lambda = c/fc;
ha = phased.ULA('NumElements',Nele,'ElementSpacing',lambda/2);
fs = 1e6;
prf = 10e3;
height = 1000;
direction = [90;0];
speed = 2000;
mountingAng = [0,30,0];

Create the GPU clutter simulation object and configure it to take a transmitted signal as an input argument. The configuration assumes the earth is flat. The maximum clutter range of interest is 5 km, and the maximum azimuth coverage is ±60°.

Rmax = 5000;
Azcov = 120;
tergamma = 0;
clutter = gpuConstantGammaClutter('Sensor',ha,...
    'PropagationSpeed',c,'OperatingFrequency',fc,'PRF',prf,...
    'SampleRate',fs,'Gamma',tergamma,'EarthModel','Flat',...
    'TransmitSignalInputPort',true,'PlatformHeight',height,...
    'PlatformSpeed',speed,'PlatformDirection',direction,...
    'MountingAngles',mountingAng,'ClutterMaxRange',Rmax,...
    'ClutterAzimuthSpan',Azcov,'SeedSource','Property','Seed',40547);

Simulate the clutter return for 10 pulses. At each object call, pass the transmit signal as an input argument. The software automatically computes the effective transmitted power of the signal. The transmit signal is a rectangular waveform with a pulse width of 2 μs.

tpower = 5000;
pw = 2e-6;
X = tpower*ones(floor(pw*fs),1);
Nsamp = fs/prf;
Npulse = 10;
clsig = zeros(Nsamp,Nele,Npulse);
for m = 1:Npulse
    clsig(:,:,m) = clutter(X);
end

Plot the angle-Doppler response of the clutter at the 20th range bin.

response = phased.AngleDopplerResponse('SensorArray',ha,...
    'OperatingFrequency',fc,'PropagationSpeed',c,'PRF',prf);
plotResponse(response,shiftdim(clsig(20,:,:)),...
    'NormalizeDoppler',true);

The results are not identical to the results obtained by using constantGammaClutter because of differences between CPU and GPU computations.

Random Number Comparison Between GPU and CPU

In most cases, it does not matter that the GPU and CPU use different random numbers. Sometimes, you may need to reproduce the same stream on both GPU and CPU. In such cases, you can set up the two global streams so they produce identical random numbers. Both GPU and CPU support the combined multiple recursive generator (mrg32k3a) with the NormalTransform parameter set to 'Inversion'.

Define a seed value to use for both the GPU stream and the CPU stream.

seed = 7151;

Create a CPU random number stream that uses the combined multiple recursive generator and the chosen seed value. Then, use this stream as the global stream for random number generation on the CPU.

stream_cpu = RandStream('CombRecursive','Seed',seed, ...
    'NormalTransform','Inversion');
RandStream.setGlobalStream(stream_cpu);

Create a GPU random number stream that uses the combined multiple recursive generator and the same seed value. Then, use this stream as the global stream for random number generation on the GPU.

stream_gpu = parallel.gpu.RandStream('CombRecursive','Seed',seed, ...
    'NormalTransform','Inversion');
parallel.gpu.RandStream.setGlobalStream(stream_gpu);

Generate clutter on both the CPU and the GPU, using the global stream on each platform.

clutter_cpu = constantGammaClutter('SeedSource','Auto');
clutter_gpu = gpuConstantGammaClutter('SeedSource','Auto');
cl_cpu = clutter_cpu();
cl_gpu = clutter_gpu();

Check that the element-wise differences between the CPU and GPU results are negligible.

maxdiff = max(max(abs(cl_cpu - cl_gpu)))

maxdiff = 3.4027e-18

eps

ans = 2.2204e-16

References

[1] Barton, David. “Land Clutter Models for Radar Design and Analysis,” Proceedings of the IEEE. Vol. 73, Number 2, February, 1985, pp. 198–204.

[2] Long, Maurice W. Radar Reflectivity of Land and Sea, 3rd Ed. Boston: Artech House, 2001.

[3] Nathanson, Fred E., J. Patrick Reilly, and Marvin N. Cohen. Radar Design Principles, 2nd Ed. Mendham, NJ: SciTech Publishing, 1999.

[4] Ward, J. “Space-Time Adaptive Processing for Airborne Radar Data Systems,” Technical Report 1015, MIT Lincoln Laboratory, December, 1994.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The gpuConstantGammaClutter function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2021a