# comm.EyeDiagram

Display eye diagram of time-domain signals

## Description

The `comm.EyeDiagram` System object™ displays multiple traces of a modulated signal to produce an eye diagram. You can use the object to reveal the modulation characteristics of the signal, such as the effects of pulse shaping or channel distortions. The eye diagram can measure signal characteristics and plot horizontal and vertical bathtub curves when the jitter and noise comply with the dual-Dirac model [1].

To display the eye diagram of an input signal:

1. Create the `comm.EyeDiagram` 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? (MATLAB).

## Creation

### Syntax

``ed = comm.EyeDiagram``
``ed = comm.EyeDiagram(Name,Value)``

### Description

````ed = comm.EyeDiagram` creates an eye diagram System object with default property values. ```

example

````ed = comm.EyeDiagram(Name,Value)` sets properties using one or more name-value pair argument. Enclose each property name in single quotes. Unspecified properties have default values.Example: ```comm.EyeDiagram('SampleRate',2,'DisplayMode','2D color histogram')``````

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

Title of eye diagram window, specified as a character vector.

Tunable: Yes

Data Types: `char`

Sample rate of the input signal in hertz, specified as a positive real-valued scalar.

Data Types: `double`

Number of samples per symbol, specified as a positive integer.

Tunable: Yes

Data Types: `double`

Number of samples to skip before plotting the first point, specified as a nonnegative integer. To avoid irregular behavior, specify the offset to be less than the product of the SamplesPerSymbol and SymbolsPerTrace properties.

Tunable: Yes

Data Types: `double`

Number of symbols per trace, specified as a positive integer. To obtain eye measurements and visualize bathtub curves, use the default value of `2`.

Tunable: Yes

Data Types: `double`

Number of traces to display, specified as a positive integer.

Tunable: Yes

#### Dependencies

To enable this property, set DisplayMode property to `'Line plot'`.

Data Types: `double`

Eye diagram display mode, specified as one of these values.

• `'Line plot'` — Overlay traces by plotting one line for each of the last TracesToDisplay traces.

• `'2D color histogram'` — Display a color gradient that shows how often the input matches different time and amplitude values.

Tunable: Yes

Data Types: `char`

Option to enable eye diagram measurements, specified as `true` or `false`. Set this property to `true` to display the measurement pane and calculations in the eye diagram.

Tunable: Yes

Data Types: `logical`

Option to enable visualization of bathtub curves, specified as `'None'`, `'Horizontal'`, `'Vertical'`, or `'Both'`.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `char`

Histogram overlay, specified as `'None'`, `'Jitter'`, or `'Noise'`.

• To overlay a horizontal histogram on the eye diagram, set this property to `'Jitter'`.

• To overlay a vertical histogram on the eye diagram, set this property to `'Noise'`.

• To display no histogram overlay, set this property to `'None'`.

Tunable: Yes

#### Dependencies

To enable this property, set the DisplayMode property to `'2D color histogram'` and EnableMeasurements property to `true`.

Data Types: `char`

Amplitude level threshold in volts, specified as a real-valued scalar. This property separates the different signaling regions for horizontal (jitter) histograms. Jitter histograms reset when this property changes.

For non-return-to-zero (NRZ) signals, set `DecisionBoundary` to 0. For return-to-zero (RZ) signals, set `DecisionBoundary` to half the maximum amplitude.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `double`

Time range for calculating eye levels, specified as a two-element row vector. Specify the vector values as percentages of the symbol duration.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `double`

Amplitude levels of the rise and fall transitions, specified as a two-element row vector. Specify the vector values as percentages of the eye amplitude. The crossing histograms of the rise and fall thresholds reset when this property changes.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `double`

Amplitude tolerance of the horizontal crossings in volts, specified as a real-valued scalar. Increase this value to provide more tolerance to spurious crossings due to noise. Jitter and the rise and fall histograms reset when this property changes.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `double`

Bit error rate (BER) used for eye measurements, specified as a scalar in the range [0, 0.5]. The System object uses this value to measure the random jitter, the total jitter, horizontal eye openings, and vertical eye openings.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `double`

BER values used to calculate the openings of bathtub curves, specified as a vector of elements in the range [0, 0.5]. Horizontal and vertical eye openings are calculated for each of the values specified by this property.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `true` and ShowBathtub property to `'Both'`, `'Horizontal'`, or `'Vertical'`.

