# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

# comm.ConstellationDiagram System object

Display a constellation diagram for input signals

## Description

The `ConstellationDiagram` System object™ plots constellation diagrams, plots signal trajectory, and provides the ability to perform EVM and MER measurements.

To plot constellation diagrams:

1. Define and set up your constellation diagram object. See Construction.

2. Call `step` to display a constellation diagram figure according to the properties of `comm.ConstellationDiagram`. The behavior of `step` is specific to each object in the toolbox.

### Note

Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, ```y = step(obj,x)``` and `y = obj(x)` perform equivalent operations.

## Construction

`H = comm.ConstellationDiagram` returns a System object, `H`, that displays real and complex-valued floating and fixed-point signals in the I/Q plane.

```H = comm.ConstellationDiagram(Name,Value, ...)``` returns a Constellation Diagram System object, `H`, with each specified property `Name` set to the specified `Value`. You can specify additional name-value pair arguments in any order as (`Name1`,`Value1`,...,`NameN`,`ValueN`).

## Properties

 `Name` Caption to display on Constellation Diagram window Specify the caption that the Constellation Diagram window displays. The default value of this property is ```Constellation Diagram```. This property is tunable. `SamplesPerSymbol` Number of samples used to represent a symbol Specify the number of samples that represent a symbol. The default value of this property is `1`. When the `SamplesPerSymbol` property is greater than 1, the object downsamples and plots the input signal. `SampleOffset` Number of samples to skip before plotting points Specify the number of samples to skip when decimating the input signal. The default value of this property is `0`. This property is tunable. This value must be a nonnegative integer less than the number of samples per symbol. `SymbolsToDisplaySource` Specify the source of symbols to display as one of `Input frame length` | `Property`]. When you set the `SymbolsToDisplaySource` to `Input frame length`, the object calculates the number of symbols to display as the input frame length divided by the value of the SamplesPerSymbol property. When you set this property to `Property`, the maximum number of symbols to display is the value of the SymbolsToDisplay property. The default is `Input frame length`. This property is tunable. `SymbolsToDisplay` The maximum number of symbols that can be displayed when input signal is long. This property is applicable when you set the SymbolsToDisplaySource property to `Property`. Always plot the latest `SymbolsToDisplay` symbols. The default value of this property is `256`. This property is tunable. `ReferenceConstellation` The ideal constellation of the input signal The object can display the ReferenceConstellation with its own marker. To obtain the signal quality measurement, you must set the ReferenceConstellation property to a valid value. The default value of this property is ```[0.7071+0.7071i -0.7071+0.7071i -0.7071-0.7071i 0.7070-0.7071i]```. This property is tunable. `ReferenceMarker` Specify the marker for reference display The default value of this property is `'+'`. This property is tunable. `ReferenceColor` Specify the color for reference display constellation The default value of this property is `[1 0 0]` (red). This property is tunable. `ShowReferenceConstellation` Option to turn on the reference constellation Set this property to `true` to show reference constellation on the display. The default value of this property is `true`. This property is tunable. `ShowTrajectory` Option to turn on the signal trajectory plot. Set this property to `true` to display a plot of the signal trajectory. The signal trajectory is a plot of the in-phase component versus the quadrature component of a modulated signal. The default value of this property is `false`. This property is tunable. `Position` Scope window position in pixels Specify the size and location of the scope window in pixels, as a four-element double vector of the form: [left bottom width height]. The default value of this property is dependent on the screen resolution, and is such that the window is positioned in the center of the screen, with a width and height of 410 and 300 pixels respectively. This property is tunable. `ShowGrid` Option to turn on grid Set this property to `true` to turn on the grid or `false` to turn off the grid. The default value of this property is `true`. This property is tunable. `ShowLegend` Option to turn on legend Set this property to true to turn on the legend. The default is `false`. This property is tunable. `ColorFading` Option to add color fading effect When you set this property to true, the points in the display fade as the interval of time after they are first plotted increases. This is for animation that resembles an oscilloscope. The default value of this property is `false`. This property is tunable. `Title` Display title Specify the display title. The default value of this property is an empty character vector. This property is tunable. `XLimits` X-axis limits Specify the x-axis limits as a two-element numeric vector: `[xmin xmax]`. The default value of this property is `[-1.375 1.375]`. This property is tunable. `YLimits` Y-axis limits Specify the y-axis limits as a two-element numeric vector: `[ymin ymax]`. The default value of this property is `[-1.375 1.375]`. This property is tunable `XLabel` X-axis label Specify the x-axis label as a character vector. The default value of this property is `'In-phase Amplitude'`. This property is tunable. `YLabel` Y-axis label Specify the y-axis label as a character vector. The default value of this property is `'Quadrature Amplitude'`. This property is tunable. `EnableMeasurements` Option to turn on measurements Set this property to `true` to activate the measurements pane, compute and display EVM or MER measurements. The default value of this property is `false`. This property is tunable. `MeasurementInterval` The measurement interval Specify `MeasurementInterval` as `'Current Display'`, `'All displays'`, or as a postive integer. When the input signal contains one sample per symbol and the reference constellation is provided, this System object can measure the signal quality in terms of EVM and MER. The measurement panel can be evoked by clicking on the Signal Quality button. This property specifies the window length for the measurement. The value of this property must be from `2` to SymbolsToDisplay. The measurement is computed after the number of input data samples is greater than `MeasurementInterval`. The default value of this property is set to `'Current Display'`, indicating the measurement interval is equal to the length of the input. This property is tunable. `EVMNormalization` EVM normalization Specify the normalization method that the object uses in the EVM calculation as one of `'Average constellation power'` or `'Peak constellation power'`. The default value of this property is `'Average constellation power'`. This property is tunable.

