Running Simulations Using the Error Rate Test Console :: Getting Started (Communications Toolbox™)

Learn more about Communications Toolbox

Running Simulations Using the Error Rate Test Console

On this page…
Loading the Error Rate Test Console Running the Simulation and Obtaining Results Generating an Error Rate Results Figure Window Running the Simulation Using Parallel Computing Toolbox Software Creating a System File and Attaching It to the Test Console Configuring the Test Console and Running a Simulation Optimizing Your System for Faster Simulations

On this page…

Loading the Error Rate Test Console

Running the Simulation and Obtaining Results

Generating an Error Rate Results Figure Window

Running the Simulation Using Parallel Computing Toolbox Software

Creating a System File and Attaching It to the Test Console

Configuring the Test Console and Running a Simulation

Optimizing Your System for Faster Simulations

Loading the Error Rate Test Console

The Error Rate Test Console is a simulation tool for obtaining error rate results. The MATLAB™ software includes a data file for use with the Error Rate Test Console. The data file contains an Error Rate Test Console object with an attached Gray coded modulation system. The test console configuration runs bit error rate simulations for various EbNo and modulation order, or M, values.

Load the file containing the Error Rate Test Console and attached Gray coded modulation system. At the MATLAB command line, type:
load GrayCodedModulationTester

Examine the test console by displaying its properties. At the MATLAB command line, type:

testConsole

MATLAB returns the following output:

testConsole = 

                   Description: 'Error Rate Test Console'
           SystemUnderTestName: 'GrayCodedModulation2'
                 IterationMode: 'Combinatorial'
               SystemResetMode: 'Reset at new simulation point'
         SimulationLimitOption: 'Number of errors or transmissions'
    TransmissionCountTestPoint: 'DemodBitErrors'
           MaxNumTransmissions: 100000000
           ErrorCountTestPoint: 'DemodBitErrors'
                  MinNumErrors: 100

Notice that SystemUnderTest is a Gray coded modulation system, and simulations run until reaching 100 errors or 1e8 bits.

Running the Simulation and Obtaining Results

Run the simulation, using the tic and toc commands to measure simulation time. At the MATLAB command line, type:
tic; run(testConsole); toc
MATLAB returns output similar to the following:
```
Running simulations...
Elapsed time is 275.671536 seconds.
```

Obtain the results of the simulation using the getResults method by typing the following at the MATLAB command line:

grayResults = getResults(testConsole)

MATLAB returns the following output:

grayResults = 

        TestConsoleName: 'commtest.ErrorRate'
    SystemUnderTestName: 'GrayCodedModulation2'
          IterationMode: 'Combinatorial'
              TestPoint: 'DemodBitErrors'
                 Metric: 'ErrorRate'
         TestParameter1: 'EbNo'
         TestParameter2: 'None'

In the next section, you use the results object to obtain error values and plot error rate curves.

Generating an Error Rate Results Figure Window

The semilogy method generates a figure containing error rate curves for the demodulator bit error test points. The next figure shows EbNo and Error Rate curve for the demodulator bit errors test point. This test point collects bit errors by comparing the bits the Gray coded 16-QAM modulation system transmits with the bits the system receives. In this example, the TestParameter1 property of grayResults represents EbNo.

Generate the figure by typing the following at the MATLAB command line:
semilogy(grayResults)
This script generates the following figure.
Generate the error rate curves for multiple M values by setting the TestParameter2 property to M. At the MATLAB command line, type:
grayResults.TestParameter2 = 'M'
The simulation runs for multiple modulation order (M) values. TestParameter1 controls the x-axis parameter, which is EbNo. This curve contains data for M=2, even though the actual simulation contains multiple M values.
MATLAB returns the following output:
```
grayResults = 

        TestConsoleName: 'commtest.ErrorRate'
    SystemUnderTestName: 'GrayCodedModulation2'
          IterationMode: 'Combinatorial'
              TestPoint: 'DemodBitErrors'
                 Metric: 'ErrorRate'
         TestParameter1: 'EbNo'
         TestParameter2: 'M'
```
Plot the error rate curves by typing the following at the MATLAB command line.
semilogy(grayResults)
This script generates the following figure.

Running the Simulation Using Parallel Computing Toolbox Software

If you have a Parallel Computing Toolbox™ user license and you create a matlabpool, the test console runs the simulation in parallel. This approach reduces the processing time.

