# powermeter

Measure power and CCDF of the power of voltage signal

## Description

The powermeter System object™ computes the power measurements of a voltage signal. When you set the ComputeCCDF property to true, the object also calculates the complementary cumulative distribution function (CCDF) of the power of a voltage signal. The CCDF measurements that the object outputs are relative power and probability (in percentage). The power measurements include average power, peak power, and peak-to-average power ratio.

For more details on how the object computes the power measurements and the CCDF measurements, see Algorithms.

To measure the power and the CCDF of the power of a voltage signal:

1. Create the powermeter object and set its properties.

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

## Creation

### Description

example

meter = powermeter returns a powermeter system object that computes power, peak-to-average power ratio (PAPR), and the complementary cumulative distribution function (CCDF) of the power of voltage signal. The CCDF helps find the probability that the instantaneous signal power exceeds a specified level above the average signal power.

meter = powermeter(Len,Overlap,Name=Value) sets the WindowLength property to Len and the OverlapLength property to Overlap.

To enable this syntax, set the ComputeCCDF property to false.

example

meter = powermeter(Name=Value) returns a powermeter system object with each specified property set to the specified value. Enclose each property name in quotes. You can use this syntax with the previous input argument.

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

Desired power measurement, specified as 'Average power', 'Peak power', 'Peak-to-average power ratio' or 'All'.

For more details on how the object computes these measurements, see Algorithms.

Reference load used by the power meter to compute the power values in ohms, specified as a positive scalar.

Tunable: Yes

Data Types: single | double

Specify whether to calculate CCDF as:

• false –– The object does not calculate the CCDF measurements. The object computes the power measurements using the Sliding Window Method.

• true –– The object computes the CCDF measurements.

• All input samples since object creation or reset are used to compute statistics. The power measurements are stationary.

• The WindowLength and OverlapLength properties become read-only and are set to Inf and 0 respectively.

Data Types: logical

The x-axis range of the computed CCDF curves in dB, specified as a positive scalar. The computed CCDF curves end at the maximum relative power, namely, peak-to-average power ratio (PAPR) of the signal, and start at PAPR - PowerRange. For the CCDF capability of the powermeter object, relative power is the power in dB by which the instantaneous signal power is above the average signal power.

#### Dependencies

To enable this property, set the ComputeCCDF property to true.

Data Types: single | double

The x-axis resolution of the computed CCDF curves in dB, specified as a positive scalar.

#### Dependencies

To enable this property, set the ComputeCCDF property to true.

Data Types: single | double

Sliding window length over which the measurement is computed, specified as a nonnegative integer.

#### Dependencies

If the ComputeCCDF property is true, then WindowLength property is set to Inf and is read-only.

Data Types: single | double

Overlap length between sliding windows, specified as a nonnegative integer. The value of overlap length varies in the range [0, WindowLength − 1]. If not specified, the overlap length is WindowLength − 1.

#### Dependencies

If the ComputeCCDF property is true, then OverlapLength property is set to 0 and is read-only.

Data Types: single | double

Units of the measured power values, specified as 'dBm', 'dBW', or 'Watts'.

## Usage

### Description

example

avgpwr = meter(x) computes the average power of the input signal x when the Measurement property is set to 'Average power'. Each column of x is treated as an independent channel. The object computes the average power of each channel of the input signal independently.

peakpwr = meter(x) computes the peak power of the input signal x when the Measurement property is set to 'Peak power'. Each column of x is treated as an independent channel. The object computes the peak power of each channel of the input signal independently.

papr = meter(x) computes the peak-to-average power ratio of the input signal x when the Measurement property is set to 'Peak-to-average power ratio'. Each column of x is treated as an independent channel. The object computes the peak-to-average power ratio of each channel of the input signal independently.

example

[avgpwr,peakpwr,papr] = meter(x) computes the average power, peak power, and the peak-to-average power ratio of the input signal x when the Measurement property is set to 'All'. Each column of x is treated as an independent channel. The object computes the power measurements of each channel of the input signal independently.

### Input Arguments

expand all

Input voltage signal, specified as a vector or a matrix in volts. If x is a matrix, the object treats each column as an independent channel and computes the power measurements along each channel.

