Using IT++ functions in Matlab


In this chapter we are going to compile IT++ functions into MATLAB Mex DLL files. This is particularly useful when you need to add new functionalities to Matlab. In this tutorial we are going to create two functions to modulate and demodulate a differential modulation scheme called 16DAPSK (also known as 16STAR-QAM or D2A8PSK see e.g. [1]).

Visual Studio 2012 Express. Download the template Wizard from here and unzip it in c:\Program Files\Microsoft Visual Studio 11\VC\.

Visual Studio 2010 Express. Download the template Wizard from here and unzip it in c:\Program Files\Microsoft Visual Studio 10\VC\.

This stage is not necessary if you have already done it in part 2 of this tutorial.

According to the IT++ and Matlab versions you will have to edit:

Visual Studio 2012 Express: C:\Program Files\Microsoft Visual Studio 11\VC\VCWizards\AppWiz\Generic\MatMex\Scripts\1033\default.js

Visual Studio 2010 Express: C:\Program Files\Microsoft Visual Studio 10\VC\VCWizards\AppWiz\Generic\MatMex\Scripts\1033\default.js

and change these two lines to reflect the correct paths:

// TODO: edit the next 2 lines to point to the correct directories

var MATLAB_LIB_PATH = "C:\\Program Files\\MATLAB\\R2011a\\extern\\lib\\win32\\microsoft;C:\\itpp-4.3.1\\lib";

var MATLAB_INC_PATH = "C:\\Program Files\\MATLAB\\R2011a\\extern\\include;C:\\itpp-4.3.1\\";

This tutorial assumes that you use the Matlab 32 bits version 2011a and IT++ release 4.3.1. If it is not the case you will have to adapt the paths shown before to point to the right Matlab directory (e.g. MATLAB71 for release 7.1 etc.) and to the right IT++ directory. The DLL generated have been tested on the following releases of Matlab: 7.01, 7.04, 7.1, 2006a, 2006b, 2007a, 2007b, 2008a, 2008b, 2009a, 2009b, 2010a, 2010b, 2011a, 2011b, 2012a and 2012b.

Copy this file in c:\itpp-4.3.1\itpp\comm.

Building the dapsk16mod function:

Launch Visual C++ Express and select File New Project in the menu. You should now have this dialog box:

Select the Matlab Mex File template and create the project in C:\itpp-4.3.1\MyProjects. Give it the name dapsk16mod, click OK and Finish to create the project. As you can see, the template has already generated the right program for you!

The thing to know is how to get and send data to Matlab. The arguments of a mexFunction are:

nlhs = number of left-hand side arguments, i.e. the number of output arguments

plhs = an array (p stands for pointer) of left-hand side arguments i.e. output arguments

nrhs = number of right-hand side arguments, i.e. the number of input arguments

prhs = an array (p stands for pointer) of right-hand side arguments i.e. input arguments

In our example, we have four input arguments: al (prhs[0]), ah (prhs[1]), lt (prhs[2]), ht (prhs[3]), input_bits (prhs[4]) and one output argument output_symbols (plhs[0]).

Build the Debug and Release versions of the DLL (F7 key or menu Build\Build Solution).

If you look in the project's directory you should find these files (Release sub-directory):

The one that is going to be used by Matlab is dapsk16mod.mexw32. Place this file in the Matlab path.

Building the 16DAPSK demodulation function:

Create a new Project in C:\itpp-4.3.1\MyProjects by selecting the Matlab Mex File template and give it the name dapsk16demod.

Edit the file dapsk16demod.cpp and replace the code by this one.

Build the Debug and Release versions of the DLL (F7 key or menu Build\Build Solution).

Place the file dapsk16demod.mexw32 (located in C:\itpp-4.3.1\MyProjects\dapsk16demod\dapsk16demod\Release) in the Matlab path.

Now let's see how we can use these two functions in Matlab to obtain the BER curve of the 16DAPSK modulation on an AWGN channel.

Using the Mex functions in Matlab:

Creating m-file templates for help purposes:

As you probably know in Matlab you can get help on a function by typing help followed by the name of the function. For C Mex function we have to provide this help by the way of an m-file having the same name as the Mex function. Here are the two help files for our two Mex functions. Copy them into the Matlab work directory (they have to be at the same place as the .mexw32 files).

Plotting the 16DAPSK BER curve for AWGN:

Here is the code of the m-file that does this:

%16DAPSK performance on AWGN
% Hervé BOEGLEN 06/2006
%Clear all variables
clear all;
%Vector of SNR values (in dB)
SNR = [0 3 6 9 12 15 18];
%Modulation parameters
%Ring Ratio rr = ah/al
rr = 2;
%Thresholds for detection
lt = 0.18; ht = 0.53;
%inner ring radius
al = 0.625;
%outer ring radius
ah = al * rr;
%Number of bits used for the simulation
nbbits = 100000;

for i=1:length(SNR)

%Take more bits when SNR > 12dB
if (SNR(i) > 12)
nbbits = 400000;

%Random bits generation
xbit = randint(nbbits,1,2);

%16DAPSK modulation
y = dapsk16mod(al,ah,lt,ht,xbit);

%We add noise
yn = y + awgn(y,SNR(i));

%16DAPSK demodulation
xbit_d = dapsk16demod(al,ah,lt,ht,yn);

%BER calculation
[errBit(i) ratBit(i)] = biterr(xbit(5:end), xbit_d(5:end)');

%BER curve
title('16DAPSK performance on AWGN')
xlabel('SNR (dB)')


Here are the plots you should get:


[1] Svensson, N.A.B. On differentially encoded star 16QAM with differential detection and diversity Vehicular Technology, IEEE Transactions on Volume 44,  Issue 3,  Aug. 1995 Page(s):586 – 593