Category Archives: MEX Files

Mex Files – 2

So continuing from the previous post, (1), we shall see how to start writing Mex code, by considering the following simple example of a uniform quantizer. Setup is assumed ready and done.

First and foremost, the filename should be “function_name.c” and not a “.m”. Once compiled, its this function_name that you will call in your other simulation running codes. Instead of the usual includes, we now use the “mex.h” header file. Note that other header files also may work, as this example will present the usage of “math.h” for the round() function.

Then, instead of the standard void main() we now start with a special type of function called mexFunction() and it can be used as follows. Note that the mexFunction is a generic name given to all mex file codes, it’s not the name of the function you want to write. So the first few lines look like this

#include "mex.h"
#include "math.h"
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])

nlhs and nrhs are the number of arguments, and *plhs and *prhs are Matlab compatible pointer array references on the output (left) and input (right) side respectively. All this seems quite complicated at first, but it’s not once you actually write one code. Just one!

So, we now need to obtain the location of the data, which is passed on to the function during the call. This is done by using the function mxGetPr(prhs[i]). For example

double *X, *nbits, *Xmax;
X = mxGetPr(prhs[0]);
nbits = mxGetPr(prhs[1]);
Xmax = mxGetPr(prhs[2]);

As this indicates, the vector to be quantized to nbits (2nd input variable) is X, the first input variable; and the maximum quantization value is Xmax, the third input variable.

More information about the dimensions of the vector or matrix can be found by using functions like Xdim = (int)mxGetM(prhs[0]) for no. of rows and mxGetN() for columns.

In case you need to create any temporary variables, typically mxMalloc() is used. However, be sure to free the memory at the end of the program by mxFree(), but we will cover this in the next post. Now we need to allocate memory for the output arguments, and assign them to pointers. Note the usage of mxCreateDoubleMatrix().

double *y, *step;
plhs[0] = mxCreateDoubleMatrix(Xdim, 1, mxREAL);
y = mxGetPr(plhs[0]);
plhs[1] = mxCreateDoubleMatrix(1, 1, mxREAL);
step = mxGetPr(plhs[1]);

where our first output argument y is the quantized vector, and the second is the computed step-size (using nbits and Xmax). The easy part of this is, the function is always mxCreateDoubleMatrix() with changes in the dimensions. Indicating Real or Complex is done by using mxREAL or mxCOMPLEX.

Once this is done, the rest of the code is like any other C code using pointers. One word of caution would be to take care of the dimensions, not to confuse between rows and columns, as this could mess up your code and take a long time to debug.

Try it out, and notice the speed-up! There are many more points, but this post is too long already 🙂 More on this, some time later. Although, at this point, the reader has sufficient knowledge to write simple mex codes on their own. Find the code here.

Advertisements

MEX Files – 1

MEX files basically are “Matlab EXecutable” files. As we know, by default Matlab is an interpreted language, and simulation happens by reading instruction by instruction. The MEX files are one option, to write code in a C-like fashion, and then generate an executable (operating system and architecture dependent) which then runs at extremely fast speeds (one of the solutions to Running Long Simulations) So, as mentioned, the executable is always dependent on OS. We shall now split the following discussion, first for Linux, and then for Windows.

On Linux, once the Matlab installation is complete, and assuming you have some version of the GNU C compiler (if you dont, just install it) the job is very easy. The easy way would be to use invoke mex -setup and try to understand what it is actually asking. We would discuss the articles for building Mex files using system ANSI compiler (mexopts.sh). The setup copies the default matlabroot/bin/mexopts.sh to your local home directory. If you open this file, you will notice that it basically contains the name of the C compiler, and other parameters. Currently gcc-4.2 is supported by Matlab. Compilation can be done by calling mex filename.c which generates a filename.mexglx an executable file for Linux machines.

On Windows, you need to get the Visual C++ Express edition maybe 2008 and install it unless you already have a C / C++ compiler. Once you have that installed, running mex -setup asks whether mex should look for compilers. Ask it to, and it should find the relevant compiler. Choose the options, and you are ready to go! Once this is done, write the C-like code for the mex file, and then run mex filename.c from the Matlab command window. This for Windows, generates a filename.mexw32 which indicates its for 32-bit windows machines.

The files generated are the executables, and you are good to go! Just call them like you would for any m file, and they should work. More on how to write this “C-like” code, in the coming posts! For the more enthusiastic, here are the 2 main links where we learnt it from. Functions Reference and MEX-files Guide.