# commscope.eyediagram

Eye diagram analysis

## Syntax

`h = commscope.eyediagramh = commscope.eyediagram(property1,value1,...)`

## Description

`h = commscope.eyediagram` constructs an eye diagram object, `h`, with default properties. This syntax is equivalent to:

```H = commscope.eyediagram('SamplingFrequency', 10000, ... 'SamplesPerSymbol', 100, ... 'SymbolsPerTrace', 2, ... 'MinimumAmplitude', -1, ... 'MaximumAmplitude', 1, ... 'AmplitudeResolution', 0.0100, ... 'MeasurementDelay', 0, ... 'PlotType', '2D Color', ... 'PlotTimeOffset', 0, ... 'PlotPDFRange', [0 1], ... 'ColorScale', 'linear', ... 'RefreshPlot', 'on');```

`h = commscope.eyediagram(property1,value1,...)` constructs an eye diagram object, `h`, with properties as specified by property/value pairs.

The eye diagram object creates a series of vertical histograms from zero to T seconds, at Ts second intervals, where T is a multiple of the symbol duration of the input signal and Ts is the sampling time. A vertical histogram is defined as the histogram of the amplitude of the input signal at a given time. The histogram information is used to obtain an approximation to the probability density function (PDF) of the input amplitude distribution. The histogram data is used to generate `'2D Color'` plots, where the color indicates the value of the PDF, and `'3D Color'` plots. The `'2D Line'` plot is obtained by constructing an eye diagram from the last n traces stored in the object, where a trace is defined as the segment of the input signal for a T second interval.

You can change the plot type by setting the `PlotType` property. The following plots are examples of each type.

2D-Color Eye Diagram

3D-Color Eye Diagram

2D-Line Eye Diagram

To see a detailed demonstration of this object's use, type ```showdemo scattereyedemo;``` at the command line.

## Properties

An eye diagram scope object has the properties shown on the following table. All properties are writable except for the ones explicitly noted otherwise.

PropertyDescription
`Type`Type of scope object (`'Eye Diagram'`). This property is not writable.
`SamplingFrequency`Sampling frequency of the input signal in hertz.
`SamplesPerSymbol`Number of samples used to represent a symbol. An increase in `SamplesPerSymbol` improves the resolution of an eye diagram.
`SymbolRate`The symbol rate of the input signal. This property is not writable and is automatically computed based on `SamplingFrequency` and `SamplesPerSymbol`.
`SymbolsPerTrace`The number of symbols spanned on the time axis of the eye diagram scope.
`MinimumAmplitude`Minimum amplitude of the input signal. Signal values less than this value are ignored both for plotting and for measurement computation.
`MaximumAmplitude`Maximum amplitude of the input signal. Signal values greater than this value are ignored both for plotting and for measurement computation.
`AmplitudeResolution`The resolution of the amplitude axis. The amplitude axis is created from `MinimumAmplitude` to `MaximumAmplitude` with `AmplitudeResolution` steps.
`MeasurementDelay`The time in seconds the scope waits before starting to collect data.
`PlotType`Type of the eye diagram plot. The choices are ```'2D Color'``` (two dimensional eye diagram, where color intensity represents the probability density function values), ```'3D Color'``` (three dimensional eye diagram, where the z-axis represents the probability density function values), and ```'2D Line'``` (two dimensional eye diagram, where each trace is represented by a line).
`NumberOfStoredTraces`The number of traces stored to display the eye diagram in ```'2D Line'``` mode.
`PlotTimeOffset`The plot time offset input values must reside in the closed interval [-Tsym Tsym], where Tsym is the symbol duration. Since the eye diagram is periodic, if the value you enter is out of range, it wraps to a position on the eye diagram that is within range.
`RefreshPlot`The switch that controls the plot refresh style. The choices are `'on'` (the eye diagram plot is refreshed every time the update method is called) and `'off'` (the eye diagram plot is not refreshed when the `update` method is called).
`PlotPDFRange`The range of the PDF values that will be displayed in the ```'2D Color'``` mode. The PDF values outside the range are set to a constant mask color.
`ColorScale`The scale used to represent the color, the z-axis, or both. The choices are `'linear'` (linear scale) and `'log'` (base ten logarithmic scale).
`SamplesProcessed`The number of samples processed by the eye diagram object. This value does not include the discarded samples during the `MeasurementDelay` period. This property is not writable.
OperationModeWhen the operation mode is complex signal, the eye diagram collects and plots data on both the in-phase component and the quadrature component. When the operation mode is real signal, the eye diagram collects and plots real signal data.
`Measurements`An eye diagram can display various types of measurements. All measurements are done on both the in-phase and quadrature signal, unless otherwise stated. For more information, see the Measurements section.

