dsp.PulseMetrics

Pulse metrics of bilevel waveforms

expand all in page

Description

The dsp.PulseMetrics object computes rise times, fall times, pulse widths, and cycle metrics including pulse period, pulse separation, and duty cycle for bilevel waveforms.

To obtain pulse metrics for a bilevel waveform:

  1. Create the dsp.PulseMetrics 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

pm = dsp.PulseMetrics
pm = dsp.PulseMetrics(Name,Value)

Description

pm = dsp.PulseMetrics creates a pulse metrics System object™, pm. The object computes the rise time, fall time, and width of a pulse. dsp.PulseMetrics also computes cycle metrics such as pulse separations, periods, and duty cycles. Because a pulse contains two transitions, the object contains a superset of the capability defined in dsp.TransitionMetrics.

example

pm = dsp.PulseMetrics(Name,Value) returns a PulseMetrics System object, pm, 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.

If CycleOutputPort is true, cycle metrics are reported for each pulse period.

Maximum samples to preserve between calls to the algorithm. This property requires a positive integer that specifies the maximum number of samples to save between calls to the algorithm. When the number of samples to be saved exceeds this length, the oldest excess samples are discarded.

Tunable: Yes

Dependencies

This property applies when the RunningMetrics property is true.

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

Lower-, middle-, and upper-percent reference levels. This property contains a three-element numeric row vector that contains the lower-, middle-, and upper-percent reference levels. These reference levels are used as an offset between the lower and upper states of the waveform when computing the duration of each transition.

Data Types: double

Tolerance of the state level (in percent). This property requires a scalar that specifies the maximum deviation from either the low or high state before it is considered to be outside that state. The tolerance is expressed as a percentage of the waveform amplitude.

Data Types: double

Polarity of pulse to extract. This property specifies the type of pulse to extract by the polarity of the leading transition. Valid values for this property are 'positive' or 'negative'.

Enable posttransition aberration metrics. If this property is set to true, overshoot and undershoot metrics are reported for a region defined immediately after each transition. The posttransition aberration region is defined as the waveform interval that begins at the end of each transition and whose duration is the value of PostshootSeekFactor times the computed transition duration. If a complete subsequent transition is detected before the interval is over, the region is truncated at the start of the subsequent transition. The metrics are computed for each transition that has a complete posttransition aberration region.

Corresponds to the duration of time to search for the overshoot and undershoot metrics immediately following each transition. The duration is expressed as a factor of the duration of the transition.

Tunable: Yes

Dependencies

This property is enabled only when the PostshootOutputPort property is set to true.

Data Types: double

Enable pretransition aberration metrics. If PreshootOutputPort is set to true, overshoot and undershoot metrics are reported for a region defined immediately before each transition. The pretransition aberration region is defined as the waveform interval that ends at the start of each transition and whose duration is PreshootSeekFactor times the computed transition duration.

Corresponds to the duration of time to search for the overshoot and undershoot metrics immediately preceding each transition. The duration is expressed as a factor of the duration of the transition.

Tunable: Yes

Dependencies

This property is enabled only when the PreshootOutputPort property is set to true.

Data Types: double

Enable metrics over all calls to the algorithm. If RunningMetrics is set to false, metrics are computed for each call to the algorithm independently. If RunningMetrics is set to true, metrics are computed across subsequent calls to the algorithm. If there are not enough samples to compute metrics associated with the last transition, posttransition aberration region, or settling seek duration in the current record, the object defers reporting all transition, aberration, and settling metrics associated with the last transition until a subsequent call to the algorithm is made with enough data to compute all enabled metrics for that transition.

Sampling rate of uniformly-sampled signal. Specify the sample rate in hertz as a positive scalar. This property is used to construct the internal time values that correspond to the input sample values. Time values start with zero.

Dependencies

This property applies when the TimeInputPort property is set to false.

Data Types: double

