comm.ACPR

Measure adjacent channel power ratio (ACPR)

Description

The comm.ACPR System object™ measures the ACPR of an input signal.

To measure the ACPR of an input signal:

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

acpr = comm.ACPR

acpr = comm.ACPR(Name,Value)

Description

acpr = comm.ACPR creates an ACPR measurement System object.

acpr = comm.ACPR(Name,Value) sets properties using one or more name-value arguments. For example, comm.ACPR('NormalizedFrequency',true) creates an ACPR measurement object with normalized frequency values.

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.

NormalizedFrequency — Normalized frequency values

0 or false (default) | 1 or true

Normalized frequency values, specified as one of these logical values.

• 0 (false) — Frequency values are measured in Hz.

• 1 (true) — Frequency values are normalized in the range [-1, 1].

Data Types: logical | double

SampleRate — Sample rate of input signal

1000000 (default) | positive scalar

Sample rate of input signal in Hz, specified as a positive scalar.

Dependencies

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

Data Types: double

MainChannelFrequency — Main channel center frequency

0 (default) | numeric scalar

Main channel center frequency, specified as a numeric scalar.

• If you set the NormalizedFrequency property to true, specify the center frequency as a normalized value in the range [−1, 1].

• If you set the NormalizedFrequency property to false, specify the center frequency in Hz.

This property specifies where the object measures the main channel power in the bandwidth specified by the MainMeasurementBandwidth property. For more details on how to set these two properties, see Algorithms.

Data Types: double

MainMeasurementBandwidth — Main channel measurement bandwidth

50000 (default) | positive scalar

Main channel measurement bandwidth, specified as a positive scalar.

• If you set the NormalizedFrequency property to true, specify the measurement bandwidth as a normalized value in the range [0, 1].

• If you set the NormalizedFrequency property to false, specify the measurement bandwidth in Hz.

This property specifies the bandwidth in which the object measures the main channel power. The measurement is taken at the center of the frequency, specified by the MainChannelFrequency property. For more details on how to set these two properties, see Algorithms.

Data Types: double

AdjacentChannelOffset — Adjacent channel frequency offsets

[-100000 100000] (default) | numeric scalar | numeric row vector

Adjacent channel frequency offsets, specified as a numeric scalar or row vector comprising frequencies that define the location of adjacent channels of interest.

• If you set the NormalizedFrequency property to true, specify the adjacent channel frequency offsets as normalized values in the range [−1, 1].

• If you set the NormalizedFrequency property to false, specify the adjacent channel frequency offsets in Hz.

The offset values indicate the distance between the main channel center frequency and adjacent channel center frequencies. Positive offsets indicate adjacent channels to the right of the main channel center frequency. Negative offsets indicate adjacent channels to the left of the main channel center frequency. For more details on how to set properties of the adjacent channels, see Algorithms.

Data Types: double

AdjacentMeasurementBandwidth — Measurement bandwidth for each adjacent channel

50000 (default) | numeric scalar or row vector

Measurement bandwidth for each adjacent channel, specified as one of these options.

• Numeric scalar — The object obtains all adjacent channel power measurements within equal measurement bandwidths.

• Numeric row vector of length equal to the number of offsets specified in the AdjacentChannelOffset property — The object obtains each adjacent channel power measurement based on its specific bandwidth that is centered at the frequency defined by the corresponding frequency offset. The AdjacentChannelOffset property defines this frequency offset.

Set the values of this property with respect to the NormalizedFrequency property.

• If you set the NormalizedFrequency property to true, specify the measurement bandwidth values as normalized values in the range [0, 1].

• If you set the NormalizedFrequency property to false, specify the measurement bandwidth values in Hz.

For more details on how to set properties of the adjacent channels, see Algorithms.

Data Types: double

MeasurementFilterSource — Source of measurement filter

'None' (default) | 'Property'

Source of the measurement filter, specified as one of these values.

• 'None' — The object does not apply filtering to obtain ACPR measurements.

• 'Property' — The object applies a measurement filter to the main channel before measuring the average power. Specify the measurement filter coefficients by using the MeasurementFilter property. Each of the adjacent channel bands also receives a measurement filter.

Data Types: char | string

MeasurementFilter — Measurement filter coefficients

1 (default) | numeric row vector

Measurement filter coefficients, specified as a numeric row vector containing the coefficients of an FIR filter in descending polynomial powers. Center the response of the filter at DC. The object automatically shifts and applies the filter response at each of the main and adjacent channel center frequencies before obtaining the average power measurements. The internal filter states persist between calls to the object. To clear the states, call the reset object function.

The default value specifies an all-pass filter that has no effect on the measurements.

Dependencies

To enable this property, set the MeasurementFilterSource property to 'Property'.

Data Types: double

SpectralEstimation — Spectral estimation control

'Auto' (default) | 'Specify frequency resolution' | 'Specify window parameters'

Spectral estimation control, specified as one of these values.

• 'Auto' — The object obtains power measurements with a Welch spectral estimator with zero-percent overlap, a Hamming window, and a segment length equal to the length of the input data vector. The spectral estimator set can achieve the maximum frequency resolution that is attainable with the input data length.

