comm.ConstellationDiagram

Display constellation diagram for input signals

Description

The comm.ConstellationDiagram System object™ displays real and complex-valued floating and fixed-point signals in the IQ plane. Use this System object to perform qualitative and quantitative analysis on modulated single-carrier signals.

In the constellation diagram window you can:

Input and plot multiple signals on a single constellation diagram. You can define one reference constellation for each input signal. For more information, see ReferenceConstellation.
Choose which channels are displayed by selecting signals in the legend. Use the ShowLegend property to display the legend. For a multichannel signal, specify the input as a matrix with individual signals defined in the columns of the matrix.
Display the EVM / MER Measurements panel, which displays calculated error vector magnitude (EVM) and modulation error ratio (MER) measurements. When multiple signals are input to a comm.ConstellationDiagram System object, use the Trace Selection pane to choose the signal being measured.

To display constellation diagrams:

Create the comm.ConstellationDiagram object and set its properties.
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

constdiag = comm.ConstellationDiagram

constdiag = comm.ConstellationDiagram(Name,Value)

Description

example

constdiag = comm.ConstellationDiagram returns a comm.ConstellationDiagram System object that displays real and complex-valued floating and fixed-point signals in the IQ plane.

example

constdiag = comm.ConstellationDiagram(Name,Value) set the properties of the System object using one or more name-value pair arguments in any order as (Name1,Value1,...,NameN,ValueN).

Example: constdiag = comm.ConstellationDiagram('SampleOffset',1e3) specifies that the first 1000 samples received will not be displayed.

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.

`Name` — Title of Constellation Diagram window
`'Constellation Diagram'` (default) | character vector

Title of the Constellation Diagram window, specified as a character vector.

`SamplesPerSymbol` — Number of samples used to represent each symbol
`1` (default) | positive integer

Number of samples used to represent each symbol, specified as a positive integer. When the SamplesPerSymbol property is greater than 1, the signal is downsampled before it is plotted.

Tunable: Yes

`SampleOffset` — Number of samples to skip before plotting points
`0` (default) | nonnegative integer

Number of samples to skip before plotting points, specified as a nonnegative integer less than SamplesPerSymbol. This property specifies the number of samples to skip when downsampling the input signal.

Tunable: Yes

`SymbolsToDisplaySource` — Source of symbols to display
`'Input frame length'` (default) | `'Property'`

Source of symbols to display, specified as:

'Input frame length' — The number of symbols to display is equal to the input frame length divided by SamplesPerSymbol.
'Property' — SymbolsToDisplay specifies the maximum number of symbols to display.

Tunable: Yes

`SymbolsToDisplay` — Maximum number of symbols to display
`256` (default) | positive integer

Maximum number of symbols to display, specified as a positive integer. Use SymbolsToDisplay to limit the maximum number of symbols displayed when long signals are input. Symbols plotted are the most recent symbols received.

Tunable: Yes

Dependencies

This property applies when SymbolsToDisplaySource is set to 'Property'.

`ReferenceConstellation` — Reference constellations
`[0.7071+0.7071i -0.7071+0.7071i -0.7071-0.7071i 0.7070-0.7071i]` (default) | row vector | cell array

Reference constellations for the input signals, specified as a row vector or cell array of vectors defining the ideal constellation points for each input signal. Input signals can be single channel or multichannel. You can define one reference constellation for each input signal. For multichannel input signals, one reference constellation specification applies to all the individual signals in that input signal. To obtain the EVM / MER Measurements, you must set the ReferenceConstellation property.

Tunable: Yes

Data Types: double
Complex Number Support: Yes

`ReferenceMarker` — Marker for reference display
`'+'` (default) | string | cell array

Specify the marker for the reference display as a string or cell array of strings. Select the marker symbol as one of the markers in this table.

Value	Description
`'o'`	Circle
`'+'`	Plus sign
`'*'`	Asterisk
`'.'`	Point
`'x'`	Cross
`'_'`	Horizontal line
`'\|'`	Vertical line
`'square'` or `'s'`	Square
`'diamond'` or `'d'`	Diamond
`'^'`	Upward-pointing triangle
`'v'`	Downward-pointing triangle
`'>'`	Right-pointing triangle
`'<'`	Left-pointing triangle
`'pentagram'` or `'p'`	Five-pointed star (pentagram)
`'hexagram'` or `'h'`	Six-pointed star (hexagram)
`'none'`	No markers

Tunable: Yes