Enable settling metrics. If the SettlingOutputPort property is set to true, settling metrics are reported for each transition. The region used to compute the settling metrics starts at the midcrossing and lasts until the SettlingSeekDuration has elapsed. If an intervening transition occurs, or the signal has not settled within the PercentStateLevelTolerance of the final level, NaN is returned for each metric. If there are not enough samples after the last transition to complete the SettlingSeekDuration, no metrics are reported for the last transition. The metrics are reported for the transition the next time the object algorithm is called if the RunningMetrics property is set to true.

Duration of time over which to search for settling. This property value is a scalar that specifies the amount of time to inspect from the mid-reference level crossing (in seconds). If the transition has not yet settled, or a subsequent complete transition is detected within this duration, the object reports NaN for all settling metrics.

Tunable: Yes

Dependencies

This property applies only when you set the SettlingOutputPort property to true.

Data Types: double

Low- and high-state levels. This property is a two-element numeric row vector that contains the low- and high-state levels. These state levels correspond to the nominal logic low and high levels of the pulse waveform.

Tunable: Yes

Data Types: double

Auto or manual state-level computation. If StateLevelsSource is set to 'Auto', the first record sent to the object is sent to dsp.StateLevels with the default settings to determine the state levels of the incoming waveform. If this property is set to 'Property', the object uses the values the user specifies in the StateLevels property.

Add input to specify sample instants. Set TimeInputPort to true to enable an additional real input column vector to the object algorithm to specify the sample instants that correspond to the sample values. If this property is false, the sample instants are built internally. The sample instants start at zero and increment by the reciprocal of the SampleRate property for subsequent samples. The sample instants continue to increment if the RunningMetrics property is set to true and no intervening calls to the reset or release methods are encountered.

Enable transition metrics. If the TransitionOutputPort property is set to true, transition metrics are reported for the initial and final transitions of each pulse.

Usage

Syntax

pulse = pm(x)
[pulse,cycle] = pm(x)
[pulse,transition] = pm(x)
[pulse,preshoot] = pm(x)
[pulse,postshoot] = pm(x)
[pulse,settling] = pm(x)
[pulse,cycle,transition,preshoot,postshoot,settling] = pm(x)
[___] = pm(x,T)

Description

example

pulse = pm(x) returns a structure array, pulse, whose fields contain real-valued column vectors. The number of rows of each field corresponds to the number of complete pulses found in the real-valued column vector input, x.

[pulse,cycle] = pm(x) returns a structure array, cycle, whose fields contain real-valued column vectors when you set the CycleOutputPort property to true. The number of rows of each field corresponds to the number of complete pulse periods found in the real-valued column vector input, x.

example

[pulse,transition] = pm(x) returns a structure array, transition, when you set the TransitionOutputPort property to true. The fields of transition contain real-valued matrices with two columns that correspond to the metrics of the first and second transitions. The number of rows corresponds to the number of pulses found in the input waveform.

[pulse,preshoot] = pm(x) returns a structure array, preshoot, when you set the PreshootOutputPort property to true. The fields of preshoot contain real-valued two-column matrices whose row length corresponds to the number of transitions found in the input waveform. The field names are identical to those of the postshoot structure array.

[pulse,postshoot] = pm(x) returns a structure, postshoot, when you set the PostshootOutputPort property to true. The fields of postshoot contain real-valued two-column matrices whose row length corresponds to the number of transitions found in the input waveform.

[pulse,settling] = pm(x) returns a structure array, settling, when you set the SettlingOutputPort property to true. The fields of settling correspond to the settling metrics for each transition. Each field is a column vector whose elements correspond to the individual settling durations, levels, and instants.

[pulse,cycle,transition,preshoot,postshoot,settling] = pm(x) which returns the pulse, cycle, transition, preshoot, postshoot, and settling structures when the CycleOutputPort, PreshootOutputPort, PostshootPort, and SettlingOutputPort properties are true. You may enable or disable any combination of output ports. However, the output arguments are defined in the order shown here.

