Components of Bit Error Rate Analysis App

The app consists of these three main components: an upper pane, a lower pane, and a separate BER Figure window.

Interaction Between Bit Error Rate Analysis App Components

The components of the app act as one integrated tool.

Section Overview

You can use the Bit Error Rate Analysis app to generate and analyze theoretical BER data. Theoretical data can be useful for comparison with your simulation results. However, closed-form BER expressions exist for only certain kinds of communications systems. For more information, see Analytical Expressions Used in BER Analysis.

To access app capabilities related to theoretical BER data, follow these steps.

For an example that shows how to generate and analyze theoretical BER data using the Bit Error Rate Analysis app, see the Use Theoretical Tab in Bit Error Rate Analysis App section.

For information about the combinations of parameters available on the Theoretical tab and the underlying functions that perform BER computations, see the Available Sets of Theoretical BER Data section.

Use Theoretical Tab in Bit Error Rate Analysis App

This example shows how to use the app to generate and plot theoretical BER data. In particular, the example compares the performance of different modulation orders for QAM in a communications system that includes an AWGN channel.

Run Theoretical BER Example

Available Sets of Theoretical BER Data

The Bit Error Rate Analysis app can generate a large set of theoretical BERs. Parameters in the Theoretical tab enable you to configure the channel type, modulation type and order, error detection and correction channel coding, and synchronization error used when the app computes the theoretical BER. The app adjusts the combination of selectable parameter values based on your choices so that the configuration is always valid or uses a dialog box to inform you of valid parameter values.

The app computes the theoretical BER for these modulation types, assuming Gray ordered binary transmission data. The app uses these BER functions to perform underlying computations and limits the modulation order to practical limits.

To compute the BER for higher modulation orders than permitted in the app, use the BER functions. For more information about specific combinations of parameters, see the reference pages for the BER functions listed in the Bit Error Rate Calculation and Estimation function group of the Test and Measurement category.

Section Overview

Using the Monte Carlo tab with the Simulation environment parameter set to MATLAB, you can use the Bit Error Rate Analysis app in conjunction with your own MATLAB communications system simulation functions to generate and analyze BER data. The app calls the simulation specified by the Function name parameter for each specified E_b/N₀ value, collects the BER data from the simulation, and creates a plot. The app also enables you to adjust the E_b/N₀ range and the stopping criteria for the simulation.

To make your own simulation functions compatible with the app, see the Prepare MATLAB Function for Use in Bit Error Rate Analysis App example on the Bit Error Rate Analysis app reference page.

Use MATLAB Function with Bit Error Rate Analysis App

This example shows how the Bit Error Rate Analysis app can run the viterbisim MATLAB simulation.

To run this example, follow these steps.

Assign Function Stopping Criteria

When you create a MATLAB simulation function for use with the Bit Error Rate Analysis app, control the simulation run duration by setting the target number of errors and maximum number of bits. The simulation stops the current E_b/N₀ when either limit is reached. For more information about this requirement, see the Requirements for Using MATLAB Functions with Bit Error Rate Analysis App section.

After you create your function, set the target number of errors and maximum number of bits on the Monte Carlo tab of the app.

Typically, a Number of errors parameter value of at least 100 produces an accurate error rate. The Number of bits value prevents the simulation from running too long. Depending on the E_b/N₀ value and other aspects of the communications system modeled (such as modulation characteristics and channel conditions), reaching 100 bit errors might not be realistic. However, if fewer than 100 errors occur because the Number of bits parameter value is too small, the returned error rate might be misleading. You can use confidence intervals to gauge the accuracy of the error rates that your simulation produces. As you increase the confidence level, the accuracy of the computed error rate decreases.

Plot Confidence Intervals

After you run a simulation with the Bit Error Rate Analysis app, the resulting data set in the data viewer has an active menu in the Confidence Level column. By default the Confidence Level value is off, meaning the simulation data in the BER Figure window does not show confidence intervals.

To show confidence intervals in the BER Figure window, set Confidence Level to 90%, 95%, or 99%.

The plot in the BER Figure window automatically responds the Confidence Level value change. This figure shows a sample plot.

For an example that plots confidence intervals for a Simulink simulation, see the Use Simulink Model with Bit Error Rate Analysis App section.

To find confidence intervals for levels not listed in the Confidence Level menu, use the berconfint function.

Curve Fit BER Points

After you run a simulation with the Bit Error Rate Analysis app, the BER Figure window plots individual BER data points. To fit a curve to a data set that contains at least four points, select Fit for that data in the data viewer.