Data Types: string

`ReferenceColor` — Color for reference display constellation
`[1 0 0]` (red) (default) | row vector | cell array

Color for reference display constellation, specified as a three-element row vector indicating RGB component colors or as a cell array containing RGB component colors for each input signal.

Data Types: double

`ShowReferenceConstellation` — Display the reference constellation
`true` (default) | `false`

Display the reference constellation, specified as true or false.

Tunable: Yes

Data Types: logical

`ShowTrajectory` — Turn on signal trajectory plot
`false` (default) | `true`

Turn on signal trajectory plot, specified as false or true. The signal trajectory is a plot of the in-phase component versus the quadrature component of a modulated signal. See the Show Signal Trajectory button on the toolbar in the Signal Display.

Tunable: Yes

Data Types: logical

`Position` — Scope window position and size
410-by-300 pixel window at center of screen (default) | four-element vector

Scope window position and size in pixels, specified as a four-element vector of the form [left bottom width height]. The first two elements in the vector indicate the location of the lower left corner and the last two specify the size of the window. The default value for the location depends on the screen resolution. By default, the window is positioned in the center of the screen with a width and height of 410 and 300 pixels, respectively.

Tunable: Yes

Data Types: double

`NumInputPorts` — Number of input ports
`1` (default) | integer in the range [1, 20]

Specify the number of input ports, as an integer in the range [1, 20]. Each input signal, whether it is a multichannel signal or a single channel signal, becomes a separate input port in the scope.

When multichannel input signals are specified, the maximum number of input ports is limited by the total number of input signals defined. The total number of input signals cannot exceed 20.

`ShowGrid` — Turn on grid
`true` (default) | `false`

Turn on the grid, specified as true or false.

Tunable: Yes

Data Types: logical

`ChannelNames` — Names for input channels
empty cell (default) | cell array of strings or character vectors

Names for input channels, specified as a cell array of strings or character vectors. If you do not specify names, the channels are labeled as Channel 1, Channel 2, etc.

The names assigned to input channels appear in the legend and the Measurements > Trace Selection pane.

To show the legend, set ShowLegend to true. The legend displays after you provide an input signal to the comm.ConstellationDiagram System object.

To show the Trace Selection pane, select Measurements > Trace Selection. To enable the Trace Selection pane, you must first provide an input signal to the comm.ConstellationDiagram System object.

Example: constDiag = comm.ConstellationDiagram('ChannelNames',{'8-QAM','8-PSK'}) assigns names for two input channels to 8-QAM and 8-PSK.

Tunable: Yes

`ShowLegend` — Display legend
`false` (default) | true

Display the legend, specified as false or true. The names listed in the legend are the signal names specified by the ChannelNames property.

From the legend, you can control which signals to plot. In the scope legend, click a signal name to hide the signal in the scope. To show the signal, click the signal name again. To show only one signal and hide all other signals, right-click the signal name. To show all signals, press Esc.

Tunable: Yes

Data Types: logical

`ColorFading` — Add color fading effect
`false` (default) | true

Add color fading effect, specified as false or true. 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 animation resembles an oscilloscope display.

Data Types: logical

`Title` — Plot title
blank (default) | character vector | string

Plot title, specified as a character vector or string.

Tunable: Yes

`XLimits` — x-axis limits
`[-1.375 1.375]` (default) | two-element numeric vector

x-axis limits, specified as a two-element numeric vector of the form [xmin xmax].

Tunable: Yes

`YLimits` — y-axis limits
`[-1.375 1.375]` (default) | two-element numeric vector

y-axis limits, specified as a two-element numeric vector of the form [ymin ymax].

Tunable: Yes

`XLabel` — x-axis label
`'In-phase Amplitude'` (default) | character vector | string

x-axis label, specified as a character vector or string.

Tunable: Yes

`YLabel` — y-axis label
`'Quadrature Amplitude'` (default) | character vector | string

y-axis label, specified as a character vector or string.

Tunable: Yes

`EnableMeasurements` — Display measurements pane
`false` (default) | `true`

Display measurements pane, specified as false or true. To compute and display EVM or MER measurements, activate this pane.

Tunable: Yes

Data Types: logical

`MeasurementInterval` — Measurement interval
`'Current Display'` (default) | `'All displays'` | positive integer

Measurement interval, specified as 'Current Display', 'All displays', or a positive integer in the range [2 SymbolsToDisplay]. This property specifies the window length for the EVM and MER measurements.