The resolution of the eye diagram in `'2D Color'` and ```'3D Color'``` modes can be increased by increasing `SamplingFrequency`, decreasing `AmplitudeResolution`, or both.

Changing `MinimumAmplitude`, `MaximumAmplitude`, `AmplitudeResolution`, `SamplesPerSymbol`, `SymbolsPerTrace`, and `MeasurementDelay` resets the measurements and updates the eye diagram.

## Methods

An eye diagram object is equipped with seven methods for inspection, object management, and visualization.

### update

This method updates the eye diagram object data.

`update(h,x)` updates the collected data of the eye diagram object `h` with the input `x`.

If the `RefreshPlot` property is set to `'on'`, the `update` method also refreshes the eye diagram figure.

The following example shows this method's use:

```% Create an eye diagram scope object h = commscope.eyediagram('RefreshPlot', 'off') % Prepare a noisy sinusoidal as input hChan = comm.AWGNChannel('NoiseMethod', 'Signal to noise ratio (SNR)',... 'SNR', 20); x = step(hChan,0.5*sin(2*pi*(0:1/100:10))+j*cos(2*pi*(0:1/100:10))); % update the eyediagram update(h, x); % Check the number of proccessed samples h.SamplesProcessed```

### plot

This method displays the eye diagram figure.

The `plot` method has three usage cases:

`plot(h)` plots the eye diagram for the eye diagram object `h` with the current colormap or the default linespec.

`plot(h,cmap)`, when used with the `plottype` set to `'2D Color'` or `'3D Color'`, plots the eye diagram for the object `h`, and sets the colormap to `cmap`.

`plot(h,linespec)`, when used with the `plottype` set to `'2D Line'`, plots the eye diagram for the object `h` using `linespec` as the line specification. See the help for plot for valid linespecs.

The following example shows this method's use:

```% Create an eye diagram scope object h = commscope.eyediagram; % Prepare a noisy sinusoid as input hChan = comm.AWGNChannel('NoiseMethod', 'Signal to noise ratio (SNR)',... 'SNR', 20); x = step(hChan, 0.5*sin(2*pi*(0:1/100:10))+ j*0.5*cos(2*pi*(0:1/100:10))); % Update the eye diagram update(h, x); % Display the eye diagram figure plot(h) % Display the eye diagram figure with jet colormap plot(h, jet(64)) % Display 2D Line eye diagram with red dashed lines h.PlotType = '2D Line'; plot(h, 'r--')```

### exportdata

This method exports the eye diagram data.

`[VERHIST EYEL HORHISTX HORHISTRF] = EXPORTDATA(H)` Exports the eye diagram data collected by the eyediagram object H.

`VERHIST` is a matrix that holds the vertical histogram, which is also used to plot '2D Color' and '3D Color' eye diagrams.

`EYEL` is a matrix that holds the data used to plot 2D Line eye diagram. Each row of the EYEC holds one trace of the input signal.

`HORHISTX` is a matrix that holds the crossing point histogram data collected for the values defined by the CrossingAmplitudes property of the MeasurementSetup object. HORHISTX(i, :) represents the histogram for CrossingAmplitudes(i).

`HORHISTRF` is a matrix that holds the crossing point histograms for rise and fall time levels. HORHISTRF(i,:) represents the histogram for AmplitudeThreshold(i).

The following example shows this method's use:

```% Create an eye diagram scope object h = commscope.eyediagram('RefreshPlot', 'off'); % Prepare a noisy sinusoidal as input hChan = comm.AWGNChannel('NoiseMethod', 'Signal to noise ratio (SNR)',... 'SNR', 20); x = step(hChan, 0.5*sin(2*pi*(0:1/100:10))+ j*0.5*cos(2*pi*(0:1/100:10))); % Update the eyediagram update(h, x); % Export the data [eyec eyel horhistx horhistrf] = exportdata(h); % Plot line data t=0:1/h.SamplingFrequency:h.SymbolsPerTrace/h.SymbolRate; plot(t, real(eyel)); xlabel('time (s)');... ylabel('Amplitude (AU)'); grid on; % Plot 2D Color data t=0:1/h.SamplingFrequency:h.SymbolsPerTrace/h.SymbolRate; a=h.MinimumAmplitude:h.AmplitudeResolution:h.MaximumAmplitude; imagesc(t,a,eyec); xlabel('time (s)'); ylabel('Amplitude (AU)'); ```

### reset

This method resets the eye diagram object.

`reset(h)` resets the eye diagram object `h`. Resetting `h` clears all the collected data.

The following example shows this method's use:

```% Create an eye diagram scope object h = commscope.eyediagram('RefreshPlot', 'off'); % Prepare a noisy sinusoidal as input hChan = comm.AWGNChannel('NoiseMethod', 'Signal to noise ratio (SNR)',... 'SNR', 20); x = step(hChan, 0.5*sin(2*pi*(0:1/100:10))+ j*0.5*cos(2*pi*(0:1/100:10))); update(h, x); % update the eyediagram h.SamplesProcessed % Check the number of proccessed samples reset(h); % reset the object h.SamplesProcessed % Check the number of proccessed samples```

### copy

This method copies the eye diagram object.

`h = copy(ref_obj)` creates a new eye diagram object `h` and copies the properties of object `h` from properties of `ref_obj`.

The following example shows this method's use:

```% Create an eye diagram scope object h = commscope.eyediagram('MinimumAmplitude', -3, ... 'MaximumAmplitude', 3); disp(h); % display object properties h1 = copy(h)```

### disp

This method displays properties of the eye diagram object.

`disp(h)` displays relevant properties of eye diagram object `h`.

If a property is not relevant to the object's configuration, it is not displayed. For example, for a `commscope.eyediagram` object, the `ColorScale` property is not relevant when `PlotType` property is set to `'2D Line'`. In this case the `ColorScale` property is not displayed.

The following is an example of its use:

```% Create an eye diagram scope object h = commscope.eyediagram; % Display object properties disp(h); h = commscope.eyediagram('PlotType', '2D Line')```

### close

This method closes the eye diagram object figure.

`close(h)` closes the figure of the eye diagram object `h`.

The following example shows this method's use:

```% Create an eye diagram scope object h = commscope.eyediagram; % Call the plot method to display the scope plot(h); % Wait for 1 seconds pause(1) % Close the scope close(h)```

### analyze

This methods executes eye diagram measurements. analyze(h) executes the eye diagram measurements on the collected data of the eye diagram scope object h. The results of the measurements are stored in the Measurements property of h. See Measurements for more information.

In some cases, the analyze method cannot determine a measurement value. If this problem occurs, verify that your settings for measurement setup values or the eye diagram are valid.

## Measurements

You can obtain the following measurements on an eye diagram:

• Amplitude Measurements

• Eye Amplitude

• Eye Crossing Amplitude

• Eye Crossing Percentage

• Eye Height

• Eye Level

• Eye SNR

• Quality Factor

• Vertical Eye Opening

• Time Measurements

• Deterministic Jitter

• Eye Crossing Time

• Eye Delay

• Eye Fall Time

• Eye Rise Time

• Eye Width

• Horizontal Eye Opening

• Peak-to-Peak Jitter

• Random Jitter

• RMS Jitter

• Total Jitter

Measurements assume that the eye diagram object has valid data. A valid eye diagram has two distinct eye crossing points and two distinct eye levels.

The deterministic jitter, horizontal eye opening, quality factor, random jitter, and vertical eye opening measurements utilize a dual-Driac algorithm. Jitter is the deviation of a signal's timing event from its intended (ideal) occurrence in time [1]. Jitter can be represented with a dual-Driac model. A dual-Driac model assumes that the jitter has two components: deterministic jitter (DJ) and random jitter (RJ). The DJ PDF comprises two delta functions, one at $\mu$L and one at $\mu$R. The RJ PDF is assumed to be Gaussian with zero mean and variance σ.