• 'Specify frequency resolution' — The object uses the value specified by the FrequencyResolution property to automatically compute the size of the spectral estimator data window.

• 'Specify window parameters' — The object obtains power measurements with a Welch spectral estimator determined by the SegmentLength, OverlapPercentage, Window, and SidelobeAttenuation properties. In this setting, the FrequencyResolution property does not apply, but you can use these properties to control also the resolution.

Data Types: char | string

SegmentLength — Segment length for spectral estimator

64 (default) | positive integer

Segment length for the spectral estimator in samples, specified as a positive integer. The segment length enables you to make tradeoffs between frequency resolution and variance in the spectral estimates. A long segment length results in better resolution. A short segment length results in more averaging and a decrease in variance.

Dependencies

To enable this property, set the SpectralEstimation property to 'Specify window parameters'.

Data Types: double

OverlapPercentage — Overlap percentage between segments

0 (default) | numeric scalar in the range [0, 100]

Overlap percentage between segments in the spectral estimator, specified as a numeric scalar in the range [0, 100].

Dependencies

To enable this property, set the SpectralEstimation property to 'Specify window parameters'.

Data Types: double

Window — Window function for spectral estimator

'Hamming' (default) | 'Bartlett' | 'Bartlett-Hanning' | 'Blackman' | 'Blackman-Harris' | 'Bohman' | 'Chebyshev' | 'Flat Top' | 'Hann' | 'Nuttall' | 'Parzen' | 'Rectangular' | 'Triangular'

Window function for the spectral estimator, specified as 'Hamming', 'Bartlett', 'Bartlett-Hanning', 'Blackman', 'Blackman-Harris', 'Bohman', 'Chebyshev', 'Flat Top', 'Hann', 'Nuttall', 'Parzen', 'Rectangular', or 'Triangular'.

The default Hamming window has a sidelobe attenuation of 42.5 dB. This attenuation can mask spectral content below this value, relative to the peak spectral content. Choosing different windows enables you to make tradeoffs between resolution and sidelobe attenuation.

Dependencies

To enable this property, set the SpectralEstimation property to 'Specify window parameters'.

Data Types: char | string

SidelobeAttenuation — Sidelobe attenuation for Chebyshev window

100 (default) | nonnegative scalar

Sidelobe attenuation for the Chebyshev window function in dB, specified as a nonnegative scalar.

Dependencies

To enable this property, set the SpectralEstimation property to 'Specify window parameters' and the Window property to 'Chebyshev'.

Data Types: double

FrequencyResolution — Frequency resolution of spectral estimator

10625 (default) | numeric scalar

Frequency resolution of the spectral estimator, specified as a numeric scalar.

• If you set the NormalizedFrequency property to true, specify the frequency resolution as a normalized value in the range [0, 1].

• If you set the NormalizedFrequency property to false, specify the frequency resolution in Hz.

Dependencies

To enable this property, set the SpectralEstimation property to 'Specify frequency resolution'.

Data Types: double

FFTLength — Number of FFT points

'Next power of 2' (default) | 'Same as segment length' | 'Custom'

Number of fast Fourier transform (FFT) points that the spectral estimator uses, specified as one of these values.

• 'Next power of 2' — The object sets the number of FFT points to the next power of 2 that is greater than max(SegmentLength,256).

• 'Same as segment length' — The object sets the number of FFT points to the value of the SegmentLength property.

• 'Custom' — The object sets the number of FFT points to the value of the CustomFFTLength property.

Data Types: char | string

CustomFFTLength — Custom number of FFT points

256 (default) | positive integer

Custom number of FFT points, specified as a positive integer.

Dependencies

To enable this property, set the FFTLength property to 'Custom'.

Data Types: double

MaxHold — Maximum-hold setting control

0 or false (default) | 1 or true

Maximum-hold setting control, specified as one of these logical values.

• 0 (false) — The object obtains power measurements by using instantaneous power spectral density estimates.

• 1 (true) — The object obtains power measurements by comparing two vectors. One vector is the current estimated power spectral density vector (obtained with the current input data frame). The object checks this vector against the previous maximum-hold accumulated power spectral density vector (obtained at the previous call of the object). The object stores the maximum values at each frequency bin and uses these values to compute average power measurements. To clear the maximum-hold spectrum, use the reset object function.

Tunable: Yes

Data Types: logical | double

PowerUnits — Power measurement units

'dBm' (default) | 'dBW' | 'Watts'

Power measurement units, specified as one of these values.

• 'dBm' or 'dBW' — The object returns ACPR measurements in a dBc scale (the adjacent channel power referenced to the main channel power).

• 'Watts' — The object returns ACPR measurements in a linear scale.

Data Types: char | string

MainChannelPowerOutputPort — Option to enable main channel power measurement output

0 or false (default) | 1 or true

Option to enable main channel power measurement output, specified as a logical 0 (false) or 1 (true). When you set this property to true, the object returns the main channel power measurement. The main channel power is the power of the input signal measured in the band specified by the MainChannelFrequency and MainMeasurementBandwidth properties. The object returns the power measurements in the unit specified by the PowerUnits property.