When the input signal contains one sample per symbol and the reference constellation is provided, the constellation diagram display can measure the signal quality in terms of EVM and MER. The EVM / MER Measurements pane can be displayed by clicking the Signal Quality button. See the toolbar in the Signal Display. After the number of input data samples is greater than MeasurementInterval, the EVM and MER measurements are computed.

Tunable: Yes

`EVMNormalization` — EVM normalization method
`'Average constellation power'` (default) | `'Peak constellation power'`

EVM normalization method, specified as 'Average constellation power' or 'Peak constellation power'. For more information, see EVM / MER Measurements.

Tunable: Yes

Usage

Syntax

constdiag(signal1,signal2,...,signalN)

Description

example

constdiag(signal1,signal2,...,signalN) displays up to NumInputPorts signals in one constellation diagram.

Input Arguments

expand all

`signal` — Input signal or signals to plot
column vector | matrix

Specify one or more signals to be plotted in the comm.ConstellationDiagram. Signals can have different data types and dimensions. To create a multichannel signal, specify a matrix with individual signals defined in the columns of the matrix.

Example: constDiag([siganl1_1,signal1_2],signal2) displays the multichannel and multi-input constellation diagram. First input is two concatenated column vectors of length N to make an N-by-2 matrix input signal and the second input is a single channel signal.

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

Specific to Scopes

`show`	Show scope window
`hide`	Hide scope window
`isVisible`	Determine visibility of scope window

Common to All System Objects