## Methods

 hide Hide scope window reset Reset internal states of the scope object show Make scope window visible step Display constellation diagram of signal in scope figure
Common to All System Objects
`clone`

Create System object with same property values

`getNumInputs`

Expected number of inputs to a System object

`getNumOutputs`

Expected number of outputs of a System object

`isLocked`

Check locked states of a System object (logical)

`release`

Allow System object property value changes

## Examples

expand all

This example shows how to create a 16-QAM modulator, transmit data using an AWGN channel, and plot the signal constellation.

Create a Rectangular QAM Modulator System object, `qamModulator`, and set the modulation order to 16. Find the constellation reference points using the `constellation` function.

```qamModulator = comm.RectangularQAMModulator('ModulationOrder',16); refC = constellation(qamModulator); ```

Create a constellation diagram System object and specify the constellation reference points and axes limits using name-value pairs.

```constDiagram = comm.ConstellationDiagram('ReferenceConstellation',refC, ... 'XLimits',[-4 4],'YLimits',[-4 4]); ```

Generate random, 16-ary data symbols.

```d = randi([0 15],1000,1); ```

Apply 16-QAM modulation.

```sym = step(qamModulator,d); ```

Pass the modulated signal through an AWGN channel.

```rcv = awgn(sym,15); ```

Display the constellation diagram.

```constDiagram(rcv) ```

This example shows how to modulate random data symbols, apply an amplitude imbalance, pass the signal through a noisy channel, and plot the resultant constellation.

Create a constellation diagram object. Because the default reference constellation for the `comm.ConstellationDiagram` System object is QPSK, it is not necessary to set additional properties.

```constDiagram = comm.ConstellationDiagram; ```

Create an AWGN channel.

```channel = comm.AWGNChannel('NoiseMethod','Signal to noise ratio (Es/No)', ... 'EsNo',20); ```

Generate random data symbols and apply QPSK modulation.

```data = randi([0 3],1000,1); modData = pskmod(data,4,pi/4); ```

Apply an amplitude imbalance to the modulated signal.

```txSig = iqimbal(modData,5); ```

Pass the transmitted signal through the AWGN channel and display the constellation diagram. Observe that the data points have shifted from their ideal locations.

```rxSig = channel(txSig); constDiagram(rxSig) ```

## Signal Display

To change the signal display settings, select View > Configuration Properties to bring up the Visuals—Constellation Properties dialog box. Then, modify the values for the Samples per symbol, Offset and Symbols to display parameters on the Main tab. You can modify the reference constellation parameters on the Reference constellation tab.

To communicate simulation data that corresponds to the current display, the scope uses the Frames indicator on the scope window. The following figure highlights important aspects of the Constellation Diagram window.

## Visuals — Constellation Properties

### Main Pane

#### Samples per symbol

Number of samples used to represent a symbol. This value must be a positive number.

#### Offset (samples)

Number of samples to skip before plotting points. The offset must be a nonnegative integer value less than the value of the samples per symbol.

#### Symbols to display

The maximum number of symbols that can be displayed. Must be a positive integer value.

### Display Pane

#### Show grid

Select this check box to turn on the grid.

#### Show legend

Select this check box to display a legend for the graph.

#### Show signal trajectory

Select this check box to display the trajectory of a modulated signal by plotting its in-phase component versus its quadrature component.