The object also accepts variable-size inputs. That is, once the object is locked, you can change the size of each input channel, but you cannot change the number of channels.

Data Types: single | double
Complex Number Support: Yes

### Output Arguments

expand all

Average power of the voltage signal, returned as a scalar, vector or a matrix, with the units determined by the PowerUnits property.

If you set the ComputeCCDF property to false, the object computes the moving average power using the Sliding Window Method.

When you input a signal of size m-by-n to the object when the ComputeCCDF property is set to false, the output has an upper bound size of ceil(m/hop size)-by-n. Hop size is window length − overlap length. In other cases, the output has a size of m-by-n.

When you generate code from this object, the variable-size behavior of the output in the generated code depends on the input frame length and whether the size of the input signal is fixed or variable. For more details, see Code Generation.

If you set the ComputeCCDF property to true, the object computes the stationary average power of the entire signal along each channel. In this case, the size of the output is 1-by-M, where M is the number of channels in the input signal.

For details on how the object computes the average power, see Average Power.

Data Types: single | double

Peak power of the voltage signal, returned as a scalar, vector or a matrix, with the units determined by the PowerUnits property.

If you set the ComputeCCDF property to false, the object computes the moving peak power using the Sliding Window Method.

When you input a signal of size m-by-n to the object when the ComputeCCDF property is set to false, the output has an upper bound size of ceil(m/hop size)-by-n. Hop size is window length − overlap length. In other cases, the output has a size of m-by-n.

When you generate code from this object, the variable-size behavior of the output in the generated code depends on the input frame length and whether the size of the input signal is fixed or variable. For more details, see Code Generation.

If you set the ComputeCCDF property to true, the object computes the stationary peak power of the entire signal along each channel. In this case, the size of the output is 1-by-M, where M is the number of channels in the input signal.

For details on how the object computes the peak power, see Peak Power.

Data Types: single | double

Peak-to-average power ratio of the voltage signal, returned as a scalar, vector or a matrix.

If you set the ComputeCCDF property to false, the object computes the moving peak-to-average power ratio using the Sliding Window Method.

When you input a signal of size m-by-n to the object when the ComputeCCDF property is set to false, the output has an upper bound size of ceil(m/hop size)-by-n. Hop size is window length − overlap length. In other cases, the output has a size of m-by-n.

When you generate code from this object, the variable-size behavior of the output in the generated code depends on the input frame length and whether the size of the input signal is fixed or variable. For more details, see Code Generation.

If you set the ComputeCCDF property to true, the object computes the stationary peak-to-average power ratio of the entire signal along each channel. In this case, the size of the output is 1-by-M, where M is the number of channels in the input signal.

For details on how the object computes the peak-to-average power ratio, see Peak-to-Average Power Ratio.

Data Types: single | 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

 plotCCDF Plot CCDF curves ccdf Get coordinates of CCDF curves relativePower Use CCDF to find relative power for specified probability probability Use CCDF to find probability for specified relative power
 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

Compute the power measurements of a noisy sinusoidal signal using a power meter. These measurements include average power, peak power, and peak-to-average power ratio.

Assume the maximum voltage of the signal to be 100 V. The instantaneous values of a sinusoidal waveform are given by the equation $\mathrm{Vi}=\mathrm{Vmax}×\mathrm{sin}\left(2\pi \mathrm{ft}\right)$, where$Vi$ is the instantaneous value, $Vmax$ is the maximum voltage of the signal, and $\mathit{f}$ is the frequency of the signal in Hz.

Initialization

The input signal is a sum of two sine waves with frequencies set to 1 kHz and 10 kHz, respectively. The frame length and the sampling frequency of the generated signal is 512 samples and 44.1 kHz, respectively.

To measure the power in this signal, create a powermeter object. Set Measurement to 'All'. This setting enables the object to measure the average power, peak power, and peak-to-average power ratio. Set the length of the sliding window to 16 samples and the reference load to 50 Ohms. Use this object to measure the power in dBm units. Visualize the power measurements using the timescope object.