Note If you do not have a Parallel Computing Toolbox user license you are unable to perform this section of the tutorial.

If you have a Parallel Computing Toolbox license, run the following command to start your default matlabpool:
matlabpool
If you have a multicore computer, then the default matlabpool uses the cores as workers.
Using the workers, run the simulation. At the MATLAB command line, type:

tic; run(testConsole); toc

MATLAB returns output similar to the following:

4 workers available for parallel computing. Simulations ...,
will be distributed among these workers. 
Running simulations...
Elapsed time is 87.449652 seconds.

Notice that the simulation runs more than three times as fast than in the previous section.

Creating a System File and Attaching It to the Test Console

In the previous sections, you used an existing Gray coded modulator system file to generate data. In this section, you create a system file and then attach it to the Error Rate Test Console.

For this example, use commdoc_gray as a starting point for your system file. This example outlines the tasks necessary for converting legacy code to a system file you can attach to the Error Rate Test Console.

Copy the system basic API template, SystemBasicTemplate.m, as MyGrayCodedModulation.m.

Rename the references to the system name in the file. First, rename the system definition by changing the class name to MyGrayCodedModulation. Replace the following lines, lines 1 and 2, of the file:

classdef SystemBasicTemplate < testconsole.SystemBasicAPI 
%SystemBasicTemplate Template for creating a system

with these lines:

classdef MyGrayCodedModulation < testconsole.SystemBasicAPI 
%MyGrayCodedModulation Gray coded modulation system

Rename the constructor by replacing:

function obj = SystemBasicTemplate
%SystemBasicTemplate Construct a system

with

function obj = MyGrayCodedModulation
%MyGrayCodedModulation Construct a Gray coded modulation system

Enter a description for your system. Update the obj.Description parameter with the following information:
```
obj.Description = 'Gray coded modulation';
```
Because you are not using the reset and setup methods for this system, leave these methods empty.
Copy lines 12–44 from commdoc_gray.m to the body of the run method.
Copy Lines 54–57 from commdoc_gray.m to the body of the run method.
Change EbNo to a test parameter. As a test parameter, EbNo becomes a variable, which allows simulations to run for different values. Locate the following line of syntax in the file:
```
EbNo = 10; % In dB
```
Replace it with:
```
EbNo = getTestParameter(obj,'EbNo');
```
Add modulation order, M, as a new test parameter for the simulation. Locate the following syntax:
```
 M = 16;                     % Size of signal constellation
```
Replace it with:
```
M = getTestParameter(obj,'M');
```
Register the test parameters to the test console.
- Declare EbNo as a test parameter by placing the following line of code in the body of the register method:
```
registerTestParameter(obj,'EbNo',0,[-50 50]);
```
  The parameter defaults to 0 dB and can take values between -50 dB and 50 dB.
- Declare M as a test parameter by placing the following line of code in the body of the register method:
```
registerTestParameter(obj,'M',16,[2 1024]);
```
  The parameter defaults to 16 QAM Modulation and can take values from 2 through 1024.
Add EbNo and M to the test parameters list in the MyGrayCodedModulationFile file.
```
 % Test Parameters
    properties
        EbNo = 0;
  M = 16;
    end
```
This adds EbNo and M to the possible test parameters list. EbNo defaults to a value of 0 dB. M defaults to a value of 16.
Define test probe locations in the run method. In this example, you are calculating end-to-end error rate. This calculation requires transmitted bits and received bits. Add one probe for obtaining transmitted bits and one probe for received bits.
- Locate the random binary data stream creation code by searching for the following lines:
```
% Create a binary data stream as a column vector.
  x = randi([0 1],n,1); % Random binary data stream
```
- Add a probe, TxBits, after the random binary data stream creation:
```
 % Create a binary data stream as a column vector.
 x = randi([0 1],n,1); % Random binary data stream
 setTestProbeData(obj,'TxBits',x);
```
  This code sends the random binary data stream, x, to the probe TxBits.
- Locate the demodulation code by searching for the following lines:
```
% Demodulate signal using 16-QAM.
z = demodulate(hDemod,yRx);
```
- Add a probe, RxBits, after the demodulation code.
```
% Demodulate signal using 16-QAM.
z = demodulate(hDemod,yRx);
setTestProbeData(obj,'RxBits',z);
```
This code sends the binary received data stream, z, to the probe RxBits.

Add the test probes to the test console, making it possible to obtain data from the system. Add these probes to the function register(obj) by typing:

function register(obj)
% REGISTER Register the system with a test console
% REGISTER(H) registers test parameters and test probes of the
% system, H, with a test console.
 
            registerTestParameter(obj,'EbNo',0,[-50 50]);
        
            registerTestProbe(obj,'TxBits')   
            registerTestProbe(obj,'RxBits')   
        end

Save the file. The file is ready for use with the system.
Create a Gray coded modulation system by typing the following at the MATLAB command line:
mySystem = MyGrayCodedModulation
MATLAB returns the following output:
```
mySystem = 

    Description: 'Gray coded modulation'
           EbNo: 0
M: 16
```

Create an Error Rate Test Console by typing the following at the MATLAB command line:

testConsole = commtest.ErrorRate

The MATLAB software returns the following output:

testConsole = 

                   Description: 'Error Rate Test Console'
           SystemUnderTestName: 'commtest.MPSKSystem'
                   FrameLength: 500
                 IterationMode: 'Combinatorial'
               SystemResetMode: 'Reset at new simulation point'
         SimulationLimitOption: 'Number of transmissions'
    TransmissionCountTestPoint: 'Not set'
           MaxNumTransmissions: 1000

Attach the system file MyGrayCodedModulation to the error rate test console by typing the following at the MATLAB command line:
attachSystem(testConsole, mySystem)

Configuring the Test Console and Running a Simulation

Configure the test console to obtain error rate metrics from the attached system. The Error Rate Test Console defines metrics as number of errors, number of transmissions, and error rate.
At the MATLAB command line, type:
registerTestPoint(testConsole, 'DemodBitErrors', 'TxBits', 'RxBits');
This line defines the test point, DemodBitErrors, and compares bits from the TxBits probe to the bits from the RxBits probe.
Run the simulations for EbNo values starting at 2 dB and ending at 10 dB, with a step size of 2 dB and M values of 2, 4, 8, and 16. At the MATLAB command line, type:
```
setTestParameterSweepValues(testConsole, 'EbNo', 2:2:10)
setTestParameterSweepValues(testConsole, 'M', [2 4 8 16])
```

Set the simulation limit to the number of transmissions.

testConsole.SimulationLimitOption = 'Number of transmissions'

Set the maximum number of transmissions to 1000.
```
testConsole.MaxNumTransmissions = 1000
```
Configure the Error Rate Test Console so it uses the demodulator bit error test point for determining the number of transmitted bits.
```
testConsole.TransmissionCountTestPoint = 'DemodBitErrors'
```
Run the simulation. At the MATLAB command line, type:
run(testConsole)
Obtain the results of the simulation. At the MATLAB command line, type:
grayResults = getResults(testConsole)
To obtain more accurate results, run the simulations for a given minimum number of errors. In this example, you also limit the number of simulation bits so that the simulations do not run indefinitely. At the MATLAB command line, type:
```
testConsole.SimulationLimitOption = 'Number of errors or transmissions'; 
testConsole.MinNumErrors = 100; 
testConsole.ErrorCountTestPoint = 'DemodBitErrors';
testConsole.MaxNumTransmissions = 1e8; 
testConsole
```
Run the simulation by typing the following at the MATLAB command line.
tic; run(testConsole); toc
Generate the new results in a Figure window by typing the following at the MATLAB command line.
```
grayResults = getResults(testConsole); 
grayResults.TestParameter2 = 'M' 
plot(grayResults)
```
This script generates the following figure.

Optimizing Your System for Faster Simulations

In the previous example, the system only utilizes the run method. Every time the object calls the run method, which is every 3e4 bits for this simulation, the object sets the M and SNR values. This time interval includes: obtaining numbers from the test console, calculating intermediate values, and setting other variables.

In contrast, the system basic API provides a setup method where the Error Rate Test Console configures the system once for each simulation point. This change relieves the run method from getting and setting simulation parameters, thus reducing simulation time.

Save the file MyGrayCodedModulation as MyGrayCodedModulationOptimized.

In the MyGrayCodedModulationOptimized file, replace the constructor name and the class definition name.

Locate the following lines of code:

classdef MyGrayCodedModulation < testconsole.SystemBasicAPI 
%MyGrayCodedModulation Gray coded modulation system

Replace them with:

classdef MyGrayCodedModulationOptimized < ...,
testconsole.SystemBasicAPI 
%MyGrayCodedModulationOptimized Gray coded modulation system