The plot in the BER Figure window automatically responds to this selection. This plot shows a curve fit to a set of BER results.

For greater flexibility in the process of fitting a curve to BER data, use the berfit function.

Template for Simulation Function

Use this template when adapting your code to work with the Bit Error Rate Analysis app. You can open the template in an editor by entering edit bertooltemplate at the MATLAB command prompt. If you develop a simulation function without using the template, be sure your function satisfies the requirements described in the Requirements for Using MATLAB Functions with Bit Error Rate Analysis App section.

function [ber,numBits] = bertooltemplateTemp(EbNo,maxNumErrs,maxNumBits,varargin)
%BERTOOLTEMPLATE Template for a BERTool (Bit Error Rate Analysis app) simulation function.
%   This file is a template for a BERTool-compatible simulation function.
%   To use the template, insert your own code in the places marked "INSERT
%   YOUR CODE HERE" and save the result as a file on your MATLAB path. Then
%   use the Monte Carlo pane of BERTool to execute the script.
%
%   [BER, NUMBITS] = YOURFUNCTION(EBNO, MAXNUMERRS, MAXNUMBITS) simulates
%   the error rate performance of a communications system. EBNO is a vector
%   of Eb/No values, MAXNUMERRS is the maximum number of errors to collect
%   before stopping the simulation, and MAXNUMBITS is the maximum number of 
%   bits to run before stopping the simulation. BER is the computed bit error 
%   rate, and NUMBITS is the actual number of bits run. Simulation can be 
%   interrupted only after an Eb/No point is simulated.
%
%   [BER, NUMBITS] = YOURFUNCTION(EBNO, MAXNUMERRS, MAXNUMBITS, BERTOOL)
%   also provides BERTOOL, which is the handle for the BERTool app and can
%   be used to check the app status to interrupt the simulation of an Eb/No
%   point.
%
%   For more information about this template and an example that uses it,
%   see the Communications Toolbox documentation.
%
%   See also BERTOOL and VITERBISIM.

% Copyright 2020 The MathWorks, Inc.

% Initialize variables related to exit criteria.
totErr  = 0; % Number of errors observed
numBits = 0; % Number of bits processed

% --- Set up the simulation parameters. ---
% --- INSERT YOUR CODE HERE.

% Simulate until either the number of errors exceeds maxNumErrs
% or the number of bits processed exceeds maxNumBits.
while((totErr < maxNumErrs) && (numBits < maxNumBits))

    % Check if the user clicked the Stop button of BERTool.
    if isBERToolSimulationStopped(varargin{:})
      break
    end
  
    % --- Proceed with the simulation.
    % --- Be sure to update totErr and numBits.
    % --- INSERT YOUR CODE HERE.

end % End of loop

% Compute the BER.
ber = totErr/numBits;

About Template for Simulation Function

The simulation function template either satisfies the requirements listed in the Requirements for Using MATLAB Functions with Bit Error Rate Analysis App section or indicates where you need to insert code. In particular, the template:

Use Simulation Function Template

Follow these steps to update the simulation function template with your own simulation code.

Section Overview

You can use the Bit Error Rate Analysis app in conjunction with Simulink models to generate and analyze BER data. The Simulink model simulates the performance of the communications system that you want to study, while the Bit Error Rate Analysis app manages a series of simulations using the model and collects the BER data.

To access the capabilities of the Bit Error Rate Analysis app related to Simulink models, open the Monte Carlo tab, and then set the Simulation environment parameter to Simulink. If using parallel processing, the output must be saved to a workspace variable so that the parallel running engine can collect the results. For example, save the output of the Error Rate Calculation block to a workspace variable by using a To Workspace (Simulink) block configured to save the output to the name specified for the BER variable name and with the Save format set to Array.

For details about confidence intervals and curve fitting for simulation data, see the Plot Confidence Intervals and Curve Fit BER Points sections, respectively.

Use Simulink Model with Bit Error Rate Analysis App

This example shows how the Bit Error Rate Analysis app can manage a series of simulations of a Simulink model and how you can vary the plot. This figure shows the commgraycode model.

To run this example, follow these steps.

For another example that uses the Bit Error Rate Analysis app to manage a series of Simulink simulations, see the Prepare Simulink Model for Use with Bit Error Rate Analysis App example on the Bit Error Rate Analysis app reference page.

Assign Model Stopping Criteria

