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

## Creation

### Syntax

``acpr = comm.ACPR``
``acpr = comm.ACPR(Name,Value)``

### Description

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

example

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

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.

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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

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`

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`

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`

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

#### Dependencies

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

Data Types: `double`

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`

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`

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`

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

expand all

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

Data Types: `double`
Complex Number Support: Yes

### Output Arguments

expand all

ACPR measurements, returned as a numeric row vector. The length of the vector equals the number of adjacent channels specified by the `AdjacentChannelOffset` property.

Data Types: `double`

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

Data Types: `double`

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`

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

 `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

collapse all

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}|\text{MainChannelFrequency}±\text{​}\text{\hspace{0.17em}}\frac{\text{MainMeasurementBandwidth}}{2}|<{F}_{\mathrm{max}}\\ |\left(\text{MainChannelFrequency}+\text{​}\text{\hspace{0.17em}}\text{AdjacentChannelOffset}\right)±\frac{\text{AdjacentMeasurementBandwidth}}{2}|<{F}_{\mathrm{max}}\end{array}$`

If you set the `NormalizedFrequency` property to `false`, ${F}_{\mathrm{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}_{\mathrm{max}}=1$.

## Version History

Introduced in R2012a