FrameLength = 512;
Fs = 44.1e3;
A = 100;
sine1 = dsp.SineWave(Amplitude=A, ...
Frequency=1e3, ...
SampleRate=44.1e3, ...
SamplesPerFrame=FrameLength);
sine2 = dsp.SineWave(Amplitude=A, ...
Frequency=10e3, ...
SampleRate=44.1e3, ...
SamplesPerFrame=FrameLength);
pm  = powermeter(16,Measurement="All", ...
PowerUnits="dBm");
scope  = timescope(NumInputPorts=4,SampleRate=Fs, ...
TimeSpanSource="property", ...
TimeSpan=96, ...
YLabel="dBm", ...
YLimits=[-30 90]);
title = 'Power Measurements';
scope.ChannelNames = {'Average power', ...
'Peak power','Peak-to-average power ratio', ...
'Expected Average Power'};
scope.Title = title;

Compute the Power Measurements

Add zero-mean white Gaussian noise with a standard deviation of 0.001 to the sum of sine waves. Vary the amplitude of the sine waves. Measure the average power, peak power, and the peak-to-average power ratio of this noisy sinusoidal signal that has a varying amplitude. For details on how the object measures these power values, see Algorithms. Compare the measured values to the expected value of the average power.

The expected value of the average power $\mathit{P}$ of the noisy sinusoidal signal is given by the following equation.

$\mathit{P}=\frac{{\mathit{A}}_{1}^{2}}{2\mathit{R}}+\frac{{\mathit{A}}_{2}^{2}}{2\mathit{R}}+\mathrm{var}\left(\mathrm{noise}\right),$

where,

• ${\mathit{A}}_{1}$ is the amplitude of the first sinusoidal signal.

• ${\mathit{A}}_{2}$ is the amplitude of the second sinusoidal signal.

• $\mathit{R}$ is the reference load in ohms.

In dBm, the expected power is computed using the following equation:

${\mathrm{expPwr}}_{\mathrm{dBm}}=10{\mathrm{log}}_{10}\left(\mathit{P}\right)+30.$

Compare the expected value with the value computed by the object. All values are in dBm. These values match very closely. To verify, view the computed measurements using the timescope object.

Vect = [1/8 1/2 1 2 1 1/2 1/8 1/16 1/32];
for index = 1:length(Vect)
V = Vect(index);
for i = 1:1000
x = V*sine1()+V*sine2()+0.001.*randn(FrameLength,1);
P = (((V*A)^2)/100)+(((V*A)^2)/100)+(0.001)^2;
expPwr = (10*log10(P)+30)*ones(FrameLength,1);
[avgPwr,pkPwr,papr] = pm(x);
scope(avgPwr,pkPwr,papr,expPwr);
end
end

Compute the CCDF measurements of a voltage signal. The CCDF measurements include the relative power and the probability. Relative power is the amount of power in dB by which the instantaneous signal power is above the average signal power. Probability in percentage refers to the probability that the instantaneous signal power is above the average signal power by the relative power in dB.

Initialize a powermeter object and set the ComputeCCDF property to true. The input to the object is a random voltage signal.

x = complex(rand(10000,1)-0.5,rand(10000,1)-0.5);
pm = powermeter(ComputeCCDF=true)
pm =
powermeter with properties:

Measurement: 'Average power'
ComputeCCDF: true
PowerRange: 50
PowerResolution: 0.1000
OutputPowerUnits: 'dBm'

WindowLength: Inf
OverlapLength: 0

By default, the powermeter object computes the average power of the signal in dBm. The reference load is 1 ohm.

averagePower = pm(x)
averagePower = 22.2189

Using the probability function, find the probability that the instantaneous power of the signal is 3 dB above the average power. The relative power in this case is 3 dB.

prob = probability(pm,3)
prob = 7.6009

Compute the relative power using the relativePower function. Verify that the relative power for the computed probability is indeed 3 dB.

relpwr = relativePower(pm,prob)
relpwr = 3.0000

Using the plotCCDF function, plot the CCDF curve. Set the reference curve to Gaussian.

plotCCDF(pm,GaussianReference=true)

expand all

## Version History

Introduced in R2021a

expand all