When you create a Simulink model for use with the Bit Error Rate Analysis app, you must set it up so that the simulation ends when it either detects a target number of errors or processes a maximum number of bits, whichever occurs first. For more information about this requirement, see the Requirements for Using Simulink Models with Bit Error Rate Analysis App section.

After creating your Simulink model, set the target number of errors and the maximum number of bits on the Monte Carlo tab of the Bit Error Rate Analysis app.

Typically, a Number of errors parameter value of at least 100 produces an accurate error rate. The Number of bits value prevents the simulation from running too long, especially at large E_b/N₀ values. However, if the Number of bits value is so small that the simulation collects very few errors, the error rate might not be accurate. You can use confidence intervals to gauge the accuracy of the error rates that your simulation produces. Larger confidence intervals result in less accurate computed error rates.

You can also click Stop in the Monte Carlo Simulation dialog box to stop a series of simulations prematurely.

Managing Data in Data Viewer

The data viewer gives you flexibility to rename and delete data sets and to reorder columns in the data viewer.

Export Bit Error Rate Analysis app Data Set

The Bit Error Rate Analysis app enables you to export individual data sets to the MATLAB workspace or to MAT-files. Exporting data enables you to process the data outside the Bit Error Rate Analysis app. For example, to create customized plots using data from the Bit Error Rate Analysis app, export the app data set to the MATLAB workspace and use any of the plotting commands in MATLAB. To reimport a structure later, see the Import Bit Error Rate Analysis app Data Set section.

To export an individual data set, follow these steps.

Examine an Exported Structure

This section describes the contents of the structure that the Bit Error Rate Analysis app exports to the workspace or to a MAT-file. This table describes the fields of the exported data structure. When you want to manipulate exported data, the fields that are most relevant are paramsEvaled and data.

Parameter Fields

The params and paramsEvaled fields are similar to each other, except that params describes the exact state of the user interface, whereas paramsEvaled indicates the values that are actually used for computations. For example, in a theoretical system with an AWGN channel, params records but paramsEvaled omits a diversity order parameter. The diversity order is not used in the computations because it is relevant for only systems with Rayleigh channels. As another example, if you type [0:3]+1 in the user interface as the range of E_b/N₀ values, params indicates [0:3]+1, whereas paramsEvaled indicates 1 2 3 4.

The length and exact contents of paramsEvaled depend on the data set because only relevant information appears. If the meaning of the contents of paramsEvaled is not clear upon inspection, one way to learn more is to reimport the data set into the Bit Error Rate Analysis app and inspect the parameter values that appear in the user interface.

Data Field

If your exported workspace variable is called ber0, the field ber0.data is a cell array that contains the numerical results in these vectors:

Save Bit Error Rate Analysis app Session

The Bit Error Rate Analysis app enables you to save an entire session. This feature is useful if your session contains multiple data sets that you want to return to in a later session. To reimport a saved session, see the Open Previous Bit Error Rate Analysis app Session section.

To save an entire Bit Error Rate Analysis app session, follow these steps.

The Bit Error Rate Analysis app saves the data in a MAT file or a binary file that records all data sets currently in the data viewer along with the user interface parameters associated with the data sets.

Import Bit Error Rate Analysis app Data Set

The Bit Error Rate Analysis app enables you to reimport individual data sets that you previously exported to a structure. For more information about exporting data sets from the Bit Error Rate Analysis app, see the Export Bit Error Rate Analysis app Data Set section.

To import an individual data set that you previously exported from the Bit Error Rate Analysis app to a structure, follow these steps.

After you dismiss the Data Import dialog box (and the file selection dialog box, in the case of a MAT-file), the data viewer shows the newly imported data set and the BER Figure window the corresponding plot.

Open Previous Bit Error Rate Analysis app Session

The Bit Error Rate Analysis app enables you to open previous saved sessions. For more information about exporting data sets from the Bit Error Rate Analysis app, see the Save Bit Error Rate Analysis app Session section.

To replace the data sets in the data viewer with data sets from a previous Bit Error Rate Analysis app session, follow these steps.

After the Bit Error Rate Analysis app reads the session file, the data viewer shows the data sets from the file.

If the Bit Error Rate Analysis app session requires particular workspace variables that you saved separately in a MAT-file, you can retrieve them by using the load function at the MATLAB command prompt. For example, to load the Bit Error Rate Analysis app session named ber_analysis_filename.mat enter this command.

load ber_analysis_filename.mat