dsp.RMS

(To be removed) Root mean square of vector elements

Description

The dsp.RMS object computes the root mean square (RMS) value.

Note

The dsp.RMS System object™ will be removed in a future release. To compute the RMS, use the rms function. To compute the running RMS in MATLAB^®, use the dsp.MovingRMS object. For more information, see Compatibility Considerations.

To compute the RMS value of your input:

Create the dsp.RMS object and set its properties.
Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects? (MATLAB).

Creation

Syntax

rms = dsp.RMS

rms = dsp.RMS(Name,Value)

Description

rms = dsp.RMS returns a System object, rms, that computes the root mean square (RMS) of an input or a sequence of inputs over the specified Dimension.

rms = dsp.RMS(Name,Value) returns an RMS System object, rms, with each specified property set to the specified value.

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 (MATLAB).

`RunningRMS` — Enable calculating RMS over time
`false` (default) | `true`

Set this property to true to enable calculating the RMS over successive calls to the object algorithm.

`ResetInputPort` — Enable resetting in running RMS mode
`false` (default) | `true`

Set this property to true to enable resetting the running RMS. When the property is set to true, you must specify a reset input to the object algorithm to reset the running RMS.

Dependencies

This property applies when you set the RunningRMS property to true.

`ResetCondition` — Reset condition for running RMS mode
`Non-zero` (default) | `Rising edge` | `Falling edge` | `Either edge`

Specify the event to reset the running RMS as one of Rising edge, Falling edge, Either edge, or Non-zero. Non-zero resets the running RMS each time a nonzero sample is acquired. See Rising and Falling Edges for definitions of rising and falling edges.

Dependencies

This property applies when you set the ResetInputPort property to true.

`Dimension` — Dimension to compute RMS value along
`Column` (default) | `All` | `Row` | `Custom`

Specify the dimension along which to calculate the RMS as one of All, Row, Column, or Custom. Specifying the Dimension property as All computes the RMS value over the entire input.

Dependencies

This property applies only when you set the RunningRMS property to false.

`CustomDimension` — Numerical dimension to operate along
`1` (default) | positive integer

Specify the dimension (one-based scalar integer value) of the input signal, along which the RMS is computed. The dimension cannot exceed the number of dimensions in the input signal.

Dependencies

This property applies when you set the Dimension property to Custom.

Usage

Syntax

y = rms(x)

y = rms(x,r)

Description

y = rms(x) computes the root mean square (RMS) output, y, of input vector x. When the RunningRMS property is true, y corresponds to the RMS of the input elements over successive calls to the object algorithm.

y = rms(x,r) resets the running RMS state based on the value of r, the reset signal, and the ResetCondition property. This computation is possible when you set both the RunningRMS and the ResetInputPort properties to true.

Input Arguments

expand all

`x` — Data input
vector | matrix

Data input, specified as a vector or a matrix. If x is a matrix, each column is treated as an independent channel. The RMS is computed along each channel. The object also accepts variable-size inputs. Once the object is locked, you can change the size of each input channel.

Data Types: single | double
Complex Number Support: Yes

`r` — Reset signal
scalar

Reset signal used to reset the running RMS, specified as a scalar value. The object resets the running RMS if the reset signal satisfies the ResetCondition.

Dependencies

To enable this signal, set the RunningRMS property to true and the ResetInputPort property to true.

Output Arguments

expand all

`y` — RMS output
scalar | vector | matrix

RMS output, returned as a scalar, vector or a matrix. If RunningRMS is set to:

false –– The object computes the RMS value of each input channel. If the input is a column vector, the output is a scalar. If the input is a multichannel signal, the output signal is a 1-by-N vector, where N is the number of input channels.
true –– The object computes the running RMS of the signal. The size of the output signal matches the size of the input signal.

Data Types: single | double
Complex Number Support: Yes

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

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

RMS Value of Matrix Input

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, obj(x) becomes step(obj,x).

Compute the RMS value of a matrix with the Dimension property set to 'All'.

in2 = magic(4);
rms2d = dsp.RMS;
rms2d.Dimension = 'All';
y_rms2 = rms2d(in2)

y_rms2 = 9.6695

The output is equivalent to reshaping the 4-by-4 matrix into a 16-by-1 or 1-by-16 vector and computing the RMS value for the vector.