[___] = pm(x,T) calculates the above metrics with respect to a sampled signal, whose sample values, x, and sample instants, T, are real-valued column vectors of the same length. The additional input T applies only when you set the TimeInputPort property to true.

Input Arguments

expand all

Input signal, specified as a real-valued column vector.

Data Types: double

Sampling instants, specified as a real-valued column vector. Set TimeInputPort to true to enable an additional real input column vector to the object algorithm to specify the sample instants that correspond to the sample values. If TimeInputPort is false, the sample instants are built internally. The sample instants start at zero and increment by the reciprocal of the SampleRate property for subsequent samples. The sample instants continue to increment if the RunningMetrics property is set to true and no intervening calls to the reset or release methods are encountered.

Dependencies

This input is applicable when you set the TimeInputPort property to true.

Data Types: double

Output Arguments

expand all

Complete pulses, returned as a structure whose fields contain real-valued column vectors. The number of rows of each field corresponds to the number of complete pulses found in the real-valued column vector input, x. Each pulse starts with a transition of the polarity specified by the Polarity property and ends with a transition of the opposite polarity.

The pulse output contains the following fields:

  • PositiveCross — Instants where the positive-going transitions cross the mid-reference level of each pulse

  • NegativeCross — Instants where the negative-going transitions cross the mid-reference level of each pulse

  • Width — Absolute difference between PositiveCross and NegativeCross of each pulse

  • RiseTime — Duration between the linearly interpolated instants when the positive-going (rising) transition of each pulse crosses the lower- and upper-reference levels

  • FallTime — Duration between the linearly interpolated instants when the negative-going (falling) transition of each pulse crosses the upper- and lower-reference levels

Data Types: struct

Complete pulse periods, returned as a structure whose fields contain real-valued column vectors. This structure can only be returned when you set the CycleOutputPort property to true. The number of rows of each field corresponds to the number of complete pulse periods found in the real-valued column vector input, x. You need at least three consecutive alternating polarity transitions that start and end with the same polarity as the value of the Polarity property if you want to compute cycle metrics. If the last transition found in the input x does not match the polarity of the Polarity property, the pulse separation, period, frequency, and duty cycle are not reported for the last pulse. If the RunningMetrics property is set to true when this occurs, all pulse, cycle, transition, preshoot, postshoot, and settling metrics associated with the last pulse are deferred until a subsequent call to the algorithm detects the next transition.

The cycle output contains the following fields:

  • Period — Duration between the first transition of the current pulse and the first transition of the next pulse.

  • Frequency — Reciprocal of the period.

  • Separation — Durations between the mid-reference level crossings of the second transition of each pulse and the first transition of the next pulse.

  • Width — Durations between the mid-reference level crossings of the first and second transitions of each pulse. This is equivalent to the width parameter of the pulse structure.

  • DutyCycle — Ratio of the width to the period for each pulse.

Data Types: struct

Transition metrics, returned as a structure array. This structure can only be returned when you set the TransitionOutputPort property to true. The fields of transition contain real-valued matrices with two columns, which correspond to the metrics of the first and second transitions. The number of rows corresponds to the number of pulses found in the input waveform.

The transition output contains the following fields:

  • Duration — Amount of time between the interpolated instants where the transition crosses the lower- and upper-reference levels

  • SlewRate — Ratio of absolute difference between the upper and lower reference levels to the transition duration

  • MiddleCross — Linearly interpolated instant in time where the transition first crosses the mid-reference level

  • LowerCross — Linearly interpolated instant where the signal crosses the lower-reference level

  • UpperCross — Linearly interpolated instant where the signal crosses the upper-reference level

Data Types: struct

Preshoot metrics, returned as a structure array. This structure can only be returned when you set the PreshootOutputPort property to true. The fields of preshoot contain real-valued two-column matrices whose row length corresponds to the number of transitions found in the input waveform.

