dsp.TransitionMetrics

Transition metrics of bilevel waveforms

expand all in page

Description

The dsp.TransitionMetrics object extracts information such as duration, slew rate, and reference-level crossings for each transition found in the bilevel waveform. The dsp.TransitionMetrics object can additionally return preshoot, postshoot and settling metrics for the regions immediately before and after each transition.

To obtain transition metrics for a bilevel waveform:

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

tm = dsp.TransitionMetrics
tm = dsp.TransitionMetrics(Name,Value)

Description

tm = dsp.TransitionMetrics creates a transition metrics System object™, tm. The object computes the rise time, fall time, and width of a pulse. TransitionMetrics additionally computes cycle metrics such as pulse separations, periods, and duty cycles.

example

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

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.

Dependencies

This property applies when RunningMetrics is true and is tunable.

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 of the lower-, middle-, and upper-percent reference levels. These reference levels are used as an offset between the low and high 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

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 and is tunable.

Data Types: double

Enable pretransition aberration metrics. If the PreshootOutputPort property 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 and is tunable.

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 SettlingOutputPort 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 algorithm is called if the RunningMetrics property is set to true.

Duration of time over which to search for settling. This property 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 TransitionMetrics 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 respectively. 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 the StateLevelsSource property is set to 'Auto', the first record sent to the algorithm uses the dsp.StateLevels object 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 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.

Usage

Syntax

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

Description

pulse = tm(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] = tm(x) returns a structure array, cycle, when you set the CycleOutputPort property to true. The fields of cycle contain real-valued column vectors. The number of rows of each field corresponds to the number of complete pulse periods found in the real-valued column vector input, x.

[pulse,transition] = tm(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, 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.

[pulse,preshoot] = tm(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.

[pulse,postshoot] = tm(x) returns a structure array, 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] = tm(x) returns a structure, 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] = tm(x) which returns the pulse, cycle, transition, preshoot, postshoot, and settling structure arrays 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.

example

[___] = tm(x,T) performs 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 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.

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 when you set the CycleOutputPort property to true. The pulse periods are returned as a structure whose fields contain real-valued column vectors. 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 first and second transitions of each 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, 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 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, 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, 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, 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).

Compute transition and preshoot information of a 2.3 V step waveform sampled at 4 MHz. Load the data.

load('transitionex.mat','x');

Construct the dsp.TransitionMetrics object. Set the SampleRate property to 4 MHz and the StateLevelsSource property to 'Auto' to estimate the state levels from the data. Set the PreshootOutputPort property to true to output pretransition aberration metrics when you call the object.

tm = dsp.TransitionMetrics('SampleRate',4e6, ...
                                 'StateLevelsSource','Auto', ...
                                 'PreshootOutputPort',true)
tm = 
  dsp.TransitionMetrics with properties:

             StateLevelsSource: 'Auto'
                   StateLevels: [0 2.3000]
    PercentStateLevelTolerance: 2
        PercentReferenceLevels: [10 50 90]
                RunningMetrics: false
                 TimeInputPort: false
                    SampleRate: 4000000
            PreshootOutputPort: true
            PreshootSeekFactor: 3
           PostshootOutputPort: false
            SettlingOutputPort: false

Call the object to compute the transition and preshoot information. Plot the result.

[transition,preshoot] = tm(x) 
transition = struct with fields:
       Duration: 1.7800e-07
       Polarity: 1
       SlewRate: 1.0310e+07
    MiddleCross: 5.1250e-06
     LowerCross: 5.0360e-06
     UpperCross: 5.2140e-06


preshoot = struct with fields:
            Overshoot: 4.8050
           Undershoot: 6.1798
       OvershootLevel: 0.1020
      UndershootLevel: -0.1500
     OvershootInstant: 4.7500e-06
    UndershootInstant: 5.0000e-06


plot(tm)

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

Compute transition, postshoot, and settling information of a 2.3 V step waveform sampled at 4 MHz. Load the data along with the sampling instants.

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

Construct the dsp.TransitionMetrics object. Set the TimeInputPort property to true, StateLevels property to [0 2.3] to match waveform statelevels. To output the postshoot information and settling information, set the PostShootOutputPort and SettlingOutputPort properties to true. Set the SettlingSeekDuration property to 2 ms.

tm = dsp.TransitionMetrics('TimeInputPort',true, ...
                                 'StateLevels',[0 2.3], ...
                                 'PostshootOutputPort',true, ...
                                 'SettlingOutputPort',true, ...
                                 'SettlingSeekDuration',2e-6)
tm = 
  dsp.TransitionMetrics with properties:

             StateLevelsSource: 'Property'
                   StateLevels: [0 2.3000]
    PercentStateLevelTolerance: 2
        PercentReferenceLevels: [10 50 90]
                RunningMetrics: false
                 TimeInputPort: true
            PreshootOutputPort: false
           PostshootOutputPort: true
           PostshootSeekFactor: 3
            SettlingOutputPort: true
          SettlingSeekDuration: 2.0000e-06

Compute the transition, postshoot, and settling information and plot the result.

 [transition,postshoot,settling] = tm(x,t) 
transition = struct with fields:
       Duration: 1.7846e-07
       Polarity: 1
       SlewRate: 1.0310e+07
    MiddleCross: 5.1261e-06
     LowerCross: 5.0369e-06
     UpperCross: 5.2153e-06


postshoot = struct with fields:
            Overshoot: 5.5483
           Undershoot: 5.1051
       OvershootLevel: 2.4276
      UndershootLevel: 2.1826
     OvershootInstant: 5.2500e-06
    UndershootInstant: 5.5000e-06


settling = struct with fields:
    Duration: 4.9529e-07
       Level: 2.2540
     Instant: 5.6214e-06


 plot(tm)

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