scale

Scale second-order sections

Syntax

scale(sysobj)

sysobjnew = scale(sysobj)

scale(sysobj,pnorm)

scale(sysobj,pnorm,opts)

scale(sysobj,pnorm,Name,Value)

Description

scale(sysobj) scales the biquadratic System object™, sysobj, using peak magnitude response scaling (L-infinity, 'Linf'). This scaling reduces the possibility of overflows when the filter object operates in fixed-point arithmetic mode.

sysobjnew = scale(sysobj) generates a new filter System object, sysobjnew, with scaled second-order sections. The original filter System object, sysobj, is not changed.

scale(sysobj,pnorm) specifies the norm used to scale the filter. The variable pnorm can be either a discrete-time-domain norm or a frequency-domain norm. Valid time-domain norms are 'l1', 'l2', and 'linf'. Valid frequency-domain norms are 'L1', 'L2', and 'Linf'. Note that L2-norm is equal to l2-norm (Parseval's theorem) but the same is not true for other norms.

The different norms can be ordered in terms of how stringent they are as follows: 'l1' >= 'Linf' >= 'L2' = 'l2' >= 'L1' >= 'linf'.

Using the most stringent scaling, 'l1', the filter is the least prone to overflow, but also has the worst signal-to-noise ratio. Linf-scaling is the most commonly used scaling in practice.

scale(sysobj,pnorm,opts) uses an options object to specify the optional scaling parameters in lieu of specifying parameter-value pairs. The opts object can be created using the scaleopts function: opts = scaleopts(sysobj).

scale(sysobj,pnorm,Name,Value) specifies optional scaling parameters via by one or more Name,Value pair arguments.

Examples

Linf-norm Scaling of a Biquadratic SOS Filter

Demonstrate the Linf-norm scaling of a biquadratic SOS filter using the scale function.

Fs = 8000; 
Fcutoff = 2000;
[z,p,k] = butter(10,Fcutoff/(Fs/2)); 
[sosMatrix,scaleValues] = zp2sos(z,p,k);
sosFilt = dsp.SOSFilter(Structure='Direct form I', ...
    Numerator=sosMatrix(:,1:3),Denominator=sosMatrix(:,4:6), ...
    HasScaleValues=true,ScaleValues=scaleValues)

sosFilt = 
  dsp.SOSFilter with properties:

            Structure: 'Direct form I'
    CoefficientSource: 'Property'
            Numerator: [5x3 double]
          Denominator: [5x3 double]
       HasScaleValues: true
          ScaleValues: [0.0029 1 1 1 1 1]

  Show all properties

scale(sosFilt,'linf',scalevalueconstraint='none',maxscalevalue=2)

Input Arguments

sysobj — Input filter

dsp.BiquadFilter System object | dsp.SOSFilter System object

Input filter, specified as one of the following System objects:

• dsp.BiquadFilter

• dsp.SOSFilter

Example: biquad = dsp.BiquadFilter('Structure', 'Direct form I', ...'SOSMatrix', s,'ScaleValues', g);

pnorm — Discrete-time-domain norm or a frequency-domain norm

'Linf' (default) | 'L1' | 'L2' | 'l1' | 'l2' | 'linf'

Valid time-domain norm values for pnorm are 'l1', 'l2', and 'linf'. Valid frequency-domain norm values are 'L1', 'L2', and 'Linf' . The 'L2' norm is equal to the 'l2' norm (by Parseval's theorem), but this equivalency does not hold for other norms — 'l1' is not the same as 'L1' and 'Linf' is not the same as 'linf'.

Filter norms can be ordered in terms of how stringent they are, as follows from most stringent to least: 'l1', 'Linf', 'l2' ('L2'), 'linf'. Using 'l1', the most stringent scaling, produces a filter that is least likely to overflow, but has the worst signal-to-noise ratio performance. The default scaling 'Linf' (default) is the most commonly used scaling norm.

opts — Scale options object

fdopts.sosscaling object

You can create an fdopts.sosscaling object, opts, using the scaleopts function.

The following table lists the properties of opts:

Parameter	Default	Description and Valid Value
sosReorder	'auto'	Reorder section prior to scaling. Valid options are 'auto' (default), 'none', 'up', 'down', 'lowpass', 'highpass', 'bandpass', and 'bandstop'.
MaxNumerator	2	Maximum allowed value for numerator coefficients.
NumeratorConstraint	'none'	Specifies whether and how to constrain numerator coefficient values. Options are 'none' (default), 'unit', 'normalize', and 'po2'.
OverflowMode	'wrap'	Sets the way the filter handles arithmetic overflow situations during scaling. Valid options are 'wrap' (default), 'saturate', and 'satall'.
ScaleValueConstraint	'unit'	Specify whether to constrain the filter scale values, and how to constrain them. Valid options are 'unit' (default), 'none', and 'po2'.
MaxScaleValue	'Not used'	Maximum allowed scale values. The filter applies the MaxScaleValue limit only when you set ScaleValueConstraint to a value other than unit. Setting MaxScaleValue to a numerical value automatically changes the ScaleValueConstraint setting to none.

Example: opts = scaleopts(biquad)

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: [z,p,k] = butter(10,2000/(8000/2)); [s,g] = zp2sos(z,p,k); biquad = dsp.BiquadFilter('Structure','Direct form I','SOSMatrix',s,'ScaleValues',g); scale(biquad,'linf','scalevalueconstraint','none','maxscalevalue',2)

Arithmetic — Arithmetic type

'double' (default) | 'single' | 'Fixed'

Arithmetic type used during analysis, specified as one of 'double', 'single', or 'fixed'. The scale method assumes a double precision filter when the arithmetic input is not specified and the filter System object is in an unlocked state. If the System object is locked, the function performs analysis based on the locked input data type. If 'Arithmetic' is 'double' or 'single', the default values are used for all scaling options that are not specified as an input to the scale function. If 'Arithmetic' is 'fixed', the values used for the scaling options are set according to the settings in the filter System object. However, if a scaling option is specified that differs from the settings in sysobj, this option is used for scaling purposes but does not change the setting in sysobj. For example, if you do not specify the 'OverflowMode' scaling option, the scale method assumes that the 'OverflowMode' is equal to the value in the OverflowAction property of the filter object. If you do specify an 'OverflowMode' scaling option, then the scale function uses this overflow mode value regardless of the value in the OverflowAction property of the System object.

sosReorder — Reorder section prior to scaling

'auto' (default) | 'none' | 'up' | 'down' | 'lowpass' | 'highpass' | 'bandpass' | 'bandstop'

Reorder filter sections prior to applying scaling. Possible options:

• 'auto'

• 'none'

• 'up'

• 'down'

• 'lowpass'

• 'highpass'

• 'bandpass'

• 'bandstop'

Automatic reordering takes effect when sysobj is obtained as a result from a design using fdesign. The sections are automatically reordered depending on the response type of the design.

MaxNumerator — Maximum value for numerator coefficients

2 (default) | positive scalar

Maximum allowed value for numerator coefficients, specified as a positive scalar.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

NumeratorConstraint — Method to constrain numerator coefficients

'none' (default) | 'normalized' | 'po2' | 'unit'

Method to constrain numerator coefficient values, specified as one of the following:

• 'none'

• 'normalized'

• 'po2'

• 'unit'

OverflowMode — Overflow mode

'wrap' (default) | 'saturate'

Sets the way the filter handles arithmetic overflow situations during scaling. If your device does not have guard bits available, and you are using saturation arithmetic for filtering, use 'satall' instead of 'saturate'. The default is 'wrap'.

ScaleValueConstraint — Constrain scale values

'unit' (default) | 'none' | 'po2'

Specify whether to constrain the filter scale values, and how to constrain them. Choosing 'unit' for the constraint disables the MaxScaleValue property setting. 'po2' constrains the scale values to be powers of 2, while 'none' removes any constraint on the scale values. 'unit' is the default value.

MaxScaleValue — Maximum value for scale values

'Not Used' (default) | positive scalar

Maximum allowed scale values. The filter applies the MaxScaleValue limit only when you set ScaleValueConstraint to a value other than unit (the default setting). Setting MaxScaleValue to any numerical value automatically changes the ScaleValueConstraint setting to none.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Output Arguments

sysobjnew — Scaled biquadratic filter object

dsp.BiquadFilter System object | dsp.SOSFilter System object

Scaled biquadratic filter object, returned as one of the following System objects:

• dsp.BiquadFilter

• dsp.SOSFilter

The returned object contains the scaled second-order sections.

References

[1] Dehner, G.F. “Noise Optimized Digital Filter Design: Tutorial and Some New Aspects.” Signal Processing. Vol. 83, Number 8, 2003, pp. 1565–1582.

Version History

Introduced in R2011a