Testing MEX Functions

On this page…
Why Use Test Scripts? Contents of the Example Test Script Using the Test Script Next Task

Why Use Test Scripts?

In this part of the tutorial, you test the MEX function that you generated in Generating MEX Functions Using Build Scripts to verify that it provides the same functionality as the original M-code. You use a separate test script to call your function code.

 Best Practice — Separating Test Bench from Function Code

 Best Practice — File Naming Convention

Back to Top

Contents of the Example Test Script

The test script emldemo_lms_test_02.m for this tutorial contains the following sections:

Set Up

Clears your MATLAB workspace and sets the playaudio flag to true to play the filtered audio signal at the end of the test script. If you do not want to listen to the audio output, set the playaudio flag to false.

%% Setting up:
% Initialize:
close all;
clear all;
clc;
% Flag to play audio:
playaudio = true;

Load Audio Signal

Loads the music sample from the file handel.mat, which is on the MATLAB path. data.y is a vector containing the discrete time samples of the audio signal, and data.Fs contains the sampling rate in samples per second.

% Load desired audio signal:
data = load('handel.mat');
desired = data.y;
Fs = data.Fs;
clear data;

Get Signal Length

Gets the length, or total number of samples, in the audio signal.

% Length of desired signal:
N = length(desired);

Set Maximum Signal Length

Sets the maximum signal length.

% Maximum signal length:
MaxLength = 128*1024;

Set Filter Length

Sets the number of samples in the filter impulse response.

% Filter length:
L = 32;

Create Distorted Signal

Generates white Gaussian noise, filters the noise using a simple low-pass filter, and adds this bandlimited noise to the audio source to create the distorted signal.

% samples
% Band-limited AWGN:
load emldemo_lms_filter.mat;
lambda = 1.0;
whiteNoise = lambda*randn(N,1);
noise = filter(b,1,whiteNoise);
% Distorted signal:
distorted = desired + noise;

Apply Original Filter

Applies the original filter emldemo_lms_01 to create a golden reference. A golden reference provides a set of expected test results. The outputs of the modified filter are compared to the golden reference to verify that the modified filter is functionally equivalent to the original filter.

%% Apply LMS Filter:
% Golden reference:
[ gold.signal gold.error gold.impulse ] = ...
  emldemo_lms_01(whiteNoise,distorted,L);

Apply Modified Filter

Applies the modified filter emldemo_lms_02_mex.

% Algorithm under test:
[ test.signal test.error test.impulse ] = ...
  emldemo_lms_02_mex(whiteNoise,distorted);

Compare Modified Code to Original Code

Computes the differences between the output signals, error signals, and impulse responses of the modified filter (algorithm under test) and the original filter (golden reference.)

%% Find differences:
diff.signal   =    test.signal   -  gold.signal;
diff.error    =    test.error    -  gold.error;
diff.impulse  =    test.impulse  -  gold.impulse;

 What is an impulse response?

Output Results

Plots the differences between the output signals, error signals, and impulse responses of the two filters and plays the filtered audio signal if playaudio is enabled.

%% Plot differences:
figure;
subplot(3,1,1);
plot(diff.signal);
title({'Algorithm Under Test versus Golden Reference' 
  'Output Signal'});
subplot(3,1,2);
plot(diff.error);
title('Error Signal');
subplot(3,1,3);
stem(diff.impulse);
title('Impulse Response');
%% Play sound:
if playaudio
  sound(test.error);
end

Back to Top

Using the Test Script

To test your emldemo_lms_02_mex MEX function, type emldemo_lms_test_02 at the MATLAB command line.

As MATLAB processes the test script, you see and hear outputs. Because playaudio is enabled, the filtered music is played. Initially, you hear the audio signal distorted by noise. Then, during the first few seconds, the filter attenuates the noise gradually, until you hear only the music playing with very little noise remaining.

• MATLAB displays a plot of the impulse response of the original filter.

  

  This is the golden reference, which demonstrates the expected filter coefficients.

• MATLAB displays a plot of the impulse response of the modified filter.

  

  By comparing the impulse response of the modified filter to the golden reference, you can see that the two outputs are nearly identical.

• MATLAB displays a plot showing the difference between the modified filter output and the original filter output. The order of operations in the Embedded MATLAB code and the MATLAB code might not be identical, so minor differences can occur due to rounding.

  

  These plots show that the difference between the modified filter and the golden reference is insignificant because:

  • The difference between the filter output signals is of the order 1 x 10^-15.

  • The difference between the filter error signals is of the order 1 x 10^-15.

  • The difference between the filter impulse responses is of the order 1 x 10^-16 or less.

  This result indicates that your Embedded MATLAB compliant filter code is functionally equivalent to the original M-code.

Back to Top

Next Task

You have generated a MEX function for your Embedded MATLAB compliant M-code and verified that it is functionally equivalent to your original M-code. Now you are ready to begin the next task in this tutorial, Generating C Code.

Back to Top

Generating MEX Functions Using Build Scripts

Generating C Code

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS