Preparing Simulation Functions for Use with BERTool :: BERTool: A Bit Error Rate Analysis GUI (Communications Toolbox™)

When you create a MATLAB function for use with BERTool, ensure the function interacts properly with the GUI. This section describes the inputs, outputs, and basic operation of a BERTool-compatible function.

Input Arguments

BERTool evaluates your entries in fields of the GUI and passes data to the function as these input arguments, in sequence:

One value from the Eb/No range vector each time BERTool invokes the simulation function
The Number of errors value
The Number of bits value

Output Arguments

Your simulation function must compute and return these output arguments, in sequence:

Bit error rate of the simulation
Number of bits processed when computing the BER

BERTool uses these output arguments when reporting and plotting results.

Simulation Operation

Your simulation function must perform these tasks:

Simulate the communication system for the E_b/N₀ value specified in the first input argument.
Stop simulating when the number of errors or the number of processed bits equals or exceeds the corresponding threshold specified in the second or third input argument, respectively.
Detect whether you click Stop in BERTool and abort the simulation in that case.

Template for a Simulation Function

Use the following template when adapting your code to work with BERTool. You can open it in an editor by entering edit bertooltemplate in the MATLAB Command Window. The description in Understanding the Template explains the template's key sections, while Using the Template indicates how to use the template with your own simulation code. Alternatively, you can develop your simulation function without using the template, but be sure it satisfies the requirements described in Requirements for Functions.

Note The template is not yet ready for use with BERTool. You must insert your own simulation code in the places marked INSERT YOUR CODE HERE. For a complete example based on this template, see Example: Preparing a Simulation Function for Use with BERTool.

function [ber, numBits] = bertooltemplate(EbNo, maxNumErrs, maxNumBits)
% Import Java class for BERTool.
import com.mathworks.toolbox.comm.BERTool;

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

% --- Set up parameters. ---
% --- INSERT YOUR CODE HERE.
% Simulate until number of errors exceeds maxNumErrs
% or number of bits processed exceeds maxNumBits.
while((totErr < maxNumErrs) && (numBits < maxNumBits))

   % Check if the user clicked the Stop button of BERTool.
   if (BERTool.getSimulationStop)
      break;
   end

   % --- Proceed with simulation.
   % --- Be sure to update totErr and numBits.
   % --- INSERT YOUR CODE HERE.
end % End of loop

% Compute the BER.
ber = totErr/numBits;

Understanding the Template

From studying the code in the function template, observe how the function either satisfies the requirements listed in Requirements for Functions or indicates where your own insertions of code should do so. In particular,

The function has appropriate input and output arguments.
The function includes a placeholder for code that simulates a system for the given E_b/N₀ value.

The function uses a loop structure to stop simulating when the number of errors exceeds maxNumErrs or the number of bits exceeds maxNumBits, whichever occurs first.

Note Although the while statement of the loop describes the exit criteria, your own code inserted into the section marked Proceed with simulation must compute the number of errors and the number of bits. If you do not perform these computations in your own code, clicking Stop is the only way to terminate the loop.

In each iteration of the loop, the function detects when the user clicks Stop in BERTool.

Using the Template

Here is a procedure for using the template with your own simulation code:

Determine the setup tasks you must perform. For example, you might want to initialize variables containing the modulation alphabet size, filter coefficients, a convolutional coding trellis, or the states of a convolutional interleaver. Place the code for these setup tasks in the template section marked Set up parameters.
Determine the core simulation tasks, assuming that all setup work has already been performed. For example, these tasks might include error-control coding, modulation/demodulation, and channel modeling. Place the code for these core simulation tasks in the template section marked Proceed with simulation.

Also in the template section marked Proceed with simulation, include code that updates the values of totErr and numBits. The quantity totErr represents the number of errors observed so far. The quantity numBits represents the number of bits processed so far. The computations to update these variables depend on how your core simulation tasks work.

Note Updating the numbers of errors and bits is important for ensuring that the loop terminates. However, if you accidentally create an infinite loop early in your development work using the function template, click Stop in BERTool to abort the simulation.

Omit any setup code that initializes EbNo, maxNumErrs, or maxNumBits, because BERTool passes these quantities to the function as input arguments after evaluating the data entered in the GUI.
Adjust your code or the template's code as necessary to use consistent variable names and meanings. For example, if your original code uses a variable called ebn0 and the template's function declaration (first line) uses the variable name EbNo, you must change one of the names so they match. As another example, if your original code uses SNR instead of E_b/N₀, you must convert quantities appropriately.

Example: Preparing a Simulation Function for Use with BERTool

This section adapts the function template given in Template for a Simulation Function to use simulation code from the documentation example in Example: Curve Fitting for an Error Rate Plot.

Preparing the Function

To prepare the function for use with BERTool, follow these steps:

Copy the template from Template for a Simulation Function into a new MATLAB file in the MATLAB Editor. Save it in a folder on your MATLAB path using the file name bertool_simfcn.

From the original example, the following lines are setup tasks. They are modified from the original example to rely on the input arguments that BERTool provides to the function, instead of defining variables such as EbNovec and numerrmin directly.

% Set up initial parameters.
siglen = 1000; % Number of bits in each trial
M = 2; % DBPSK is binary.
hMod = modem.dpskmod('M', M); % Create a DPSK modulator
hDemod = modem.dpskdemod(hMod); % Create a DPSK
                   % demodulator using the modulator object
snr = EbNo; % Because of binary modulation
ntrials = 0; % Number of passes through the loop

Place these lines of code in the template section marked Set up parameters.

From the original example, the following lines are the core simulation tasks, after all setup work has been performed.

msg = randint(siglen, 1, M); % Generate message sequence.
txsig = modulate(hMod, msg); % Modulate.
rxsig = awgn(txsig, snr, 'measured'); % Add noise.
decodmsg = demodulate(hDemod, rxsig); % Demodulate.
newerrs = biterr(msg,decodmsg); % Errors in this trial
ntrials = ntrials + 1; % Update trial index.

Place the code for these core simulation tasks in the template section marked Proceed with simulation.

Also in the template section marked Proceed with simulation (after the code from the previous step), include the following new lines of code to update the values of totErr and numBits.
```
% Update the total number of errors.
totErr = totErr + newerrs;

% Update the total number of bits processed.
numBits = ntrials * siglen;
```

The bertool_simfcn function is now compatible with BERTool. Note that unlike the original example, the function here does not initialize EbNovec, define EbNo as a scalar, or use numerrmin as the target number of errors; this is because BERTool provides input arguments for similar quantities. The bertool_simfcn function also excludes code related to plotting, curve fitting, and confidence intervals in the original example because BERTool enables you to do similar tasks interactively without writing code.

Using the Prepared Function

To use bertool_simfcn in conjunction with BERTool, continue the example by following these steps:

Open BERTool and go to the Monte Carlo tab.
Set parameters on the Monte Carlo tab as shown in the following figure.
Click Run.
BERTool spends some time computing results and then plots them. They do not appear to fall along a smooth curve because the simulation required only five errors for each value in EbNo.
To fit a curve to the series of points in the BER Figure window, select the box next to Fit in the data viewer.
BERTool plots the curve, as shown in the following figure.

Running MATLAB Simulations

Running Simulink Simulations

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

Products & Services	Solutions	Academia	Support	User Community	Company