Data Types: `double`

Duration of initial data discarded from measurements in seconds, specified as a nonnegative scalar.

#### Dependencies

To enable this property, set the EnableMeasurements property to `true`.

Data Types: `double`

Oversampling method, specified as `'None'`, ```'Input interpolation'```, or `'Histogram interpolation'`.

To plot eye diagrams as quickly as possible, set `OversamplingMethod` to `'None'`. The drawback to not oversampling is that the plots look pixelated when the number of sybomls per trace is small.

To create smoother, less-pixelated plots using a small number of symbols per trace, set `OversamplingMethod` to`'Input interpolation'` or `'Histogram interpolation'`. In this case, ```'Input interpolation'``` is the faster interpolation method and produces good results when the signal-to-noise ratio (SNR) is high. With a low SNR, this oversampling method is not recommended because it introduces a bias to the centers of the histogram ranges. `'Histogram interpolation'` is not as fast as the other techniques, but it provides good results even when the SNR is low.

Tunable: Yes

#### Dependencies

To enable this property, set the DisplayMode property to `'2D color histogram'`.

Data Types: `char`

Color scale of the histogram, specified as `'Linear'` or `'Logarithmic'`. Change this property if certain areas of the histogram include a disproportionate number of points. Use the `'Logarithmic'` option for eye diagrams with sharp peaks, where the signal repetitively matches specific time and amplitude values.

Tunable: Yes

#### Dependencies

To enable this property, set the DisplayMode property to `'2D color histogram'`.

Data Types: `char`

Color fading, specified as `true` or `false`. To fade the points in the display as the interval of time after they are first plotted increases, set this property to `true`. This animation resembles an oscilloscope.

Tunable: Yes

#### Dependencies

To enable this property, set the DisplayMode property to `'Line plot'`.

Data Types: `logical`

Show imaginary signal component, specified as `true` or `false`. To view the imaginary or quadrature component of the input signal, set this property to `true`.

Tunable: Yes

#### Dependencies

To enable this property, set the EnableMeasurements property to `false`.

Data Types: `logical`

Y-axis limits of the eye diagram in volts, specified as a two-element vector. The first element corresponds to ymin and the second to ymax. The second element must be greater than the first.

Tunable: Yes

Data Types: `double`

Option to enable grid display on the eye diagram, specified as `true` or `false`. To display a grid on the eye diagram, set this property to `true`.

Tunable: Yes

Data Types: `logical`

Scope window position in pixels, specified as a four-element row vector of the form [left bottom width height].

Tunable: Yes

Data Types: `double`

## Usage

### Syntax

``ed(x)``

### Description

````ed(x)` displays and analyzes input signal `x` in an eye diagram.```

### Input Arguments

expand all