The Total Jitter (TJ) PDF is the convolution of these two PDFs, which is composed of two Gaussian curves with variance $\sigma$and mean values $\mu$L and $\mu$R. See the following figure.

The dual-Dirac model is described in [5] in more detail. The amplitude of the two Dirac functions may not be the same. In such a case, the analyze method estimates these amplitudes, $\rho$L and $\rho$R.

### Amplitude Measurements

You can use the vertical histogram to obtain a variety of amplitude measurements. For complex signals, measurements are done on both in-phase and the quadrature components, unless otherwise specified.

 Note:   For amplitude measurements, at least one bin per vertical histogram must reach 10 hits before the measurement is taken, ensuring higher accuracy.

#### Eye Amplitude (EyeAmplitude)

Eye Amplitude, measured in Amplitude Units (AU), is defined as the distance between two neighboring eye levels. For an NRZ signal, there are only two levels: the high level (level 1 in figure) and the low level (level 0 in figure). The eye amplitude is the difference of these two values, as shown in figure [3].

#### Eye Crossing Amplitude (EyeCrossingLevel)

Eye crossing amplitudes are the amplitude levels at which the eye crossings occur, measured in Amplitude Units (AU). The analyze method calculates this value using the mean value of the vertical histogram at the crossing times [3]. See the following figure.

The next figure shows the vertical histogram at the first eye crossing time.

#### Eye Crossing Percentage (EyeOpeningVer)

Eye Crossing Percentage is the location of the eye crossing levels as a percentage of the eye amplitude.

#### Eye Height (EyeHeight)

Eye Height, measured in Amplitude Units (AU), is defined as the 3σ distance between two neighboring eye levels.

For an NRZ signal, there are only two levels: the high level (level 1 in figure) and the low level (level 0 in figure). The eye height is the difference of the two 3σ points, as shown in the next figure. The 3σ point is defined as the point that is three standard deviations away from the mean value of a PDF.

#### Eye Level (EyeLevel)

Eye Level is the amplitude level used to represent data bits, measured in Amplitude Units (AU).

For an ideal NRZ signal, there are two eye levels: +A and –A. The analyze method calculates eye levels by estimating the mean value of the vertical histogram in a window around the EyeDelay, which is also the 50% point between eye crossing times [3]. The width of this window is determined by the EyeLevelBoundary property of the eyemeasurementsetup object, shown in the next figure.

The analyze method calculates the mean value of all the vertical histograms within the eye level boundaries. The mean vertical histogram appears in the following figure. There are two distinct PDFs, one for each eye level. The mean values of the individual histograms are the eye levels as shown in this figure.

#### Eye SNR (EyeSNR)

Eye signal-to-noise ratio is defined as the ratio of the eye amplitude to the sum of the standard deviations of the two eye levels. It can be expressed as:

SNR = $\frac{{L}_{1}-{L}_{0}}{{\sigma }_{1}+{\sigma }_{0}}$

where L1 and L0 represent eye level 1 and 0, respectively, and $\sigma$1 and $\sigma$2 are the standard deviation of eye level 1 and 0, respectively.

For an NRZ signal, eye level 1 corresponds to the high level, and the eye level 0 corresponds to low level.

#### Quality Factor (QualityFactor)

The analyze method calculates Quality Factor the same way as the eye SNR. However, instead of using the mean and standard deviation values of the vertical histogram for L1 and $\sigma$1, the analyze method uses the mean and standard deviation values estimated using the dual-Dirac method. [2] See dual-Dirac section for more detail.

#### Vertical Eye Opening (EyeOpeningVer)

Vertial Eye Opening is defined as the vertical distance between two points on the vertical histogram at EyeDelay that corresponds to the BER value defined by the BERThreshold property of the eyemeasurementsetup object. The analyze method calculates this measurement taking into account the random and deterministic components using a dual-Dirac model [5] (see the Dual Dirac Section). A typical BER value for the eye opening measurements is 10-12, which approximately corresponds to the 7σ point assuming a Gaussian distribution.

### Time Measurements

You can use the horizontal histogram of an eye diagram to obtain a variety of timing measurements.

 Note:   For time measurements, at least one bin per horizontal histogram must reach 10 hits before the measurement is taken.