The preshoot output contains the following fields:

  • Overshoot — Overshoot of the region of interest expressed as a percentage of the waveform amplitude

  • Undershoot — Undershoot of the region of interest expressed as a percentage of the waveform amplitude

  • OvershootLevel — Level of the overshoot

  • UndershootLevel — Level of the undershoot

  • OvershootInstant — Instant that corresponds to the overshoot

  • UndershootInstant — Instant that corresponds to the undershoot

Data Types: struct

Postshoot metrics, returned as a structure array. This structure can only be returned when you set the PostshootOutputPort property to true. The fields of postshoot contain real-valued two-column matrices whose row length corresponds to the number of transitions found in the input waveform.

The postshoot output contains the following fields:

  • Overshoot — Overshoot of the region of interest expressed as a percentage of the waveform amplitude

  • Undershoot — Undershoot of the region of interest expressed as a percentage of the waveform amplitude

  • OvershootLevel — Level of the overshoot

  • UndershootLevel — Level of the undershoot

  • OvershootInstant — Instant that corresponds to the overshoot

  • UndershootInstant — Instant that corresponds to the undershoot

Data Types: struct

Settling metrics for each transition, returned as a structure array. This structure can only be returned when you set the SettlingOutputPort property to true. The fields of settling correspond to the settling metrics for each transition. Each field is a column vector whose elements correspond to the individual settling durations, levels, and instants.

The settling output contains the following fields:

  • Duration — Amount of time from when the signal crosses the mid-reference level to the time where the signal enters and remains within the specified PercentStateLevelTolerance of the waveform amplitude over the specified settling seek duration

  • Instant — Instant in time where the signal enters and remains within the specified tolerance

  • Level — Level of the waveform where it enters and remains within the specified tolerance

Data Types: struct

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

plotPlot pulse signal and metrics
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Open Live Script

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

Determine the width, period, and duty cycle of a 5 V pulse sampled at 4 MHz.

 load('pulseex.mat','x','t');

Construct the dsp.PulseMetrics object. Set the TimeInputPort property to true to specify the sampling instants as an input. Set the CycleOutputPort property to true to obtain metrics for each pulse. Because the input is a 5 V pulse, set the StateLevels property to [0 5].

 pm = dsp.PulseMetrics('TimeInputPort',true, ...
                            'CycleOutputPort', true, ...
                            'StateLevels',[0 5])
pm = 
  dsp.PulseMetrics with properties:

                      Polarity: 'Positive'
             StateLevelsSource: 'Property'
                   StateLevels: [0 5]
    PercentStateLevelTolerance: 2
        PercentReferenceLevels: [10 50 90]
                RunningMetrics: false
                 TimeInputPort: true
               CycleOutputPort: true
          TransitionOutputPort: false
            PreshootOutputPort: false
           PostshootOutputPort: false
            SettlingOutputPort: false

Call the object to compute the cycle metrics and plot the result.

 [pulse,cycle] = pm(x,t);   
 plot(pm) 
 text(t(2),-0.5,['Duty Cycle: ',num2str(cycle.DutyCycle)]);

Open Live Script

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

Find the slew rates of the leading and trailing edges of a 2.3 V digital clock sampled at 4 MHz. 

 load('pulseex.mat','x','t');

Construct the dsp.PulseMetrics object. Set the TransitionOutputPort property to true to report transition metrics for the initial and final transitions. Set the StateLevelsSource property to 'Auto' to estimate the state levels from the data. 

 pm = dsp.PulseMetrics('SampleRate',4e6, ...
                            'TransitionOutputPort', true, ...
                            'StateLevelsSource','Auto');

Compute the pulse and transition metrics and plot the result.

 [pulse,transition] = pm(x); 
 plot(pm);

References

[1] IEEE® Standard on Transitions, Pulses, and Related Waveforms, IEEE Standard 181, 2003.

See Also

Objects

Introduced in R2012a

DSP System Toolbox Documentation

Support