Input signal to be analyzed and displayed in the eye diagram, specified as a vector or matrix. `x` can be either a real or complex vector, or a real two-column matrix.

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

 `show` Show scope window `hide` Hide scope window `horizontalBathtub` Horizontal bathtub curve `verticalBathtub` Vertical bathtub curve `jitterHistogram` Jitter histogram `noiseHistogram` Noise histogram `measurements` Measure eye diagram parameters
 `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

Specify the sample rate and the number of output samples per symbol parameters.

```fs = 1000; sps = 4; ```

Create transmit filter and eye diagram objects.

```txfilter = comm.RaisedCosineTransmitFilter('OutputSamplesPerSymbol',sps); ed = comm.EyeDiagram('SampleRate',fs*sps,'SamplesPerSymbol',sps); ```

Generate random symbols and apply QPSK modulation. Then filter the modulated signal and display the eye diagram.

```data = randi([0 3],1000,1); modSig = pskmod(data,4,pi/4); txSig = txfilter(modSig); ed(txSig) ```

Show the effects of different interpolation methods on 2-D histograms for different signal-to-noise ratio (SNR) conditions.

Create GMSK modulator and eye diagram System objects. Specify that the eye diagram displays using a 2-D color histogram and plots the real and imaginary signals.

```gmsk = comm.GMSKModulator('PulseLength',3); ed = comm.EyeDiagram('DisplayMode','2D color histogram', ... 'ShowImaginaryEye',true,'YLimits',[-2 2]); ```

Generate bipolar data and apply GMSK modulation.

```d = 2*randi([0 1],1e4,1)-1; x = gmsk(d); ```
```%Pass the signal through an AWGN channel having a 25 dB SNR and with a fixed seed for repeatable results. randStream = RandStream('mt19937ar','Seed',5489); y = awgn(x,25,'measured',randStream); ```

Display the eye diagram.

```ed(y) ```

For a small number of samples per trace (16), the lack of interpolation causes piecewise-continuous behavior.

To compensate for the piecewise-continuous behavior, set the `OversamplingMethod` property to `'Input interpolation'`. Reset the object and display the eye diagram.

```ed.OversamplingMethod = 'Input interpolation'; reset(ed) ed(y) ```

The interpolation smooths the eye diagram.

Now pass the GMSK-modulated signal through an AWGN channel having a 10 dB SNR. Display the eye diagram.

```y = awgn(x,10,'measured',randStream); reset(ed) ed(y) ```

The vertical striping is the result of input interpolation, which has limited accuracy in low-SNR conditions.

Set the `OversamplingMethod` property to `'Histogram interpolation'`. Plot the eye diagram.

```ed.OversamplingMethod = 'Histogram interpolation'; reset(ed) ed(y) ```

The eye diagram plot now renders accurately because the histogram interpolation method works for all SNR values. This method results in increased execution time.

Visualize the eye diagram of a dual-dirac input signal. Compute eye measurements, and visualize horizontal and vertical bathtub curves. Overlay the horizontal (jitter) histogram.

Specify the sample rate, the samples per symbol, and the number of traces.

```fs = 10000; sps = 200; numTraces = 2000; ```

Create an eye diagram object having these properties:

• 2-D color histogram display

• Logarithmic color scale

• Jitter histogram overlay

• Horizontal and vertical bathtub curves

• Y-axis limits of [-1.3 1.3]

• Increased window height

```ed = comm.EyeDiagram('SampleRate',fs,'SamplesPerSymbol',sps,'SampleOffset',sps/2, ... 'DisplayMode','2D color histogram','ColorScale','Logarithmic', ... 'EnableMeasurements',true,'OverlayHistogram','Jitter', ... 'ShowBathtub','Both','YLimits', [-1.3 1.3]); ed.Position = ed.Position + [0 0 0 120]; ```

Generate a waveform having dual-dirac and random jitter. Specify 3 ms rise and fall times.

```src = commsrc.pattern('SamplesPerSymbol',sps,'RiseTime',3e-3,'FallTime', 3e-3); src.Jitter = commsrc.combinedjitter('RandomJitter','on','DiracJitter','on', ... 'DiracDelta',[-10e-04 10e-04],'RandomStd',5e-4); ```

Generate two symbols for each trace.

```symbols = src.generate(numTraces*2); ```

Process the data in packets of 40e3 symbols, add noise, and display the eye diagram.

```for idx = 1:(numTraces-1)/100 x = symbols(1+(idx-1)*100*2*sps:idx*100*2*sps); % Read 40,000 symbols y = awgn(x,30); % Add noise ed(y); % Display eye diagram end ```

Display the eye diagram for a waveform having dual-dirac and random jitter. Plot the jitter and noise histograms.

Specify the sample rate, the samples per symbol, and the number of traces parameters.

```fs = 1000; sps = 200; numTraces = 1000; ```

Create an eye diagram object.

```ed = comm.EyeDiagram('SampleRate',fs,'SamplesPerSymbol',sps,'SampleOffset',sps/2, ... 'DisplayMode','2D color histogram','ColorScale','Logarithmic', ... 'EnableMeasurements',true,'YLimits',[-1.2 1.2]); ```

Generate a waveform having dual-dirac and random jitter. Specify 3 ms rise and fall times.

```src = commsrc.pattern('SamplesPerSymbol',sps,'RiseTime',3e-3,'FallTime', 3e-3); src.Jitter = commsrc.combinedjitter('RandomJitter','on','DiracJitter','on', ... 'DiracDelta',[-10e-04 10e-04],'RandomStd',5e-4); ```

Generate two symbols for each trace.

```x = src.generate(numTraces*2); ```

Pass the signal through an AWGN channel with a fixed seed for repeatable results.

```randStream = RandStream('mt19937ar','Seed',5489); y = awgn(x,30,'measured',randStream); ed(y) ```

Calculate the jitter histogram count for each bin by using the `jitterHistogram` method. Plot the histogram.

```jbins = jitterHistogram(ed); plot(jbins) ```

Calculate the noise histogram count for each bin by using the `noiseHistogram` method. Plot the histogram.

```nbins = noiseHistogram(ed); plot(nbins) ```

Display the eye diagram for a waveform having dual-dirac and random jitter. Generate and plot the horizontal and vertical bathtub curves.

Specify the sample rate, the samples per symbol, and the number of traces parameters.

```fs = 1000; sps = 200; numTraces = 1000; ```

Create an eye diagram object.

```ed = comm.EyeDiagram('SampleRate',fs,'SamplesPerSymbol',sps,'SampleOffset',sps/2, ... 'DisplayMode','2D color histogram','ColorScale','Logarithmic', ... 'EnableMeasurements',true,'ShowBathtub','Both','YLimits',[-1.2 1.2]); ```

Generate a waveform having dual-dirac and random jitter. Specify 3 ms rise and fall times.

```src = commsrc.pattern('SamplesPerSymbol',sps,'RiseTime',3e-3,'FallTime', 3e-3); src.Jitter = commsrc.combinedjitter('RandomJitter','on','DiracJitter','on', ... 'DiracDelta',[-5e-04 5e-04],'RandomStd',2e-4); ```

Generate two symbols for each trace.

```x = src.generate(numTraces*2); ```

Pass the signal through an AWGN channel with a fixed seed for repeatable results.

```randStream = RandStream('mt19937ar','Seed',5489); y = awgn(x,30,'measured',randStream); ```

Display the eye diagram.

```ed(y) ```

Generate the horizontal bathtub data for the eye diagram. Plot the curve.

```hb = horizontalBathtub(ed) semilogy([hb.LeftThreshold],[hb.BER],'b',[hb.RightThreshold],[hb.BER],'b') grid ```
```hb = 1x13 struct array with fields: BER LeftThreshold RightThreshold ```

Generate the vertical bathtub data for the eye diagram. Plot the curve.

```vb = verticalBathtub(ed) semilogx([vb.BER],[vb.LowerThreshold],'b',[vb.BER],[vb.UpperThreshold],'b') grid ```
```vb = 1x13 struct array with fields: BER UpperThreshold LowerThreshold ```

Create a combined jitter object having random jitter with a 2e-4 standard deviation.

```jtr = commsrc.combinedjitter('RandomJitter','on','RandomStd',2e-4); ```

Generate an NRZ signal having random jitter and 3 ms rise and fall times.

```genNRZ = commsrc.pattern('Jitter',jtr,'RiseTime',3e-3,'FallTime',3e-3); x = generate(genNRZ,2000); ```

Pass the signal through an AWGN channel with fixed seed for repeatable results.

```randStream = RandStream('mt19937ar','Seed',5489); y = awgn(x,30,'measured',randStream); ```

Create an eye diagram object. Enable the measurements.

```ed = comm.EyeDiagram('SamplesPerSymbol',genNRZ.SamplesPerSymbol, ... 'SampleRate',genNRZ.SamplingFrequency,'SampleOffset',genNRZ.SamplesPerSymbol/2, ... 'EnableMeasurements',true,'DisplayMode','2D color histogram', ... 'OversamplingMethod','Input interpolation','ColorScale','Logarithmic','YLimits',[-1.2 1.2]); ```

To compute the rise and fall times, determine the rise and fall thresholds from the eye level and eye amplitude measurements. Plot the eye diagram to calculate these parameters.

```ed(y) ```

Pass the signal through the eye diagram object again to measure the rise and fall times.

```ed(y) hide(ed) ```

Display the data by using the `measurements` method.

```eyestats = measurements(ed); riseTime = eyestats.RiseTime fallTime = eyestats.FallTime ```
```riseTime = 0.0030 fallTime = 0.0030 ```

The measured values match the 3 ms specification.

expand all

## References

[1] Stephens, Ransom. "Jitter analysis: The dual-Dirac model, RJ/DJ, and Q-scale." Agilent Technical Note (2004).

[2] Ou, N., T. Farahmand, A. Kuo, S. Tabatabaei, and A. Ivanov. “Jitter Models for the Design and Test of Gbps-Speed Serial Interconnects.” IEEE Design and Test of Computers 21, no. 4 (July 2004): 302–13. https://doi.org/10.1109/MDT.2004.34.