Data Types: logical | double

AdjacentChannelPowerOutputPort — Option to enable adjacent channel power measurements output

0 or false (default) | 1 or true

Option to enable adjacent channel power measurements output, specified as a logical 0 (false) or 1 (true). When you set this property to true, the object returns a vector containing adjacent channel power measurements. The adjacent channel powers correspond to the power of the input measured in the bands specified by the AdjacentChannelOffset and AdjacentMeasurementBandwidth properties. The object returns the power measurements in the unit specified by the PowerUnits property.

Data Types: logical | double

Usage

Syntax

adjChPowRatio = acpr(signal)

[adjChPowRatio,mainChPow] = acpr(signal)

[adjChPowRatio,adjChPow] = acpr(signal)

[adjChPowRatio,mainChPow,adjChPow] = acpr(signal)

Description

adjChPowRatio = acpr(signal) measures the ACPR in input data signal. The measurements are at the frequency bands specified by the MainChannelFrequency, MainMeasurementBandwidth, AdjacentChannelOffset, and AdjacentMeasurementBandwidth properties.

[adjChPowRatio,mainChPow] = acpr(signal) measures the main channel power, mainChPow. To use this syntax, set the MainChannelPowerOutputPort property to true. The main channel power is measured within the main channel frequency band specified by the MainChannelFrequency and MainMeasurementBandwidth properties.

[adjChPowRatio,adjChPow] = acpr(signal) measures the adjacent channel powers, adjChPow. To use this syntax, set the AdjacentChannelPowerOutputPort property to true. The adjacent channel powers are measured at the adjacent frequency bands specified by the AdjacentChannelOffset and AdjacentMeasurementBandwidth properties.

[adjChPowRatio,mainChPow,adjChPow] = acpr(signal) measures the ACPR, the main channel power, and adjacent channel powers. To use this syntax, set the MainChannelPowerOutputPort and AdjacentChannelPowerOutputPort properties to true.

Input Arguments

signal — Input signal

column vector of complex numbers

Input signal, specified as a column vector of complex numbers.

Data Types: double | single
Complex Number Support: Yes

Output Arguments

adjChPowRatio — ACPR measurements

numeric row vector

ACPR measurements, returned as a numeric row vector. The length of the vector equals the number of adjacent channels specified by the AdjacentChannelOffset property. The output has same data type as input signal.

Data Types: double | single

mainChPow — Main channel power measurements

numeric scalar

Main channel power measurements, returned as a numeric scalar. The PowerUnits property specifies the units used for the returned value.

Data Types: double | single

adjChPow — Adjacent channel power measurements

numeric row vector

Adjacent channel power measurements, returned as a numeric row vector. The length of the vector equals the number of adjacent channels specified by the AdjacentChannelOffset property. The PowerUnits property specifies the units used for the returned value.

Data Types: double | single

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

Measure ACPR of 16-QAM Signal

Generate data with an alphabet size of 16, and then modulate the data.

x = randi([0 15],5000,1);
y = qammod(x,16);

Upsample the data by using a rectangular pulse shape.

L = 8;
yPulse = rectpulse(y,L);

Create an ACPR measurement object.

acpr = comm.ACPR(...
    'SampleRate',3.84e6*8, ...
    'MainChannelFrequency',0, ...
    'MainMeasurementBandwidth',3.84e6, ...
    'AdjacentChannelOffset',[-5e6 5e6], ...
    'AdjacentMeasurementBandwidth',3.84e6, ...
    'MainChannelPowerOutputPort',true, ...
    'AdjacentChannelPowerOutputPort',true);

Measure the ACPR, main channel power, and adjacent channel powers of the modulated signal.

[adjChPowRatio,mainChPow,adjChPow] = acpr(yPulse)

adjChPowRatio = 1×2

  -14.3659  -14.3681

mainChPow = 
38.8668

adjChPow = 1×2

   24.5010   24.4988

Algorithms

To comply with the Nyquist sampling theorem, these conditions must be satisfied when you set the frequencies and measurement bandwidths of the main and adjacent channels.

$$\begin{array}{l}\left|\text{MainChannelFrequency}\pm \text{}\frac{\text{MainMeasurementBandwidth}}{2}\right|<F_{\max }\\ \left|(\text{MainChannelFrequency}+\text{}\text{AdjacentChannelOffset})\pm \frac{\text{AdjacentMeasurementBandwidth}}{2}\right|<F_{\max }\end{array}$$

If you set the NormalizedFrequency property to false, $$F_{\max }=F_s/2$$, where $$F_s$$ is the sampling frequency specified by the SampleRate property.

If you set the NormalizedFrequency property to true, $$F_{\max }=1$$.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Supports MEX code generation. Does not support code generation for standalone applications.

• See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2012a

R2024a: Add single data type support

The comm.ACPR System object adds support for input of single-precision data signals. For a single-precision input signal, the object natively computes in single precision and returns the output as data type single.

Before R2024a, would error for single-precision input data.