When you set select this check box, the points in the display fade as the interval of time after they are first plotted increases. The default value of this property is `false`. This property is tunable.

#### X-limits (Minimum)

Specify the minimum value of the x-axis.

#### X-limits (Maximum)

Specify the maximum value of the x-axis.

#### Y-limits (Minimum)

Specify the minimum value of the y-axis.

#### Y-limits (Maximum)

Specify the maximum value of the y-axis.

#### Title

Specify a label that appears above the constellation diagram plot. By default, there is no title.

#### X-axis label

Specify the text the scope displays along the x-axis

#### Y-axis label

Specify the text the scope displays along the y-axis

### Reference Constellation Pane

#### Show reference constellation

Select the check box to display the reference constellation.

#### Reference constellation

Select the reference constellation from `BPSK` | `QPSK` | `8-PSK` | `16-QAM` | `64-QAM` | `256-QAM` | `<user-defined>`. If not selected, the reference constellation is specified in the variable `refConst`.

#### Constellation normalization

Select the type of constellation normalization as ```Minimum distance```, `Average power`, or `Peak power`.

#### Reference minimum distance

Specify the minimum distance between symbols in the reference constellation as a positive real scalar. This parameter is available when Constellation normalization is set to ```Minimum distance```.

#### Average reference power

Specify the average power of the reference constellation as a positive real scalar. This parameter is available when Constellation normalization is set to `Average power`.

#### Peak reference power

Specify the peak power of the reference constellation as a positive real scalar. This parameter is available when Constellation normalization is set to `Peak power`.

Specify the phase offset of the reference constellation in radians as a real scalar.

## Measurements Panels

### Measurements Panel Buttons

Each of the Measurements panels contains the following buttons that enable you to modify the appearance of the current panel.

ButtonDescription

Move the current panel to the top. When you are displaying more than one panel, this action moves the current panel above all the other panels.

Collapse the current panel. When you first enable a panel, by default, it displays one or more of its panes. Click this button to hide all of its panes to conserve space. After you click this button, it becomes the expand button .

Expand the current panel. This button appears after you click the collapse button to hide the panes in the current panel. Click this button to display the panes in the current panel and show measurements again. After you click this button, it becomes the collapse button again.

Undock the current panel. This button lets you move the current panel into a separate window that can be relocated anywhere on your screen. After you click this button, it becomes the dock button in the new window.

Dock the current panel. This button appears only after you click the undock button. Click this button to put the current panel back into the right side of the Scope window. After you click this button, it becomes the undock button again.

Close the current panel. This button lets you remove the current panel from the right side of the Scope window.

Some panels have their measurements separated by category into a number of panes. Click the pane expand button to show each pane that is hidden in the current panel. Click the pane collapse button to hide each pane that is shown in the current panel.

### Signal Quality Panel

The Signal Quality panel controls the Settings and Signal Quality panes. Both panels can be independently expanded or collapsed.

You can choose to hide or display the Signal Quality panel. In the Scope menu, select Tools > Measurements > Signal Quality.

### Settings Pane

The Settings pane enables you to define the measurement interval and normalization method the scope uses when obtaining signal measurements.

• Measurement interval — The duration of the EVM or MER measurement, specified as ```'Current Display'```, `'All displays'`, or as a postive integer. The value of this property must be greater than one and less than or equal to the setting for the number of symbols to display. The measurement is computed after number of input data samples is greater than the measurement interval.

• EVM normalization — For the EVM calculations, you may use one of two normalization methods: ```Average constellation power``` or `Peak constellation power`. The scope performs EVM calculations using the `comm.EVM` System object. For more information, see `comm.EVM`.

• Reference constellation — Select the reference constellation as `BPSK` | `QPSK` | `8-PSK` | `16-QAM` | `64-QAM` | `256-QAM` | `<user-defined>`.

• Constellation normalization — Select the type of constellation normalization as `Minimum distance`, ```Average power```, or `Peak power`.

• Minimum distance — Specify the minimum distance between symbols in the reference constellation as a positive real scalar. This parameter is available when Constellation normalization is set to `Minimum distance`.

• Average reference power — Specify the average power of the reference constellation as a positive real scalar. This parameter is available when Constellation normalization is set to `Average power`.

• Peak reference power — Specify the peak power of the reference constellation as a positive real scalar. This parameter is available when Constellation normalization is set to `Peak power`.

• Reference phase offset — Specify the phase offset of the reference constellation in radians as a real scalar.

### Signal Quality Pane

The Signal Quality pane displays the calculation results.