Cut lines 58–60, 62, and 84–88 and paste them into the setup method.
Replace M with the object property M and EbNo with the object property EbNo. This change provides access to these values from the run method.
```
obj.M = getTestParameter(obj,'M');
obj.EbNo = getTestParameter(obj,'EbNo');
```

The object calculates the SNR value once and accesses it in the run method. Define an SNR property and store the SNR value in this property. Define this property as a private property because it is not a test parameter, but an internal variable. At the MATLAB command line, type:

   % Internal variables
    properties (Access = private)
        SNR
    end

        function setup(obj)
            %SETUP   Initialize the system
            % SETUP(H) gets current test parameter value(s) from the test
            % console and initializes system, H, accordingly.
 
            % Get M
            obj.M = getTestParameter(obj,'M');
            k = log2(obj.M);                % Number of bits per symbol
            
            % Get EbNo and calculate SNR
            obj.EbNo = getTestParameter(obj,'EbNo');
            obj.SNR = obj.EbNo + 10*log10(k) - 10*log10(nSamp);
        end

In the run method, replace M with obj.M and SNR with obj.SNR.

            hMod = modem.qammod(obj.M);    % Create a 16-QAM modulator
            yNoisy = awgn(yTx,obj.SNR,'measured');

Notice that the run method creates the QAM modulator and demodulator.

Move the QAM modulator and demodulator out of the run method by creating hMod and hDemod properties and adding two new internal variables, Modulator and Demodulator. Storing the QAM modulator and demodulator as properties moves their creation out of the run method while still providing access to them.
```
    % Internal variables
    properties (Access = private)
        SNR
        Modulator
        Demodulator
    end
```

Create the modulator and demodulator once for the entire simulation run, by defining them in the constructor instead of the run method.

Cut lines 78–83 and paste them in the constructor.

function obj = GrayCodedModulationOptimized
     % GrayCodedModulationOptimized Construct 
		 % a Gray coded modulation system
            
      obj.Description = 'Gray coded modulation';
        
      %% Create Modulator and Demodulator
      hMod = modem.qammod(M);         % Create a 16-QAM modulator
      hMod.InputType = 'Bit';         % Accept bits as inputs
      hMod.SymbolOrder = 'Gray';      % Accept bits as inputs
      hDemod = modem.qamdemod(hMod);              
  end

Locate the following lines of code, which creates the modulator:

hMod = modem.qammod(M);         % Create a 16-QAM modulator
hMod.InputType = 'Bit';         % Accept bits as inputs
hMod.SymbolOrder = 'Gray';      % Accept bits as inputs

Replace them with these lines of code:

obj.Modulator = modem.qammod(obj.M);    % Create a QAM modulator
obj.Modulator.InputType = 'Bit';        % Accept bits as inputs
obj.Modulator.SymbolOrder = 'Gray';     % Accept bits as inputs

Locate the following line of code, which creates the demodulator.
```
hDemod = modem.qamdemod(hMod);  
```
Replace it with the following line of code:
```
obj.Demodulator = modem.qamdemod(obj.Modulator);  
```

Locate the setup region of the file:

function setup(obj)
% SETUP   Initialize the system
% SETUP(H) gets current test parameter value(s) from the test
%  console and initializes system, H, accordingly.

Set the M value of the modulator and demodulator by adding the following lines of code to the setup:

nSamp = 1;                      % Oversampling rate
            
% Get M and calculate k
obj.M = getTestParameter(obj,'M');
k = log2(obj.M);                % Number of bits per symbol
obj.Modulator.M = obj.M;
obj.Demodulator.M = obj.M;
            
% Get EbNo and calculate SNR
obj.EbNo = getTestParameter(obj,'EbNo');
obj.SNR = obj.EbNo + 10*log10(k) - 10*log10(nSamp);
end

Save the file.
Run the simulation by typing the following at the MATLAB command line.
tic; run(testConsole); toc
Notice how quickly the simulation runs with the new code changes.
Generate the new results in a Figure window by typing the following at the MATLAB command line.
```
grayResults = getResults(testConsole); 
grayResults.TestParameter2 = 'M' 
plot(grayResults)
```
This script generates the following figure.

Simulating a Communication System

Learning More

Free Early Verification Kit

Learn how to apply early verification to your development process through these technical resources.

Get technical kit

Trial software available

How much time do you spend on testing to ensure implementation meets system-level requirements?

Learn more