`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

Plot Amplitude-Imbalanced QPSK Constellation

Open Live Script

QPSK modulate random data symbols and apply an amplitude imbalance to the signal. Pass the signal through a noisy channel. 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;

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 an AWGN channel and display the constellation diagram. Observe that the data points have shifted from their ideal locations.

rxSig = awgn(txSig,20);
constDiagram(rxSig)

Plot 16-QAM Constellation

Open Live Script

Apply 16-QAM modulation, transmit data using an AWGN channel, and plot the signal constellation.

Create a 16-QAM reference constellation.

M = 16;
refC = qammod(0:M-1,M);

Create a comm.ConstellationDiagram System object. 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.

data = randi([0 M-1],1000,1);

Apply 16-QAM modulation.

sym = qammod(data,M);

Pass the modulated signal through an AWGN channel.

rcv = awgn(sym,15);

Display the constellation diagram.

constDiagram(rcv)

View Multi-Input Signals Constellation

Open Live Script

Use the comm.ConstellationDiagram System object to visualize the constellation of multi-input and multichannel modulated signals. Plot a multichannel signal with two 16-QAM signals with SNR 10 and 20 for the first input, and one 8-PSK signal for the second input.

Create a 16-QAM and a 8-PSK reference constellation.

M = 16;
refQAM = qammod(0:M-1,M);
S = 8;
refPSK = pskmod(0:S-1,S,pi/8);

Create a comm.ConstellationDiagram object™.

constDiag = comm.ConstellationDiagram(2,...
      'ReferenceConstellation',{refQAM,refPSK},'ShowLegend',true,...
      'XLimits',[-6 6],'YLimits',[-6 6], ...
      'ChannelNames',{'16-QAM , SNR 10 dB','16-QAM , SNR 20 dB','8-PSK'});

Generate random data symbols, modulate the symbols, and add AWGN with two different SNRs to yield two received signals.

d = randi([0 M-1],1000,1);
dQAM = qammod(d,M);
rcv1_1 = awgn(dQAM,10);
rcv1_2 = awgn(dQAM,20);
d = randi([0 S-1],1000,1);
dPSK = pskmod(d,S,pi/8);
rcv2 = awgn(dPSK,20);

For the first input, create a multichannel signal by concatenating the two received 16-QAM signals. A single reference constellation is applied for all the multichannel signals of one input. Second input uses a single channel 8-PSK signal. This input has a separate reference constellation.

View the multi-input and multichannel signals .

constDiag([rcv1_1,rcv1_2],rcv2);

More About

expand all

Signal Display

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

To change the Constellation Diagram window settings, select menu options under File, Tools, and View. Changes made via menu options adjust the property settings of the System object accordingly.

EVM / MER Measurements

The EVM / MER signal quality pane displays the measurement settings, and error vector magnitude (EVM) and modulation error ratio (MER) measurement calculation results for the specified trace selection.

EVM — An error vector is a vector in the IQ plane from the ideal constellation point to the actual point at the receiver. The root mean square error vector magnitude, EVM_RMS, is measured for the average and peak constellation power.

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

EVM Normalization Method Algorithm

EVM Normalization Method	Algorithm
`Average constellation power`	Average constellation power normalization: ${EVM}_{k} = 100 \sqrt{\frac{e_{k}}{P_{avg}}}$ EVM_RMS, in percent, for average constellation power normalization: ${EVM}_{RMS} (%) = 100 \sqrt{\frac{\frac{1}{N} \sum_{k = 1}^{N} (e_{k})}{P_{avg}}}$
`Peak constellation power`	Peak constellation power normalization ${EVM}_{k} = 100 \sqrt{\frac{e_{k}}{P_{max}}}$ EVM_RMS, in percent, for peak constellation power normalization ${EVM}_{RMS} (%) = 100 \sqrt{\frac{\frac{1}{N} \sum_{k = 1}^{N} (e_{k})}{P_{max}}}$

Average constellation power

Average constellation power normalization:

${EVM}_{k} = 100 \sqrt{\frac{e_{k}}{P_{avg}}}$

EVM_RMS, in percent, for average constellation power normalization:

${EVM}_{RMS} (%) = 100 \sqrt{\frac{\frac{1}{N} \sum_{k = 1}^{N} (e_{k})}{P_{avg}}}$

Peak constellation power

Peak constellation power normalization

${EVM}_{k} = 100 \sqrt{\frac{e_{k}}{P_{max}}}$

EVM_RMS, in percent, for peak constellation power normalization

${EVM}_{RMS} (%) = 100 \sqrt{\frac{\frac{1}{N} \sum_{k = 1}^{N} (e_{k})}{P_{max}}}$

The EVM / MER pane shows the average and peak EVM_RMS in both percent and decibels for the selected trace. The EVM reported in decibels is computed as EVM (dB) = 10‑log10(EVM_MS) = 20‑log10(EVM_RMS), where:

$e_{k} = {(I_{k} - {\tilde{I}}_{k})}^{2} + {(Q_{k} - {\tilde{Q}}_{k})}^{2}$
I_k is the in-phase value of the kth symbol in the input vector.
Q_k is the quadrature phase value of the kth symbol in the input vector.
I_k and Q_k represent ideal (reference) symbol values. ${\tilde{I}}_{k}$ and ${\tilde{Q}}_{k}$ represent measured (received) symbol values.
N is the input vector length.
P_avg is the value for Average constellation power.
P_max is the value for Peak constellation power.
${EVM}_{RMS} = \sqrt{{EVM}_{MS}}$

The maximum EVM value in a vector is ${EVM}_{max} = max_{k \in [1, ..., N]} {{EVM}_{k}},$ where k is the kth symbol in a vector of length N.

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 EVM / MER pane indicates average MER measurement result in decibels for the selected trace.
MER is a measure of the SNR in a modulated signal, calculated in dB. The MER over N symbols is
$MER = 10 \cdot \log_{10} (\frac{\sum_{n = 1}^{N} (I_{k}^{2} + Q_{k}^{2})}{\sum_{n = 1}^{N} (e_{k})}) dB,$
where:
- $e_{k} = {(I_{k} - {\tilde{I}}_{k})}^{2} + {(Q_{k} - {\tilde{Q}}_{k})}^{2}$
- I_k is the in-phase value of the kth symbol in the input vector.
- Q_k is the quadrature phase value of the kth symbol in the input vector.
- I_k and Q_k represent ideal (reference) values. ${\tilde{I}}_{k}$ and ${\tilde{Q}}_{k}$ represent measured (received) symbols.
For more information, see comm.MER.

Tips

If you want any of these features, use a comm.ConstellationDiagram System object.
- Measurements
- Basic reference constellations
- Signal trajectory plots
- Maintaining state between calls
If you want a simple signal constellation snapshot, use the scatterplot function.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Supports MEX code generation by treating the calls to the object as extrinsic. Does not support code generation for standalone applications.
See System Objects in MATLAB Code Generation (MATLAB Coder).

Documentation

comm.ConstellationDiagram

Description

Creation

Syntax

Description

Properties

Name — Title of Constellation Diagram window 'Constellation Diagram' (default) | character vector

SamplesPerSymbol — Number of samples used to represent each symbol 1 (default) | positive integer

SampleOffset — Number of samples to skip before plotting points 0 (default) | nonnegative integer

SymbolsToDisplaySource — Source of symbols to display 'Input frame length' (default) | 'Property'

SymbolsToDisplay — Maximum number of symbols to display 256 (default) | positive integer

Dependencies

ReferenceConstellation — Reference constellations [0.7071+0.7071i -0.7071+0.7071i -0.7071-0.7071i 0.7070-0.7071i] (default) | row vector | cell array

ReferenceMarker — Marker for reference display '+' (default) | string | cell array

ReferenceColor — Color for reference display constellation [1 0 0] (red) (default) | row vector | cell array

ShowReferenceConstellation — Display the reference constellation true (default) | false

ShowTrajectory — Turn on signal trajectory plot false (default) | true

Position — Scope window position and size 410-by-300 pixel window at center of screen (default) | four-element vector

NumInputPorts — Number of input ports 1 (default) | integer in the range [1, 20]

ShowGrid — Turn on grid true (default) | false

ChannelNames — Names for input channels empty cell (default) | cell array of strings or character vectors

ShowLegend — Display legend false (default) | true

ColorFading — Add color fading effect false (default) | true

Title — Plot title blank (default) | character vector | string

XLimits — x-axis limits [-1.375 1.375] (default) | two-element numeric vector

YLimits — y-axis limits [-1.375 1.375] (default) | two-element numeric vector

XLabel — x-axis label 'In-phase Amplitude' (default) | character vector | string

YLabel — y-axis label 'Quadrature Amplitude' (default) | character vector | string

EnableMeasurements — Display measurements pane false (default) | true

MeasurementInterval — Measurement interval 'Current Display' (default) | 'All displays' | positive integer

EVMNormalization — EVM normalization method 'Average constellation power' (default) | 'Peak constellation power'

Usage

Syntax

Description

Input Arguments

signal — Input signal or signals to plot column vector | matrix

Object Functions

Specific to Scopes

Common to All System Objects

Examples

Plot Amplitude-Imbalanced QPSK Constellation

Plot 16-QAM Constellation

View Multi-Input Signals Constellation

More About

Signal Display

EVM / MER Measurements

Tips

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

See Also

Blocks

Functions

Communications Toolbox Documentation

Support

`Name` — Title of Constellation Diagram window
`'Constellation Diagram'` (default) | character vector

`SamplesPerSymbol` — Number of samples used to represent each symbol
`1` (default) | positive integer

`SampleOffset` — Number of samples to skip before plotting points
`0` (default) | nonnegative integer

`SymbolsToDisplaySource` — Source of symbols to display
`'Input frame length'` (default) | `'Property'`

`SymbolsToDisplay` — Maximum number of symbols to display
`256` (default) | positive integer

`ReferenceConstellation` — Reference constellations
`[0.7071+0.7071i -0.7071+0.7071i -0.7071-0.7071i 0.7070-0.7071i]` (default) | row vector | cell array

`ReferenceMarker` — Marker for reference display
`'+'` (default) | string | cell array

`ReferenceColor` — Color for reference display constellation
`[1 0 0]` (red) (default) | row vector | cell array

`ShowReferenceConstellation` — Display the reference constellation
`true` (default) | `false`

`ShowTrajectory` — Turn on signal trajectory plot
`false` (default) | `true`

`Position` — Scope window position and size
410-by-300 pixel window at center of screen (default) | four-element vector

`NumInputPorts` — Number of input ports
`1` (default) | integer in the range [1, 20]

`ShowGrid` — Turn on grid
`true` (default) | `false`

`ChannelNames` — Names for input channels
empty cell (default) | cell array of strings or character vectors

`ShowLegend` — Display legend
`false` (default) | true

`ColorFading` — Add color fading effect
`false` (default) | true

`Title` — Plot title
blank (default) | character vector | string

`XLimits` — x-axis limits
`[-1.375 1.375]` (default) | two-element numeric vector

`YLimits` — y-axis limits
`[-1.375 1.375]` (default) | two-element numeric vector

`XLabel` — x-axis label
`'In-phase Amplitude'` (default) | character vector | string

`YLabel` — y-axis label
`'Quadrature Amplitude'` (default) | character vector | string

`EnableMeasurements` — Display measurements pane
`false` (default) | `true`

`MeasurementInterval` — Measurement interval
`'Current Display'` (default) | `'All displays'` | positive integer

`EVMNormalization` — EVM normalization method
`'Average constellation power'` (default) | `'Peak constellation power'`

`signal` — Input signal or signals to plot
column vector | matrix

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.