• EVM — An error vector is a vector in the I-Q plane between the ideal constellation point and the actual point at the receiver. The root mean square error vector magnitude, EVMRMS, is measured for the average and peak constellation power.

On the constellation diagram, you can display the EVMRMS measurements normalized by the `Average constellation power` or ```Peak constellation power``` as computed using these algorithms.

EVM Normalization MethodAlgorithm
`Average constellation power`

EVMRMS in percent for average constellation power normalization

`$EV{M}_{RMS}\left(percent\right)=\sqrt{\frac{\frac{1}{N}\sum _{k=1}^{N}\left({e}_{k}\right)}{{P}_{avg}}}*100$`

`Peak constellation power`

EVMRMS in percent for peak constellation power normalization

`$EV{M}_{RMS}\left(percent\right)=\sqrt{\frac{\frac{1}{N}\sum _{k=1}^{N}\left({e}_{k}\right)}{{P}_{\mathrm{max}}}}*\text{​}100$`

The display shows the average and peak EVMRMS in percent and in decibels. The EVM reported in decibels is computed as EVM (dB) = 10*log10(EVMMS) = 20*log10(EVMRMS)

Where:

• ek = ${\left({I}_{k}-\stackrel{~}{{I}_{k}}\right)}^{2}+{\left({Q}_{k}-{\stackrel{~}{Q}}_{k}\right)}^{2}$

• Ik = In-phase measurement of the kth symbol in the burst

• Qk = Quadrature phase measurement of the kth symbol in the burst

• N = Input vector length

• Pavg = The value for Average constellation power

• Pmax = The value for Peak constellation power

• Ik and Qk represent ideal (reference) values. ${\stackrel{~}{I}}_{k}$ and ${\stackrel{~}{Q}}_{k}$ represent measured (received) symbols.

• EVMRMS = sqrt(EVMMS)

The max EVM is the maximum EVM value in a frame or $EV{M}_{\mathrm{max}}=\underset{k\in \left[1,...,N\right]}{\mathrm{max}}\left\{EV{M}_{k}\right\}\text{\hspace{0.17em}},$ where k is the kth symbol in a burst of length N.

EVM NormalizationAlgorithm
`Average constellation power`

Average constellation power normalization

`$EV{M}_{k}=\sqrt{\frac{{e}_{k}}{{P}_{avg}}}*100$`

`Peak constellation power`

Peak constellation power normalization

`$EV{M}_{k}=\sqrt{\frac{{e}_{k}}{{P}_{\mathrm{max}}}}*\text{​}100$`

For more information, see `comm.EVM`.

• MER — MER is the ratio of the average power of the transmitted signal to the average power of the error vector. The scope indicates the measurement result in decibels.

MER is a measure of the SNR in a modulated signal calculated in dB. The MER over N symbols is

`$MER=10*\text{​}{\mathrm{log}}_{10}\left(\frac{\sum _{n=1}^{N}\left({I}_{k}^{2}+{Q}_{k}^{2}\right)}{\sum _{n=1}^{N}\left({e}_{k}\right)}\right)\text{\hspace{0.17em}}\text{dB}\text{.}$`

where:

• ek = ${\left({I}_{k}-\stackrel{~}{{I}_{k}}\right)}^{2}+{\left({Q}_{k}-{\stackrel{~}{Q}}_{k}\right)}^{2}$

• Ik = In-phase measurement of the kth symbol in the burst

• Qk = Quadrature phase measurement of the kth symbol in the burst

• Ik and Qk represent ideal (reference) values. ${\stackrel{~}{I}}_{k}$ and ${\stackrel{~}{Q}}_{k}$ represent measured (received) symbols.

For more information, see `comm.MER`.

## Style Dialog Box

In the Style dialog box, you can customize the style of displays. You are able to change the color of the figure containing the displays, the background and foreground colors of display axes, and properties of lines in a display. From the scope menu, select View > Style to open this dialog box.

### Properties

The Style dialog box allows you to modify the following elements of the scope figure:

#### Figure color

Specify the color that you want to apply to the background of the scope figure. By default, the figure color is gray.

#### Axes colors

Specify the color that you want to apply to the background of the axes for the active display. Using a second drop down, you can also specify the color of the ticks, labels, and grid lines.

Specify the marker shape, marker size, marker line width, and color for the signal on the active display. The marker shape cannot be set to `none` unless the `ShowTrajectory` property is `true`.

#### Signal trajectory