#### Deterministic Jitter (JitterDeterministic)

Deterministic Jitter is the deterministic component of the jitter. You calculate it using the tail mean value, which is estimated using the dual-Dirac method as follows [5]:

DJ = $\mu$L$\mu$R

where $\mu$L and $\mu$R are the mean values returned by the dual-Dirac algorithm.

#### Eye Crossing Time (EyeCrossingTime)

Eye crossing times are calculated as the mean of the horizontal histogram for each crossing point, around the reference amplitude level. This value is measured in seconds. The mean value of all the horizontal PDFs is calculated in a region defined by the CrossingBandWith property of the eyemeasurementsetup object.

The region is from -Atotal* BW to +Atotal* BW, where Atotal is the total amplitude range of the eye diagram (i.e., A total = A maxAmin) and BW is the crossing band width, shown in the following figure.

The following figure shows the average PDF in this region. Because this example assumes two symbols per trace, there are two crossing points.

 Note:   When an eye crossing time measurement falls within the [-0.5/Fs, 0) seconds interval, the time measurement wraps to the end of the eye diagram, i.e., the measurement wraps by 2*Ts seconds (where Ts is the symbol time). For a complex signal case, the analyze method issues a warning if the crossing time measurement of the in-phase branch wraps while that of the quadrature branch does not (or vice versa).To avoid the time-wrapping or a warning, add a half-symbol duration delay to the current value in the MeasurementDelay property of the eye diagram object. This additional delay repositions the eye in the approximate center of the scope.

#### Eye Delay (EyeDelay)

Eye Delay is the distance from the midpoint of the eye to the time origin, measured in seconds. The analyze method calculates this distance using the crossing time. For a symmetric signal, EyeDelay is also the best sampling point.

#### Eye Fall Time (EyeFallTime)

Eye Fall Time is the mean time between the high and low threshold values defined by the AmplitudeThreshold property of the eyemeasurementsetup object. The previous figure shows the fall time calculated from 10% to 90% of the eye amplitude.

#### Eye Rise Time (EyeRiseTime)

Eye Rise Time is the mean time between the low and high threshold values defined by the AmplitudeThreshold property of the eyemeasurementsetup object. The following figure shows the rise time calculated from 10% to 90% of the eye amplitude.

#### Eye Width (EyeWidth)

Eye Width is the horizontal distance between two points that are three standard deviations (3σ ) from the mean eye crossing times, towards the center of the eye. The value for Eye Width measurements is seconds.

#### Horizontal Eye Opening (EyeOpeningHor)

Horizontal Eye Opening is the horizontal distance between two points on the horizontal histogram that correspond to the BER value defined by the BERThreshold property of the eyemeasurementsetup object. The measurement is take at the amplitude value defined by the ReferenceAmplitude property of the eyemeasurementsetup object. It is calculated taking into account the random and deterministic components using a dual-Dirac model [5] (see the Dual Dirac Section).

A typical BER value for the eye opening measurements is 10-12, which approximately corresponds to the 7$\sigma$ point assuming a Gaussian distribution.

#### Peak-to-Peak Jitter (JitterP2P)

Peak-To-Peak Jitter is the difference between the extreme data points of the histogram.

#### Random Jitter (JitterRandom)

Random Jitter is defined as the Gaussian unbounded component of the jitter. The analyze method calculates it using the tail standard deviation estimated using the dual-Dirac method as follows [5]:

RJ = (QL + QR) * $\sigma$

where

${Q}_{L}=\sqrt{2}*erf{c}^{-1}\left(\frac{2*BER}{{\rho }_{L}}\right)$

and

${Q}_{R}=\sqrt{2}*erf{c}^{-1}\left(\frac{2*BER}{{\rho }_{R}}\right)$

BER is the bit error ratio at which the random jitter is calculated. It is defined with the BERThreshold property of the eyemeasuremensetup object.

#### RMS Jitter (JitterRMS)

RMS Jitter is the standard deviation of the jitter calculated from the horizontal histogram.

#### Total Jitter (JitterTotal)

Total Jitter is the sum of the random jitter and the deterministic jitter [5].

## Measurement Setup Parameters

A number of set-up parameters control eye diagram measurements. This section describes these set-up parameters and the measurements they affect.