More About

expand all

Root Mean Square Level

The root-mean-square level of a vector, X, is

$x_{RMS} = \sqrt{\frac{1}{N} \sum_{n = 1}^{N} {| x_{n} |}^{2}},$

with the summation performed along the specified dimension.

Rising and Falling Edges

A rising edge:

Rises from a negative value to a positive value or zero.
Rises from zero to a positive value, where the rise is not a continuation of a rise from a negative value to zero.

A falling edge:

Falls from a positive value to a negative value or zero.
Falls from zero to a negative value, where the fall is not a continuation of a fall from a positive value to zero.

Algorithms

This object implements the algorithm, inputs, and outputs described on the RMS block reference page. The object properties correspond to the Simulink^® block parameters, except:

The Treat sample-based row input as a column block parameter is not supported by the dsp.RMS object.
The Reset Port block parameter corresponds to both the ResetCondition and the ResetInputPort object properties.

Compatibility Considerations

expand all

`dsp.RMS` System object will be removed

Warns starting in R2019b

The dsp.RMS System object will be removed in a future release. To compute the RMS, use the rms function. To compute the running RMS, use the dsp.MovingRMS object.

Update Code

This table shows typical usage of the System object and explains how to update existing code to use the equivalent function.

Discouraged Usage Recommended Replacement

Discouraged Usage	Recommended Replacement
RMS rm = dsp.RMS; x = randn(100,1); y = rm(x); Running RMS rm = dsp.RMS; rm.RunningRMS = true; x = randn(100,1); % Running RMS y = rm(x); If you are using a release prior to R2016b, replace `rm(x)` with `step(rm,x)`.	RMS x = randn(100,1); y = rms(x); Running RMS mvgRMS = dsp.MovingRMS; mvgRMS.SpecifyWindowLength = false; x = randn(100,1); y = mvgRMS(x);

RMS

rm = dsp.RMS;
x = randn(100,1);
y = rm(x);

Running RMS

rm = dsp.RMS;
rm.RunningRMS = true;
x = randn(100,1);
% Running RMS
y = rm(x);

If you are using a release prior to R2016b, replace rm(x) with step(rm,x).

RMS

x = randn(100,1);
y = rms(x);

Running RMS

mvgRMS = dsp.MovingRMS;
mvgRMS.SpecifyWindowLength = false;
x = randn(100,1);
y = mvgRMS(x);

Extended Capabilities

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

Usage notes and limitations:

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

Documentation

dsp.RMS

Description

Note

Creation

Syntax

Description

Properties

RunningRMS — Enable calculating RMS over time false (default) | true

ResetInputPort — Enable resetting in running RMS mode false (default) | true

Dependencies

ResetCondition — Reset condition for running RMS mode Non-zero (default) | Rising edge | Falling edge | Either edge

Dependencies

Dimension — Dimension to compute RMS value along Column (default) | All | Row | Custom

Dependencies

CustomDimension — Numerical dimension to operate along 1 (default) | positive integer

Dependencies

Usage

Syntax

Description

Input Arguments

x — Data input vector | matrix

r — Reset signal scalar

Dependencies

Output Arguments

y — RMS output scalar | vector | matrix

Object Functions

Common to All System Objects

Examples

RMS Value of Matrix Input

More About

Root Mean Square Level

Rising and Falling Edges

Algorithms

Compatibility Considerations

dsp.RMS System object will be removed

Extended Capabilities

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

See Also

Functions

Objects

Blocks

Introduced in R2012a

DSP System Toolbox Documentation

Support

`RunningRMS` — Enable calculating RMS over time
`false` (default) | `true`

`ResetInputPort` — Enable resetting in running RMS mode
`false` (default) | `true`

`ResetCondition` — Reset condition for running RMS mode
`Non-zero` (default) | `Rising edge` | `Falling edge` | `Either edge`

`Dimension` — Dimension to compute RMS value along
`Column` (default) | `All` | `Row` | `Custom`

`CustomDimension` — Numerical dimension to operate along
`1` (default) | positive integer

`x` — Data input
vector | matrix

`r` — Reset signal
scalar

`y` — RMS output
scalar | vector | matrix

`dsp.RMS` System object will be removed

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