Specify the line type, width, and color for the signal trajectory plot. The line type can only be set to something other than `no line` when the `ShowTrajectory` property is `true`. Conversely, the line type must be `no line` when the `ShowTrajectory` property is `false`.

#### Reference constellation

Specify the marker shape, marker size, marker line width, and color for the reference constellation shown on the active display. These settings are only applicable when the `ShowReferenceConstellation` property is `true`.

#### Marker symbols

Specify the markers for the selected signal and the reference constellation on the active display. This parameter is similar to the `Marker` property for the MATLAB® Handle Graphics® plot objects.

SpecifierMarker Type
noneNo marker
Circle
Square
Cross
Point (default)
Plus sign
Asterisk
Diamond
Downward-pointing triangle
Upward-pointing triangle
Left-pointing triangle
Right-pointing triangle
Five-pointed star (pentagram)
Six-pointed star (hexagram)

### Properties

The Tools—Axes Scaling Properties dialog box appears as follows.

#### Axes scaling

Specify when the scope automatically scales the axes. You can select one of the following options:

• `Manual` — When you select this option, the scope does not automatically scale the axes. You can manually scale the axes in any of the following ways:

• Select Tools > Axes Scaling Properties.

• Press one of the Scale Axis Limits toolbar buttons.

• When the scope figure is the active window, press and simultaneously.

• `Auto` — When you select this option, the scope scales the axes as needed, both during and after simulation. Selecting this option shows the Do not allow Y-axis limits to shrink check box.

• `After N Updates` — Selecting this option causes the scope to scale the axes after a specified number of updates. This option is useful and more efficient when your scope display starts with one axis scale, but quickly reaches a different steady state axis scale. Selecting this option shows the Number of updates edit box.

By default, this property is set to `Auto`. This property is Tunable (Simulink).

#### Do not allow Y-axis limits to shrink

When you select this property, the y-axis is allowed only to grow during axes scaling operations. If you clear this check box, the y-axis or color limits may shrink during axes scaling operations.

This property appears only when you select `Auto` for the Axis scaling property. When you set the Axes scaling property to `Manual` or ```After N Updates```, the y-axis or color limits are allowed to shrink. Tunable (Simulink).

Specify as a positive integer the number of updates after which to scale the axes. This property appears only when you select ```After N Updates``` for the Axes scaling property. Tunable (Simulink).

#### Scale axes limits at stop

Select this check box to scale the axes when the simulation stops. The y-axis is always scaled. The x-axis limits are only scaled if you also select the Scale X-axis limits check box.

#### Y-axis Data range (%)

Set the percentage of the y-axis that the scope uses to display the data when scaling the axes. Valid values are from 1 through 100. For example, if you set this property to `100`, the Scope scales the y-axis limits such that your data uses the entire y-axis range. If you then set this property to `30`, the scope increases the y-axis range such that your data uses only 30% of the y-axis range. Tunable (Simulink).

#### Y-axis Align

Specify where the scope aligns your data along the y-axis when it scales the axes. You can select `Top`, `Center`, or `Bottom`. Tunable (Simulink).

#### Autoscale X-axis limits

Check this box to allow the scope to scale the x-axis limits when it scales the axes. If Axes scaling is set to `Auto`, checking Autoscale X-axis limits only scales the data currently within the axes, not the entire signal in the data buffer. If Autoscale X-axis limits is on and the resulting axis is greater than the span of the scope, trigger position markers will not be displayed. Triggers are controlled using the Trigger Measurements panel. Tunable (Simulink).

#### X-axis Data range (%)

Set the percentage of the x-axis that the scope uses to display the data when scaling the axes. Valid values are from 1 through 100. For example, if you set this property to `100`, the scope scales the x-axis limits such that your data uses the entirex-axis range. If you then set this property to `30`, the scope increases the x-axis range such that your data uses only 30% of the x-axis range. Use the x-axis Align property to specify data placement along the x-axis.

This property appears only when you select the Scale X-axis limits check box. Tunable (Simulink).

#### X-axis Align

Specify how the scope aligns your data along the x-axis: `Left`, `Center`, or `Right`. This property appears only when you select the Scale X-axis limits check box. Tunable (Simulink).

## Programmatic Configuration

You can programmatically configure the scope properties with callbacks or within scripts by using a scope configuration object as describe in Control Scopes Programmatically (Simulink).

## Tips

Use `comm.ConstellationDiagram` when these are required:

• Measurements

• Basic reference constellations

• Signal trajectory plots

• Maintaining state between calls

Use `scatterplot` when:

• A simple snapshot of the signal constellation is needed.