### Eye Level Boundaries

Eye Level Boundaries are defined as a percentage of the symbol duration. The analyze method calculates the eye levels by averaging the vertical histogram within a given time interval defined by the eye level boundaries. A common value you can use for NRZ signals is 40% to 60%. For RZ signals, a narrower band of 5% is more appropriate. The default setting for Eye level Boundaries is a 2-by-1 vector where the first element is the lower boundary and the second element is the upper boundary. When the eye level boundary changes, the object recalculates this value.

### Reference Amplitude

Reference Amplitude is the boundary value at which point the signal crosses from one signal level to another. Reference amplitude represents the decision boundary of the modulation scheme. This value is used to perform jitter measurements. The default setting for Reference Amplitude is a 2-by-1 double vector where the first element is the lower boundary and the second element is the upper boundary. Setting the reference amplitude resets the eye diagram.

The crossing instants of the input signal are detected and recorded as crossing times. A common value you can use for NRZ signals is `0`. For RZ signals, you can use the mean value of `1` and `0` levels. Reference amplitude is stored in a 2-by-N matrix, where the first row is the in-phase values and second row is the quadrature values. See Eye Crossing Time for more information.

### Crossing Bandwidth

Crossing Bandwidth is the amplitude band used to measure the crossing times of the eye diagram. Crossing Bandwidth represents a percentage of the amplitude span of the eye diagram, typically 5%. See Eye Crossing Time for more information. The default setting for Crossing Bandwidth is 0.0500.

### Bit Error Rate Threshold

The eye opening measurements, random, and total jitter measurements are performed at a given BER value. This BER value defines the BER threshold. A typical value is 1e-12. The default setting for Bit Error Threshold is 1.0000e-12. When the bit error rate threshold changes, the object recalculates this value.

### Amplitude Threshold

The rise time of the signal is defined as the time required for the signal to travel from the lower amplitude threshold to the upper amplitude threshold. The fall time, measured from the upper amplitude threshold to the lower amplitude threshold, is defined as a percentage of the eye amplitude. The default setting is 10% for the lower threshold and 90% for the upper threshold. Setting the amplitude threshold resets the eye diagram. See Eye Rise Time and Eye Fall Time for more information.

### Jitter Hysteresis

You can use the JitterHysteresis property of the `eyemeasurementsetup` object to remove the effect of noise from the horizontal histogram estimation. The default value for Jitter Hysteresis is zero. Setting the jitter hysteresis value resets the eye diagram.

If channel noise impairs the signal being tested, as shown in the following figure, the signal may seem like it crosses the reference amplitude level multiple times during a single 0-1 or 1-0 transition.

See the zoomed—in image for more detail.

To eliminate the effect of noise, define a hysteresis region between two threshold values: Aref + ΔA and Aref - ΔA, where Aref is the reference amplitude value and ΔA is the jitter hysteresis value. If the signal crosses both threshold values, level crossing is declared. Then, linear interpolation calculates the crossing point in the horizontal histogram estimation.

## Examples

```% Construct an eye diagram object for signals in the range % of [-3 3] h = commscope.eyediagram('MinimumAmplitude', -3, ... 'MaximumAmplitude', 3) % Construct an eye diagram object for a signal with % 1e-3 seconds of transient time h = commscope.eyediagram('MeasurementDelay', 1e-3) % Construct an eye diagram object for '2D Line' plot type % with 100 traces to display h = commscope.eyediagram('PlotType', '2D Line', ... 'NumberOfStoredTraces', 100)```

## References

[1] Nelson Ou, et al, Models for the Design and Test of Gbps-Speed Serial Interconnects,IEEE Design & Test of Computers, pp. 302-313, July-August 2004.

[2] HP E4543A Q Factor and Eye Contours Application Software, Operating Manual, http://agilent.com

[3] Agilent 71501D Eye-Diagram Analysis, User's Guide, http://www.agilent.com

[4] 4] Guy Foster, Measurement Brief: Examining Sampling Scope Jitter Histograms, White Paper, SyntheSys Research, Inc., July 2005.

[5] Jitter Analysis: The dual-Dirac Model, RJ/DJ, and Q-Scale, White Paper, Agilent Technologies, December 2004, http://www.agilent.com